Skip to main content

nautilus_finfeed/
loaders.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//! Standalone historical ingestion with reusable outcome definitions.
17
18use std::{collections::HashMap, num::NonZeroUsize, sync::Arc};
19
20use anyhow::Context;
21use nautilus_core::{UnixNanos, string::secret::SecretString, time::get_atomic_clock_realtime};
22use nautilus_model::{
23    data::{Bar, BarType, OrderBookDelta, QuoteTick, TradeTick},
24    identifiers::InstrumentId,
25    instruments::BinaryOption,
26};
27use parking_lot::{Mutex, RwLock};
28
29use crate::{
30    book,
31    common::symbol::from_instrument_id,
32    history,
33    http::client::{FinFeedHttpClient, FinFeedHttpConfig},
34    instruments::{
35        FinFeedInstrumentSelection, check_duplicate_outcome, fetch_instrument, selected_ids,
36    },
37};
38
39/// Fetches historical Nautilus data using retained outcome definitions.
40///
41/// Construction sends no requests and resolves credentials on the first network operation.
42/// Load or register definitions before requesting market data. Requests share one HTTP client,
43/// including its attempt allowance. Definition refreshes are explicit; each history request uses
44/// a snapshot of its registered definition and returns no partial result on failure.
45#[derive(Debug)]
46pub struct FinFeedDataLoader {
47    api_key: Option<SecretString>,
48    http_config: FinFeedHttpConfig,
49    http: Mutex<Option<Arc<FinFeedHttpClient>>>,
50    instruments: RwLock<HashMap<InstrumentId, BinaryOption>>,
51}
52
53impl FinFeedDataLoader {
54    /// Creates a loader with an empty instrument registry and lazy HTTP transport.
55    #[must_use]
56    pub fn new(api_key: Option<SecretString>) -> Self {
57        Self::with_http_config(api_key, FinFeedHttpConfig::default())
58    }
59
60    /// Creates a loader with explicit HTTP controls, without resolving credentials or sending requests.
61    #[must_use]
62    pub fn with_http_config(api_key: Option<SecretString>, http_config: FinFeedHttpConfig) -> Self {
63        Self {
64            api_key,
65            http_config,
66            http: Mutex::new(None),
67            instruments: RwLock::new(HashMap::new()),
68        }
69    }
70
71    /// Registers an outcome definition, replacing the same ID after validation.
72    ///
73    /// # Errors
74    ///
75    /// Returns an error if the ID is not a FinFeed outcome or an outcome token has another owner.
76    pub fn add_instrument(&self, instrument: BinaryOption) -> anyhow::Result<()> {
77        from_instrument_id(instrument.id)?;
78        let mut instruments = self.instruments.write();
79        check_duplicate_outcome(&instruments, &instrument)?;
80        instruments.insert(instrument.id, instrument);
81        Ok(())
82    }
83
84    /// Returns a retained definition.
85    ///
86    /// # Errors
87    ///
88    /// Returns an error if the definition has not been loaded or registered.
89    pub fn instrument(&self, instrument_id: InstrumentId) -> anyhow::Result<BinaryOption> {
90        self.instruments
91            .read()
92            .get(&instrument_id)
93            .cloned()
94            .with_context(|| format!("No loaded instrument {instrument_id}"))
95    }
96
97    /// Fetches and retains a fresh outcome definition.
98    ///
99    /// # Errors
100    ///
101    /// Returns an error if retrieval, identity checks, or definition validation fails.
102    pub async fn request_instrument(
103        &self,
104        instrument_id: InstrumentId,
105    ) -> anyhow::Result<BinaryOption> {
106        let http = self.http()?;
107        let now = get_atomic_clock_realtime().get_time_ns();
108        let instrument = fetch_instrument(&http, instrument_id, now).await?;
109        self.add_instrument(instrument.clone())?;
110        Ok(instrument)
111    }
112
113    /// Fetches the supplied outcome selections and retains them atomically.
114    ///
115    /// # Errors
116    ///
117    /// Returns an error if selections, retrieval, or any definition fails validation.
118    /// Failures preserve all previously registered definitions.
119    pub async fn request_instruments(
120        &self,
121        instruments: &[FinFeedInstrumentSelection],
122    ) -> anyhow::Result<Vec<BinaryOption>> {
123        let ids = selected_ids(instruments)?;
124        let http = self.http()?;
125        let now = get_atomic_clock_realtime().get_time_ns();
126        let mut loaded = Vec::with_capacity(ids.len());
127        for id in ids {
128            loaded.push(fetch_instrument(&http, id, now).await?);
129        }
130
131        let mut instruments = self.instruments.write();
132        let mut candidate = instruments.clone();
133        for instrument in &loaded {
134            check_duplicate_outcome(&candidate, instrument)?;
135            candidate.insert(instrument.id, instrument.clone());
136        }
137
138        *instruments = candidate;
139        Ok(loaded)
140    }
141
142    /// Retrieves historical book deltas using the retained definition.
143    ///
144    /// Bounds are inclusive on the adapter's ordering clock. The local limit preserves complete
145    /// book batches. A missing snapshot seed or ambiguous continuation rejects book history.
146    ///
147    /// # Errors
148    ///
149    /// Returns an error if metadata is missing, bounds are invalid, or retrieval or conversion fails.
150    pub async fn request_book_deltas(
151        &self,
152        instrument_id: InstrumentId,
153        start: UnixNanos,
154        end: UnixNanos,
155        limit: Option<NonZeroUsize>,
156    ) -> anyhow::Result<Vec<OrderBookDelta>> {
157        let instrument = self.instrument(instrument_id)?;
158        let now = get_atomic_clock_realtime().get_time_ns();
159
160        let window = history::Window::new(
161            Some(start.to_datetime_utc()),
162            Some(end.to_datetime_utc()),
163            limit,
164            now.to_datetime_utc(),
165        )?;
166
167        let http = self.http()?;
168        let batches = history::books(&http, &instrument, &window).await?;
169        book::deltas(batches, limit)
170    }
171
172    /// Retrieves historical quotes using the retained definition.
173    ///
174    /// Bounds are inclusive on the adapter's ordering clock.
175    ///
176    /// # Errors
177    ///
178    /// Returns an error if metadata is missing, bounds are invalid, or retrieval or conversion fails.
179    pub async fn request_quotes(
180        &self,
181        instrument_id: InstrumentId,
182        start: UnixNanos,
183        end: UnixNanos,
184        limit: Option<NonZeroUsize>,
185    ) -> anyhow::Result<Vec<QuoteTick>> {
186        let instrument = self.instrument(instrument_id)?;
187        let now = get_atomic_clock_realtime().get_time_ns();
188
189        let window = history::Window::new(
190            Some(start.to_datetime_utc()),
191            Some(end.to_datetime_utc()),
192            limit,
193            now.to_datetime_utc(),
194        )?;
195
196        let http = self.http()?;
197        history::quotes(&http, &instrument, &window).await
198    }
199
200    /// Retrieves historical trades using the retained definition.
201    ///
202    /// Bounds are inclusive on the adapter's ordering clock.
203    ///
204    /// # Errors
205    ///
206    /// Returns an error if metadata is missing, bounds are invalid, or retrieval or conversion fails.
207    pub async fn request_trades(
208        &self,
209        instrument_id: InstrumentId,
210        start: UnixNanos,
211        end: UnixNanos,
212        limit: Option<NonZeroUsize>,
213    ) -> anyhow::Result<Vec<TradeTick>> {
214        let instrument = self.instrument(instrument_id)?;
215        let now = get_atomic_clock_realtime().get_time_ns();
216
217        let window = history::Window::new(
218            Some(start.to_datetime_utc()),
219            Some(end.to_datetime_utc()),
220            limit,
221            now.to_datetime_utc(),
222        )?;
223
224        let http = self.http()?;
225        history::trades(&http, &instrument, &window).await
226    }
227
228    /// Retrieves historical bars using the retained definition.
229    ///
230    /// Bounds are inclusive on the adapter's ordering clock.
231    ///
232    /// # Errors
233    ///
234    /// Returns an error if metadata is missing, bounds are invalid, or retrieval or conversion fails.
235    pub async fn request_bars(
236        &self,
237        bar_type: BarType,
238        start: UnixNanos,
239        end: UnixNanos,
240        limit: Option<NonZeroUsize>,
241    ) -> anyhow::Result<Vec<Bar>> {
242        let instrument_id = bar_type.instrument_id();
243        let instrument = self.instrument(instrument_id)?;
244        let now = get_atomic_clock_realtime().get_time_ns();
245
246        let window = history::Window::new(
247            Some(start.to_datetime_utc()),
248            Some(end.to_datetime_utc()),
249            limit,
250            now.to_datetime_utc(),
251        )?;
252
253        let http = self.http()?;
254        history::bars(
255            &http,
256            &instrument,
257            bar_type,
258            &window,
259            now.to_datetime_utc(),
260            history::period_length(bar_type)?,
261        )
262        .await
263    }
264
265    fn http(&self) -> anyhow::Result<Arc<FinFeedHttpClient>> {
266        let mut http = self.http.lock();
267        if let Some(client) = http.as_ref() {
268            return Ok(Arc::clone(client));
269        }
270
271        let client = FinFeedHttpClient::new(self.api_key.clone(), self.http_config.clone())?;
272        let client = Arc::new(client);
273        *http = Some(Arc::clone(&client));
274        Ok(client)
275    }
276}