finance_query/providers/

config.rs

use crate::adapters::yahoo::client::ClientConfig;
use crate::error::Result;
use crate::providers::{
    Fetch, Provider, ProviderAdapter, ProviderHealth, ProviderSet, RetryPolicy, Routes,
    build_providers,
};
use std::sync::Arc;
use std::time::Duration;

/// Central provider configuration shared across query handles.
///
/// Build once with [`Providers::builder`], then create lightweight
/// [`Ticker`](crate::Ticker) handles that share the same underlying
/// provider connections and authentication.
///
/// # Example
///
/// ```no_run
/// use finance_query::{Providers, Provider, Fetch, Capability};
///
/// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
/// let providers = Providers::builder()
///     .route(Capability::QUOTE, [Provider::Yahoo])
///     .fetch(Fetch::Sequential)
///     .build().await?;
///
/// // All Ticker handles share the same Arc<ProviderSet>
/// let aapl = providers.ticker("AAPL").build().await?;
/// let nvda = providers.ticker("NVDA").logo().build().await?;
/// # Ok(())
/// # }
/// ```
pub struct Providers {
    pub(crate) set: Arc<ProviderSet>,
    lang: String,
}

impl std::fmt::Debug for Providers {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("Providers")
            .field("set", &self.set)
            .field("lang", &self.lang)
            .finish()
    }
}

impl Providers {
    /// Create a builder for configuring providers.
    pub fn builder() -> ProvidersBuilder {
        ProvidersBuilder::default()
    }

    /// Wrap a [`ProviderSet`] assembled by hand.
    ///
    /// The lower-level counterpart to [`builder`](Self::builder), for a caller
    /// that has already built its own adapters and route table. Nothing is
    /// initialised: [`ProviderAdapter::initialize`](crate::ProviderAdapter::initialize)
    /// is the builder's job, so a hand-built set must be ready to use.
    pub fn from_set(set: Arc<ProviderSet>) -> Self {
        Self::from_set_with_lang(set, ClientConfig::default().lang)
    }

    /// [`from_set`](Self::from_set) with an explicit language for the handles
    /// this set creates.
    pub fn from_set_with_lang(set: Arc<ProviderSet>, lang: impl Into<String>) -> Self {
        Self {
            set,
            lang: lang.into(),
        }
    }

    /// The underlying set, for `TickerBuilder::with_provider_set` and friends.
    pub fn provider_set(&self) -> &Arc<ProviderSet> {
        &self.set
    }

    /// Create a [`TickerBuilder`](crate::TickerBuilder) pre-wired to this provider set.
    ///
    /// The returned builder accepts the same optional configuration as
    /// [`Ticker::builder`](crate::Ticker::builder) (`.cache()`, `.logo()`,
    /// `.format()`) before calling `.build()`.
    ///
    /// The language configured via [`ProvidersBuilder::lang`] or
    /// [`ProvidersBuilder::region`] is inherited (override with `.lang()` on
    /// the returned builder). With the `translation` feature, a non-English
    /// language translates text fields automatically.
    pub fn ticker(&self, symbol: impl Into<String>) -> crate::TickerBuilder {
        crate::Ticker::builder(symbol)
            .lang(self.lang.clone())
            .with_provider_set(Arc::clone(&self.set))
    }

    /// Create a [`TickersBuilder`](crate::TickersBuilder) pre-wired to this provider set.
    ///
    /// The returned builder accepts the same optional configuration as
    /// [`Tickers::builder`](crate::Tickers::builder) (`.cache()`,
    /// `.max_concurrency()`, `.logo()`, `.format()`) before calling `.build()`.
    ///
    /// The language configured via [`ProvidersBuilder::lang`] or
    /// [`ProvidersBuilder::region`] is inherited (override with `.lang()` on
    /// the returned builder). With the `translation` feature, a non-English
    /// language translates text fields automatically.
    pub fn tickers<S, I>(&self, symbols: I) -> crate::TickersBuilder
    where
        S: Into<String>,
        I: IntoIterator<Item = S>,
    {
        crate::Tickers::builder(symbols)
            .lang(self.lang.clone())
            .with_provider_set(Arc::clone(&self.set))
    }

    /// Create a [`CryptoCoin`](crate::CryptoCoin) handle backed by this provider set.
    ///
    /// Compiled in unconditionally. With no built-in provider for this
    /// capability, register one with [`ProvidersBuilder::with_adapter`] or
    /// enable its feature, or these calls return `NoProviderAvailable`.
    pub fn crypto(&self, id: impl Into<String>) -> crate::domains::CryptoCoin {
        crate::domains::CryptoCoin::with_providers(id.into().into(), Arc::clone(&self.set))
    }

    /// Create a [`ForexPair`](crate::ForexPair) handle backed by this provider set.
    ///
    /// Compiled in unconditionally. With no built-in provider for this
    /// capability, register one with [`ProvidersBuilder::with_adapter`] or
    /// enable its feature, or these calls return `NoProviderAvailable`.
    pub fn forex(
        &self,
        from: impl Into<String>,
        to: impl Into<String>,
    ) -> crate::domains::ForexPair {
        crate::domains::ForexPair::with_providers(
            from.into().into(),
            to.into().into(),
            Arc::clone(&self.set),
        )
    }

    /// Create an [`EconomicIndicator`](crate::EconomicIndicator) handle backed by this provider set.
    ///
    /// Compiled in unconditionally. With no built-in provider for this
    /// capability, register one with [`ProvidersBuilder::with_adapter`] or
    /// enable its feature, or these calls return `NoProviderAvailable`.
    pub fn economic(&self, series_id: impl Into<String>) -> crate::domains::EconomicIndicator {
        crate::domains::EconomicIndicator::with_providers(
            series_id.into().into(),
            Arc::clone(&self.set),
        )
    }

    /// Create an [`Index`](crate::Index) handle backed by this provider set.
    pub fn index(&self, symbol: impl Into<String>) -> crate::domains::Index {
        crate::domains::Index::with_providers(symbol.into().into(), Arc::clone(&self.set))
    }

    /// Create a [`FuturesContract`](crate::FuturesContract) handle backed by this provider set.
    pub fn futures(&self, symbol: impl Into<String>) -> crate::domains::FuturesContract {
        crate::domains::FuturesContract::with_providers(symbol.into().into(), Arc::clone(&self.set))
    }

    /// Create a [`Commodity`](crate::Commodity) handle backed by this provider set.
    pub fn commodity(&self, symbol: impl Into<String>) -> crate::domains::Commodity {
        crate::domains::Commodity::with_providers(symbol.into().into(), Arc::clone(&self.set))
    }

    /// Create a [`Discovery`](crate::Discovery) handle backed by this provider set.
    ///
    /// Routes symbol search, reference data, and screening through
    /// [`Capability::DISCOVERY`](crate::Capability::DISCOVERY). Distinct from
    /// [`crate::finance::search`], which is a Yahoo-only shortcut.
    pub fn discovery(&self) -> crate::domains::Discovery {
        crate::domains::Discovery::with_providers(Arc::clone(&self.set))
    }

    /// Create a [`MarketCalendar`](crate::MarketCalendar) handle backed by this provider set.
    ///
    /// Routes market-wide earnings/IPO/dividend/split/economic calendars
    /// through [`Capability::CALENDAR`](crate::Capability::CALENDAR).
    pub fn calendar(&self) -> crate::domains::MarketCalendar {
        crate::domains::MarketCalendar::with_providers(Arc::clone(&self.set))
    }

    /// Create a [`Market`](crate::Market) handle backed by this provider set.
    ///
    /// Routes sector/industry performance and movers through
    /// [`Capability::MARKET`](crate::Capability::MARKET). Movers work on the
    /// default keyless route (Yahoo screeners); the sector/industry
    /// statistics need a keyed provider (FMP).
    pub fn market(&self) -> crate::domains::Market {
        crate::domains::Market::with_providers(Arc::clone(&self.set))
    }

    /// Create an [`EconomicCatalog`](crate::EconomicCatalog) handle backed by
    /// this provider set.
    ///
    /// Routes series search and category/release browsing through
    /// [`Capability::ECONOMIC`](crate::Capability::ECONOMIC). Unlike
    /// [`economic`](Self::economic) it takes no series id — it is how you find
    /// one.
    ///
    /// Compiled in unconditionally. With no built-in provider for this
    /// capability, register one with [`ProvidersBuilder::with_adapter`] or
    /// enable its feature, or these calls return `NoProviderAvailable`.
    pub fn economic_catalog(&self) -> crate::domains::EconomicCatalog {
        crate::domains::EconomicCatalog::with_providers(Arc::clone(&self.set))
    }

    /// Create a [`Snapshot`](crate::Snapshot) handle backed by this provider set.
    ///
    /// Routes cross-market snapshots through
    /// [`Capability::QUOTE`](crate::Capability::QUOTE). Needs a provider whose
    /// snapshot endpoint spans asset classes, currently Polygon alone.
    ///
    /// Compiled in unconditionally. With no built-in provider for this
    /// capability, register one with [`ProvidersBuilder::with_adapter`] or
    /// enable its feature, or these calls return `NoProviderAvailable`.
    pub fn snapshot(&self) -> crate::domains::Snapshot {
        crate::domains::Snapshot::with_providers(Arc::clone(&self.set))
    }

    /// Create a [`Filings`](crate::Filings) handle backed by this provider set.
    ///
    /// Always available — EDGAR is auto-injected when no other FILINGS provider
    /// is configured.
    pub fn filings(&self, symbol: impl Into<String>) -> crate::domains::Filings {
        crate::domains::Filings::with_providers(symbol.into().into(), Arc::clone(&self.set))
    }

    /// Snapshot recent health for every configured provider.
    ///
    /// Each [`ProviderHealth`] entry reflects up to the last 20 dispatch
    /// outcomes recorded in-process for that provider (recency window is
    /// internal and unspecified beyond "recent"), plus a best-effort
    /// rate-limit budget estimate where the provider exposes one. Purely
    /// observational — it does not affect routing or retries.
    ///
    /// # Example
    ///
    /// ```no_run
    /// use finance_query::Providers;
    ///
    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// let providers = Providers::builder().build().await?;
    /// for health in providers.health() {
    ///     println!("{:?}: healthy={}", health.provider, health.is_healthy);
    /// }
    /// # Ok(())
    /// # }
    /// ```
    pub fn health(&self) -> Vec<ProviderHealth> {
        self.set.health()
    }
}

/// Builder for [`Providers`].
pub struct ProvidersBuilder {
    provider_ids: Vec<Provider>,
    adapters: Vec<Arc<dyn crate::ProviderAdapter>>,
    config: ClientConfig,
    routes: Routes,
    retry: Option<RetryPolicy>,
    api_keys: std::collections::HashMap<&'static str, String>,
    request_limits: std::collections::HashMap<&'static str, u32>,
    endpoints: std::collections::HashMap<&'static str, String>,
}

impl std::fmt::Debug for ProvidersBuilder {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("ProvidersBuilder")
            .field("provider_ids", &self.provider_ids)
            .field(
                "adapters",
                &self.adapters.iter().map(|a| a.id()).collect::<Vec<_>>(),
            )
            .field("routes", &self.routes)
            .field("retry", &self.retry)
            .field(
                "api_keys",
                &self.api_keys.keys().copied().collect::<Vec<_>>(),
            )
            .finish()
    }
}

impl Default for ProvidersBuilder {
    fn default() -> Self {
        Self {
            provider_ids: vec![Provider::Yahoo],
            adapters: Vec::new(),
            config: ClientConfig::default(),
            routes: Routes::new(Fetch::Sequential),
            retry: None,
            api_keys: std::collections::HashMap::new(),
            request_limits: std::collections::HashMap::new(),
            endpoints: std::collections::HashMap::new(),
        }
    }
}

/// Reject a builder option set for a provider that is not configured or would ignore it.
fn check_scoped_options(
    set: &ProviderSet,
    option: &str,
    providers: &[&str],
    accepts: impl Fn(&dyn ProviderAdapter) -> bool,
) -> Result<()> {
    for key in providers {
        let adapter = Provider::from_id_str(key).and_then(|id| set.adapter(id));
        if !adapter.is_some_and(|p| accepts(p.as_ref())) {
            return Err(crate::FinanceError::InvalidParameter {
                param: option.into(),
                reason: format!("provider `{key}` is not configured or does not support {option}"),
            });
        }
    }
    Ok(())
}

impl ProvidersBuilder {
    /// Select initialized providers instead of the default Yahoo provider.
    /// Providers already named in routes are retained.
    pub fn providers(mut self, providers: impl IntoIterator<Item = Provider>) -> Self {
        self.provider_ids = providers.into_iter().collect();
        for route in self.routes.map.values() {
            for provider in &route.providers {
                if !matches!(provider, Provider::Custom(_)) && !self.provider_ids.contains(provider)
                {
                    self.provider_ids.push(*provider);
                }
            }
        }
        self
    }
    /// Set the request budget for this provider's API key. Zero is rejected by build.
    ///
    /// Instances using the same key share one bucket: the most recently built
    /// explicit budget sets its rate, and instances without one never change it.
    /// Requires an explicit [`api_key`](Self::api_key) and a provider whose
    /// adapter [accepts a budget](crate::ProviderAdapter::accepts_request_budget).
    pub fn requests_per_minute(mut self, provider: Provider, limit: u32) -> Self {
        self.request_limits.insert(provider.as_str(), limit);
        self
    }

    /// Send this provider's requests to a compatible service or local HTTP fixture.
    ///
    /// Only HTTPS and loopback HTTP origins are accepted, and continuations cannot
    /// leave the origin. No global endpoint is modified. Requires an explicit
    /// [`api_key`](Self::api_key) and a provider whose adapter
    /// [accepts an endpoint](crate::ProviderAdapter::accepts_endpoint).
    pub fn endpoint(mut self, provider: Provider, base_url: impl Into<String>) -> Self {
        self.endpoints.insert(provider.as_str(), base_url.into());
        self
    }
    /// Configure how providers are queried. Default: `Sequential`.
    ///
    /// Use [`Fetch::Sequential`] or [`Fetch::Parallel`].
    pub fn fetch(mut self, mode: Fetch) -> Self {
        self.routes.fetch = mode;
        self
    }

    /// Set `provider`'s API key for the [`Providers`] this builds, instead of
    /// the process-global key from its `init` function.
    ///
    /// Two `Providers` can hold different keys for the same provider, and a
    /// key can be replaced without restarting. Each distinct key gets its own
    /// rate-limit budget. Providers left unset fall back to the process-global
    /// key, then to the environment variable.
    pub fn api_key(mut self, provider: Provider, key: impl Into<String>) -> Self {
        self.api_keys.insert(provider.as_str(), key.into());
        self
    }

    /// Route a capability to a specific provider priority list.
    ///
    /// Providers referenced in the route are automatically added to the
    /// initialisation list if not already present. If omitted for a capability,
    /// Yahoo is used as default.
    pub fn route(
        self,
        cap: crate::providers::Capability,
        providers: impl IntoIterator<Item = Provider>,
    ) -> Self {
        self.insert_route(cap, providers, None)
    }

    /// Route a capability, overriding [`fetch`](Self::fetch) for it alone.
    ///
    /// Lets a quota-limited capability stay sequential while another races
    /// its providers.
    pub fn route_with(
        self,
        cap: crate::providers::Capability,
        providers: impl IntoIterator<Item = Provider>,
        fetch: Fetch,
    ) -> Self {
        self.insert_route(cap, providers, Some(fetch))
    }

    fn insert_route(
        mut self,
        cap: crate::providers::Capability,
        providers: impl IntoIterator<Item = Provider>,
        fetch: Option<Fetch>,
    ) -> Self {
        let providers: Vec<Provider> = providers.into_iter().collect();
        for provider in &providers {
            // A Custom id has no arm in `build_providers`; it arrives only
            // through `with_adapter`.
            if matches!(provider, Provider::Custom(_)) {
                continue;
            }
            if !self.provider_ids.contains(provider) {
                self.provider_ids.push(*provider);
            }
        }
        self.routes
            .map
            .insert(cap, super::routes::Route { providers, fetch });
        self
    }

    /// Set the region (automatically sets lang and region code).
    pub fn region(mut self, region: crate::constants::Region) -> Self {
        self.config.lang = region.lang().to_string();
        self.config.region = region.region().to_string();
        self
    }

    /// Set the language code (e.g., "en-US", "ja-JP").
    ///
    /// Inherited by every `Ticker`/`Tickers` handle created from the built
    /// [`Providers`]. With the `translation` feature, a non-English language
    /// translates text fields on those handles automatically.
    pub fn lang(mut self, lang: impl Into<String>) -> Self {
        self.config.lang = lang.into();
        self
    }

    /// Set the region code (e.g., "US", "JP", "DE").
    ///
    /// For standard countries, prefer `.region()` instead to ensure correct
    /// lang/region pairing.
    pub fn region_code(mut self, region: impl Into<String>) -> Self {
        self.config.region = region.into();
        self
    }

    /// Set the HTTP request timeout.
    pub fn timeout(mut self, t: Duration) -> Self {
        self.config.timeout = t;
        self
    }

    /// Set the proxy URL.
    pub fn proxy(mut self, p: impl Into<String>) -> Self {
        self.config.proxy = Some(p.into());
        self
    }

    /// Opt into retrying `FinanceError::RateLimited` errors during dispatch
    /// See [`RetryPolicy`] for the exact semantics.
    ///
    /// **Default is no retry** — omitting this call preserves the exact
    /// prior behavior: a `RateLimited` error is treated like any other
    /// failure and dispatch moves straight to the next routed provider.
    pub fn retry(mut self, policy: RetryPolicy) -> Self {
        self.retry = Some(policy);
        self
    }

    /// Register an adapter this crate does not build itself.
    ///
    /// Route to it by the id its [`ProviderCore::id`](crate::ProviderCore::id)
    /// returns, usually [`Provider::Custom`]. Registering alone does not route
    /// anything: a capability with no explicit route still falls back to its
    /// default provider.
    ///
    /// ```no_run
    /// # use std::sync::Arc;
    /// # use finance_query::{Capability, Provider, Providers, ProviderAdapter};
    /// # async fn f(my_adapter: Arc<dyn ProviderAdapter>) -> finance_query::Result<()> {
    /// let providers = Providers::builder()
    ///     .with_adapter(my_adapter)
    ///     .route(Capability::ECONOMIC, [Provider::custom("my-source")])
    ///     .build()
    ///     .await?;
    /// # let _ = providers;
    /// # Ok(())
    /// # }
    /// ```
    #[must_use]
    pub fn with_adapter(mut self, adapter: Arc<dyn crate::ProviderAdapter>) -> Self {
        self.adapters.push(adapter);
        self
    }

    /// Build the [`Providers`] instance, initialising all configured providers.
    pub async fn build(self) -> Result<Providers> {
        for provider in self.request_limits.keys().chain(self.endpoints.keys()) {
            if !self.api_keys.contains_key(provider) {
                return Err(crate::FinanceError::InvalidParameter {
                    param: "provider_options".into(),
                    reason: format!("options for `{provider}` require an explicit API key"),
                });
            }
        }
        let budgets: Vec<&'static str> = self.request_limits.keys().copied().collect();
        let endpoints: Vec<&'static str> = self.endpoints.keys().copied().collect();
        if self.request_limits.values().any(|limit| *limit == 0) {
            return Err(crate::FinanceError::InvalidParameter {
                param: "requests_per_minute".into(),
                reason: "limit must be positive".into(),
            });
        }
        for endpoint in self.endpoints.values() {
            let valid = reqwest::Url::parse(endpoint).is_ok_and(|url| {
                (url.scheme() == "https"
                    || (url.scheme() == "http"
                        && matches!(url.host_str(), Some("localhost" | "127.0.0.1" | "[::1]"))))
                    && url.host_str().is_some()
                    && url.username().is_empty()
                    && url.password().is_none()
                    && url.query().is_none()
                    && url.fragment().is_none()
                    && url.path() == "/"
            });
            if !valid {
                return Err(crate::FinanceError::InvalidParameter {
                    param: "endpoint".into(),
                    reason: "expected an HTTPS or loopback HTTP origin without credentials".into(),
                });
            }
        }
        #[cfg(feature = "translation")]
        crate::translation::Lang::parse(&self.config.lang)?;
        for adapter in &self.adapters {
            let id = adapter.id();
            // `from_id_str` resolves interned custom ids too, so ask the
            // built-in list directly.
            if let Provider::Custom(custom) = id
                && Provider::all()
                    .iter()
                    .any(|p| p.as_str() == custom.as_str())
            {
                return Err(crate::FinanceError::InvalidParameter {
                    param: "adapter".to_string(),
                    reason: format!(
                        "custom provider id `{}` collides with a built-in",
                        custom.as_str()
                    ),
                });
            }
            let duplicate = self.provider_ids.contains(&id)
                || self.adapters.iter().filter(|a| a.id() == id).count() > 1;
            if duplicate {
                return Err(crate::FinanceError::InvalidParameter {
                    param: "adapter".to_string(),
                    reason: format!("provider id `{id}` is already configured"),
                });
            }
        }
        let lang = self.config.lang.clone();
        let mut keys = crate::adapters::keys::KeyMap::new();
        for (provider_key, api_key) in self.api_keys {
            if api_key.trim().is_empty() {
                return Err(crate::FinanceError::InvalidParameter {
                    param: provider_key.to_string(),
                    reason: "API key must not be empty".to_string(),
                });
            }
            let mut key = crate::adapters::keys::ScopedKey::new(api_key, self.config.timeout);
            key.rpm = self.request_limits.get(provider_key).copied();
            key.base_url = self
                .endpoints
                .get(provider_key)
                .map(|s| s.trim_end_matches('/').to_string());
            keys.insert(provider_key, key);
        }
        // `initialize` builds each keyed client, so the scope has to cover
        // construction as well as dispatch.
        let set = crate::adapters::keys::scope(
            Arc::new(keys.clone()),
            build_providers(&self.provider_ids, self.adapters, &self.config, self.routes),
        )
        .await?
        .with_api_keys(keys)
        .with_retry_policy(self.retry);
        check_scoped_options(&set, "requests_per_minute", &budgets, |p| {
            p.accepts_request_budget()
        })?;
        check_scoped_options(&set, "endpoint", &endpoints, |p| p.accepts_endpoint())?;
        Ok(Providers {
            set: Arc::new(set),
            lang,
        })
    }
}