nautilus_common/cache/
database.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//! Provides a `Cache` database backing.
17
18// Under development
19#![allow(dead_code)]
20#![allow(unused_variables)]
21
22use ahash::AHashMap;
23use bytes::Bytes;
24use nautilus_core::UnixNanos;
25use nautilus_model::{
26    accounts::AccountAny,
27    data::{Bar, DataType, FundingRateUpdate, GreeksData, QuoteTick, TradeTick, YieldCurveData},
28    events::{OrderEventAny, OrderSnapshot, position::snapshot::PositionSnapshot},
29    identifiers::{
30        AccountId, ClientId, ClientOrderId, ComponentId, InstrumentId, PositionId, StrategyId,
31        VenueOrderId,
32    },
33    instruments::{InstrumentAny, SyntheticInstrument},
34    orderbook::OrderBook,
35    orders::OrderAny,
36    position::Position,
37    types::Currency,
38};
39use ustr::Ustr;
40
41use crate::{custom::CustomData, signal::Signal};
42
43#[derive(Debug, Default)]
44pub struct CacheMap {
45    pub currencies: AHashMap<Ustr, Currency>,
46    pub instruments: AHashMap<InstrumentId, InstrumentAny>,
47    pub synthetics: AHashMap<InstrumentId, SyntheticInstrument>,
48    pub accounts: AHashMap<AccountId, AccountAny>,
49    pub orders: AHashMap<ClientOrderId, OrderAny>,
50    pub positions: AHashMap<PositionId, Position>,
51    pub greeks: AHashMap<InstrumentId, GreeksData>,
52    pub yield_curves: AHashMap<String, YieldCurveData>,
53}
54
55#[async_trait::async_trait]
56pub trait CacheDatabaseAdapter {
57    /// Closes the cache database connection.
58    ///
59    /// # Errors
60    ///
61    /// Returns an error if the database fails to close properly.
62    fn close(&mut self) -> anyhow::Result<()>;
63
64    /// Flushes any pending changes to the database.
65    ///
66    /// # Errors
67    ///
68    /// Returns an error if flushing changes fails.
69    fn flush(&mut self) -> anyhow::Result<()>;
70
71    /// Loads all cached data into memory.
72    ///
73    /// # Errors
74    ///
75    /// Returns an error if loading data from the database fails.
76    async fn load_all(&self) -> anyhow::Result<CacheMap>;
77
78    /// Loads raw key-value data from the database.
79    ///
80    /// # Errors
81    ///
82    /// Returns an error if the load operation fails.
83    fn load(&self) -> anyhow::Result<AHashMap<String, Bytes>>;
84
85    /// Loads all currencies from the cache.
86    ///
87    /// # Errors
88    ///
89    /// Returns an error if loading currencies fails.
90    async fn load_currencies(&self) -> anyhow::Result<AHashMap<Ustr, Currency>>;
91
92    /// Loads all instruments from the cache.
93    ///
94    /// # Errors
95    ///
96    /// Returns an error if loading instruments fails.
97    async fn load_instruments(&self) -> anyhow::Result<AHashMap<InstrumentId, InstrumentAny>>;
98
99    /// Loads all synthetic instruments from the cache.
100    ///
101    /// # Errors
102    ///
103    /// Returns an error if loading synthetic instruments fails.
104    async fn load_synthetics(&self) -> anyhow::Result<AHashMap<InstrumentId, SyntheticInstrument>>;
105
106    /// Loads all accounts from the cache.
107    ///
108    /// # Errors
109    ///
110    /// Returns an error if loading accounts fails.
111    async fn load_accounts(&self) -> anyhow::Result<AHashMap<AccountId, AccountAny>>;
112
113    /// Loads all orders from the cache.
114    ///
115    /// # Errors
116    ///
117    /// Returns an error if loading orders fails.
118    async fn load_orders(&self) -> anyhow::Result<AHashMap<ClientOrderId, OrderAny>>;
119
120    /// Loads all positions from the cache.
121    ///
122    /// # Errors
123    ///
124    /// Returns an error if loading positions fails.
125    async fn load_positions(&self) -> anyhow::Result<AHashMap<PositionId, Position>>;
126
127    /// Loads all [`GreeksData`] from the cache.
128    ///
129    /// # Errors
130    ///
131    /// Returns an error if loading greeks data fails.
132    async fn load_greeks(&self) -> anyhow::Result<AHashMap<InstrumentId, GreeksData>> {
133        Ok(AHashMap::new())
134    }
135
136    /// Loads all [`YieldCurveData`] from the cache.
137    ///
138    /// # Errors
139    ///
140    /// Returns an error if loading yield curve data fails.
141    async fn load_yield_curves(&self) -> anyhow::Result<AHashMap<String, YieldCurveData>> {
142        Ok(AHashMap::new())
143    }
144
145    /// Loads mapping from order IDs to position IDs.
146    ///
147    /// # Errors
148    ///
149    /// Returns an error if loading the index order-position mapping fails.
150    fn load_index_order_position(&self) -> anyhow::Result<AHashMap<ClientOrderId, Position>>;
151
152    /// Loads mapping from order IDs to client IDs.
153    ///
154    /// # Errors
155    ///
156    /// Returns an error if loading the index order-client mapping fails.
157    fn load_index_order_client(&self) -> anyhow::Result<AHashMap<ClientOrderId, ClientId>>;
158
159    /// Loads a single currency by code.
160    ///
161    /// # Errors
162    ///
163    /// Returns an error if loading a single currency fails.
164    async fn load_currency(&self, code: &Ustr) -> anyhow::Result<Option<Currency>>;
165
166    /// Loads a single instrument by ID.
167    ///
168    /// # Errors
169    ///
170    /// Returns an error if loading a single instrument fails.
171    async fn load_instrument(
172        &self,
173        instrument_id: &InstrumentId,
174    ) -> anyhow::Result<Option<InstrumentAny>>;
175
176    /// Loads a single synthetic instrument by ID.
177    ///
178    /// # Errors
179    ///
180    /// Returns an error if loading a single synthetic instrument fails.
181    async fn load_synthetic(
182        &self,
183        instrument_id: &InstrumentId,
184    ) -> anyhow::Result<Option<SyntheticInstrument>>;
185
186    /// Loads a single account by ID.
187    ///
188    /// # Errors
189    ///
190    /// Returns an error if loading a single account fails.
191    async fn load_account(&self, account_id: &AccountId) -> anyhow::Result<Option<AccountAny>>;
192
193    /// Loads a single order by client order ID.
194    ///
195    /// # Errors
196    ///
197    /// Returns an error if loading a single order fails.
198    async fn load_order(&self, client_order_id: &ClientOrderId)
199    -> anyhow::Result<Option<OrderAny>>;
200
201    /// Loads a single position by position ID.
202    ///
203    /// # Errors
204    ///
205    /// Returns an error if loading a single position fails.
206    async fn load_position(&self, position_id: &PositionId) -> anyhow::Result<Option<Position>>;
207
208    /// Loads actor state by component ID.
209    ///
210    /// # Errors
211    ///
212    /// Returns an error if loading actor state fails.
213    fn load_actor(&self, component_id: &ComponentId) -> anyhow::Result<AHashMap<String, Bytes>>;
214
215    /// Loads strategy state by strategy ID.
216    ///
217    /// # Errors
218    ///
219    /// Returns an error if loading strategy state fails.
220    fn load_strategy(&self, strategy_id: &StrategyId) -> anyhow::Result<AHashMap<String, Bytes>>;
221
222    /// Loads signals by name.
223    ///
224    /// # Errors
225    ///
226    /// Returns an error if loading signals fails.
227    fn load_signals(&self, name: &str) -> anyhow::Result<Vec<Signal>>;
228
229    /// Loads custom data by data type.
230    ///
231    /// # Errors
232    ///
233    /// Returns an error if loading custom data fails.
234    fn load_custom_data(&self, data_type: &DataType) -> anyhow::Result<Vec<CustomData>>;
235
236    /// Loads an order snapshot by client order ID.
237    ///
238    /// # Errors
239    ///
240    /// Returns an error if loading the order snapshot fails.
241    fn load_order_snapshot(
242        &self,
243        client_order_id: &ClientOrderId,
244    ) -> anyhow::Result<Option<OrderSnapshot>>;
245
246    /// Loads a position snapshot by position ID.
247    ///
248    /// # Errors
249    ///
250    /// Returns an error if loading the position snapshot fails.
251    fn load_position_snapshot(
252        &self,
253        position_id: &PositionId,
254    ) -> anyhow::Result<Option<PositionSnapshot>>;
255
256    /// Loads quote ticks by instrument ID.
257    ///
258    /// # Errors
259    ///
260    /// Returns an error if loading quotes fails.
261    fn load_quotes(&self, instrument_id: &InstrumentId) -> anyhow::Result<Vec<QuoteTick>>;
262
263    /// Loads trade ticks by instrument ID.
264    ///
265    /// # Errors
266    ///
267    /// Returns an error if loading trades fails.
268    fn load_trades(&self, instrument_id: &InstrumentId) -> anyhow::Result<Vec<TradeTick>>;
269
270    /// Loads funding rate updates by instrument ID.
271    ///
272    /// # Errors
273    ///
274    /// Returns an error if loading funding rates fails.
275    fn load_funding_rates(
276        &self,
277        instrument_id: &InstrumentId,
278    ) -> anyhow::Result<Vec<FundingRateUpdate>>;
279
280    /// Loads bars by instrument ID.
281    ///
282    /// # Errors
283    ///
284    /// Returns an error if loading bars fails.
285    fn load_bars(&self, instrument_id: &InstrumentId) -> anyhow::Result<Vec<Bar>>;
286
287    /// Adds a generic key-value pair to the cache.
288    ///
289    /// # Errors
290    ///
291    /// Returns an error if adding a generic key/value fails.
292    fn add(&self, key: String, value: Bytes) -> anyhow::Result<()>;
293
294    /// Adds a currency to the cache.
295    ///
296    /// # Errors
297    ///
298    /// Returns an error if adding a currency fails.
299    fn add_currency(&self, currency: &Currency) -> anyhow::Result<()>;
300
301    /// Adds an instrument to the cache.
302    ///
303    /// # Errors
304    ///
305    /// Returns an error if adding an instrument fails.
306    fn add_instrument(&self, instrument: &InstrumentAny) -> anyhow::Result<()>;
307
308    /// Adds a synthetic instrument to the cache.
309    ///
310    /// # Errors
311    ///
312    /// Returns an error if adding a synthetic instrument fails.
313    fn add_synthetic(&self, synthetic: &SyntheticInstrument) -> anyhow::Result<()>;
314
315    /// Adds an account to the cache.
316    ///
317    /// # Errors
318    ///
319    /// Returns an error if adding an account fails.
320    fn add_account(&self, account: &AccountAny) -> anyhow::Result<()>;
321
322    /// Adds an order to the cache.
323    ///
324    /// # Errors
325    ///
326    /// Returns an error if adding an order fails.
327    fn add_order(&self, order: &OrderAny, client_id: Option<ClientId>) -> anyhow::Result<()>;
328
329    /// Adds an order snapshot to the cache.
330    ///
331    /// # Errors
332    ///
333    /// Returns an error if adding an order snapshot fails.
334    fn add_order_snapshot(&self, snapshot: &OrderSnapshot) -> anyhow::Result<()>;
335
336    /// Adds a position to the cache.
337    ///
338    /// # Errors
339    ///
340    /// Returns an error if adding a position fails.
341    fn add_position(&self, position: &Position) -> anyhow::Result<()>;
342
343    /// Adds a position snapshot to the cache.
344    ///
345    /// # Errors
346    ///
347    /// Returns an error if adding a position snapshot fails.
348    fn add_position_snapshot(&self, snapshot: &PositionSnapshot) -> anyhow::Result<()>;
349
350    /// Adds an order book to the cache.
351    ///
352    /// # Errors
353    ///
354    /// Returns an error if adding an order book fails.
355    fn add_order_book(&self, order_book: &OrderBook) -> anyhow::Result<()>;
356
357    /// Adds a signal to the cache.
358    ///
359    /// # Errors
360    ///
361    /// Returns an error if adding a signal fails.
362    fn add_signal(&self, signal: &Signal) -> anyhow::Result<()>;
363
364    /// Adds custom data to the cache.
365    ///
366    /// # Errors
367    ///
368    /// Returns an error if adding custom data fails.
369    fn add_custom_data(&self, data: &CustomData) -> anyhow::Result<()>;
370
371    /// Adds a quote tick to the cache.
372    ///
373    /// # Errors
374    ///
375    /// Returns an error if adding a quote tick fails.
376    fn add_quote(&self, quote: &QuoteTick) -> anyhow::Result<()>;
377
378    /// Adds a trade tick to the cache.
379    ///
380    /// # Errors
381    ///
382    /// Returns an error if adding a trade tick fails.
383    fn add_trade(&self, trade: &TradeTick) -> anyhow::Result<()>;
384
385    /// Adds a funding rate update to the cache.
386    ///
387    /// # Errors
388    ///
389    /// Returns an error if adding a funding rate update fails.
390    fn add_funding_rate(&self, funding_rate: &FundingRateUpdate) -> anyhow::Result<()>;
391
392    /// Adds a bar to the cache.
393    ///
394    /// # Errors
395    ///
396    /// Returns an error if adding a bar fails.
397    fn add_bar(&self, bar: &Bar) -> anyhow::Result<()>;
398
399    /// Adds greeks data to the cache.
400    ///
401    /// # Errors
402    ///
403    /// Returns an error if adding greeks data fails.
404    fn add_greeks(&self, greeks: &GreeksData) -> anyhow::Result<()> {
405        Ok(())
406    }
407
408    /// Adds yield curve data to the cache.
409    ///
410    /// # Errors
411    ///
412    /// Returns an error if adding yield curve data fails.
413    fn add_yield_curve(&self, yield_curve: &YieldCurveData) -> anyhow::Result<()> {
414        Ok(())
415    }
416
417    /// Deletes actor state from the cache.
418    ///
419    /// # Errors
420    ///
421    /// Returns an error if deleting actor state fails.
422    fn delete_actor(&self, component_id: &ComponentId) -> anyhow::Result<()>;
423
424    /// Deletes strategy state from the cache.
425    ///
426    /// # Errors
427    ///
428    /// Returns an error if deleting strategy state fails.
429    fn delete_strategy(&self, component_id: &StrategyId) -> anyhow::Result<()>;
430
431    /// Deletes an order from the cache.
432    ///
433    /// # Errors
434    ///
435    /// Returns an error if deleting an order fails.
436    fn delete_order(&self, client_order_id: &ClientOrderId) -> anyhow::Result<()>;
437
438    /// Deletes a position from the cache.
439    ///
440    /// # Errors
441    ///
442    /// Returns an error if deleting a position fails.
443    fn delete_position(&self, position_id: &PositionId) -> anyhow::Result<()>;
444
445    /// Deletes an account event from the cache.
446    ///
447    /// # Errors
448    ///
449    /// Returns an error if deleting account events fails.
450    fn delete_account_event(&self, account_id: &AccountId, event_id: &str) -> anyhow::Result<()>;
451
452    /// Indexes a venue order ID with its client order ID.
453    ///
454    /// # Errors
455    ///
456    /// Returns an error if indexing venue order ID fails.
457    fn index_venue_order_id(
458        &self,
459        client_order_id: ClientOrderId,
460        venue_order_id: VenueOrderId,
461    ) -> anyhow::Result<()>;
462
463    /// Indexes an order-position mapping.
464    ///
465    /// # Errors
466    ///
467    /// Returns an error if indexing order-position mapping fails.
468    fn index_order_position(
469        &self,
470        client_order_id: ClientOrderId,
471        position_id: PositionId,
472    ) -> anyhow::Result<()>;
473
474    /// Updates actor state in the cache.
475    ///
476    /// # Errors
477    ///
478    /// Returns an error if updating actor state fails.
479    fn update_actor(&self) -> anyhow::Result<()>;
480
481    /// Updates strategy state in the cache.
482    ///
483    /// # Errors
484    ///
485    /// Returns an error if updating strategy state fails.
486    fn update_strategy(&self) -> anyhow::Result<()>;
487
488    /// Updates an account in the cache.
489    ///
490    /// # Errors
491    ///
492    /// Returns an error if updating an account fails.
493    fn update_account(&self, account: &AccountAny) -> anyhow::Result<()>;
494
495    /// Updates an order in the cache with an order event.
496    ///
497    /// # Errors
498    ///
499    /// Returns an error if updating an order fails.
500    fn update_order(&self, order_event: &OrderEventAny) -> anyhow::Result<()>;
501
502    /// Updates a position in the cache.
503    ///
504    /// # Errors
505    ///
506    /// Returns an error if updating a position fails.
507    fn update_position(&self, position: &Position) -> anyhow::Result<()>;
508
509    /// Creates a snapshot of order state.
510    ///
511    /// # Errors
512    ///
513    /// Returns an error if snapshotting order state fails.
514    fn snapshot_order_state(&self, order: &OrderAny) -> anyhow::Result<()>;
515
516    /// Creates a snapshot of position state.
517    ///
518    /// # Errors
519    ///
520    /// Returns an error if snapshotting position state fails.
521    fn snapshot_position_state(&self, position: &Position) -> anyhow::Result<()>;
522
523    /// Records a heartbeat timestamp.
524    ///
525    /// # Errors
526    ///
527    /// Returns an error if heartbeat recording fails.
528    fn heartbeat(&self, timestamp: UnixNanos) -> anyhow::Result<()>;
529}
nautilus_common/cache/database.rs

nautilus_common/cache/
database.rs
