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

{ctrader_api_client-0.7.0 → ctrader_api_client-0.7.2}/.gitignore

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ctrader-api-client
-Version: 0.7.0
+Version: 0.7.2
 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.0 → ctrader_api_client-0.7.2}/docs/api/events.md

@@ -159,6 +159,25 @@ the existing connection with backoff and emits a `ReadyEvent` on success. The
 event is informational; subscribe to it only if you want to observe or log the
 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 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:
       show_source: false

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

@@ -1,6 +1,6 @@
 [project]
 name = "ctrader-api-client"
-version = "0.7.0"
+version = "0.7.2"
 description = "API Client to interact with the cTrader Open API spec"
 readme = "README.md"
 authors = [

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

@@ -14,7 +14,8 @@ import anyio.abc
 
 from .._internal import Clock, MonotonicClock
 from ..enums import AuthTrigger
-from ..events import EventPublisher, ReconnectedEvent
+from ..events import AccountDisconnectEvent, EventPublisher, ReadyEvent, ReconnectedEvent
+from ..exceptions import AccountAuthError
 from ._session import AwaitingRecovery, SessionAuthenticator, SessionStore
 from .policy import ReauthPolicy
 
@@ -55,6 +56,10 @@ class SessionRecovery:
         # Wakes the recovery monitor when an account needs re-authenticating
         self._reauth_signal = anyio.Event()
 
+        # Accounts whose reported disconnect is still being checked, so a
+        # repeated report does not start a second check against the server.
+        self._verifying: set[int] = set()
+
         self._task_scope: anyio.CancelScope | None = None
         self._running = False
 
@@ -90,24 +95,84 @@ class SessionRecovery:
         if self._task_scope is not None:
             self._task_scope.cancel()
 
-    def handle_account_disconnect(self, account_id: int) -> None:
-        """Handle a server-side account disconnect.
+    async def handle_account_disconnect(self, account_id: int) -> None:
+        """Establish whether a reported account disconnect actually happened.
+
+        The server reports a disconnect whenever the token behind an
+        authorization is rotated, even though the session on this channel is
+        untouched. Taking the report at face value would mark a working account
+        unauthorized and publish a drop that never occurred, so the report is
+        checked against the server before anything acts on it.
+
+        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.
 
-        Marks the account's session as no longer authorized and schedules
-        recovery re-authentication on the existing connection. Idempotent while
-        a recovery is already pending for the account.
+        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 not self._store.flag_for_recovery(account_id):
+        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
 
-        self._reauth_signal.set()
+        if account_id in self._verifying:
+            return
+
+        self._verifying.add(account_id)
+        try:
+            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)
+        finally:
+            self._verifying.discard(account_id)
+
+    async def _report_dropped(self, account_id: int) -> None:
+        """Publish a confirmed drop and arm recovery for it.
+
+        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",
             account_id,
         )
+        self._store.flag_for_recovery(account_id)
+        self._reauth_signal.set()
+        await self._publisher.emit(AccountDisconnectEvent(account_id=account_id))
 
     async def on_connection_lost(self) -> None:
         """Discard the sessions that died with the link.
@@ -229,6 +294,26 @@ class SessionRecovery:
             for account_id, credentials, state in due:
                 try:
                     await self._authenticator.establish(credentials, AuthTrigger.ACCOUNT_REAUTH)
+                except AccountAuthError as e:
+                    if not e.is_already_authorized():
+                        logger.warning(
+                            "Recovery re-authentication for account %d failed, will retry: %s",
+                            account_id,
+                            e,
+                        )
+                        self._defer_recovery(account_id, state)
+                        continue
+                    # The session came back by some other route between
+                    # attempts. Retrying could only be refused the same way, so
+                    # take the account as recovered and announce it, noting that
+                    # nothing re-applied the subscriptions the dead session took
+                    # with it.
+                    logger.warning(
+                        "Account %d holds a session again; its subscriptions were not re-applied",
+                        account_id,
+                    )
+                    self._store.authorize(credentials)
+                    await self._publisher.emit(ReadyEvent(account_id=account_id, trigger=AuthTrigger.ACCOUNT_REAUTH))
                 except Exception as e:
                     logger.warning(
                         "Recovery re-authentication for account %d failed, will retry: %s",

{ctrader_api_client-0.7.0 → ctrader_api_client-0.7.2}/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.0 → ctrader_api_client-0.7.2}/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.0 → ctrader_api_client-0.7.2}/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.0 → ctrader_api_client-0.7.2}/src/ctrader_api_client/events/router.py

@@ -27,7 +27,6 @@ from ..models import Trendbar
 from ._execution import execution_event_from_proto
 from .emitter import EventEmitter
 from .types import (
-    AccountDisconnectEvent,
     ClientDisconnectEvent,
     DepthEvent,
     DepthQuote,
@@ -52,8 +51,8 @@ logger = logging.getLogger(__name__)
 class SessionRecovery(TypingProtocol):
     """Whatever knows how to restore an account session the server dropped."""
 
-    def handle_account_disconnect(self, account_id: int) -> None:
-        """Schedule re-authentication for the disconnected account."""
+    async def handle_account_disconnect(self, account_id: int) -> None:
+        """Check the reported disconnect, then publish and recover a real one."""
         ...
 
 
@@ -276,13 +275,15 @@ class EventRouter:
         self,
         proto: ProtoOAAccountDisconnectEvent,
     ) -> None:
-        """Convert ProtoOAAccountDisconnectEvent to AccountDisconnectEvent."""
-        event = AccountDisconnectEvent(
-            account_id=proto.ctid_trader_account_id,
-        )
-        logger.warning("Account %d disconnected by server", event.account_id)
-        self._recovery.handle_account_disconnect(event.account_id)
-        await self._emitter.emit(event)
+        """Hand a reported account disconnect to recovery, which publishes it.
+
+        The server reports a disconnect on every token rotation, for a session
+        it has not actually ended, so the report is checked before anyone hears
+        about it. Recovery does that checking and emits `AccountDisconnectEvent`
+        only for a drop that turns out to be real.
+        """
+        logger.debug("Account %d reported as disconnected by server", proto.ctid_trader_account_id)
+        await self._recovery.handle_account_disconnect(proto.ctid_trader_account_id)
 
     async def _handle_symbol_changed(
         self,

{ctrader_api_client-0.7.0 → ctrader_api_client-0.7.2}/src/ctrader_api_client/events/types.py

@@ -238,11 +238,17 @@ class ClientDisconnectEvent:
 class AccountDisconnectEvent:
     """Account disconnect event.
 
-    Emitted when a specific account session is terminated by the server while
-    the underlying connection stays up. The client handles recovery
-    automatically: it re-authenticates the account on the existing connection
-    with backoff until it succeeds, then emits a ReadyEvent. This event is
-    informational; no user action is required to restore the session.
+    Emitted when an account's session has been terminated by the server while
+    the underlying connection stays up, and could not be re-established on the
+    spot. The client keeps re-authenticating on the existing connection with
+    backoff until it succeeds, then emits a ReadyEvent; no user action is
+    required to restore the session.
+
+    The server also reports a disconnect whenever the token behind an
+    authorization is rotated, for a session it has not actually ended. Those
+    reports are checked against the server and discarded, so they do not appear
+    here — every event published is a drop that outlived a re-authentication
+    attempt.
 
     Attributes:
         account_id: The cTID trader account ID.

{ctrader_api_client-0.7.0 → ctrader_api_client-0.7.2}/src/ctrader_api_client/exceptions.py

@@ -108,6 +108,15 @@ class AccountAuthError(AuthenticationError):
             message += f" - {description}"
         super().__init__(message)
 
+    def is_already_authorized(self) -> bool:
+        """Whether the account was rejected for holding a live session already.
+
+        The server refuses to authorize an account twice on one channel. A
+        caller that was trying to reach exactly that state has already reached
+        it, so this is a rejection worth reading as success.
+        """
+        return self.error_code == ProtoOAErrorCode.ALREADY_LOGGED_IN.name
+
 
 class TokenExpiredError(AuthenticationError):
     """Access token has expired."""