1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
//! Client for the cTrader Open API, which exchanges Protobuf messages over TLS.
//!
//! [`client::OpenApiClient`] is the entry point: it opens one connection, authorises the
//! application and its trading accounts on it, and carries every request. The other modules
//! hold the requests of one group each and the values they return.
//!
//! ```no_run
//! use ctrader_connector::common::config::ConfigurationOpenApi;
//! use ctrader_connector::open_api::client::OpenApiClient;
//! use ctrader_connector::open_api::symbols::SymbolsParams;
//!
//! # async fn run() -> Result<(), ctrader_connector::common::errors::ConnectorError> {
//! let client = OpenApiClient::connect(ConfigurationOpenApi::from_env()?).await?;
//! client.authorise_application().await?;
//! let account = client.accounts().await?[0].id;
//! client.authorise_account(account).await?;
//! let listed = client.symbols(SymbolsParams::new(account)).await?;
//! println!("{} symbols", listed.symbols.len());
//! client.shutdown().await;
//! # Ok(())
//! # }
//! ```
//!
//! # Configuration
//!
//! [`ConfigurationOpenApi`](crate::common::config::ConfigurationOpenApi) is built with
//! [`demo`](crate::common::config::ConfigurationOpenApi::demo),
//! [`live`](crate::common::config::ConfigurationOpenApi::live) or read from the environment
//! with [`from_env`](crate::common::config::ConfigurationOpenApi::from_env).
//!
//! | Variable | Builder option | Required | Default |
//! |---|---|---|---|
//! | `BROKER_CLIENT_ID` | `client_id` | yes | none |
//! | `BROKER_CLIENT_SECRET` | `client_secret` | yes | none |
//! | `BROKER_ACCESS_TOKEN` | `access_token` | yes | none |
//! | `BROKER_REFRESH_TOKEN` | `refresh_token` | no | none; a refresh then fails |
//! | `BROKER_ENVIRONMENT` | `demo()` or `live()` | no | `demo` |
//! | `BROKER_DEMO_HOST` | `host` | no | `demo.ctraderapi.com`; read for demo only |
//! | `BROKER_TOKEN_URL` | `token_url` | no | `https://connect.spotware.com/apps/token` |
//! | none | `host` | no | `live.ctraderapi.com` for live |
//! | none | `port` | no | 5035 |
//! | none | `timeout` | no | 10 s for one response |
//! | none | `retries` | no | 3 after a limit error |
//! | none | `backoff` | no | 1 s before the first retry |
//! | none | `reconnect_delay` | no | 5 s before the first attempt |
//!
//! An empty variable counts as absent. Secrets are held in types that do not print their
//! value.
//!
//! [`OpenApiClient::connect_with`](client::OpenApiClient::connect_with) also takes
//! [`ConnectionOptions`](connection::ConnectionOptions) for what the configuration does not
//! cover:
//!
//! | Option | Default |
//! |---|---|
//! | `heartbeat_interval` | 10 s |
//! | `inbound_timeout` | 75 s |
//! | `reconnect_attempts` | unlimited |
//! | `request_limit` | 50 per second |
//! | `historical_limit` | 5 per second |
//! | `command_capacity` | 64 requests waiting for the connection |
//! | `event_capacity` | 1024 events held for a reader |
//!
//! # Connection lifecycle
//!
//! One task owns the socket; see [`connection`] for the whole account.
//!
//! - Heartbeat: the task sends one whenever nothing was written for the heartbeat interval.
//! - Inbound silence: a server that sends nothing, not even its own heartbeat, for the
//! inbound timeout counts as lost, as does a write that does not complete in time.
//! - Reconnect: after a loss the requests in flight fail,
//! [`Event::Disconnected`](connection::Event::Disconnected) is reported and the task
//! connects again, waiting twice as long before every further attempt, up to a minute or
//! the configured delay when that is longer.
//! - Replay: once connected it authorises the application and the accounts again, restores
//! the subscriptions and reports [`Event::Reconnected`](connection::Event::Reconnected).
//! Requests made while the connection is down fail at once.
//! - Never sent again: orders. A request that trades is written at most once; it is neither
//! retried after a limit error nor replayed after a reconnection.
//! - [`OpenApiClient::shutdown`](client::OpenApiClient::shutdown) ends the task; later
//! requests fail with [`ConnectorError::Closed`](crate::common::errors::ConnectorError::Closed).
//!
//! # Error handling
//!
//! Every call returns [`ConnectorError`](crate::common::errors::ConnectorError).
//!
//! | Variant | Meaning | Reaction |
//! |---|---|---|
//! | `Config`, `Value` | Rejected before anything was sent. | Correct the input. |
//! | `Server` | The server refused; the error carries its code and text. | Decide by the code. |
//! | `Transport` | The connection failed or is down. | Wait for `Event::Reconnected`, then repeat a request that reads. |
//! | `Timeout` | No answer in time to a request that may be repeated. | Repeat it. |
//! | `OutcomeUnknown` | A request that trades was written and no answer came: the server may have acted on it. | Look the order up with [`reconcile`](client::OpenApiClient::reconcile) or by its label before placing it again. |
//! | `SessionEnded` | The server ended the authorisation of the account or the application. | Authorise again, see [`client`]; then subscribe again. |
//! | `Lagged` | A reader fell behind and events were dropped. | Go on reading; refresh the state from the server. |
//! | `Incomplete` | The server announced more history than it sent. | Treat the range the error names as missing: it cannot be asked for in smaller parts. |
//! | `Token` | A token refresh failed. | Obtain a new pair. |
//! | `Closed` | The client was shut down. | Connect anew. |
//!
//! # Streams
//!
//! The typed streams are each read with `next`. A subscription returns the first three of
//! them; the streams of executions and of margin events send no request and read what the
//! server reports for an authorised account:
//! [`QuoteStream`](quotes::QuoteStream), [`DepthStream`](depth::DepthStream),
//! [`TrendbarStream`](trendbars::TrendbarStream),
//! [`ExecutionStream`](executions::ExecutionStream) and
//! [`MarginStream`](margin::MarginStream).
//! [`OpenApiClient::events`](client::OpenApiClient::events) gives every event of the
//! connection untyped. Streams are bounded: a stream read too slowly loses its oldest events
//! and reports the loss once with `Lagged`, after which it goes on. Subscriptions are
//! restored after a reconnection, and a stream reports `SessionEnded` when the
//! authorisation of its account ends.
//!
//! # Rate limits
//!
//! The server accepts 50 requests per second on a connection and 5 per second for
//! historical data. The task holds requests back so that neither limit is exceeded. When
//! the server still answers that a limit was exceeded, the task pauses and sends the
//! request again, up to the configured number of retries, with a pause that doubles up to
//! thirty seconds, or up to the configured backoff when that is longer. Long ranges of bars
//! and ticks take several requests, each counted.
//!
//! # Logging
//!
//! With the `logging` feature the connection task emits `tracing` events at debug level:
//! connected, connection lost, reconnected, reconnection failed, replayed request failed,
//! authorisation ended and limit exceeded. They carry no secret. Without the feature nothing
//! is emitted and `tracing` is not compiled in. The application installs the subscriber.
//!
//! # Testing
//!
//! - Mock servers: the tests named `open_api_*_mock` and `open_api_mock` run against
//! scripted servers on the loopback interface, reached through
//! [`Plain`](crate::common::transport::Plain) and
//! [`connect_with`](client::OpenApiClient::connect_with). `open_api_clock_mock` runs over
//! a stream held in memory, on a paused clock. They need no credentials.
//! - Live tests: `open_api_live` refuses any environment but the demo one; the host is the
//! one the configuration names. It reads the variables of the table above and
//! `BROKER_ENV_FILE`, the absolute
//! path of a file that holds the token pair as `export BROKER_ACCESS_TOKEN=` and
//! `export BROKER_REFRESH_TOKEN=` lines.
//! - Token rotation: a refresh makes the old pair useless at once. The live test of the
//! refresh writes the new pair back to that file; a run that cannot write it loses the
//! pair, and a session opened with the old access token ends with `SessionEnded`.
//! - Live tests trade the smallest volume, label what they create and remove it afterwards.
//!
//! # Protocol facts
//!
//! - Prices travel as integers in 1/100000 of a unit and volumes in 0.01 of a unit; the
//! library takes and returns decimals in units, see [`crate::common::decimals`].
//! - Ticks: on the wire `toTimestamp` is exclusive. [`ticks`] takes a range with both ends
//! included and asks for one millisecond more.
//! - Bars: on the wire `toTimestamp` is inclusive; [`trendbars`] returns the bars that
//! overlap the range, oldest first, without the bar still forming.
//! - A stop-limit order is a stop price and a slippage in points, not two prices.
//! - An order at market takes its stop loss and take profit as distances from the fill
//! price; absolute prices are refused before anything is sent.
//! - A request that trades is answered by the first execution event for it, for an order at
//! market its acceptance; the fill follows on the [`executions`] stream.