Trait DataProvider

pub trait DataProvider {
    type Error: Display + Debug;

    // Required methods
    fn symbol_info<'life0, 'async_trait>(
        &'life0 self,
        symbol: String,
    ) -> Pin<Box<dyn Future<Output = Result<PartialSymbolInfo, DataProviderError<Self::Error>>> + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn candlesticks(
        &self,
        symbol: String,
        timeframe: TimeFrame,
        from_time: i64,
    ) -> LocalBoxStream<'static, Result<CandlestickItem, DataProviderError<Self::Error>>>;
}

Supplies candlestick data and symbol metadata to the VM.

Implement this trait and pass it as the first argument to Instance::builder. It serves two purposes: main chart K-lines consumed by Instance::run and MTF/cross-symbol data for request.security() calls.

For simple single-symbol use cases, pass a Vec<Candlestick> directly — it implements DataProvider and wraps bars as CandlestickItem::Confirmed.

Contract

• candlesticks must return bars in strict ascending time order.
• The stream should start at or before from_time so that MTF bar state is initialised even before the first chart bar.
• Returning Err(DataProviderError::InvalidSymbol(_)) from either method causes request.security() to return na when ignore_invalid_symbol = true, or a runtime error otherwise.

Required Associated Types

type Error: Display + Debug

The error payload type for DataProviderError::Other.

Required Methods

fn symbol_info<'life0, 'async_trait>( &'life0 self, symbol: String, ) -> Pin<Box<dyn Future<Output = Result<PartialSymbolInfo, DataProviderError<Self::Error>>> + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Returns partial symbol metadata for the given symbol string.

Any None field falls back to a default derived from the symbol’s exchange prefix. Return PartialSymbolInfo::default() if you only want the defaults.

fn candlesticks( &self, symbol: String, timeframe: TimeFrame, from_time: i64, ) -> LocalBoxStream<'static, Result<CandlestickItem, DataProviderError<Self::Error>>>

Returns a stream of candlestick items for the given symbol and timeframe.

• symbol — e.g. "BINANCE:BTCUSDT", "NASDAQ:AAPL"
• timeframe — the requested timeframe
• from_time — epoch-millisecond timestamp of the first chart bar; start at or before this time

Items must be yielded in strict ascending time order.

Stream protocol

The expected sequence is:

Confirmed(t0) Confirmed(t1) … Confirmed(tN)   <- historical closed bars
HistoryEnd                                     <- boundary marker
Realtime(tA)                                   <- forming bar, first tick
Realtime(tA)                                   <- same timestamp = update
Realtime(tB)  (tB > tA)                        <- new timestamp:
                                                   VM auto-confirms tA,
                                                   then opens tB
Realtime(tB)                                   <- update tB
…

Key rules:

• Confirmed — a fully closed bar. Only used for historical bars. Do not emit Confirmed for a realtime bar that has just closed; instead, send the next Realtime(tNew) with a later timestamp and the VM will automatically confirm the previous bar internally.
• Realtime — a bar that is still forming. Multiple consecutive Realtime items with the same timestamp are treated as in-place updates (tick updates). A Realtime item whose timestamp is later than the previous bar implicitly confirms the previous bar and starts a new one. At most one realtime bar is open at any time.
• HistoryEnd — emitted once, after all historical Confirmed bars and before the first Realtime bar. If the stream ends after HistoryEnd with an open Realtime bar, the VM confirms it automatically.

Yield Err(DataProviderError::InvalidSymbol(_)) as the first item when the symbol is not recognised.

Implementations on Foreign Types

impl DataProvider for Vec<CandlestickItem>

Vec<CandlestickItem> implements DataProvider by yielding the items as-is on every candlesticks() call, regardless of symbol/timeframe.

Use this when you need to mix CandlestickItem::Confirmed, CandlestickItem::Realtime, and/or CandlestickItem::HistoryEnd in a single stream. For plain historical bars, prefer Vec<Candlestick>.

type Error = Infallible

fn symbol_info<'life0, 'async_trait>( &'life0 self, _symbol: String, ) -> Pin<Box<dyn Future<Output = Result<PartialSymbolInfo, DataProviderError<Self::Error>>> + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

fn candlesticks( &self, _symbol: String, _timeframe: TimeFrame, _from_time: i64, ) -> LocalBoxStream<'static, Result<CandlestickItem, DataProviderError<Self::Error>>>

impl DataProvider for Vec<Candlestick>

Vec<Candlestick> implements DataProvider for the simple case of running a script against a fixed set of historical bars.

All candlesticks() requests (regardless of symbol/timeframe) receive the same bars wrapped as CandlestickItem::Confirmed, followed by a CandlestickItem::HistoryEnd marker.

For script_info() queries that need no data, pass vec![].

type Error = Infallible

fn symbol_info<'life0, 'async_trait>( &'life0 self, _symbol: String, ) -> Pin<Box<dyn Future<Output = Result<PartialSymbolInfo, DataProviderError<Self::Error>>> + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

fn candlesticks( &self, _symbol: String, _timeframe: TimeFrame, _from_time: i64, ) -> LocalBoxStream<'static, Result<CandlestickItem, DataProviderError<Self::Error>>>

impl<P> DataProvider for Rc<P>

where P: DataProvider + 'static,

Rc<P> implements DataProvider by delegating to the inner P.

Allows sharing a single provider instance between multiple Instance builders or background tasks without cloning the provider value itself.

type Error = <P as DataProvider>::Error

fn symbol_info<'life0, 'async_trait>( &'life0 self, symbol: String, ) -> Pin<Box<dyn Future<Output = Result<PartialSymbolInfo, DataProviderError<Self::Error>>> + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

fn candlesticks( &self, symbol: String, timeframe: TimeFrame, from_time: i64, ) -> LocalBoxStream<'static, Result<CandlestickItem, DataProviderError<Self::Error>>>

Implementors