ctrader-api-client 0.7.1__tar.gz → 0.7.3__tar.gz

{ctrader_api_client-0.7.1 → ctrader_api_client-0.7.3}/.gitignore

@@ -12,6 +12,10 @@ wheels/
 # IDE-specific files
 .idea/
 .vscode/
+
 # Test artifacts
 .coverage
 .pytest_cache/
+
+# Built documentation
+site/

{ctrader_api_client-0.7.1 → ctrader_api_client-0.7.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ctrader-api-client
-Version: 0.7.1
+Version: 0.7.3
 Summary: API Client to interact with the cTrader Open API spec
 Author-email: Elio <elioachukri@pm.me>
 License-File: LICENSE

{ctrader_api_client-0.7.1 → ctrader_api_client-0.7.3}/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
@@ -161,10 +169,22 @@ drop. Check current authorization with `client.is_account_authorized(account_id)
 
 A disconnect the server reports is checked before it is published. Rotating an
 access token makes the server report one for a session it has not ended, so the
-client re-authenticates to find out which it is: an account that still holds its
-session is refused as already authorized, and nothing is published. What reaches
-a handler is therefore always a session that was really gone at the moment it
-was checked.
+client asks whether the account is still served on this connection: if it is,
+nothing is published. The check does not re-authenticate, because that answers
+for the token as much as for the session, and the rotation prompting the report
+is the very thing that would make such an answer unreliable.
+
+The check also waits for any token refresh on that account to finish first.
+Rotating a token means the server drops the old authorization and the client
+establishes a new one, and in between the account is genuinely unauthorized — it
+refuses everything, including the check. Since the refresh always begins before
+the report it provokes, waiting for it to settle is what keeps a moment the
+client itself created from reading as a lost session.
+
+A check that cannot be completed — a timeout, a link that has just gone — is not
+read as a disconnect either. The account is left as it was, and the next report
+is checked afresh. What reaches a handler is therefore always a session the
+server confirmed it was no longer serving.
 
 ::: ctrader_api_client.events.TokenInvalidatedEvent
     options:

{ctrader_api_client-0.7.1 → ctrader_api_client-0.7.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ctrader-api-client"
-version = "0.7.1"
+version = "0.7.3"
 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.1 → ctrader_api_client-0.7.3}/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")
 
@@ -104,14 +113,32 @@ class SessionRecovery:
         unauthorized and publish a drop that never occurred, so the report is
         checked against the server before anything acts on it.
 
-        Re-authenticating is the check: a session that is already live is
-        refused with `ALREADY_LOGGED_IN`, which says the report was spurious and
-        there is nothing to tell anyone. Any other answer means the session
-        really did end, and only then is the drop published and recovery armed.
+        Every report the server sends for a token rotation arrives while the
+        client is replacing that authorization, and for the length of that
+        replacement the account really is unauthorized: it answers nothing, and
+        asking it anything would only confirm a state the client is already
+        undoing. So the check waits for the refresh to settle before it asks.
+        The refresh always starts before the report it provokes, so there is no
+        ordering in which the report escapes the wait.
+
+        The check itself asks whether the account is still served on this link
+        rather than trying to re-authorize it, since re-authorizing answers for
+        the token as much as for the session.
+
+        A check that cannot be completed is not an answer of no. The account is
+        left as it was, because nothing has said the session ended.
 
         Args:
             account_id: The cTID trader account ID reported as disconnected.
         """
+        if self._store.is_refreshing(account_id):
+            logger.debug(
+                "Account %d was reported as disconnected while its token was being "
+                "refreshed; waiting for that to settle before checking",
+                account_id,
+            )
+            await self._store.wait_for_refresh(account_id)
+
         credentials = self._store.credentials(account_id)
         if credentials is None or not self._store.is_authorized(account_id):
             return
@@ -121,30 +148,36 @@ class SessionRecovery:
 
         self._verifying.add(account_id)
         try:
-            await self._authenticator.establish(credentials, AuthTrigger.ACCOUNT_REAUTH)
-        except AccountAuthError as e:
-            if e.is_already_authorized():
+            try:
+                alive = await self._authenticator.probe_session(account_id)
+            except Exception as e:
+                logger.debug(
+                    "Could not check the disconnect reported for account %d, leaving it as it is: %s",
+                    account_id,
+                    e,
+                )
+                return
+
+            if alive:
                 logger.debug(
                     "Account %d reported as disconnected still holds its session; ignoring",
                     account_id,
                 )
                 return
-            await self._report_dropped(account_id, e)
-        except Exception as e:
-            await self._report_dropped(account_id, e)
+
+            await self._report_dropped(account_id)
         finally:
             self._verifying.discard(account_id)
 
-    async def _report_dropped(self, account_id: int, error: Exception) -> None:
+    async def _report_dropped(self, account_id: int) -> None:
         """Publish a confirmed drop and arm recovery for it.
 
-        Reached once the server has refused to re-authorize the account, so the
-        session is genuinely gone and could not be re-established on the spot.
+        Reached once the server has stopped serving the account on this link, so
+        the session is genuinely gone.
         """
         logger.warning(
-            "Account %d disconnected by server; scheduling re-authentication: %s",
+            "Account %d disconnected by server; scheduling re-authentication",
             account_id,
-            error,
         )
         self._store.flag_for_recovery(account_id)
         self._reauth_signal.set()
@@ -157,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:
@@ -166,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...")
 
@@ -173,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,
@@ -204,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.
 
@@ -242,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
@@ -250,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.1 → ctrader_api_client-0.7.3}/src/ctrader_api_client/auth/_refresh.py

@@ -142,6 +142,11 @@ class TokenRefresher:
 
         last_error: Exception | None = None
 
+        # Held from before the request goes out until the account is authorized
+        # again, because the disconnect the server reports for the old token
+        # arrives inside that window and means nothing about the session.
+        self._store.begin_refresh(account_id)
+
         try:
             async for attempt in AsyncRetrying(
                 stop=stop_after_attempt(self._policy.retry_attempts),
@@ -198,6 +203,8 @@ class TokenRefresher:
             last_error = e
         except Exception as e:
             last_error = e
+        finally:
+            self._store.end_refresh(account_id)
 
         if last_error is not None:
             raise TokenRefreshError(account_id, last_error)

{ctrader_api_client-0.7.1 → ctrader_api_client-0.7.3}/src/ctrader_api_client/auth/_session.py

@@ -17,6 +17,8 @@ from __future__ import annotations
 from dataclasses import dataclass
 from typing import Protocol as TypingProtocol
 
+import anyio
+
 from ..enums import AuthTrigger
 from .credentials import AccountCredentials
 
@@ -77,6 +79,15 @@ class SessionAuthenticator(TypingProtocol):
         """Authorize an account, recording why so the right events follow."""
         ...
 
+    async def probe_session(self, account_id: int, timeout: float = 10.0) -> bool:
+        """Whether the account still holds a live session on this link.
+
+        Raises whatever stopped the question from being answered — including a
+        refusal that is about the token rather than the session — which is not
+        the same as an answer of no.
+        """
+        ...
+
 
 class SessionStore:
     """Every account the client knows about, keyed by cTID trader account ID.
@@ -90,6 +101,33 @@ class SessionStore:
     def __init__(self) -> None:
         self._accounts: dict[int, TrackedAccount] = {}
 
+        # Accounts whose authorization is being replaced by a token refresh.
+        # The server drops the old authorization as it issues the new pair, so
+        # for that stretch the account is genuinely unauthorized and answers
+        # nothing — a state no observer should mistake for a lost session.
+        self._refreshing: dict[int, anyio.Event] = {}
+
+    def begin_refresh(self, account_id: int) -> None:
+        """Note that the account's authorization is being replaced."""
+        if account_id not in self._refreshing:
+            self._refreshing[account_id] = anyio.Event()
+
+    def end_refresh(self, account_id: int) -> None:
+        """Note that it has been replaced, or that the attempt gave up."""
+        settled = self._refreshing.pop(account_id, None)
+        if settled is not None:
+            settled.set()
+
+    def is_refreshing(self, account_id: int) -> bool:
+        """Whether a refresh is currently replacing the account's authorization."""
+        return account_id in self._refreshing
+
+    async def wait_for_refresh(self, account_id: int) -> None:
+        """Wait until no refresh is replacing the account's authorization."""
+        settled = self._refreshing.get(account_id)
+        if settled is not None:
+            await settled.wait()
+
     def account_ids(self) -> list[int]:
         """Every account held, oldest first."""
         return list(self._accounts)

{ctrader_api_client-0.7.1 → ctrader_api_client-0.7.3}/src/ctrader_api_client/auth/manager.py

@@ -15,6 +15,8 @@ from .._internal.proto import (
     ProtoOAAccountAuthRes,
     ProtoOAApplicationAuthReq,
     ProtoOAApplicationAuthRes,
+    ProtoOATraderReq,
+    ProtoOATraderRes,
 )
 from ..enums import AuthTrigger
 from ..events import EventPublisher, ReadyEvent
@@ -238,6 +240,43 @@ class AuthManager:
                 await self._restorer.restore(credentials.account_id)
             await self._publisher.emit(ReadyEvent(account_id=credentials.account_id, trigger=trigger))
 
+    async def probe_session(self, account_id: int, timeout: float = 10.0) -> bool:
+        """Whether the account still holds a live session on this link.
+
+        Asks the server for something only an authorized account is told. The
+        request carries no access token of its own, but the authorization behind
+        it does: while a rotation is in flight the server refuses everything for
+        the account, including this. That refusal names the token, and it is
+        raised rather than answered, because it says nothing about the session.
+
+        Args:
+            account_id: The cTID trader account ID.
+            timeout: Request timeout in seconds.
+
+        Returns:
+            True if the server still serves the account on this link.
+
+        Raises:
+            APIError: If the refusal is about the token rather than the account.
+            CTraderConnectionTimeoutError: If the request times out.
+            CTraderConnectionClosedError: If the link is gone.
+        """
+        request = ProtoOATraderReq(ctid_trader_account_id=account_id)
+
+        try:
+            await self._protocol.request(request, ProtoOATraderRes, timeout=timeout)
+        except APIError as e:
+            logger.debug(
+                "Account %d was refused a trader lookup: %s (%s)",
+                account_id,
+                e.error_code,
+                e.description,
+            )
+            if e.is_token_failure():
+                raise
+            return False
+        return True
+
     def remove_account(self, account_id: int) -> bool:
         """Remove an account from refresh monitoring.
 

{ctrader_api_client-0.7.1 → ctrader_api_client-0.7.3}/src/ctrader_api_client/connection/protocol.py

@@ -109,6 +109,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 +449,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 +468,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,20 +495,44 @@ 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.
         """
         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
@@ -501,6 +545,7 @@ class Protocol:
             self._fail_pending("Reconnection error")
         finally:
             self._reconnecting = False
+            self._redo_requested = False
 
     def _fail_pending(self, reason: str) -> None:
         """Resolve every in-flight request with a connection error."""

{ctrader_api_client-0.7.1 → ctrader_api_client-0.7.3}/src/ctrader_api_client/connection/transport.py

@@ -104,7 +104,7 @@ class Transport:
                     await stream.aclose()
                 if close_scope.cancelled_caught:
                     logger.debug("Graceful TLS shutdown timed out, forcing close")
-            except (OSError, anyio.ClosedResourceError):
+            except (OSError, anyio.ClosedResourceError, anyio.BrokenResourceError):
                 pass
 
     async def send(self, data: bytes) -> None:

{ctrader_api_client-0.7.1 → ctrader_api_client-0.7.3}/src/ctrader_api_client/events/types.py

@@ -324,8 +324,14 @@ class ReconnectedEvent:
     Use this event for any custom logic that depends on reconnection, such as logging or alerting.
 
     Attributes:
-        app_auth_restored: Whether app authentication succeeded.
+        app_auth_restored: Whether app authentication succeeded on the attempt
+            this event reports. False is not final: the client keeps retrying
+            with backoff, and announces each account it restores afterwards with
+            a ReadyEvent. Check `client.auth.is_app_authenticated` for the
+            state now.
         restored_accounts: Account IDs that were successfully re-authenticated.
+            Empty when app authentication failed, since nothing can be
+            authorized before it succeeds — not a report that they were lost.
         failed_accounts: Accounts that failed, as (account_id, error_message) tuples.
     """