Skip to main content

tessera/
async_client.rs

1//! Asyncio-native Tessera API client (`async fn` surface).
2
3#[cfg(feature = "polars")]
4use polars::prelude::{DataFrame, LazyFrame};
5
6use crate::base::{
7    PreparedRequest, datasets_request, download_request, parse_retry_after, partitions_request,
8    should_retry,
9};
10use crate::config::{ClientConfig, backoff_delay};
11use crate::error::{TesseraError, error_from_response};
12use crate::models::{
13    DatasetsResponse, DownloadBody, IntoCoins, IntoMonths, PartitionRef, PartitionsResponse,
14    download_urls,
15};
16#[cfg(any(feature = "polars", feature = "duckdb"))]
17use crate::readers::ResolvedPartition;
18use crate::readers::expand_refs;
19#[cfg(any(feature = "polars", feature = "duckdb"))]
20use crate::resolver::resolve_async;
21
22/// An async client for the Tessera API.
23///
24/// Mirror of [`crate::TesseraClient`] with `async fn`; use it inside tokio
25/// runtimes (including when the sync client would panic).
26pub struct AsyncTesseraClient {
27    config: ClientConfig,
28    http: reqwest::Client,
29}
30
31impl AsyncTesseraClient {
32    /// Create a client with defaults, resolving the key from `api_key` or
33    /// `$TESSERA_API_KEY`.
34    ///
35    /// # Errors
36    ///
37    /// Returns [`TesseraError::Configuration`] when no API key can be resolved.
38    pub fn new(api_key: Option<&str>) -> Result<Self, TesseraError> {
39        Self::from_config(ClientConfig::new(api_key)?)
40    }
41
42    /// Create a client from a fully-specified [`ClientConfig`].
43    ///
44    /// # Errors
45    ///
46    /// Returns [`TesseraError::Network`] when the HTTP client cannot be built.
47    pub fn from_config(config: ClientConfig) -> Result<Self, TesseraError> {
48        let http = reqwest::Client::builder()
49            .redirect(reqwest::redirect::Policy::none())
50            .default_headers(config.auth_headers())
51            .timeout(config.timeout)
52            .build()
53            .map_err(|err| TesseraError::Network(err.to_string()))?;
54        Ok(Self { config, http })
55    }
56
57    /// The resolved configuration this client was built with.
58    #[must_use]
59    pub fn config(&self) -> &ClientConfig {
60        &self.config
61    }
62
63    /// Close the client.
64    ///
65    /// `reqwest::Client` tears its pool down on drop; taking the client out
66    /// eagerly releases the handle for parity with the Python `aclose()`.
67    pub fn close(&mut self) {
68        self.http = reqwest::Client::new();
69    }
70
71    /// Send a prepared request, retrying transient failures.
72    async fn request(&self, prepared: &PreparedRequest) -> Result<reqwest::Response, TesseraError> {
73        send_with_retries(
74            &self.http,
75            &self.config.base_url,
76            self.config.max_retries,
77            prepared,
78        )
79        .await
80    }
81
82    /// Parse a success response body as JSON.
83    async fn json<T: serde::de::DeserializeOwned>(
84        &self,
85        response: reqwest::Response,
86    ) -> Result<T, TesseraError> {
87        parse_json(response).await
88    }
89
90    /// List every dataset visible to your entitlement.
91    ///
92    /// # Errors
93    ///
94    /// Returns any [`TesseraError`] the API or transport raises.
95    pub async fn datasets(&self) -> Result<DatasetsResponse, TesseraError> {
96        let response = self.request(&datasets_request()).await?;
97        self.json(response).await
98    }
99
100    /// List the partitions of `asset`, optionally filtered by coin/month.
101    ///
102    /// # Errors
103    ///
104    /// Returns any [`TesseraError`] the API or transport raises.
105    pub async fn partitions(
106        &self,
107        asset: &str,
108        coin: Option<&str>,
109        month: Option<&str>,
110    ) -> Result<PartitionsResponse, TesseraError> {
111        let response = self
112            .request(&partitions_request(asset, coin, month))
113            .await?;
114        self.json(response).await
115    }
116
117    /// Mint presigned download URLs for one partition.
118    ///
119    /// A finalised month is a single object ([`crate::DownloadResponse`]). The
120    /// open month is day-backed and answers with one URL per day
121    /// ([`crate::DayDownloadResponse`]); use [`download_urls`] to flatten either
122    /// shape into URLs.
123    ///
124    /// # Errors
125    ///
126    /// Returns any [`TesseraError`] the API or transport raises.
127    pub async fn download_url(
128        &self,
129        asset: &str,
130        coin: &str,
131        month: &str,
132    ) -> Result<DownloadBody, TesseraError> {
133        let response = self.request(&download_request(asset, coin, month)).await?;
134        self.json(response).await
135    }
136
137    /// Expand `(asset, coins, months)` into concrete partition references.
138    ///
139    /// # Errors
140    ///
141    /// Returns [`TesseraError::InvalidArgument`] on empty/invalid arguments.
142    pub fn partition_refs(
143        &self,
144        asset: &str,
145        coin: impl IntoCoins,
146        month: impl IntoMonths,
147    ) -> Result<Vec<PartitionRef>, TesseraError> {
148        let _ = self;
149        expand_refs(asset, coin, month)
150    }
151
152    /// Resolve presigned URLs for every ref, concurrently and order-preserving.
153    #[cfg(any(feature = "polars", feature = "duckdb"))]
154    async fn resolve(&self, refs: &[PartitionRef]) -> Result<Vec<ResolvedPartition>, TesseraError> {
155        let http = self.http.clone();
156        let base_url = self.config.base_url.clone();
157        let max_retries = self.config.max_retries;
158        resolve_async(
159            move |partition| {
160                let http = http.clone();
161                let base_url = base_url.clone();
162                async move {
163                    let prepared =
164                        download_request(&partition.asset, &partition.coin, &partition.month);
165                    let response =
166                        send_with_retries(&http, &base_url, max_retries, &prepared).await?;
167                    download_urls(parse_json(response).await?)
168                }
169            },
170            refs,
171        )
172        .await
173    }
174
175    /// Lazily scan one or more partitions into a Polars `LazyFrame`.
176    ///
177    /// # Errors
178    ///
179    /// Returns any [`TesseraError`] the API or transport raises.
180    #[cfg(feature = "polars")]
181    pub async fn scan(
182        &self,
183        asset: &str,
184        coin: impl IntoCoins,
185        month: impl IntoMonths,
186        columns: Option<&[&str]>,
187    ) -> Result<LazyFrame, TesseraError> {
188        let parts = self.resolve(&expand_refs(asset, coin, month)?).await?;
189        crate::readers::polars::build_lazyframe(&parts, columns)
190    }
191
192    /// Eagerly read one or more partitions into a Polars `DataFrame`.
193    ///
194    /// # Errors
195    ///
196    /// Returns any [`TesseraError`] the API or transport raises, including
197    /// [`TesseraError::PresignExpired`] for rejected presigned URLs.
198    #[cfg(feature = "polars")]
199    pub async fn read(
200        &self,
201        asset: &str,
202        coin: impl IntoCoins,
203        month: impl IntoMonths,
204        columns: Option<&[&str]>,
205    ) -> Result<DataFrame, TesseraError> {
206        let parts = self.resolve(&expand_refs(asset, coin, month)?).await?;
207        let lazy = crate::readers::polars::build_lazyframe(&parts, columns)?;
208        crate::readers::polars::collect(lazy)
209    }
210
211    /// Open one or more partitions as an in-memory DuckDB connection exposing
212    /// a `tessera` view for SQL querying.
213    ///
214    /// # Errors
215    ///
216    /// Returns any [`TesseraError`] the API or transport raises.
217    #[cfg(feature = "duckdb")]
218    pub async fn to_duckdb(
219        &self,
220        asset: &str,
221        coin: impl IntoCoins,
222        month: impl IntoMonths,
223        columns: Option<&[&str]>,
224    ) -> Result<duckdb::Connection, TesseraError> {
225        let parts = self.resolve(&expand_refs(asset, coin, month)?).await?;
226        let owned_columns: Option<Vec<String>> =
227            columns.map(|cols| cols.iter().map(|c| (*c).to_string()).collect());
228        tokio::task::spawn_blocking(move || {
229            let borrowed: Option<Vec<&str>> = owned_columns
230                .as_deref()
231                .map(|cols| cols.iter().map(String::as_str).collect());
232            crate::readers::duckdb::build_relation(&parts, borrowed.as_deref())
233        })
234        .await
235        .map_err(|err| TesseraError::Network(format!("duckdb task failed: {err}")))?
236    }
237}
238
239/// Send a request with the shared retry policy (transient network errors and
240/// retryable statuses back off exponentially, honouring `Retry-After`).
241async fn send_with_retries(
242    http: &reqwest::Client,
243    base_url: &str,
244    max_retries: u32,
245    prepared: &PreparedRequest,
246) -> Result<reqwest::Response, TesseraError> {
247    for attempt in 0..=max_retries {
248        let last = attempt == max_retries;
249        let sent = http
250            .get(format!("{base_url}{}", prepared.path))
251            .query(&prepared.params)
252            .send()
253            .await;
254        match sent {
255            Err(err) if err.is_connect() || err.is_timeout() || err.is_request() => {
256                if last {
257                    return Err(TesseraError::Network(format!(
258                        "network error contacting Tessera: {err}"
259                    )));
260                }
261                tokio::time::sleep(backoff_delay(attempt, None)).await;
262            }
263            Ok(response) if !last && should_retry(response.status().as_u16()) => {
264                let retry_after = parse_retry_after(response.headers());
265                tokio::time::sleep(backoff_delay(attempt, retry_after)).await;
266            }
267            Ok(response) => {
268                if response.status().is_success() {
269                    return Ok(response);
270                }
271                let status = response.status().as_u16();
272                let body = response
273                    .bytes()
274                    .await
275                    .map_err(|err| TesseraError::Network(err.to_string()))?;
276                return Err(error_from_response(status, &body));
277            }
278            Err(err) => {
279                return Err(TesseraError::Network(format!(
280                    "network error contacting Tessera: {err}"
281                )));
282            }
283        }
284    }
285    unreachable!("retry loop always returns")
286}
287
288/// Parse a success response body as JSON.
289async fn parse_json<T: serde::de::DeserializeOwned>(
290    response: reqwest::Response,
291) -> Result<T, TesseraError> {
292    let body = response
293        .bytes()
294        .await
295        .map_err(|err| TesseraError::Network(err.to_string()))?;
296    serde_json::from_slice(&body).map_err(|err| TesseraError::Network(err.to_string()))
297}
298
299impl std::fmt::Debug for AsyncTesseraClient {
300    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
301        f.debug_struct("AsyncTesseraClient")
302            .field("base_url", &self.config.base_url)
303            .field("timeout", &self.config.timeout)
304            .finish_non_exhaustive()
305    }
306}