feat: WebSocket client v2 (ws_v2)

TESTING.md

@@ -0,0 +1,92 @@
+# Testing Guide
+
+This document defines how tests are chosen, written, and evaluated.
+
+---
+
+## Testing philosophy
+
+- Use commentary with `## Arrange` `## Act` and `## Assert` sections for test structure.
+- Tests exist to lock behaviour, not to chase coverage.
+- Avoid tests that duplicate what the language/runtime already guarantees.
+- Use fixtures for setup/teardown of test state.
+- Mock internal dependencies for unit tests. Mock external dependencies for integration tests.
+- Prefer integration tests for verifying component boundaries and data flow.
+- Capture and assert on logs for error and warning conditions.
+
+## Guidelines
+
+- When `time.time` is used, use `mock_module_time` from `test.test_utils` rather than waiting for the time to pass.
+
+
+## Test Type Structure
+
+Tests are organized into three main categories:
+
+```
+test/
+├── unit/         # Fast, isolated tests for core logic 
+├── integration/  # Multi-component tests 
+└── manual/       # Manual and performance tests 
+```
+
+
+## Test types and boundaries
+
+Use the lightest test type that still provides confidence.
+
+### Unit tests
+Use when:
+- logic is isolated and deterministic
+- behaviour can be validated without wiring other components
+
+Guidelines:
+- No network, filesystem, threads, or time dependence.
+- Mock only at clear boundaries; do not mock internals of the unit under test.
+- Data should be small, synthetic, and explicit.
+- Prefer clarity over clever parametrisation.
+
+### Integration tests
+Use when:
+- correctness depends on interaction between components
+- data flow or ordering matters
+
+Guidelines:
+- Mock only outside the test boundary (eg. broker, network).
+- Use realistic but minimal fixtures.
+- Allow threads/timers only if they are part of the behaviour being tested.
+- Failures should clearly indicate which interaction broke.
+
+### Manual / performance tests
+Use when:
+- validating full-system flows
+- measuring throughput, latency, or concurrency
+- interacting with real or near-real external systems
+
+Guidelines:
+- Never run automatically in CI.
+- Keep secrets out of test code.
+- Prefer recorded or replayable inputs where possible.
+- Treat results as diagnostic, not pass/fail gates.
+
+
+## Choosing what to test
+
+Test:
+- decision logic
+- state transitions
+- boundary conditions
+- error and warning paths
+- behaviour that has broken before
+
+Do not test:
+- trivial getters/setters
+- pure delegation
+- obvious library behaviour
+- formatting or logging text unless it signals correctness
+
+
+## Running tests
+
+- Prefer running the smallest relevant subset while iterating.
+- Run broader suites when touching core or high-risk code.

docs/websocket/core-concepts/events.md

@@ -0,0 +1,125 @@
+# Events
+
+Events in IBind WebSocket client are typed Pydantic dataclasses representing messages, errors, state changes and lifecycle updates, intended for consumption by the application code.
+
+There are several types of events:
+
+- Internal events - State changes, errors and subscription status updates.
+- IBKR unsolicited events - Messages received from the IBKR server without a topic subscription.
+- IBKR solicited events - Messages received from the IBKR server in response to a subscription request.
+- IBKR auxiliary events - Meta-messages derived from the IBKR messages. 
+
+
+## Event Consumption
+
+Events are automatically generated by the client and emitted using the Sink pattern. There are several built-in classes implementing the Sink protocol:
+
+- CallbackSink - Sink that invokes registered callbacks for specific event types.
+- QueueSink - Sink that stores events in separate queues per event type.
+- CompositeSink - Sink that forwards events to multiple child sinks. 
+- LogSink - Sink that logs events using the project logger.
+
+Example usage:
+
+```python
+from ibind import CallbackSink, events
+
+def on_market_data(event: events.MarketData):
+    print(event)
+
+sink = CallbackSink()
+sink.on(events.MarketData, on_market_data)
+```
+
+See [Sinks documentation][sinks] to learn more about event consumption.
+
+## Solicited and Unsolicited Messages
+_(from [IBKR Campus documentation](https://www.interactivebrokers.com/campus/ibkr-api-page/cpapi-v1/#ws-messages))_
+
+> There are two types of messages sent to clients via the websocket:
+> 
+> * **Solicited messages**: Messages delivered to the client in response to an explicit, client-initiated subscription to a topic.
+> * **Unsolicited messages**: Messages delivered automatically to the client by the server. These messages are not associated with a topic subscription that can be canceled, and they typically contain session or other administrative information.
+
+## Event Types
+
+### Base type
+
+`WsEvent` is the WebSocket event base class used by all events. 
+
+Each WsEvent contains a `received_at` field that records the date and time the event was received from the WebSocket.
+
+### Internal
+
+Events generated by the WebSocket client as a result of state changes, errors and subscription status updates.
+
+| Event Class           | Represents                          | Attributes                                                                                                                                                                     |
+|-----------------------|-------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `WsStarting`          | Connection is starting              | -                                                                                                                                                                              |
+| `WsStopping`          | Connection is stopping              | -                                                                                                                                                                              |
+| `WsStopped`           | Connection has stopped              | -                                                                                                                                                                              |
+| `WsOpen`              | Connection has successfully opened  | -                                                                                                                                                                              |
+| `WsAuthenticated`     | Connection is authenticated         | -                                                                                                                                                                              |
+| `WsDegraded`          | Connection entered a degraded state | -                                                                                                                                                                              |
+| `WsReady`             | Connection is ready for use         | -                                                                                                                                                                              |
+| `WsClose`             | Connection is closed                | <ul><li>`close_status_code` (int \| None): WebSocket close status code.</li><li>`close_msg` (str \| None): Close message.</li></ul>                                            |
+| `WsError`             | Error occurred                      | <ul><li>`error` (Exception): The exception that occurred.</li></ul>                                                                                                            |
+| `SubscriptionUpdated` | Subscription status changes         | <ul><li>`subscription` (Subscription): The subscription that changed.</li><li>`binding_key` (str): The binding key of the subscription.</li><li>`status` (BindingStatus): The new status of the subscription.</li></ul> |
+
+
+### IBKR Unsolicited
+
+Messages delivered automatically to the client by the server. These messages are not associated with a topic subscription that can be canceled, and they typically contain session or other administrative information.
+
+| Event Class            | Represents                         | Attributes |
+|------------------------|------------------------------------|-----------|
+| `IbkrError`            | An error message from IBKR         | <ul><li>`data` (dict): The raw error payload from IBKR.</li></ul> |
+| `WaitingForSession`    | Authentication is pending          | - |
+| `Notification`         | IBKR notification                  | <ul><li>`data` (dict): The notification payload.</li></ul> |
+| `Bulletin`             | IBKR bulletin                      | <ul><li>`data` (dict): The bulletin payload.</li></ul> |
+| `AccountUpdate`        | Details of the current account     | <ul><li>`data` (dict): The account update payload.</li></ul> |
+| `System`               | Connection confirmations           | <ul><li>`data` (dict): The system message payload.</li></ul> |
+| `AuthenticationStatus` | Session authentication status change | <ul><li>`data` (dict): The raw status payload.</li><li>`authenticated` (bool \| None): Whether the session is authenticated.</li><li>`competing` (bool \| None): Whether another session is competing for the same account.</li></ul> |
+
+### IBKR Solicited
+
+Messages delivered to the client in response to an explicit, client-initiated subscription to a topic.
+
+See [IBKR WebSocket documentation][ibkr-websocket] for exact payload format.
+
+| Event Class      | Represents                       | Attributes                                                                                                                                                                                                                                                                |
+|------------------|----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `AccountSummary` | Account summary messages         | <ul><li>`account_id` (str): The account the summary belongs to.</li><li>`data` (dict): The account summary payload.</li></ul>                                                                                                                                            |
+| `AccountLedger`  | Account ledger messages          | <ul><li>`account_id` (str): The account the ledger entry belongs to.</li><li>`data` (dict): The ledger payload.</li></ul>                                                                                                                                                |
+| `MarketData`     | Update to market data            | <ul><li>`conid` (str): The contract identifier the update applies to.</li><li>`data` (dict): The changed market data fields.</li></ul>                                                                                                              |
+| `MarketHistory`  | Historical OHLC bar              | <ul><li>`conid` (str): The contract identifier the bars apply to.</li><li>`data` (dict): The historical bar payload.</li></ul>                                                                                                                                           |
+| `Orders`         | Live order updates               | <ul><li>`data` (dict): The order update payload.</li></ul>                                                                                                                                                                                                               |
+| `PriceLadder`    | BookTrader price ladder data     | <ul><li>`account_id` (str): The account the ladder is requested for.</li><li>`conid` (str): The contract identifier the ladder applies to.</li><li>`exchange` (str): The exchange the ladder is sourced from.</li><li>`data` (dict): The price ladder payload.</li></ul> |
+| `Pnl`            | Live profit and loss information | <ul><li>`data` (dict): The profit and loss payload.</li></ul>                                                                                                                                                                                                            |
+| `Trades`         | Trade took place                 | <ul><li>`data` (dict): The trade payload.</li></ul>                                                                                                                                                                                                                      |
+
+### IBKR Auxiliary
+
+Auxiliary messages from IBKR.
+
+| Event Class        | Represents                             | Attributes |
+|--------------------|----------------------------------------|-----------|
+| `GenericIbkrEvent` | Uncategorised IBKR message             | <ul><li>`message` (dict \| None): The full raw message as received from IBKR.</li><li>`topic` (str \| None): The message topic, if one was present.</li><li>`data` (dict \| None): The message arguments, if any were extracted.</li></ul> |
+| `ServerId`         | Server ID extracted for Market History | <ul><li>`target_event_type` (type[IbkrTopicEvent]): The topic event the server ID belongs to.</li><li>`conid` (str): The contract identifier mapped to the server ID.</li><li>`server_id` (str): The server ID assigned by IBKR.</li></ul> |
+| `Unsubscription`   | Explicit unsubscription confirmation   | <ul><li>`target_event_type` (type[IbkrTopicEvent]): The topic event that was unsubscribed.</li><li>`conid` (str \| None): The contract identifier when the subscription was contract-specific, otherwise None.</li></ul> |
+
+
+## <a name="internal-event-systems"></a> Internal Event Systems
+
+There are two distinct event systems in the WebSocket client:
+
+- TransportEvents - private transport events, facilitating the `WebSocket -> transport -> runtime` communication. These are never propagated outside of the internal transport queue.
+- WsEvents - main events that can be consumed by sinks, such as in reaction to data received from the server or indicating lifecycle changes.
+
+Note that everywhere in this documentation the word "event" is used, it refers to `WsEvents`. The TransportEvents are private and should be opaque to the external code.
+
+
+[sinks]: ./sinks.md
+[subscriptions]: ./subscriptions.md
+
+[ibkr-websocket]: https://www.interactivebrokers.com/campus/ibkr-api-page/cpapi-v1/#websockets