nautilus_common/clients/
data.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
3//  https://nautechsystems.io
4//
5//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
6//  You may not use this file except in compliance with the License.
7//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
8//
9//  Unless required by applicable law or agreed to in writing, software
10//  distributed under the License is distributed on an "AS IS" BASIS,
11//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12//  See the License for the specific language governing permissions and
13//  limitations under the License.
14// -------------------------------------------------------------------------------------------------
15
16//! Data client trait definition.
17
18use async_trait::async_trait;
19use nautilus_model::identifiers::{ClientId, Venue};
20
21use super::log_not_implemented;
22use crate::messages::data::{
23    RequestBars, RequestBookDepth, RequestBookSnapshot, RequestCustomData, RequestInstrument,
24    RequestInstruments, RequestQuotes, RequestTrades, SubscribeBars, SubscribeBookDeltas,
25    SubscribeBookDepth10, SubscribeCustomData, SubscribeFundingRates, SubscribeIndexPrices,
26    SubscribeInstrument, SubscribeInstrumentClose, SubscribeInstrumentStatus, SubscribeInstruments,
27    SubscribeMarkPrices, SubscribeQuotes, SubscribeTrades, UnsubscribeBars, UnsubscribeBookDeltas,
28    UnsubscribeBookDepth10, UnsubscribeCustomData, UnsubscribeFundingRates, UnsubscribeIndexPrices,
29    UnsubscribeInstrument, UnsubscribeInstrumentClose, UnsubscribeInstrumentStatus,
30    UnsubscribeInstruments, UnsubscribeMarkPrices, UnsubscribeQuotes, UnsubscribeTrades,
31};
32#[cfg(feature = "defi")]
33use crate::messages::defi::{
34    RequestPoolSnapshot, SubscribeBlocks, SubscribePool, SubscribePoolFeeCollects,
35    SubscribePoolFlashEvents, SubscribePoolLiquidityUpdates, SubscribePoolSwaps, UnsubscribeBlocks,
36    UnsubscribePool, UnsubscribePoolFeeCollects, UnsubscribePoolFlashEvents,
37    UnsubscribePoolLiquidityUpdates, UnsubscribePoolSwaps,
38};
39
40/// Defines the interface for a data client, managing connections, subscriptions, and requests.
41///
42/// # Thread Safety
43///
44/// Client instances are not intended to be sent across threads. The `?Send` bound
45/// allows implementations to hold non-Send state for any Python interop.
46#[async_trait(?Send)]
47pub trait DataClient {
48    /// Returns the unique identifier for this data client.
49    fn client_id(&self) -> ClientId;
50
51    /// Returns the optional venue this client is associated with.
52    fn venue(&self) -> Option<Venue>;
53
54    /// Starts the data client.
55    ///
56    /// # Errors
57    ///
58    /// Returns an error if the operation fails.
59    fn start(&mut self) -> anyhow::Result<()>;
60
61    /// Stops the data client.
62    ///
63    /// # Errors
64    ///
65    /// Returns an error if the operation fails.
66    fn stop(&mut self) -> anyhow::Result<()>;
67
68    /// Resets the data client to its initial state.
69    ///
70    /// # Errors
71    ///
72    /// Returns an error if the operation fails.
73    fn reset(&mut self) -> anyhow::Result<()>;
74
75    /// Disposes of client resources and cleans up.
76    ///
77    /// # Errors
78    ///
79    /// Returns an error if the operation fails.
80    fn dispose(&mut self) -> anyhow::Result<()>;
81
82    /// Returns `true` if the client is currently connected.
83    fn is_connected(&self) -> bool;
84
85    /// Returns `true` if the client is currently disconnected.
86    fn is_disconnected(&self) -> bool;
87
88    /// Connects the client to the data provider.
89    ///
90    /// For live clients, this triggers the actual connection to external APIs.
91    /// For backtest clients, this is a no-op.
92    ///
93    /// # Errors
94    ///
95    /// Returns an error if the connection fails.
96    async fn connect(&mut self) -> anyhow::Result<()> {
97        Ok(())
98    }
99
100    /// Disconnects the client from the data provider.
101    ///
102    /// For live clients, this closes connections to external APIs.
103    /// For backtest clients, this is a no-op.
104    ///
105    /// # Errors
106    ///
107    /// Returns an error if the disconnection fails.
108    async fn disconnect(&mut self) -> anyhow::Result<()> {
109        Ok(())
110    }
111
112    /// Subscribes to custom data types according to the command.
113    ///
114    /// # Errors
115    ///
116    /// Returns an error if the subscribe operation fails.
117    fn subscribe(&mut self, cmd: &SubscribeCustomData) -> anyhow::Result<()> {
118        log_not_implemented(&cmd);
119        Ok(())
120    }
121
122    /// Subscribes to instruments list for the specified venue.
123    ///
124    /// # Errors
125    ///
126    /// Returns an error if the subscribe operation fails.
127    fn subscribe_instruments(&mut self, cmd: &SubscribeInstruments) -> anyhow::Result<()> {
128        log_not_implemented(&cmd);
129        Ok(())
130    }
131
132    /// Subscribes to data for a single instrument.
133    ///
134    /// # Errors
135    ///
136    /// Returns an error if the subscribe operation fails.
137    fn subscribe_instrument(&mut self, cmd: &SubscribeInstrument) -> anyhow::Result<()> {
138        log_not_implemented(&cmd);
139        Ok(())
140    }
141
142    /// Subscribes to order book delta updates for the specified instrument.
143    ///
144    /// # Errors
145    ///
146    /// Returns an error if the subscribe operation fails.
147    fn subscribe_book_deltas(&mut self, cmd: &SubscribeBookDeltas) -> anyhow::Result<()> {
148        log_not_implemented(&cmd);
149        Ok(())
150    }
151
152    /// Subscribes to top 10 order book depth updates for the specified instrument.
153    ///
154    /// # Errors
155    ///
156    /// Returns an error if the subscribe operation fails.
157    fn subscribe_book_depth10(&mut self, cmd: &SubscribeBookDepth10) -> anyhow::Result<()> {
158        log_not_implemented(&cmd);
159        Ok(())
160    }
161
162    /// Subscribes to quote updates for the specified instrument.
163    ///
164    /// # Errors
165    ///
166    /// Returns an error if the subscribe operation fails.
167    fn subscribe_quotes(&mut self, cmd: &SubscribeQuotes) -> anyhow::Result<()> {
168        log_not_implemented(&cmd);
169        Ok(())
170    }
171
172    /// Subscribes to trade updates for the specified instrument.
173    ///
174    /// # Errors
175    ///
176    /// Returns an error if the subscribe operation fails.
177    fn subscribe_trades(&mut self, cmd: &SubscribeTrades) -> anyhow::Result<()> {
178        log_not_implemented(&cmd);
179        Ok(())
180    }
181
182    /// Subscribes to mark price updates for the specified instrument.
183    ///
184    /// # Errors
185    ///
186    /// Returns an error if the subscribe operation fails.
187    fn subscribe_mark_prices(&mut self, cmd: &SubscribeMarkPrices) -> anyhow::Result<()> {
188        log_not_implemented(&cmd);
189        Ok(())
190    }
191
192    /// Subscribes to index price updates for the specified instrument.
193    ///
194    /// # Errors
195    ///
196    /// Returns an error if the subscribe operation fails.
197    fn subscribe_index_prices(&mut self, cmd: &SubscribeIndexPrices) -> anyhow::Result<()> {
198        log_not_implemented(&cmd);
199        Ok(())
200    }
201
202    /// Subscribes to funding rate updates for the specified instrument.
203    ///
204    /// # Errors
205    ///
206    /// Returns an error if the subscribe operation fails.
207    fn subscribe_funding_rates(&mut self, cmd: &SubscribeFundingRates) -> anyhow::Result<()> {
208        log_not_implemented(&cmd);
209        Ok(())
210    }
211
212    /// Subscribes to bar updates of the specified bar type.
213    ///
214    /// # Errors
215    ///
216    /// Returns an error if the subscribe operation fails.
217    fn subscribe_bars(&mut self, cmd: &SubscribeBars) -> anyhow::Result<()> {
218        log_not_implemented(&cmd);
219        Ok(())
220    }
221
222    /// Subscribes to status updates for the specified instrument.
223    ///
224    /// # Errors
225    ///
226    /// Returns an error if the subscribe operation fails.
227    fn subscribe_instrument_status(
228        &mut self,
229        cmd: &SubscribeInstrumentStatus,
230    ) -> anyhow::Result<()> {
231        log_not_implemented(&cmd);
232        Ok(())
233    }
234
235    /// Subscribes to instrument close events for the specified instrument.
236    ///
237    /// # Errors
238    ///
239    /// Returns an error if the subscription operation fails.
240    fn subscribe_instrument_close(&mut self, cmd: &SubscribeInstrumentClose) -> anyhow::Result<()> {
241        log_not_implemented(&cmd);
242        Ok(())
243    }
244
245    #[cfg(feature = "defi")]
246    /// Subscribes to blocks for a specified blockchain.
247    ///
248    /// # Errors
249    ///
250    /// Returns an error if the subscription operation fails.
251    fn subscribe_blocks(&mut self, cmd: &SubscribeBlocks) -> anyhow::Result<()> {
252        log_not_implemented(&cmd);
253        Ok(())
254    }
255
256    #[cfg(feature = "defi")]
257    /// Subscribes to pool definition updates for a specified AMM pool.
258    ///
259    /// # Errors
260    ///
261    /// Returns an error if the subscription operation fails.
262    fn subscribe_pool(&mut self, cmd: &SubscribePool) -> anyhow::Result<()> {
263        log_not_implemented(&cmd);
264        Ok(())
265    }
266
267    #[cfg(feature = "defi")]
268    /// Subscribes to pool swaps for a specified AMM pool.
269    ///
270    /// # Errors
271    ///
272    /// Returns an error if the subscription operation fails.
273    fn subscribe_pool_swaps(&mut self, cmd: &SubscribePoolSwaps) -> anyhow::Result<()> {
274        log_not_implemented(&cmd);
275        Ok(())
276    }
277
278    #[cfg(feature = "defi")]
279    /// Subscribes to pool liquidity updates for a specified AMM pool.
280    ///
281    /// # Errors
282    ///
283    /// Returns an error if the subscription operation fails.
284    fn subscribe_pool_liquidity_updates(
285        &mut self,
286        cmd: &SubscribePoolLiquidityUpdates,
287    ) -> anyhow::Result<()> {
288        log_not_implemented(&cmd);
289        Ok(())
290    }
291
292    #[cfg(feature = "defi")]
293    /// Subscribes to pool fee collects for a specified AMM pool.
294    ///
295    /// # Errors
296    ///
297    /// Returns an error if the subscription operation fails.
298    fn subscribe_pool_fee_collects(
299        &mut self,
300        cmd: &SubscribePoolFeeCollects,
301    ) -> anyhow::Result<()> {
302        log_not_implemented(&cmd);
303        Ok(())
304    }
305
306    #[cfg(feature = "defi")]
307    /// Subscribes to pool flash loan events for a specified AMM pool.
308    ///
309    /// # Errors
310    ///
311    /// Returns an error if the subscription operation fails.
312    fn subscribe_pool_flash_events(
313        &mut self,
314        cmd: &SubscribePoolFlashEvents,
315    ) -> anyhow::Result<()> {
316        log_not_implemented(&cmd);
317        Ok(())
318    }
319
320    /// Unsubscribes from custom data types according to the command.
321    ///
322    /// # Errors
323    ///
324    /// Returns an error if the unsubscribe operation fails.
325    fn unsubscribe(&mut self, cmd: &UnsubscribeCustomData) -> anyhow::Result<()> {
326        log_not_implemented(&cmd);
327        Ok(())
328    }
329
330    /// Unsubscribes from instruments list for the specified venue.
331    ///
332    /// # Errors
333    ///
334    /// Returns an error if the unsubscribe operation fails.
335    fn unsubscribe_instruments(&mut self, cmd: &UnsubscribeInstruments) -> anyhow::Result<()> {
336        log_not_implemented(&cmd);
337        Ok(())
338    }
339
340    /// Unsubscribes from data for the specified instrument.
341    ///
342    /// # Errors
343    ///
344    /// Returns an error if the unsubscribe operation fails.
345    fn unsubscribe_instrument(&mut self, cmd: &UnsubscribeInstrument) -> anyhow::Result<()> {
346        log_not_implemented(&cmd);
347        Ok(())
348    }
349
350    /// Unsubscribes from order book delta updates for the specified instrument.
351    ///
352    /// # Errors
353    ///
354    /// Returns an error if the unsubscribe operation fails.
355    fn unsubscribe_book_deltas(&mut self, cmd: &UnsubscribeBookDeltas) -> anyhow::Result<()> {
356        log_not_implemented(&cmd);
357        Ok(())
358    }
359
360    /// Unsubscribes from top 10 order book depth updates for the specified instrument.
361    ///
362    /// # Errors
363    ///
364    /// Returns an error if the unsubscribe operation fails.
365    fn unsubscribe_book_depth10(&mut self, cmd: &UnsubscribeBookDepth10) -> anyhow::Result<()> {
366        log_not_implemented(&cmd);
367        Ok(())
368    }
369
370    /// Unsubscribes from quote updates for the specified instrument.
371    ///
372    /// # Errors
373    ///
374    /// Returns an error if the unsubscribe operation fails.
375    fn unsubscribe_quotes(&mut self, cmd: &UnsubscribeQuotes) -> anyhow::Result<()> {
376        log_not_implemented(&cmd);
377        Ok(())
378    }
379
380    /// Unsubscribes from trade updates for the specified instrument.
381    ///
382    /// # Errors
383    ///
384    /// Returns an error if the unsubscribe operation fails.
385    fn unsubscribe_trades(&mut self, cmd: &UnsubscribeTrades) -> anyhow::Result<()> {
386        log_not_implemented(&cmd);
387        Ok(())
388    }
389
390    /// Unsubscribes from mark price updates for the specified instrument.
391    ///
392    /// # Errors
393    ///
394    /// Returns an error if the unsubscribe operation fails.
395    fn unsubscribe_mark_prices(&mut self, cmd: &UnsubscribeMarkPrices) -> anyhow::Result<()> {
396        log_not_implemented(&cmd);
397        Ok(())
398    }
399
400    /// Unsubscribes from index price updates for the specified instrument.
401    ///
402    /// # Errors
403    ///
404    /// Returns an error if the unsubscribe operation fails.
405    fn unsubscribe_index_prices(&mut self, cmd: &UnsubscribeIndexPrices) -> anyhow::Result<()> {
406        log_not_implemented(&cmd);
407        Ok(())
408    }
409
410    /// Unsubscribes from funding rate updates for the specified instrument.
411    ///
412    /// # Errors
413    ///
414    /// Returns an error if the unsubscribe operation fails.
415    fn unsubscribe_funding_rates(&mut self, cmd: &UnsubscribeFundingRates) -> anyhow::Result<()> {
416        log_not_implemented(&cmd);
417        Ok(())
418    }
419
420    /// Unsubscribes from bar updates of the specified bar type.
421    ///
422    /// # Errors
423    ///
424    /// Returns an error if the unsubscribe operation fails.
425    fn unsubscribe_bars(&mut self, cmd: &UnsubscribeBars) -> anyhow::Result<()> {
426        log_not_implemented(&cmd);
427        Ok(())
428    }
429
430    /// Unsubscribes from instrument status updates for the specified instrument.
431    ///
432    /// # Errors
433    ///
434    /// Returns an error if the unsubscribe operation fails.
435    fn unsubscribe_instrument_status(
436        &mut self,
437        cmd: &UnsubscribeInstrumentStatus,
438    ) -> anyhow::Result<()> {
439        log_not_implemented(&cmd);
440        Ok(())
441    }
442
443    /// Unsubscribes from instrument close events for the specified instrument.
444    ///
445    /// # Errors
446    ///
447    /// Returns an error if the unsubscribe operation fails.
448    fn unsubscribe_instrument_close(
449        &mut self,
450        cmd: &UnsubscribeInstrumentClose,
451    ) -> anyhow::Result<()> {
452        log_not_implemented(&cmd);
453        Ok(())
454    }
455
456    #[cfg(feature = "defi")]
457    /// Unsubscribes from blocks for a specified blockchain.
458    ///
459    /// # Errors
460    ///
461    /// Returns an error if the subscription operation fails.
462    fn unsubscribe_blocks(&mut self, cmd: &UnsubscribeBlocks) -> anyhow::Result<()> {
463        log_not_implemented(&cmd);
464        Ok(())
465    }
466
467    #[cfg(feature = "defi")]
468    /// Unsubscribes from pool definition updates for a specified AMM pool.
469    ///
470    /// # Errors
471    ///
472    /// Returns an error if the subscription operation fails.
473    fn unsubscribe_pool(&mut self, cmd: &UnsubscribePool) -> anyhow::Result<()> {
474        log_not_implemented(&cmd);
475        Ok(())
476    }
477
478    #[cfg(feature = "defi")]
479    /// Unsubscribes from swaps for a specified AMM pool.
480    ///
481    /// # Errors
482    ///
483    /// Returns an error if the subscription operation fails.
484    fn unsubscribe_pool_swaps(&mut self, cmd: &UnsubscribePoolSwaps) -> anyhow::Result<()> {
485        log_not_implemented(&cmd);
486        Ok(())
487    }
488
489    #[cfg(feature = "defi")]
490    /// Unsubscribes from pool liquidity updates for a specified AMM pool.
491    ///
492    /// # Errors
493    ///
494    /// Returns an error if the subscription operation fails.
495    fn unsubscribe_pool_liquidity_updates(
496        &mut self,
497        cmd: &UnsubscribePoolLiquidityUpdates,
498    ) -> anyhow::Result<()> {
499        log_not_implemented(&cmd);
500        Ok(())
501    }
502
503    #[cfg(feature = "defi")]
504    /// Unsubscribes from pool fee collects for a specified AMM pool.
505    ///
506    /// # Errors
507    ///
508    /// Returns an error if the subscription operation fails.
509    fn unsubscribe_pool_fee_collects(
510        &mut self,
511        cmd: &UnsubscribePoolFeeCollects,
512    ) -> anyhow::Result<()> {
513        log_not_implemented(&cmd);
514        Ok(())
515    }
516
517    #[cfg(feature = "defi")]
518    /// Unsubscribes from pool flash loan events for a specified AMM pool.
519    ///
520    /// # Errors
521    ///
522    /// Returns an error if the subscription operation fails.
523    fn unsubscribe_pool_flash_events(
524        &mut self,
525        cmd: &UnsubscribePoolFlashEvents,
526    ) -> anyhow::Result<()> {
527        log_not_implemented(&cmd);
528        Ok(())
529    }
530
531    /// Sends a custom data request to the provider.
532    ///
533    /// # Errors
534    ///
535    /// Returns an error if the data request fails.
536    fn request_data(&self, request: &RequestCustomData) -> anyhow::Result<()> {
537        log_not_implemented(&request);
538        Ok(())
539    }
540
541    /// Requests a list of instruments from the provider for a given venue.
542    ///
543    /// # Errors
544    ///
545    /// Returns an error if the instruments request fails.
546    fn request_instruments(&self, request: &RequestInstruments) -> anyhow::Result<()> {
547        log_not_implemented(&request);
548        Ok(())
549    }
550
551    /// Requests detailed data for a single instrument.
552    ///
553    /// # Errors
554    ///
555    /// Returns an error if the instrument request fails.
556    fn request_instrument(&self, request: &RequestInstrument) -> anyhow::Result<()> {
557        log_not_implemented(&request);
558        Ok(())
559    }
560
561    /// Requests a snapshot of the order book for a specified instrument.
562    ///
563    /// # Errors
564    ///
565    /// Returns an error if the book snapshot request fails.
566    fn request_book_snapshot(&self, request: &RequestBookSnapshot) -> anyhow::Result<()> {
567        log_not_implemented(&request);
568        Ok(())
569    }
570
571    /// Requests historical or streaming quote data for a specified instrument.
572    ///
573    /// # Errors
574    ///
575    /// Returns an error if the quotes request fails.
576    fn request_quotes(&self, request: &RequestQuotes) -> anyhow::Result<()> {
577        log_not_implemented(&request);
578        Ok(())
579    }
580
581    /// Requests historical or streaming trade data for a specified instrument.
582    ///
583    /// # Errors
584    ///
585    /// Returns an error if the trades request fails.
586    fn request_trades(&self, request: &RequestTrades) -> anyhow::Result<()> {
587        log_not_implemented(&request);
588        Ok(())
589    }
590
591    /// Requests historical or streaming bar data for a specified instrument and bar type.
592    ///
593    /// # Errors
594    ///
595    /// Returns an error if the bars request fails.
596    fn request_bars(&self, request: &RequestBars) -> anyhow::Result<()> {
597        log_not_implemented(&request);
598        Ok(())
599    }
600
601    /// Requests historical order book depth data for a specified instrument.
602    ///
603    /// # Errors
604    ///
605    /// Returns an error if the order book depths request fails.
606    fn request_book_depth(&self, request: &RequestBookDepth) -> anyhow::Result<()> {
607        log_not_implemented(&request);
608        Ok(())
609    }
610
611    #[cfg(feature = "defi")]
612    /// Requests a snapshot of a specific AMM pool.
613    ///
614    /// # Errors
615    ///
616    /// Returns an error if the pool snapshot request fails.
617    fn request_pool_snapshot(&self, request: &RequestPoolSnapshot) -> anyhow::Result<()> {
618        log_not_implemented(&request);
619        Ok(())
620    }
621}
nautilus_common/clients/data.rs

nautilus_common/clients/
data.rs
