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

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

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

@@ -159,6 +159,13 @@ 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 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.
+
 ::: ctrader_api_client.events.TokenInvalidatedEvent
     options:
       show_source: false

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

@@ -1,6 +1,6 @@
 [project]
 name = "ctrader-api-client"
-version = "0.7.0"
+version = "0.7.1"
 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.1}/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,60 @@ 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.
 
-        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.
+        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.
 
         Args:
             account_id: The cTID trader account ID reported as disconnected.
         """
-        if not self._store.flag_for_recovery(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:
+            await self._authenticator.establish(credentials, AuthTrigger.ACCOUNT_REAUTH)
+        except AccountAuthError as e:
+            if e.is_already_authorized():
+                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)
+        finally:
+            self._verifying.discard(account_id)
+
+    async def _report_dropped(self, account_id: int, error: Exception) -> 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.
+        """
         logger.warning(
-            "Account %d disconnected by server; scheduling re-authentication",
+            "Account %d disconnected by server; scheduling re-authentication: %s",
             account_id,
+            error,
         )
+        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 +270,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.1}/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.1}/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.1}/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."""

{ctrader_api_client-0.7.0 → ctrader_api_client-0.7.1}/tests/behavior/auth/test_token_lifecycle.py

@@ -8,9 +8,9 @@ import betterproto
 import pytest
 
 from ctrader_api_client._internal.proto import ProtoOAAccountAuthReq, ProtoOARefreshTokenReq
-from ctrader_api_client.auth import AuthManager, ReauthPolicy
+from ctrader_api_client.auth import AuthManager, ReauthPolicy, SessionRecovery, SessionStore
 from ctrader_api_client.enums import AuthTrigger
-from ctrader_api_client.events import ReadyEvent, TokenRefreshFailedEvent
+from ctrader_api_client.events import AccountDisconnectEvent, ReadyEvent, TokenRefreshFailedEvent
 from ctrader_api_client.exceptions import APIError, TokenExpiredError
 
 from ...harness import ManualClock, RecordingPublisher, RecordingStore, StubProtocol, factories
@@ -292,17 +292,55 @@ async def test_a_transient_store_outage_recovers_on_the_next_check(
     assert protocol.sent_of(ProtoOAAccountAuthReq)[-1].access_token == "new-access-token"
 
 
-async def test_a_disconnected_account_stops_being_authorized(
+async def test_an_account_the_server_confirms_is_gone_stops_being_authorized(
     auth: AuthManager,
     monitors: Monitors,
     protocol: StubProtocol,
     clock: ManualClock,
+    publisher: RecordingPublisher,
 ) -> None:
-    await start_with_account(auth, protocol, clock, expires_in=PLENTY_OF_TIME)
+    """A report the server stands behind is a real drop, and is published as one."""
+    protocol.respond_in_sequence(
+        ProtoOAAccountAuthReq,
+        [factories.account_auth_res(), APIError(error_code="TEMPORARY")],
+    )
+    await auth.authenticate_trader(factories.credentials(expires_in=PLENTY_OF_TIME))
+    await clock.wait_for_sleepers(SLEEPERS_WHEN_STARTED)
 
-    monitors.recovery.handle_account_disconnect(factories.ACCOUNT_ID)
+    await monitors.recovery.handle_account_disconnect(factories.ACCOUNT_ID)
 
     assert not auth.is_account_authorized(factories.ACCOUNT_ID)
+    assert publisher.of(AccountDisconnectEvent) == [AccountDisconnectEvent(factories.ACCOUNT_ID)]
+
+
+async def test_a_session_the_server_still_holds_is_left_alone(
+    auth: AuthManager,
+    monitors: Monitors,
+    protocol: StubProtocol,
+    clock: ManualClock,
+    publisher: RecordingPublisher,
+) -> None:
+    """A token rotation makes the server report a disconnect it did not perform.
+
+    Regression guard: taking that report at face value marked a working account
+    unauthorized, published a drop that never happened, and left recovery
+    retrying an account the server would only ever refuse as already logged in.
+    """
+    protocol.respond_in_sequence(
+        ProtoOAAccountAuthReq,
+        [
+            factories.account_auth_res(),
+            APIError(error_code="ALREADY_LOGGED_IN", description="Trading account is already authorized"),
+        ],
+    )
+    await auth.authenticate_trader(factories.credentials(expires_in=PLENTY_OF_TIME))
+    await clock.wait_for_sleepers(SLEEPERS_WHEN_STARTED)
+
+    await monitors.recovery.handle_account_disconnect(factories.ACCOUNT_ID)
+
+    assert auth.is_account_authorized(factories.ACCOUNT_ID)
+    assert publisher.of(AccountDisconnectEvent) == []
+    assert publisher.of(ReadyEvent) == [ReadyEvent(factories.ACCOUNT_ID, AuthTrigger.INITIAL)]
 
 
 async def test_a_disconnected_account_is_re_authenticated(
@@ -314,7 +352,7 @@ async def test_a_disconnected_account_is_re_authenticated(
 ) -> None:
     await start_with_account(auth, protocol, clock, expires_in=PLENTY_OF_TIME)
 
-    monitors.recovery.handle_account_disconnect(factories.ACCOUNT_ID)
+    await monitors.recovery.handle_account_disconnect(factories.ACCOUNT_ID)
     await publisher.wait_for_type(ReadyEvent, count=2)
 
     assert auth.is_account_authorized(factories.ACCOUNT_ID)
@@ -332,6 +370,8 @@ async def test_recovery_keeps_trying_after_a_failure(
         ProtoOAAccountAuthReq,
         [
             factories.account_auth_res(),
+            # The check that confirms the drop, then the first retry after it.
+            APIError(error_code="TEMPORARY"),
             APIError(error_code="TEMPORARY"),
             factories.account_auth_res(),
         ],
@@ -339,7 +379,7 @@ async def test_recovery_keeps_trying_after_a_failure(
     await auth.authenticate_trader(factories.credentials(expires_in=PLENTY_OF_TIME))
     await clock.wait_for_sleepers(SLEEPERS_WHEN_STARTED)
 
-    monitors.recovery.handle_account_disconnect(factories.ACCOUNT_ID)
+    await monitors.recovery.handle_account_disconnect(factories.ACCOUNT_ID)
     # The failed attempt arms a backoff; time has to move for the retry.
     await clock.wait_for_sleepers(SLEEPERS_WHEN_STARTED + 1)
     await clock.advance(1.0)
@@ -372,12 +412,11 @@ async def test_an_account_dropped_during_another_backoff_is_recovered_at_once(
 
     protocol.respond_with(ProtoOAAccountAuthReq, answer)
 
-    monitors.recovery.handle_account_disconnect(stubborn)
+    await monitors.recovery.handle_account_disconnect(stubborn)
     # Its failed attempt parks recovery on a ten second backoff.
     await clock.wait_for_sleepers(SLEEPERS_WHEN_STARTED + 1)
 
-    monitors.recovery.handle_account_disconnect(healthy)
-    await protocol.wait_for_sent(ProtoOAAccountAuthReq, count=4)
+    await monitors.recovery.handle_account_disconnect(healthy)
 
     assert auth.is_account_authorized(healthy)
     assert not auth.is_account_authorized(stubborn)
@@ -391,26 +430,36 @@ async def test_a_disconnect_for_an_unknown_account_is_ignored(
 ) -> None:
     await start_with_account(auth, protocol, clock, expires_in=PLENTY_OF_TIME)
 
-    monitors.recovery.handle_account_disconnect(999_999)
+    await monitors.recovery.handle_account_disconnect(999_999)
     await clock.wait_for_sleepers(SLEEPERS_WHEN_STARTED)
 
     assert len(protocol.sent_of(ProtoOAAccountAuthReq)) == 1
     assert auth.is_account_authorized(factories.ACCOUNT_ID)
 
 
-async def test_repeated_disconnect_reports_do_not_stack_up_recoveries(
+async def test_a_report_for_an_account_already_recovering_is_not_checked_again(
     auth: AuthManager,
-    monitors: Monitors,
     protocol: StubProtocol,
-    clock: ManualClock,
     publisher: RecordingPublisher,
+    sessions: SessionStore,
+    clock: ManualClock,
 ) -> None:
-    await start_with_account(auth, protocol, clock, expires_in=PLENTY_OF_TIME)
+    """Once a drop is confirmed, further reports say nothing the queue does not.
 
-    monitors.recovery.handle_account_disconnect(factories.ACCOUNT_ID)
-    monitors.recovery.handle_account_disconnect(factories.ACCOUNT_ID)
-    monitors.recovery.handle_account_disconnect(factories.ACCOUNT_ID)
-    await publisher.wait_for_type(ReadyEvent, count=2)
-    await clock.wait_for_sleepers(SLEEPERS_WHEN_STARTED)
+    The monitor is not served here: recovery's own retries would be
+    indistinguishable from a second check of the same report.
+    """
+    recovery = SessionRecovery(store=sessions, authenticator=auth, publisher=publisher, clock=clock)
+    protocol.respond_in_sequence(
+        ProtoOAAccountAuthReq,
+        [factories.account_auth_res(), APIError(error_code="TEMPORARY")],
+    )
+    await auth.authenticate_trader(factories.credentials(expires_in=PLENTY_OF_TIME))
+
+    await recovery.handle_account_disconnect(factories.ACCOUNT_ID)
+    checked = len(protocol.sent_of(ProtoOAAccountAuthReq))
+    await recovery.handle_account_disconnect(factories.ACCOUNT_ID)
+    await recovery.handle_account_disconnect(factories.ACCOUNT_ID)
 
-    assert len(protocol.sent_of(ProtoOAAccountAuthReq)) == 2
+    assert len(protocol.sent_of(ProtoOAAccountAuthReq)) == checked
+    assert publisher.of(AccountDisconnectEvent) == [AccountDisconnectEvent(factories.ACCOUNT_ID)]

{ctrader_api_client-0.7.0 → ctrader_api_client-0.7.1}/tests/behavior/events/test_routing.py

@@ -542,16 +542,17 @@ async def test_a_client_disconnect_carries_its_reason(
     assert received.only.reason == "Maintenance"
 
 
-async def test_an_account_disconnect_names_the_account(
+async def test_an_account_disconnect_is_not_published_by_the_router(
     routing: EventEmitter,
     protocol: StubProtocol,
 ) -> None:
+    """The report is unverified here; recovery publishes the ones that hold up."""
     received: Recorder[AccountDisconnectEvent] = Recorder()
     routing.subscribe(AccountDisconnectEvent, received)
 
     await protocol.emit(ProtoOAAccountDisconnectEvent(ctid_trader_account_id=factories.ACCOUNT_ID))
 
-    assert received.only.account_id == factories.ACCOUNT_ID
+    assert received.count == 0
 
 
 @pytest.mark.usefixtures("routing")

{ctrader_api_client-0.7.0 → ctrader_api_client-0.7.1}/tests/behavior/test_client.py

@@ -17,6 +17,7 @@ from ctrader_api_client._internal.proto import (
 )
 from ctrader_api_client.auth import AccountCredentials
 from ctrader_api_client.events import (
+    AccountDisconnectEvent,
     ReadyEvent,
     ReconnectedEvent,
     SpotEvent,
@@ -49,6 +50,14 @@ def rejecting(_request: betterproto.Message) -> betterproto.Message:
     return factories.error_res(error_code="ACCOUNT_NOT_AUTHORIZED")
 
 
+def already_logged_in(_request: betterproto.Message) -> betterproto.Message:
+    """Refuse the way the server refuses an account whose session is still live."""
+    return factories.error_res(
+        error_code="ALREADY_LOGGED_IN",
+        description="Trading account is already authorized in this channel",
+    )
+
+
 # -----------------------------------------------------------------------------
 # Lifecycle
 # -----------------------------------------------------------------------------
@@ -387,15 +396,39 @@ async def test_a_dropped_account_stays_unauthorized_until_recovery_succeeds(
     server: FakeServer,
 ) -> None:
     await authenticate(client, server)
+    dropped: Recorder[AccountDisconnectEvent] = Recorder()
+    client.register_handler(AccountDisconnectEvent, dropped)
     server.on(ProtoOAAccountAuthReq, rejecting)
 
     await server.push(ProtoOAAccountDisconnectEvent(ctid_trader_account_id=factories.ACCOUNT_ID))
-    await server.wait_for_request(ProtoOAAccountAuthReq, count=2)
+    # The drop is published once the server has confirmed it, which is also when
+    # the account stops counting as authorized.
+    await dropped.wait_for(1)
 
     assert client.is_account_authorized(factories.ACCOUNT_ID) is False
     assert client.is_connected is True
 
 
+async def test_a_disconnect_the_server_does_not_stand_behind_is_not_published(
+    client: CTraderClient,
+    server: FakeServer,
+) -> None:
+    """A token rotation makes the server report a disconnect it did not perform."""
+    await authenticate(client, server)
+    dropped: Recorder[AccountDisconnectEvent] = Recorder()
+    ready: Recorder[ReadyEvent] = Recorder()
+    client.register_handler(AccountDisconnectEvent, dropped)
+    client.register_handler(ReadyEvent, ready)
+    server.on(ProtoOAAccountAuthReq, already_logged_in)
+
+    await server.push(ProtoOAAccountDisconnectEvent(ctid_trader_account_id=factories.ACCOUNT_ID))
+    await server.wait_for_request(ProtoOAAccountAuthReq, count=2)
+
+    assert dropped.count == 0
+    assert ready.count == 0
+    assert client.is_account_authorized(factories.ACCOUNT_ID) is True
+
+
 # -----------------------------------------------------------------------------
 # Token refresh
 # -----------------------------------------------------------------------------

{ctrader_api_client-0.7.0 → ctrader_api_client-0.7.1}/tests/harness/recorder.py

@@ -133,7 +133,7 @@ class RecordingRecovery:
     def __init__(self) -> None:
         self.disconnected: list[int] = []
 
-    def handle_account_disconnect(self, account_id: int) -> None:
+    async def handle_account_disconnect(self, account_id: int) -> None:
         """Record the disconnected account."""
         self.disconnected.append(account_id)
 

{ctrader_api_client-0.7.0 → ctrader_api_client-0.7.1}/uv.lock

@@ -270,7 +270,7 @@ wheels = [
 
 [[package]]
 name = "ctrader-api-client"
-version = "0.7.0"
+version = "0.7.1"
 source = { editable = "." }
 dependencies = [
     { name = "anyio" },

ctrader_api_client-0.7.0/HARDENING.md

@@ -1,251 +0,0 @@
-# Architecture hardening
-
-Working notes for the `harden-architecture` branch. Everything below is against
-`master` at `8f649f2`.
-
-## Done
-
-Each item is one commit, in order.
-
-### Connection and auth lifecycle tests — `de41c4d`
-
-Edge cases the existing suite did not reach, added before any of the
-refactoring below so the refactoring had something to fail against: framing,
-reconnection, token lifecycle and client startup.
-
-### Typed request correlation — `bb66230`
-
-`Protocol` tracked in-flight requests across three parallel dicts keyed by
-message id. They could disagree. Replaced by a single object holding the event,
-the outcome and the expected response type, so a pending request is one thing
-that either exists or does not.
-
-### Event handler registration — `4131424`
-
-Registering a handler and unregistering it were written out separately at every
-call site. `on_event` now returns a disposer, and callers hold that instead of
-remembering how to undo their own registration.
-
-### Pluggable token storage — `b6dc7df`
-
-Added the `TokenStore` protocol and the option to pass one to the client. The
-client writes through it whenever tokens rotate, so a process that restarts can
-pick up where it left off rather than re-authenticating from credentials.
-
-Two things moved in passing, both breaking:
-
-- `AuthTrigger` moved from `auth/trigger.py`, which is gone, to `enums.py`. It
-  describes why a session was established, which the event types need and the
-  auth package should not own alone.
-- `ReadyEvent.is_reconnect` is now a property over a `trigger: AuthTrigger`
-  field. Reading it is unchanged; constructing a `ReadyEvent` is not.
-
-### Dead code and a start() guard — `de21183`
-
-Removed `on_handler_error()`, which nothing called. Made
-`HeartbeatManager.start()` idempotent: a second call used to overwrite the
-nursery reference and leave the first loop unreachable, so `stop()` could never
-find it.
-
-### Automatic subscription restore — `e0a3273`
-
-Subscriptions were restored by an explicit call after reconnection, which meant
-every reconnection path had to remember to make it. `MarketDataAPI` is now
-registered as a restorer and the reconnect path drives it.
-
-### TokenStore documentation — `2f17ac3`
-
-No code change. `TokenStore` is write-only by design — the library never reads
-it back, because only the caller knows which accounts a given process is
-responsible for. The name suggested otherwise, so the docstrings, the README
-example and `docs/api/client.md` now say so and show the startup branch the
-caller is expected to write.
-
-Deliberately **not** done: adding `load()` to the protocol. The library would
-have no reason to call it.
-
-### Composition root — `b3e6fb5`
-
-`CTraderClient.__init__` built eleven collaborators and wired them together,
-which made the client impossible to construct with a substitute for any one of
-them. That wiring moved verbatim to `composition.py` as `build_graph()`
-returning a frozen `ClientGraph`, and `CTraderClient.from_graph()` adopts one.
-
-Two ordering constraints in the wiring are load-bearing and are noted in the
-source: market data is built before auth because it is the restorer, and auth
-before the router because it is the recovery.
-
-Deliberately **not** done: a `build_client()` convenience wrapper.
-`build_graph` plus `from_graph` already covers it.
-
-### Lifecycle inversion — `bd92f44` — **breaking**
-
-`Protocol`, `HeartbeatManager` and `AuthManager` each held a task group handed
-to them by a `start()` call and exited by a later `stop()` call from a different
-task. `start()` replaced by `serve()`, which owns its nursery lexically and
-suspends inside it; `stop()` reduced to cancelling the scope, which is allowed
-from any task.
-
-`CTraderClient.connect()` and `.close()` are **gone**. `async with client:` is
-the only way to bring a client up. The nursery lives in the `async with` block,
-so a background loop that dies is raised out of it rather than discovered at
-shutdown.
-
-Three things fell out of this:
-
-- Every `except Exception: pass` in a `stop()` is gone; there is nothing left
-  to swallow.
-- Cleanup moved into each `serve()`'s `finally`, so cancellation now cleans up
-  as thoroughly as an orderly stop.
-- `task_group.start` rather than `start_soon` in the client means the reader is
-  provably live before anything is sent. That ordering used to be implicit.
-
-Test-side, `connected` and `serving` fixtures give the *test* ownership of the
-task group, for the same reason: a loop that dies mid-test surfaces at the end
-of it instead of vanishing.
-
-### B1 — connection supervisor — `9df080b` — **breaking**
-
-`Protocol` reported drops and recoveries through two callbacks the client set
-on it by hand, and `CTraderClient._lifecycle` knew the order transport,
-protocol, heartbeat and auth had to come up in. Both are gone.
-
-`ConnectionSupervisor` owns the transport, the protocol and the heartbeat.
-`serving()` is an async context manager rather than a `serve()`: connecting
-happens before the block is entered, so a server that is not there still raises
-`CTraderConnectionFailedError` instead of the `ExceptionGroup` a task group
-would make of it. `_lifecycle` is now the supervisor's block with auth and the
-router inside it.
-
-The callbacks became one port. `ConnectionListener` — `on_connection_lost` and
-`on_connection_restored` — is what `Protocol` reports to and what the
-supervisor fans out to. The supervisor puts the heartbeat back itself before
-notifying, because that is its own machinery rather than a listener's concern.
-
-The listener is `AuthManager`, not the client. Re-authenticating the
-application and every account after a reconnect, and reporting the outcome as
-`ReconnectedEvent`, is session work; it only lived on the client because the
-callback did. That takes ~70 lines off `client.py`, and puts the logic where
-B3's `SessionRecovery` would want it.
-
-Breaking: `Protocol.set_reconnect_handler` and `set_disconnect_handler` are
-replaced by `Protocol.set_listener`, and `AuthManager.handle_connection_lost`
-is now the private `_forget_sessions`, reached through the port.
-
-Test-side, a `make_graph` fixture hands tests the graph before the client
-adopts it, which is how the listener fan-out is exercised.
-
-### Exception shape at the client boundary — `ff6137a`
-
-Found while placing automatic application authentication. Since the lifecycle
-inversion, the task group holding the background tasks surrounds the `yield` in
-`_lifecycle`, so *every* exception leaving `async with client:` passed through
-it — and anyio wraps a lone exception as readily as a group. A caller's own
-`ValueError` came back as `ExceptionGroup: unhandled errors in a TaskGroup (1
-sub-exception)`, and `except CTraderConnectionFailedError` would have stopped
-matching anything the machinery raised.
-
-`__aenter__` and `__aexit__` now peel single-exception groups, recursively,
-since the supervisor's task group nests inside the client's. Several failures
-still arrive as a group, because that is what they are, and the block's own
-exception is returned to the caller untouched rather than re-raised.
-
-Not a break against `master`: this restores the shape callers had before the
-branch.
-
-### B3 — split AuthManager — `651da82` — **breaking**
-
-`auth/manager.py` was 751 lines doing four unrelated jobs. It is now four
-pieces, each with one:
-
-- `auth/_session.py` — `SessionStore`, joining the session state types already
-  there. It owns the dict, its invalidation and every query over it, so the
-  distinction between credentials (which outlive a link) and sessions (which do
-  not) is stated once instead of being re-derived by each collaborator.
-- `auth/_refresh.py` — `TokenRefresher`, the refresh loop, its retry policy and
-  the `TokenStore` write-through.
-- `auth/_recovery.py` — `SessionRecovery`, the reauth loop and the
-  `ConnectionListener` methods. It is also the `SessionRecovery` port the event
-  router already typed its collaborator as, so the names finally line up.
-- `auth/manager.py` — `AuthManager`, down to turning credentials into live
-  sessions.
-
-The refresher and the recovery monitor each serve themselves, so `_lifecycle`
-starts two tasks where it started one, and `AuthManager` no longer has a
-lifecycle of its own.
-
-The public surface was cut at the same time, on the rule that nothing returning
-a bare `ProtoOA` message should be public:
-
-- `authenticate_app` is called by the client as it connects, and on every
-  reconnect. A client that cannot authenticate does not open, and the failure
-  arrives as `ApplicationAuthError` thanks to the unwrapping above.
-- `authenticate_account` became `authenticate_trader`, returning nothing. The
-  `trigger` argument moved to the internal `establish`, where the refresher and
-  the recovery monitor use it.
-- `get_accounts` and `resolve_account_id` moved to `AccountsAPI` as
-  `list_by_token` and `resolve_account_id`. They are account queries, not auth.
-- `authenticate_by_trader_login` is gone with no replacement. Resolving a login
-  and authenticating an account are two steps, and the convenience of joining
-  them cost a second way to do the same thing:
-  `await client.auth.authenticate_trader(await store.load(account_id))` is now
-  the only shape, restart or not.
-
-`APIError.is_token_failure()` replaces the module-level helper, since three
-modules now need to ask.
-
-### Flat public surface — `6cc397c`
-
-The package exported `CTraderClient`, `ClientConfig` and seven of the fourteen
-enums "for easier access". The seven were an arbitrary subset: a caller reading
-`order.status`, `order.time_in_force`, `deal.status`, `symbol.trading_mode` or
-`account.access_rights` had to switch to `ctrader_api_client.enums` halfway down
-the file. `AccountCredentials`, the one type nobody can avoid constructing, sat
-two modules deep.
-
-The top level now carries what a caller names — what you construct, what you
-receive, what you catch — and the subpackages keep what the composition root
-wires. Sixty-eight names: the client and its config, the credentials and the two
-policies and the `TokenStore` protocol, every enum, every model, every event
-type, every exception. `AuthManager`, `SessionStore`, `TokenRefresher`,
-`SessionRecovery`, the emitter/publisher/router and everything under `api/`,
-`connection/` and `_internal/` stay where they are, since the client hands them
-to you already assembled.
-
-The result models are exported despite `Account`, `Order`, `Position`, `Symbol`
-and `Event` being names a trading codebase may well use itself. A name you
-receive is a name you annotate, and `import ctrader_api_client as ct` is there
-for anyone with a conflict.
-
-Additive: the subpackage paths still work. Importing costs nothing extra either,
-since `from .client import CTraderClient` already pulled the whole graph in.
-
-The `Environment` enum was deleted in passing — declared, documented, and
-referenced nowhere. `ClientConfig` takes a `host` string.
-
-## Open
-
-### Version bump and changelog
-
-The lifecycle inversion removes `connect()` and `close()` from the public API,
-and the connection supervisor replaces `Protocol.set_reconnect_handler` /
-`set_disconnect_handler` with `set_listener` and drops
-`AuthManager.handle_connection_lost`. The AuthManager split then removes
-`authenticate_app`, `authenticate_account`, `authenticate_by_trader_login`,
-`get_accounts` and `resolve_account_id` from `client.auth`, adding
-`authenticate_trader` in their place and moving the two queries to
-`client.accounts`. The `TokenStore` commit moved `AuthTrigger` out of
-`auth.trigger` into `enums`, and turned `ReadyEvent.is_reconnect` into a
-property over a new `trigger` field, which breaks anyone constructing the event
-themselves. This needs a bump from `0.6.0` and a note saying so.
-
-The flat surface is additive and breaks nobody, but the `Environment` enum it
-deleted was public, so it belongs in the same note. Nothing else on the branch
-breaks a caller.
-
-### Smaller things noticed but not acted on
-
-- `client.py` is down to 501 lines, nearly all delegation and docstrings.
-- `protocol.py` is 550 lines and does framing, correlation, dispatch and
-  reconnection. Splitting it was never discussed; noting it as an observation
-  rather than a proposal.