ctrader-api-client 0.7.2__tar.gz → 0.8.0__tar.gz

{ctrader_api_client-0.7.2 → ctrader_api_client-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ctrader-api-client
-Version: 0.7.2
+Version: 0.8.0
 Summary: API Client to interact with the cTrader Open API spec
 Author-email: Elio <elioachukri@pm.me>
 License-File: LICENSE
@@ -354,10 +354,14 @@ config = ClientConfig(
     heartbeat_timeout=30.0, # Or 0 to disable server heartbeat checks
     request_timeout=30.0,
 
-    # Reconnection
-    reconnect_attempts=5,
+    # Reconnection: None retries for as long as the client is open (the
+    # default), an integer caps the attempts, 0 disables reconnection. A
+    # finite budget that runs out raises CTraderReconnectAbandonedError out
+    # of the `async with client:` block.
+    reconnect_attempts=None,
     reconnect_min_wait=1.0,
     reconnect_max_wait=60.0,
+    connect_timeout=30.0,
 
     # Token refresh: when to refresh access tokens and how hard to retry
     refresh_policy=RefreshPolicy(

{ctrader_api_client-0.7.2 → ctrader_api_client-0.8.0}/README.md

@@ -335,10 +335,14 @@ config = ClientConfig(
     heartbeat_timeout=30.0, # Or 0 to disable server heartbeat checks
     request_timeout=30.0,
 
-    # Reconnection
-    reconnect_attempts=5,
+    # Reconnection: None retries for as long as the client is open (the
+    # default), an integer caps the attempts, 0 disables reconnection. A
+    # finite budget that runs out raises CTraderReconnectAbandonedError out
+    # of the `async with client:` block.
+    reconnect_attempts=None,
     reconnect_min_wait=1.0,
     reconnect_max_wait=60.0,
+    connect_timeout=30.0,
 
     # Token refresh: when to refresh access tokens and how hard to retry
     refresh_policy=RefreshPolicy(

{ctrader_api_client-0.7.2 → ctrader_api_client-0.8.0}/docs/api/events.md

@@ -146,6 +146,14 @@ async def on_reconnected(event: ReconnectedEvent):
         print(f"Failed accounts: {event.failed_accounts}")
 ```
 
+An `app_auth_restored=False` is not the end of the story. The server can refuse
+application authentication for transient reasons of its own, so the client keeps
+retrying with backoff and announces each account it restores afterwards with a
+`ReadyEvent`. Treat this event as a signal that the link is back but degraded —
+stop acting on the session until the accounts are announced ready — rather than
+as a permanent failure. Check the current state with
+`client.auth.is_app_authenticated`.
+
 ::: ctrader_api_client.events.ClientDisconnectEvent
     options:
       show_source: false

{ctrader_api_client-0.7.2 → ctrader_api_client-0.8.0}/docs/api/exceptions.md

@@ -153,6 +153,32 @@ other handlers for that event.
     options:
       show_source: false
 
+::: ctrader_api_client.CTraderReconnectAbandonedError
+    options:
+      show_source: false
+
+This is the one connection exception that reaches you without your having called
+anything: it is raised out of the `async with client:` block itself. Reconnection
+is unbounded by default, so seeing it means either that `reconnect_attempts` was
+set to a finite number and every one was spent, or that something failed which
+the reconnection logic did not anticipate.
+
+```python
+while True:
+    try:
+        async with client:
+            await asyncio.Event().wait()
+    except CTraderReconnectAbandonedError:
+        logger.exception("Client abandoned its connection; starting a new one")
+        await asyncio.sleep(30)
+```
+
+Catching it is only worthwhile if you intend to build a fresh client, since the
+one that raised it is finished. Letting it propagate and having a process
+supervisor restart you is an equally good answer, and the reason it is raised
+rather than logged: a client that has stopped reconnecting has no reader and no
+heartbeat left to notice anything, so nothing short of a restart brings it back.
+
 ### Authentication
 
 ::: ctrader_api_client.AuthenticationError

{ctrader_api_client-0.7.2 → ctrader_api_client-0.8.0}/docs/getting-started.md

@@ -312,13 +312,22 @@ config = ClientConfig(
     heartbeat_timeout=0,  # 0 to disable server heartbeat checks (default)
     request_timeout=30.0,
 
-    # Reconnection
-    reconnect_attempts=5,
+    # Reconnection: None retries for as long as the client is open (the
+    # default), an integer caps the attempts, 0 disables reconnection.
+    reconnect_attempts=None,
     reconnect_min_wait=1.0,
     reconnect_max_wait=60.0,
+    connect_timeout=30.0,
 )
 ```
 
+Reconnection is unbounded by default because a finite budget that runs out
+leaves a client that can never recover: there is no reader and no heartbeat left
+to notice anything, so it stays offline until the process restarts. If you do
+set a finite `reconnect_attempts`, spending it raises
+`CTraderReconnectAbandonedError` out of the `async with client:` block rather
+than leaving the client alive and permanently disconnected.
+
 ## Next Steps
 
 - [API Reference - Client](api/client.md) - Full client documentation

{ctrader_api_client-0.7.2 → ctrader_api_client-0.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ctrader-api-client"
-version = "0.7.2"
+version = "0.8.0"
 description = "API Client to interact with the cTrader Open API spec"
 readme = "README.md"
 authors = [
@@ -79,6 +79,7 @@ select = [
     "RUF022", # Unsorted __all__ blocks
     "FURB157",  # Check unnecessary casts in Decimal constructors
     "RUF032",  # Check for Decimal calls passing a float literal
+    "G004",  # Check for all f strings in logging calls
 ]
 
 [tool.ruff.lint.per-file-ignores]

{ctrader_api_client-0.7.2 → ctrader_api_client-0.8.0}/src/ctrader_api_client/__init__.py

@@ -92,6 +92,7 @@ from .exceptions import (
     CTraderConnectionFailedError,
     CTraderConnectionTimeoutError,
     CTraderError,
+    CTraderReconnectAbandonedError,
     DeserializationError,
     FramingError,
     ProtocolError,
@@ -139,6 +140,7 @@ __all__ = [
     "CTraderConnectionFailedError",
     "CTraderConnectionTimeoutError",
     "CTraderError",
+    "CTraderReconnectAbandonedError",
     "ClientConfig",
     "ClientDisconnectEvent",
     "CloseDetail",

{ctrader_api_client-0.7.2 → ctrader_api_client-0.8.0}/src/ctrader_api_client/auth/_recovery.py

@@ -60,6 +60,14 @@ class SessionRecovery:
         # repeated report does not start a second check against the server.
         self._verifying: set[int] = set()
 
+        # A reconnect whose application re-authentication failed, left for the
+        # recovery loop to keep retrying. Nothing can be authorized on a link
+        # the application itself is not authenticated on, so this is settled
+        # before any account is attempted.
+        self._app_auth_pending = False
+        self._app_auth_attempts = 0
+        self._app_auth_next_at = 0.0
+
         self._task_scope: anyio.CancelScope | None = None
         self._running = False
 
@@ -85,6 +93,7 @@ class SessionRecovery:
         finally:
             self._running = False
             self._task_scope = None
+            self._app_auth_pending = False
             self._store.invalidate_all()
             logger.debug("Session recovery monitor stopped")
 
@@ -181,6 +190,11 @@ class SessionRecovery:
         credentials are kept, so the sessions can be re-established once the
         link is back.
         """
+        # Any application re-authentication still being retried belonged to the
+        # link that just died. The reconnection attempts it again from scratch
+        # and re-arms this if it has to, so carrying the old state forward would
+        # only make the next backoff start deeper than it should.
+        self._app_auth_pending = False
         self._store.invalidate_all()
 
     async def on_connection_restored(self) -> None:
@@ -190,6 +204,11 @@ class SessionRecovery:
         link is already back, and a caller can only act on a failure it is told
         about. Without application authentication nothing else can be
         attempted, so that failure is reported on its own.
+
+        Only the first attempt is made here. This runs inside the protocol's
+        reconnection task, which cannot detect a further drop while it is
+        blocked, so a failure is handed to the recovery loop to keep retrying in
+        the background rather than waited out inline.
         """
         logger.debug("Connection restored, re-authenticating...")
 
@@ -197,7 +216,8 @@ class SessionRecovery:
             await self._authenticator.authenticate_app()
             logger.debug("App re-authenticated successfully")
         except Exception as e:
-            logger.error("Failed to re-authenticate app after reconnect: %s", e)
+            logger.error("Failed to re-authenticate app after reconnect, will retry: %s", e)
+            self._arm_app_auth_recovery()
             await self._publisher.emit(
                 ReconnectedEvent(
                     app_auth_restored=False,
@@ -228,15 +248,66 @@ class SessionRecovery:
             )
         )
 
+    def _backoff_delay(self, attempts: int) -> float:
+        """How long to wait before attempt number `attempts`, per the policy."""
+        return min(self._policy.min_wait * 2 ** (attempts - 1), self._policy.max_wait)
+
     def _defer_recovery(self, account_id: int, state: AwaitingRecovery) -> None:
         """Back off before the next recovery attempt for a single account."""
         attempts = state.attempts + 1
-        delay = min(self._policy.min_wait * 2 ** (attempts - 1), self._policy.max_wait)
         self._store.reschedule_recovery(
             account_id,
-            AwaitingRecovery(attempts=attempts, next_attempt_at=self._clock.now() + delay),
+            AwaitingRecovery(
+                attempts=attempts,
+                next_attempt_at=self._clock.now() + self._backoff_delay(attempts),
+            ),
         )
 
+    def _arm_app_auth_recovery(self) -> None:
+        """Hand a failed application re-authentication to the recovery loop.
+
+        Every account is flagged alongside it: their sessions died with the
+        link, and the re-authentication that would have restored them is the
+        very thing that failed, so they are recovered by the same loop once the
+        application is authenticated again.
+        """
+        self._app_auth_pending = True
+        self._app_auth_attempts = 0
+        self._defer_app_auth()
+
+        for credentials in self._store.all_credentials():
+            self._store.flag_for_recovery(credentials.account_id)
+
+        self._reauth_signal.set()
+
+    def _defer_app_auth(self) -> None:
+        """Back off before the next application re-authentication attempt."""
+        self._app_auth_attempts += 1
+        self._app_auth_next_at = self._clock.now() + self._backoff_delay(self._app_auth_attempts)
+
+    async def _retry_app_auth(self) -> bool:
+        """Attempt the deferred application re-authentication once.
+
+        Returns:
+            True if the application is authenticated again, False if the
+            attempt failed and has been deferred for another try.
+        """
+        try:
+            await self._authenticator.authenticate_app()
+        except Exception as e:
+            self._defer_app_auth()
+            logger.warning(
+                "Re-authenticating the application failed (attempt %d), will retry: %s",
+                self._app_auth_attempts,
+                e,
+            )
+            return False
+
+        self._app_auth_pending = False
+        self._app_auth_attempts = 0
+        logger.info("Application re-authenticated; restoring accounts")
+        return True
+
     async def _wait_for_retry(self, delay: float, flagged: anyio.Event) -> None:
         """Wait out a backoff, returning early if another account needs recovery.
 
@@ -266,6 +337,11 @@ class SessionRecovery:
         and retries continue until every account succeeds, is removed, or the
         monitor stops. A successful re-auth restores authorized state and emits
         a ReadyEvent so subscriptions can be restored.
+
+        Also carries the application re-authentication a reconnect could not
+        complete. That one is not per-account and blocks every account behind
+        it, so it is settled first and the accounts are left flagged until it
+        succeeds.
         """
         while self._running:
             # Consume any pending notification before reading the queue, so a
@@ -274,6 +350,16 @@ class SessionRecovery:
                 self._reauth_signal = anyio.Event()
             flagged = self._reauth_signal
 
+            if self._app_auth_pending:
+                waiting = self._app_auth_next_at - self._clock.now()
+                if waiting > 0:
+                    await self._wait_for_retry(waiting, flagged)
+                    continue
+                if not await self._retry_app_auth():
+                    continue
+                # Authenticating the application is exactly what the flagged
+                # accounts were held up by, so go straight on to them.
+
             queue = self._store.awaiting_recovery()
             if not queue:
                 await flagged.wait()

{ctrader_api_client-0.7.2 → ctrader_api_client-0.8.0}/src/ctrader_api_client/composition.py

@@ -78,6 +78,7 @@ def build_graph(
         host=config.host,
         port=config.port,
         use_ssl=config.use_ssl,
+        connect_timeout=config.connect_timeout,
     )
     protocol = Protocol(
         transport=transport,

{ctrader_api_client-0.7.2 → ctrader_api_client-0.8.0}/src/ctrader_api_client/config.py

@@ -17,7 +17,12 @@ class ClientConfig(BaseModel):
         heartbeat_interval: Seconds between heartbeat sends.
         heartbeat_timeout: Seconds without server-initiated messages before disconnect. Set to 0 to disable.
         request_timeout: Default timeout for API requests in seconds.
-        reconnect_attempts: Max reconnection attempts (0 to disable).
+        connect_timeout: Seconds allowed for the TCP connection and TLS
+            handshake together, after which the attempt is failed and retried.
+        reconnect_attempts: Max reconnection attempts. None (the default)
+            retries for as long as the client is open. 0 disables reconnection.
+            A finite budget that runs out abandons the connection and raises
+            CTraderReconnectAbandonedError out of the `async with` block.
         reconnect_min_wait: Initial wait between reconnection attempts.
         reconnect_max_wait: Maximum wait between reconnection attempts.
         refresh_policy: When to refresh access tokens and how hard to try.
@@ -51,9 +56,10 @@ class ClientConfig(BaseModel):
 
     # Request settings
     request_timeout: float = Field(default=30.0, gt=0)
+    connect_timeout: float = Field(default=30.0, gt=0)
 
     # Reconnection settings
-    reconnect_attempts: int = Field(default=5, ge=0)
+    reconnect_attempts: int | None = Field(default=None, ge=0)
     reconnect_min_wait: float = Field(default=1.0, gt=0)
     reconnect_max_wait: float = Field(default=60.0, gt=0)
 

{ctrader_api_client-0.7.2 → ctrader_api_client-0.8.0}/src/ctrader_api_client/connection/protocol.py

@@ -12,6 +12,7 @@ from tenacity import (
     AsyncRetrying,
     retry_if_exception_type,
     stop_after_attempt,
+    stop_never,
     wait_exponential,
 )
 
@@ -29,6 +30,7 @@ from ..exceptions import (
     CTraderConnectionClosedError,
     CTraderConnectionFailedError,
     CTraderConnectionTimeoutError,
+    CTraderReconnectAbandonedError,
     FramingError,
 )
 from .listener import ConnectionListener
@@ -73,7 +75,7 @@ class Protocol:
     def __init__(
         self,
         transport: Transport,
-        reconnect_attempts: int = 5,
+        reconnect_attempts: int | None = None,
         reconnect_min_wait: float = 1.0,
         reconnect_max_wait: float = 60.0,
     ) -> None:
@@ -81,7 +83,10 @@ class Protocol:
 
         Args:
             transport: The underlying transport for sending/receiving data.
-            reconnect_attempts: Maximum reconnection attempts (0 to disable).
+            reconnect_attempts: Maximum reconnection attempts. None retries for
+                as long as the client is open, which is the default: an outage
+                that outlasts a finite budget otherwise leaves a client that
+                can never recover. 0 disables reconnection entirely.
             reconnect_min_wait: Initial wait between attempts (seconds).
             reconnect_max_wait: Maximum wait between attempts (seconds).
         """
@@ -109,6 +114,11 @@ class Protocol:
         # reader loop and the heartbeat loop both detecting the same drop).
         self._reconnecting = False
 
+        # Set when the link drops again while a reconnection is already in
+        # flight. The detector that saw it cannot start its own reconnection,
+        # so the one already running goes round again on its behalf.
+        self._redo_requested = False
+
         # Told about link transitions; set by whoever owns this protocol.
         self._listener: ConnectionListener | None = None
 
@@ -444,11 +454,17 @@ class Protocol:
         standalone task decouples the reconnection from the cancel scope of
         whichever loop detected the drop.
 
-        Idempotent: calls made while a reconnection is already in flight are
-        ignored, so the reader and heartbeat loops racing to report the same
-        drop only produce a single reconnection.
+        Idempotent: calls made while a reconnection is already in flight do not
+        start a second one, so the reader and heartbeat loops racing to report
+        the same drop only produce a single reconnection. Such a call is still
+        recorded, because it may be reporting a *fresh* drop of the link the
+        running reconnection just restored — and the caller cannot retry for
+        itself, since the reader loop exits as soon as it has reported.
         """
-        if not self._running or self._reconnecting:
+        if not self._running:
+            return
+        if self._reconnecting:
+            self._redo_requested = True
             return
         if self._task_group is None:
             return
@@ -457,16 +473,25 @@ class Protocol:
         logger.warning("Connection lost, attempting to reconnect...")
 
         # State tied to the dead link is invalid from this moment on. Report it
-        # before reconnecting so nothing observes a session that no longer
-        # exists, and never let a failing listener block the reconnection.
-        if self._listener is not None:
-            try:
-                await self._listener.on_connection_lost()
-            except Exception:
-                logger.exception("Connection listener failed on disconnect")
+        # before reconnecting so nothing observes a session that no longer exists.
+        await self._notify_connection_lost()
 
         self._task_group.start_soon(self._reconnect_task)
 
+    async def _notify_connection_lost(self) -> None:
+        """Tell the listener the link is gone.
+
+        Never lets a failing listener block the reconnection: whatever
+        bookkeeping it does matters less than getting the link back.
+        """
+        if self._listener is None:
+            return
+
+        try:
+            await self._listener.on_connection_lost()
+        except Exception:
+            logger.exception("Connection listener failed on disconnect")
+
     async def _reconnect_task(self) -> None:
         """Own the full reconnection lifecycle from a standalone task.
 
@@ -475,32 +500,90 @@ class Protocol:
         escape: an unhandled error here would propagate into the protocol task
         group and tear down every other task. A terminal reconnection failure is
         instead recorded by stopping the protocol and waking pending requests.
+
+        Loops rather than running once, so a link that drops again while this is
+        working — reported through `handle_disconnect` as `_redo_requested`, the
+        only route left once the reader has exited — is reconnected too instead
+        of being stranded.
+
+        Raises:
+            CTraderReconnectAbandonedError: If reconnection is given up on. This
+                is deliberately allowed to escape into the protocol task group
+                and tear the client down: see :meth:`_abandon`.
         """
         try:
-            # The reader loop is reading a dead stream; cancel it before we
-            # reconnect so a stale reader can't race the fresh one we restart.
-            if self._reader_scope is not None:
-                self._reader_scope.cancel()
-                self._reader_scope = None
-
-            # Close the old transport (idempotent — the task that detected the
-            # drop may have already raced us to it).
-            await self._transport.close()
-
-            await self._reconnect()
-            logger.info("Reconnection successful")
+            while True:
+                self._redo_requested = False
+
+                # The reader loop is reading a dead stream; cancel it before we
+                # reconnect so a stale reader can't race the fresh one we restart.
+                if self._reader_scope is not None:
+                    self._reader_scope.cancel()
+                    self._reader_scope = None
+
+                # Close the old transport (idempotent — the task that detected
+                # the drop may have already raced us to it). Tearing down a dead
+                # socket can fail on its own, which says nothing about whether
+                # reconnecting will work: swallow it here so it can never be
+                # mistaken below for an exhausted reconnection.
+                try:
+                    await self._transport.close()
+                except Exception:
+                    logger.debug("Ignoring error while closing dead transport", exc_info=True)
+
+                await self._reconnect()
+                logger.info("Reconnection successful")
+
+                if not self._redo_requested:
+                    break
+
+                logger.warning("Connection lost again while reconnecting, retrying...")
+                # The sessions this pass just restored died with the link that
+                # dropped underneath it, so report that loss before going round
+                # again — nothing else will, since `handle_disconnect` only
+                # recorded the drop rather than handling it.
+                await self._notify_connection_lost()
         except (CTraderConnectionFailedError, CTraderConnectionClosedError) as e:
             logger.error("Reconnection failed, giving up: %s", e)
-            self._running = False
-            # Wake all pending requests so callers fail fast instead of hanging.
-            self._fail_pending("Connection lost and reconnection failed")
-        except Exception:
-            # Defensive: never let the reconnection task crash the task group.
+            self._abandon("connection lost and reconnection failed", e)
+        except Exception as e:
+            # Nothing here is expected to fail this way — the retry loop below
+            # absorbs every failure connecting — so treat it as a defect rather
+            # than a state to sit quietly in.
             logger.exception("Unexpected error while reconnecting")
-            self._running = False
-            self._fail_pending("Reconnection error")
+            self._abandon("unexpected error while reconnecting", e)
         finally:
             self._reconnecting = False
+            self._redo_requested = False
+
+    def _abandon(self, reason: str, cause: BaseException) -> None:
+        """Stop the protocol and make giving up impossible to miss.
+
+        A client that has stopped reconnecting cannot recover on its own: the
+        reader has exited, the heartbeat loop returns as soon as its next write
+        fails, and `handle_disconnect` refuses everything once `_running` is
+        False. Nothing is left that could try again. Staying alive in that state
+        only means a consumer polling `is_connected` sees a link that is down
+        and assumes, reasonably and wrongly, that something is working on it.
+
+        So the failure is raised instead of recorded. It escapes into the
+        protocol task group, through the supervisor's, and out of the
+        `async with client:` block, where a process supervisor will see it.
+
+        Raises:
+            CTraderReconnectAbandonedError: Always, unless reconnection was
+                disabled by configuration, which is a choice rather than a
+                failure and keeps the previous behaviour of a client that
+                rejects further requests.
+        """
+        self._running = False
+        # Wake all pending requests so callers fail fast instead of hanging.
+        self._fail_pending(reason)
+
+        if self._reconnect_attempts == 0:
+            return
+
+        raise CTraderReconnectAbandonedError(reason, cause) from cause
 
     def _fail_pending(self, reason: str) -> None:
         """Resolve every in-flight request with a connection error."""
@@ -511,27 +594,35 @@ class Protocol:
     async def _reconnect(self) -> None:
         """Attempt reconnection with exponential backoff.
 
+        Retries on *any* failure rather than on an enumerated set of exception
+        types. The budget exists to outlast a server that cannot be reached,
+        and an unrecognised exception is no evidence that it can be: a
+        whitelist here meant an exception nobody had thought of skipped the
+        retries entirely and went straight to being fatal.
+
         Raises:
-            CTraderConnectionClosedError: If reconnection is disabled or all attempts fail.
-            CTraderConnectionFailedError: If connection cannot be established.
+            CTraderConnectionClosedError: If reconnection is disabled.
+            CTraderConnectionFailedError: If every attempt in the budget failed.
         """
         if self._reconnect_attempts == 0:
             raise CTraderConnectionClosedError("Connection lost and reconnection disabled")
 
+        budget = "unlimited" if self._reconnect_attempts is None else self._reconnect_attempts
+
         async for attempt in AsyncRetrying(
-            stop=stop_after_attempt(self._reconnect_attempts),
+            stop=stop_never if self._reconnect_attempts is None else 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),
+            retry=retry_if_exception_type(Exception),
             reraise=True,
         ):
             with attempt:
                 logger.debug(
-                    "Reconnection attempt %d/%d",
+                    "Reconnection attempt %d/%s",
                     attempt.retry_state.attempt_number,
-                    self._reconnect_attempts,
+                    budget,
                 )
                 await self._transport.connect()