ctrader-api-client 0.1.0__py3-none-any.whl

ctrader_api_client/connection/protocol.py

@@ -0,0 +1,366 @@
+from __future__ import annotations
+
+import logging
+from collections.abc import Awaitable, Callable
+from typing import TypeVar
+
+import anyio
+import anyio.abc
+import betterproto
+from tenacity import (
+    AsyncRetrying,
+    retry_if_exception_type,
+    stop_after_attempt,
+    wait_exponential,
+)
+
+from .._internal import (
+    ClientMessageIdGenerator,
+    deserialize_proto_message,
+    encode_with_length_prefix,
+    read_framed_message,
+    unwrap_message,
+    wrap_message,
+)
+from .._internal.proto import ProtoMessage, ProtoOAErrorRes
+from ..exceptions import (
+    APIError,
+    CTraderConnectionClosedError,
+    CTraderConnectionFailedError,
+    CTraderConnectionTimeoutError,
+    FramingError,
+)
+from .transport import Transport
+
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T", bound=betterproto.Message)
+EventHandler = Callable[[T], Awaitable[None]]
+
+
+class Protocol:
+    """Message-level protocol handling with correlation and dispatch.
+
+    Manages the reader loop, request/response correlation, event dispatch,
+    and automatic reconnection with exponential backoff.
+    """
+
+    def __init__(
+        self,
+        transport: Transport,
+        reconnect_attempts: int = 5,
+        reconnect_min_wait: float = 1.0,
+        reconnect_max_wait: float = 60.0,
+    ) -> None:
+        """Initialize the protocol handler.
+
+        Args:
+            transport: The underlying transport for sending/receiving data.
+            reconnect_attempts: Maximum reconnection attempts (0 to disable).
+            reconnect_min_wait: Initial wait between attempts (seconds).
+            reconnect_max_wait: Maximum wait between attempts (seconds).
+        """
+        self._transport = transport
+        self._id_generator = ClientMessageIdGenerator()
+
+        # Request correlation
+        self._pending: dict[str, anyio.Event] = {}
+        self._results: dict[str, betterproto.Message] = {}
+        self._errors: dict[str, Exception] = {}
+
+        # Event dispatch
+        self._event_handlers: dict[type, list[EventHandler]] = {}
+
+        # Concurrency control
+        self._write_lock: anyio.Lock = anyio.Lock()
+        self._reader_scope: anyio.CancelScope | None = None
+        self._task_group: anyio.abc.TaskGroup | None = None
+        self._running = False
+
+        # Reconnection config
+        self._reconnect_attempts = reconnect_attempts
+        self._reconnect_min_wait = reconnect_min_wait
+        self._reconnect_max_wait = reconnect_max_wait
+
+        # Reconnection callback (set by CTraderClient)
+        self._on_reconnect: Callable[[], Awaitable[None]] | None = None
+
+    @property
+    def is_connected(self) -> bool:
+        """Whether protocol is connected and reader is running."""
+        return self._transport.is_connected and self._running
+
+    async def start(self) -> None:
+        """Start the reader task.
+
+        Call this after transport.connect() to begin reading messages.
+        """
+        if self._running:
+            return
+
+        self._running = True
+        self._task_group = anyio.create_task_group()
+        await self._task_group.__aenter__()
+        self._task_group.start_soon(self._reader_loop)
+
+    async def stop(self) -> None:
+        """Stop the reader task gracefully."""
+        self._running = False
+
+        if self._reader_scope is not None:
+            self._reader_scope.cancel()
+
+        if self._task_group is not None:
+            self._task_group.cancel_scope.cancel()
+            try:
+                await self._task_group.__aexit__(None, None, None)
+            except Exception:
+                pass
+            self._task_group = None
+
+        # Signal all pending requests to wake up
+        for event in self._pending.values():
+            event.set()
+
+    async def send_request(
+        self,
+        message: betterproto.Message,
+        timeout: float = 30.0,
+    ) -> betterproto.Message:
+        """Send request and wait for correlated response.
+
+        Args:
+            message: The protobuf message to send.
+            timeout: Timeout in seconds for waiting for a response.
+
+        Returns:
+            The response message from the server.
+
+        Raises:
+            CTraderConnectionClosedError: If not connected and reconnection fails.
+            CTraderConnectionTimeoutError: If response not received within timeout.
+            APIError: If server returns ProtoOAErrorRes.
+        """
+        if not self._running:
+            raise CTraderConnectionClosedError("Protocol not running")
+
+        msg_id = self._id_generator.next_id()
+        wrapped = wrap_message(message, client_msg_id=msg_id)
+
+        # Create event for this request
+        event = anyio.Event()
+        self._pending[msg_id] = event
+
+        try:
+            # Lock write and send message
+            async with self._write_lock:
+                encoded = encode_with_length_prefix(wrapped)
+                await self._transport.send(encoded)
+
+            # Wait for response
+            with anyio.fail_after(timeout):
+                await event.wait()
+
+            # Check if we were stopped
+            if not self._running:
+                raise CTraderConnectionClosedError("Protocol stopped while waiting for response")
+
+            # Check for error response
+            if msg_id in self._errors:
+                raise self._errors.pop(msg_id)
+
+            return self._results.pop(msg_id)
+
+        except TimeoutError:
+            raise CTraderConnectionTimeoutError(timeout, "request") from None
+        finally:
+            self._pending.pop(msg_id, None)
+            self._results.pop(msg_id, None)
+            self._errors.pop(msg_id, None)
+
+    async def send_event(self, message: betterproto.Message) -> None:
+        """Send message without expecting response (e.g., heartbeat).
+
+        Args:
+            message: The protobuf message to send.
+
+        Raises:
+            CTraderConnectionClosedError: If not connected.
+        """
+        if not self._running:
+            raise CTraderConnectionClosedError("Protocol not running")
+
+        wrapped = wrap_message(message)
+
+        async with self._write_lock:
+            encoded = encode_with_length_prefix(wrapped)
+            await self._transport.send(encoded)
+
+    def on_event(self, message_type: type[T], handler: EventHandler[T]) -> None:
+        """Register async handler for event type.
+
+        Multiple handlers can be registered for the same event type.
+
+        Args:
+            message_type: The protobuf message type to handle.
+            handler: Async callable that receives the message.
+        """
+        if message_type not in self._event_handlers:
+            self._event_handlers[message_type] = []
+        self._event_handlers[message_type].append(handler)
+
+    def remove_handler(self, message_type: type[T], handler: EventHandler[T]) -> None:
+        """Remove previously registered handler.
+
+        Fails silently if handler not found.
+
+        Args:
+            message_type: The protobuf message type.
+            handler: The handler to remove.
+        """
+        if message_type in self._event_handlers:
+            try:
+                self._event_handlers[message_type].remove(handler)
+            except ValueError:
+                pass  # Handler not found
+
+    async def _reader_loop(self) -> None:
+        """Continuously read and dispatch messages until stopped."""
+        with anyio.CancelScope() as scope:
+            self._reader_scope = scope
+            while self._running:
+                try:
+                    raw = await read_framed_message(self._transport.stream)
+                    proto_msg = deserialize_proto_message(raw)
+                    inner = unwrap_message(proto_msg)
+                    await self._dispatch_message(proto_msg, inner)
+                except (FramingError, anyio.ClosedResourceError, anyio.EndOfStream):
+                    # Connection closed or corrupted
+                    if self._running:
+                        await self.handle_disconnect()
+                    break
+                except anyio.get_cancelled_exc_class():
+                    break
+                except Exception as e:
+                    # Log but continue - don't crash reader on single message errors
+                    logger.warning("Error processing message: %s", e)
+                    continue
+
+    async def _dispatch_message(
+        self,
+        proto_msg: ProtoMessage,
+        inner: betterproto.Message,
+    ) -> None:
+        """Route message to pending request or event handlers.
+
+        Args:
+            proto_msg: The wrapper message containing client_msg_id.
+            inner: The unwrapped inner message.
+        """
+        msg_id = proto_msg.client_msg_id
+
+        # Check if this is a response to a pending request
+        if msg_id and msg_id in self._pending:
+            if isinstance(inner, ProtoOAErrorRes):
+                self._errors[msg_id] = APIError.from_proto(inner)
+            else:
+                self._results[msg_id] = inner
+            self._pending[msg_id].set()
+        else:
+            # Server-initiated event
+            await self._dispatch_event(inner)
+
+    async def _dispatch_event(self, message: betterproto.Message) -> None:
+        """Spawn tasks for registered handlers of this event type.
+
+        Handlers are spawned as concurrent tasks to prevent deadlocks if
+        handlers perform some blocking I/O calls that require responses from the reader loop.
+
+        Args:
+            message: The event message to dispatch.
+        """
+        handlers = self._event_handlers.get(type(message), [])
+        for handler in handlers:
+            if self._task_group is not None:
+                self._task_group.start_soon(self._call_handler_safe, handler, message)
+            else:
+                # Fallback if task group not available (shouldn't happen in normal operation)
+                await self._call_handler_safe(handler, message)
+
+    @staticmethod
+    async def _call_handler_safe(
+        handler: EventHandler,
+        message: betterproto.Message,
+    ) -> None:
+        """Call an event handler with exception safety.
+
+        Args:
+            handler: The handler to call.
+            message: The message to pass to the handler.
+        """
+        try:
+            await handler(message)
+        except Exception as e:
+            # Log but don't crash - other handlers should still run
+            logger.warning("Event handler error: %s", e)
+
+    async def handle_disconnect(self) -> None:
+        """Handle unexpected disconnection and attempt reconnection."""
+        logger.info("Connection lost, attempting to reconnect...")
+
+        # Cancel the reader loop first to prevent race conditions
+        if self._reader_scope is not None:
+            self._reader_scope.cancel()
+            self._reader_scope = None
+
+        # Close the transport
+        await self._transport.close()
+
+        # Attempt reconnection
+        try:
+            await self._reconnect()
+            logger.info("Reconnection successful")
+        except (CTraderConnectionFailedError, CTraderConnectionClosedError) as e:
+            logger.error("Reconnection failed: %s", e)
+            self._running = False
+            # Signal all pending requests to wake up with error
+            for msg_id in list(self._pending.keys()):
+                self._errors[msg_id] = CTraderConnectionClosedError("Connection lost and reconnection failed")
+                self._pending[msg_id].set()
+            raise
+
+    async def _reconnect(self) -> None:
+        """Attempt reconnection with exponential backoff.
+
+        Raises:
+            CTraderConnectionClosedError: If reconnection is disabled or all attempts fail.
+            CTraderConnectionFailedError: If connection cannot be established.
+        """
+        if self._reconnect_attempts == 0:
+            raise CTraderConnectionClosedError("Connection lost and reconnection disabled")
+
+        async for attempt in AsyncRetrying(
+            stop=stop_after_attempt(self._reconnect_attempts),
+            wait=wait_exponential(
+                min=self._reconnect_min_wait,
+                max=self._reconnect_max_wait,
+            ),
+            retry=retry_if_exception_type(CTraderConnectionFailedError),
+            reraise=True,
+        ):
+            with attempt:
+                logger.info(
+                    "Reconnection attempt %d/%d",
+                    attempt.retry_state.attempt_number,
+                    self._reconnect_attempts,
+                )
+                await self._transport.connect()
+
+        # Restart the reader loop
+        if self._task_group is not None:
+            self._task_group.start_soon(self._reader_loop)
+
+        # Notify callback for re-authentication
+        if self._on_reconnect is not None:
+            await self._on_reconnect()

ctrader_api_client/connection/transport.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+import ssl
+
+import anyio
+from anyio.abc import ByteReceiveStream, ByteStream
+
+from ..exceptions import CTraderConnectionClosedError, CTraderConnectionFailedError
+
+
+class Transport:
+    """Low-level TCP/SSL transport.
+
+    Handles raw socket connections without knowledge of protobuf or message semantics.
+    """
+
+    def __init__(self, host: str, port: int, use_ssl: bool = True) -> None:
+        """Initialize transport configuration.
+
+        Args:
+            host: The server hostname to connect to.
+            port: The server port to connect to.
+            use_ssl: Whether to use SSL/TLS encryption. Defaults to True.
+        """
+        self._host = host
+        self._port = port
+        self._ssl = use_ssl
+        self._stream: ByteStream | None = None
+
+    @property
+    def host(self) -> str:
+        """The host this transport connects to."""
+        return self._host
+
+    @property
+    def port(self) -> int:
+        """The port this transport connects to."""
+        return self._port
+
+    @property
+    def is_connected(self) -> bool:
+        """Whether transport has an active connection."""
+        return self._stream is not None
+
+    @property
+    def stream(self) -> ByteReceiveStream:
+        """Get the underlying stream for reading.
+
+        Raises:
+            CTraderConnectionClosedError: If not connected.
+        """
+        if self._stream is None:
+            raise CTraderConnectionClosedError("Not connected")
+        return self._stream
+
+    async def connect(self) -> None:
+        """Establish TCP/SSL connection.
+
+        If already connected, this method returns immediately.
+
+        Raises:
+            CTraderConnectionFailedError: If connection cannot be established.
+        """
+        if self._stream is not None:
+            return  # Already connected
+
+        try:
+            if self._ssl:
+                ssl_context = ssl.create_default_context()
+                self._stream = await anyio.connect_tcp(
+                    self._host,
+                    self._port,
+                    ssl_context=ssl_context,
+                    tls_standard_compatible=True,
+                )
+            else:
+                self._stream = await anyio.connect_tcp(self._host, self._port)
+        except OSError as e:
+            raise CTraderConnectionFailedError(self._host, self._port, e) from e
+
+    async def close(self) -> None:
+        """Close the connection gracefully.
+
+        This method is idempotent - calling it multiple times is safe.
+        Handles already-closed streams gracefully.
+        """
+        if self._stream is not None:
+            stream = self._stream
+            self._stream = None  # Clear reference first to prevent re-entry
+            try:
+                await stream.aclose()
+            except (OSError, anyio.ClosedResourceError):
+                # Stream already closed or in bad state - ignore
+                pass
+
+    async def send(self, data: bytes) -> None:
+        """Send raw bytes over the connection.
+
+        Args:
+            data: The bytes to send.
+
+        Raises:
+            CTraderConnectionClosedError: If not connected.
+        """
+        if self._stream is None:
+            raise CTraderConnectionClosedError("Not connected")
+        await self._stream.send(data)
+
+    async def receive(self, max_bytes: int) -> bytes:
+        """Receive up to max_bytes from the connection.
+
+        Args:
+            max_bytes: Maximum number of bytes to receive.
+
+        Returns:
+            The received bytes, or empty bytes on EOF.
+
+        Raises:
+            CTraderConnectionClosedError: If not connected.
+        """
+        if self._stream is None:
+            raise CTraderConnectionClosedError("Not connected")
+        return await self._stream.receive(max_bytes)

ctrader_api_client/enums.py

@@ -0,0 +1,138 @@
+from __future__ import annotations
+
+from enum import Enum, StrEnum
+
+
+class Environment(StrEnum):
+    """Trading environment."""
+
+    DEMO = "DEMO"
+    LIVE = "LIVE"
+
+
+class ExecutionType(Enum):
+    """Type of execution event."""
+
+    ORDER_ACCEPTED = "ORDER_ACCEPTED"
+    ORDER_FILLED = "ORDER_FILLED"
+    ORDER_REPLACED = "ORDER_REPLACED"
+    ORDER_CANCELLED = "ORDER_CANCELLED"
+    ORDER_EXPIRED = "ORDER_EXPIRED"
+    ORDER_REJECTED = "ORDER_REJECTED"
+    ORDER_CANCEL_REJECTED = "ORDER_CANCEL_REJECTED"
+    ORDER_PARTIAL_FILL = "ORDER_PARTIAL_FILL"
+    SWAP = "SWAP"
+    DEPOSIT_WITHDRAW = "DEPOSIT_WITHDRAW"
+    BONUS_DEPOSIT_WITHDRAW = "BONUS_DEPOSIT_WITHDRAW"
+
+
+class OrderSide(Enum):
+    """Order side (direction)."""
+
+    BUY = "BUY"
+    SELL = "SELL"
+
+
+class OrderType(Enum):
+    """Order type."""
+
+    MARKET = "MARKET"
+    LIMIT = "LIMIT"
+    STOP = "STOP"
+    STOP_LIMIT = "STOP_LIMIT"
+    MARKET_RANGE = "MARKET_RANGE"
+    STOP_LOSS_TAKE_PROFIT = "STOP_LOSS_TAKE_PROFIT"
+
+
+class OrderStatus(Enum):
+    """Order status."""
+
+    ACCEPTED = "ACCEPTED"
+    FILLED = "FILLED"
+    REJECTED = "REJECTED"
+    EXPIRED = "EXPIRED"
+    CANCELLED = "CANCELLED"
+
+
+class PositionStatus(Enum):
+    """Position status."""
+
+    OPEN = "OPEN"
+    CLOSED = "CLOSED"
+    CREATED = "CREATED"
+    ERROR = "ERROR"
+
+
+class TimeInForce(Enum):
+    """Order time in force."""
+
+    GOOD_TILL_CANCEL = "GTC"
+    GOOD_TILL_DATE = "GTD"
+    IMMEDIATE_OR_CANCEL = "IOC"
+    FILL_OR_KILL = "FOK"
+    MARKET_ON_OPEN = "MOO"
+
+
+class DealStatus(Enum):
+    """Deal execution status."""
+
+    FILLED = "FILLED"
+    PARTIALLY_FILLED = "PARTIALLY_FILLED"
+    REJECTED = "REJECTED"
+    INTERNALLY_REJECTED = "INTERNALLY_REJECTED"
+    ERROR = "ERROR"
+    MISSED = "MISSED"
+
+
+class AccessRights(Enum):
+    """Account access rights."""
+
+    FULL_ACCESS = "FULL_ACCESS"
+    CLOSE_ONLY = "CLOSE_ONLY"
+    NO_TRADING = "NO_TRADING"
+    NO_LOGIN = "NO_LOGIN"
+
+
+class AccountType(Enum):
+    """Account type."""
+
+    HEDGED = "HEDGED"
+    NETTED = "NETTED"
+    SPREAD_BETTING = "SPREAD_BETTING"
+
+
+class TradingMode(Enum):
+    """Symbol trading mode."""
+
+    ENABLED = "ENABLED"
+    DISABLED_WITHOUT_PENDINGS_EXECUTION = "DISABLED_WITHOUT_PENDINGS"
+    DISABLED_WITH_PENDINGS_EXECUTION = "DISABLED_WITH_PENDINGS"
+    CLOSE_ONLY = "CLOSE_ONLY"
+
+
+class TrendbarPeriod(Enum):
+    """Trendbar/candle period."""
+
+    M1 = "M1"
+    M2 = "M2"
+    M3 = "M3"
+    M4 = "M4"
+    M5 = "M5"
+    M10 = "M10"
+    M15 = "M15"
+    M30 = "M30"
+    H1 = "H1"
+    H4 = "H4"
+    H12 = "H12"
+    D1 = "D1"
+    W1 = "W1"
+    MN1 = "MN1"
+
+
+class StopTriggerMethod(Enum):
+    """Method for triggering stop orders."""
+
+    TRADE = "TRADE"
+    OPPOSITE = "OPPOSITE"
+    DOUBLE_TRADE = "DOUBLE_TRADE"
+    DOUBLE_OPPOSITE = "DOUBLE_OPPOSITE"

ctrader_api_client/events/__init__.py

@@ -0,0 +1,65 @@
+"""Event system for cTrader API client.
+
+This module provides a pub/sub mechanism for handling async events from
+the cTrader server, such as price updates, order executions, and account
+changes.
+
+Example:
+    ```python
+    from ctrader_api_client.events import EventEmitter, SpotEvent
+
+    emitter = EventEmitter()
+
+
+    async def on_price(event: SpotEvent):
+        print(f"{event.symbol_id}: {event.bid}/{event.ask}")
+
+
+    emitter.subscribe(SpotEvent, on_price, symbol_id=1)
+    ```
+"""
+
+from .emitter import EventEmitter
+from .router import EventRouter
+from .types import (
+    AccountDisconnectEvent,
+    ClientDisconnectEvent,
+    DepthEvent,
+    DepthQuote,
+    Event,
+    ExecutionEvent,
+    MarginCallTriggerEvent,
+    MarginChangeEvent,
+    OrderErrorEvent,
+    PnLChangeEvent,
+    ReadyEvent,
+    ReconnectedEvent,
+    SpotEvent,
+    SymbolChangedEvent,
+    TokenInvalidatedEvent,
+    TraderUpdateEvent,
+    TrailingStopChangedEvent,
+)
+
+
+__all__ = [
+    "AccountDisconnectEvent",
+    "ClientDisconnectEvent",
+    "DepthEvent",
+    "DepthQuote",
+    "Event",
+    "EventEmitter",
+    "EventRouter",
+    "ExecutionEvent",
+    "MarginCallTriggerEvent",
+    "MarginChangeEvent",
+    "OrderErrorEvent",
+    "PnLChangeEvent",
+    "ReadyEvent",
+    "ReconnectedEvent",
+    "SpotEvent",
+    "SymbolChangedEvent",
+    "TokenInvalidatedEvent",
+    "TraderUpdateEvent",
+    "TrailingStopChangedEvent",
+]