Skip to main content

tensorlake/
client.rs

1//! HTTP client that interacts with the Tensorlake Cloud API.
2use eventsource_stream::Eventsource;
3use futures::{Stream, StreamExt};
4use reqwest::{
5    Method, Request, Response, StatusCode,
6    header::{ACCEPT, CONTENT_LENGTH, HeaderMap, HeaderValue, InvalidHeaderValue},
7};
8use reqwest_middleware::{ClientBuilder as ReqwestClientBuilder, ClientWithMiddleware, Middleware};
9use serde::de::DeserializeOwned;
10use std::{
11    ops::{Deref, DerefMut},
12    pin::Pin,
13    result::Result,
14    sync::{Arc, Once},
15    time::Duration,
16};
17
18use crate::error::SdkError;
19
20pub const REQUEST_TIMEOUT_HEADER: &str = "X-Tensorlake-Request-Timeout-Ms";
21
22/// Wraps any SDK operation result with the W3C `trace_id` so callers can
23/// correlate the request with its server-side spans in Datadog APM or any
24/// other OTEL-compatible backend.
25///
26/// All fields and methods of `T` are accessible via `Deref`/`DerefMut`, so
27/// most existing code compiles unchanged. Use `into_inner()` when you need an
28/// owned `T`.
29///
30/// # Example
31///
32/// ```rust,ignore
33/// let result = sdk.sandboxes("ns", false).create(&request).await?;
34/// println!("{}", result.sandbox_id); // existing field — accessible via Deref
35/// println!("{}", result.trace_id);   // new: look this up in Datadog APM
36/// ```
37#[derive(Debug, Clone)]
38pub struct Traced<T> {
39    /// W3C trace ID for this request (32 lowercase hex chars).
40    pub trace_id: String,
41    value: T,
42}
43
44impl<T> Traced<T> {
45    pub fn new(trace_id: String, value: T) -> Self {
46        Self { trace_id, value }
47    }
48
49    pub fn into_inner(self) -> T {
50        self.value
51    }
52
53    pub fn map<U>(self, f: impl FnOnce(T) -> U) -> Traced<U> {
54        Traced {
55            trace_id: self.trace_id,
56            value: f(self.value),
57        }
58    }
59}
60
61impl<T> Deref for Traced<T> {
62    type Target = T;
63    fn deref(&self) -> &T {
64        &self.value
65    }
66}
67
68impl<T> DerefMut for Traced<T> {
69    fn deref_mut(&mut self) -> &mut T {
70        &mut self.value
71    }
72}
73
74/// HTTP client that interacts with the Tensorlake Cloud API.
75#[derive(Clone)]
76pub struct Client {
77    /// Base URL of the API, used to construct the full URL for each request.
78    base_url: String,
79    /// Base client to construct more specialized clients, used to construct EventSource requests.
80    base_client: reqwest::Client,
81    /// Client with user provided middlewares. Used to perform regular HTTP requests.
82    client: ClientWithMiddleware,
83    /// Default headers configured on the underlying clients.
84    default_headers: HeaderMap,
85    /// User-Agent configured on the underlying client.
86    user_agent: String,
87    /// Total request timeout configured for this client.
88    timeout: Option<Duration>,
89}
90
91/// Builder for creating a [`Client`] with a fluent API.
92///
93/// The base URL is required, while bearer token, middlewares, and scope are optional.
94pub struct ClientBuilder {
95    base_url: String,
96    bearer_token: Option<String>,
97    middlewares: Vec<Arc<dyn Middleware + 'static>>,
98    organization_id: Option<String>,
99    project_id: Option<String>,
100    user_agent: Option<String>,
101    timeout: Option<Duration>,
102}
103
104impl ClientBuilder {
105    pub(crate) fn base_url(&self) -> &str {
106        &self.base_url
107    }
108
109    /// Create a new [`ClientBuilder`] with the specified base URL.
110    ///
111    /// # Arguments
112    ///
113    /// * `base_url` - The base URL of the API
114    pub fn new(base_url: &str) -> Self {
115        Self {
116            base_url: base_url.to_string(),
117            bearer_token: None,
118            middlewares: Vec::new(),
119            organization_id: None,
120            project_id: None,
121            user_agent: None,
122            timeout: None,
123        }
124    }
125
126    /// Override the User-Agent header sent with every request.
127    ///
128    /// Defaults to `tensorlake-rust-sdk/{CARGO_PKG_VERSION}`. Callers that
129    /// wrap this client (e.g. the Python SDK via PyO3) should set a value like
130    /// `tensorlake-python-sdk/{version}` so server logs can distinguish traffic
131    /// by SDK language.
132    pub fn user_agent(mut self, ua: &str) -> Self {
133        self.user_agent = Some(ua.to_string());
134        self
135    }
136
137    /// Set the total timeout for each HTTP request.
138    pub fn timeout(mut self, timeout: Duration) -> Self {
139        self.timeout = Some(timeout);
140        self
141    }
142
143    /// Set the bearer token for authentication.
144    pub fn bearer_token(mut self, token: &str) -> Self {
145        self.bearer_token = Some(token.to_string());
146        self
147    }
148
149    /// Add middleware to the client.
150    pub fn middleware<M>(mut self, middleware: M) -> Self
151    where
152        M: Middleware + 'static,
153    {
154        self.middlewares.push(Arc::new(middleware));
155        self
156    }
157
158    /// Add multiple middlewares to the client.
159    pub fn middlewares(mut self, middlewares: Vec<Arc<dyn Middleware + 'static>>) -> Self {
160        self.middlewares = middlewares;
161        self
162    }
163
164    /// Set the organization and project scope.
165    pub fn scope(mut self, organization_id: &str, project_id: &str) -> Self {
166        self.organization_id = Some(organization_id.to_string());
167        self.project_id = Some(project_id.to_string());
168        self
169    }
170
171    /// Build the [`Client`].
172    ///
173    /// # Errors
174    ///
175    /// Returns an error if the HTTP client cannot be created or configured.
176    pub fn build(self) -> Result<Client, SdkError> {
177        let mut default_headers = HeaderMap::new();
178
179        // Add bearer token if provided
180        if let Some(token) = &self.bearer_token {
181            default_headers = new_default_headers(token)?;
182        }
183
184        // Add scope headers if provided
185        if let Some(org_id) = &self.organization_id {
186            default_headers.insert("X-Forwarded-Organization-Id", str_to_header_value(org_id)?);
187        }
188        if let Some(project_id) = &self.project_id {
189            default_headers.insert("X-Forwarded-Project-Id", str_to_header_value(project_id)?);
190        }
191
192        let ua = self
193            .user_agent
194            .as_deref()
195            .unwrap_or(concat!("tensorlake-rust-sdk/", env!("CARGO_PKG_VERSION")));
196        let base_client = new_base_client(&default_headers, ua, self.timeout)?;
197        let mut builder = ReqwestClientBuilder::new(base_client.clone());
198
199        for middleware in &self.middlewares {
200            builder = builder.with_arc(middleware.clone());
201        }
202
203        let client = builder.build();
204
205        Ok(Client {
206            base_url: self.base_url,
207            base_client,
208            client,
209            default_headers,
210            user_agent: ua.to_string(),
211            timeout: self.timeout,
212        })
213    }
214}
215
216type EventSourceStream<T> = Pin<Box<dyn Stream<Item = Result<T, SdkError>> + Send>>;
217
218impl Client {
219    pub(crate) fn base_url(&self) -> &str {
220        &self.base_url
221    }
222
223    pub(crate) fn default_headers(&self) -> HeaderMap {
224        self.default_headers.clone()
225    }
226
227    /// Create a new client that shares the same underlying HTTP connection pool but uses a
228    /// different base URL. Cloning `reqwest::Client` shares its Arc-backed connection pool, so
229    /// HTTP/2 connections established for one base URL can be reused (via connection coalescing)
230    /// when talking to another host that resolves to the same IP with the same TLS certificate.
231    pub fn with_base_url(&self, new_url: &str) -> Self {
232        let client = ReqwestClientBuilder::new(self.base_client.clone()).build();
233        Self {
234            base_url: new_url.to_string(),
235            base_client: self.base_client.clone(),
236            client,
237            default_headers: self.default_headers.clone(),
238            user_agent: self.user_agent.clone(),
239            timeout: self.timeout,
240        }
241    }
242
243    /// Create a new client for a different base URL without a total request timeout.
244    ///
245    /// Sandbox proxy clients use this for long-running process and follow streams,
246    /// where the server-side process timeout is independent from lifecycle HTTP deadlines.
247    pub fn with_base_url_without_timeout(&self, new_url: &str) -> Result<Self, SdkError> {
248        self.with_base_url_and_timeout(new_url, None)
249    }
250
251    /// Create a new client for a different base URL with an explicit total request timeout.
252    pub fn with_base_url_and_timeout(
253        &self,
254        new_url: &str,
255        timeout: Option<Duration>,
256    ) -> Result<Self, SdkError> {
257        let base_client = new_base_client(&self.default_headers, &self.user_agent, timeout)?;
258        let client = ReqwestClientBuilder::new(base_client.clone()).build();
259        Ok(Self {
260            base_url: new_url.to_string(),
261            base_client,
262            client,
263            default_headers: self.default_headers.clone(),
264            user_agent: self.user_agent.clone(),
265            timeout,
266        })
267    }
268
269    fn prepare_request(&self, request: &mut Request) {
270        let (traceparent, _) = generate_traceparent();
271        if let Ok(value) = traceparent.parse::<HeaderValue>() {
272            request.headers_mut().insert("traceparent", value);
273        }
274        self.insert_request_timeout_header(request);
275    }
276
277    fn prepare_traced_request(&self, request: &mut Request) -> String {
278        let (traceparent, trace_id) = generate_traceparent();
279        if let Ok(value) = traceparent.parse::<HeaderValue>() {
280            request.headers_mut().insert("traceparent", value);
281        }
282        self.insert_request_timeout_header(request);
283        trace_id
284    }
285
286    fn insert_request_timeout_header(&self, request: &mut Request) {
287        let Some(timeout) = self.timeout else {
288            return;
289        };
290        let millis = timeout.as_millis();
291        if millis == 0 {
292            return;
293        }
294        if let Ok(value) = HeaderValue::from_str(&millis.to_string()) {
295            request.headers_mut().insert(REQUEST_TIMEOUT_HEADER, value);
296        }
297    }
298
299    /// Execute an HTTP request. Injects a W3C `traceparent` header for server-side
300    /// correlation. Use [`execute_traced`] or [`execute_json`] when you need the
301    /// `trace_id` returned to the caller.
302    pub async fn execute(&self, mut request: Request) -> Result<Response, SdkError> {
303        self.prepare_request(&mut request);
304        let response = self.client.execute(request).await?;
305        self.handle_response(response).await
306    }
307
308    /// Execute an HTTP request without mapping non-success statuses to [`SdkError`].
309    /// Injects a W3C `traceparent` header for server-side correlation.
310    pub async fn execute_raw(&self, mut request: Request) -> Result<Response, SdkError> {
311        self.prepare_request(&mut request);
312        let response = self.client.execute(request).await?;
313        Ok(response)
314    }
315
316    /// Execute an HTTP request, inject a W3C `traceparent` header, and return
317    /// the raw response alongside the `trace_id`. Use this when you need the
318    /// `trace_id` but want to handle the response body yourself.
319    pub async fn execute_traced(&self, mut request: Request) -> Result<Traced<Response>, SdkError> {
320        let trace_id = self.prepare_traced_request(&mut request);
321        let response = self.client.execute(request).await?;
322        let response = self.handle_response(response).await?;
323        Ok(Traced::new(trace_id, response))
324    }
325
326    /// Execute an HTTP request, inject a W3C `traceparent` header, deserialize
327    /// the JSON response body, and return both alongside the `trace_id`.
328    ///
329    /// This is the primary building block for service-level methods that return
330    /// structured responses. The `trace_id` lets callers look up the full
331    /// server-side cascade in Datadog APM.
332    pub async fn execute_json<T: DeserializeOwned>(
333        &self,
334        request: Request,
335    ) -> Result<Traced<T>, SdkError> {
336        let traced = self.execute_traced(request).await?;
337        Self::decode_traced_json(traced).await
338    }
339
340    /// Execute an HTTP request and deserialize JSON if the status is success or
341    /// explicitly listed in `allowed_statuses`.
342    pub async fn execute_json_allow_status<T: DeserializeOwned>(
343        &self,
344        mut request: Request,
345        allowed_statuses: &[StatusCode],
346    ) -> Result<Traced<T>, SdkError> {
347        let trace_id = self.prepare_traced_request(&mut request);
348        let response = self.client.execute(request).await?;
349        let response =
350            if response.status().is_success() || allowed_statuses.contains(&response.status()) {
351                response
352            } else {
353                self.handle_response(response).await?
354            };
355        Self::decode_traced_json(Traced::new(trace_id, response)).await
356    }
357
358    async fn decode_traced_json<T: DeserializeOwned>(
359        traced: Traced<Response>,
360    ) -> Result<Traced<T>, SdkError> {
361        let trace_id = traced.trace_id.clone();
362        let bytes = traced.into_inner().bytes().await?;
363        let jd = &mut serde_json::Deserializer::from_slice(bytes.as_ref());
364        let value: T = serde_path_to_error::deserialize(jd)?;
365        Ok(Traced::new(trace_id, value))
366    }
367
368    pub fn request(
369        &self,
370        method: reqwest::Method,
371        path: &str,
372    ) -> reqwest_middleware::RequestBuilder {
373        self.client.request(method, self.base_url.clone() + path)
374    }
375
376    pub async fn build_event_source_request<T>(
377        &self,
378        path: &str,
379    ) -> Result<Traced<EventSourceStream<T>>, SdkError>
380    where
381        T: DeserializeOwned,
382    {
383        let (traceparent, trace_id) = generate_traceparent();
384        let mut request_builder = self
385            .base_client
386            .get(self.base_url.clone() + path)
387            .header(ACCEPT, "text/event-stream")
388            .header("traceparent", traceparent);
389        if let Some(timeout) = self.timeout {
390            let millis = timeout.as_millis();
391            if millis > 0 {
392                request_builder =
393                    request_builder.header(REQUEST_TIMEOUT_HEADER, millis.to_string());
394            }
395        }
396        let response = request_builder.send().await?;
397
398        let stream = response
399            .bytes_stream()
400            .eventsource()
401            .filter_map(move |event| async move {
402                match event {
403                    Ok(msg) => match serde_json::from_str::<T>(&msg.data) {
404                        Ok(evt) => Some(Ok(evt)),
405                        Err(error) => Some(Err(SdkError::Json(error))),
406                    },
407                    Err(error) => Some(Err(SdkError::EventSourceError(error.to_string()))),
408                }
409            });
410        Ok(Traced::new(trace_id, Box::pin(stream)))
411    }
412
413    pub fn build_multipart_request(
414        &self,
415        method: reqwest::Method,
416        path: &str,
417        form: reqwest::multipart::Form,
418    ) -> Result<reqwest::Request, SdkError> {
419        self.request(method, path)
420            .multipart(form)
421            .build()
422            .map_err(Into::into)
423    }
424
425    pub fn build_empty_post_request(&self, path: &str) -> Result<reqwest::Request, SdkError> {
426        build_empty_post_request_from_builder(self.request(Method::POST, path))
427    }
428
429    pub fn build_bytes_post_request(
430        &self,
431        path: &str,
432        body: Vec<u8>,
433    ) -> Result<reqwest::Request, SdkError> {
434        build_bytes_post_request_from_builder(self.request(Method::POST, path), body)
435    }
436
437    /// Helper function to build POST, PUT or PATCH requests with JSON body
438    pub fn build_post_json_request(
439        &self,
440        method: reqwest::Method,
441        path: &str,
442        body: &impl serde::Serialize,
443    ) -> Result<reqwest::Request, SdkError> {
444        Ok(self.request(method, path).json(body).build()?)
445    }
446
447    /// Helper function to build GET requests that return JSON responses
448    pub fn build_get_json_request(
449        &self,
450        path: &str,
451        query: Option<&[(&str, &str)]>,
452    ) -> Result<reqwest::Request, SdkError> {
453        let mut req_builder = self.request(Method::GET, path);
454        if let Some(query) = query {
455            req_builder = req_builder.query(query);
456        }
457        Ok(req_builder.header(ACCEPT, "application/json").build()?)
458    }
459
460    /// Helper function to handle HTTP responses and convert status codes to appropriate errors
461    async fn handle_response(
462        &self,
463        response: reqwest::Response,
464    ) -> Result<reqwest::Response, SdkError> {
465        let status = response.status();
466
467        match status {
468            StatusCode::UNAUTHORIZED => {
469                let message = body_message_or_default(response, "Unauthorized").await;
470                Err(SdkError::Authentication(message))
471            }
472            StatusCode::FORBIDDEN => {
473                let message = body_message_or_default(response, "Forbidden").await;
474                Err(SdkError::Authorization(message))
475            }
476            status if status.is_server_error() => {
477                let message = body_message_or_default(response, "Server error").await;
478                Err(SdkError::ServerError { status, message })
479            }
480            status if !status.is_success() => {
481                let message = body_message_or_default(response, "Request failed").await;
482                Err(SdkError::ServerError { status, message })
483            }
484            _ => Ok(response),
485        }
486    }
487}
488
489pub(crate) fn build_empty_post_request_from_builder(
490    builder: reqwest_middleware::RequestBuilder,
491) -> Result<reqwest::Request, SdkError> {
492    builder
493        .header(CONTENT_LENGTH, "0")
494        .build()
495        .map_err(Into::into)
496}
497
498pub(crate) fn build_bytes_post_request_from_builder(
499    builder: reqwest_middleware::RequestBuilder,
500    body: Vec<u8>,
501) -> Result<reqwest::Request, SdkError> {
502    let len = body.len().to_string();
503    builder
504        .header(CONTENT_LENGTH, len)
505        .body(body)
506        .build()
507        .map_err(Into::into)
508}
509
510fn generate_traceparent() -> (String, String) {
511    let trace_id = hex::encode(rand::random::<[u8; 16]>());
512    let span_id = hex::encode(rand::random::<[u8; 8]>());
513    (format!("00-{trace_id}-{span_id}-01"), trace_id)
514}
515
516async fn body_message_or_default(response: Response, default: &str) -> String {
517    let message = response
518        .text()
519        .await
520        .unwrap_or_else(|_| default.to_string());
521    if message.is_empty() {
522        default.to_string()
523    } else {
524        message
525    }
526}
527
528fn new_default_headers(bearer_token: &str) -> Result<HeaderMap, SdkError> {
529    let mut headers = HeaderMap::new();
530    headers.insert(
531        "Authorization",
532        str_to_header_value(&format!("Bearer {}", bearer_token))?,
533    );
534    Ok(headers)
535}
536
537fn str_to_header_value(value: &str) -> Result<HeaderValue, SdkError> {
538    value
539        .parse()
540        .map_err(|e: InvalidHeaderValue| SdkError::InvalidHeaderValue(e.to_string()))
541}
542
543fn ensure_rustls_provider() {
544    static INSTALL_PROVIDER: Once = Once::new();
545    INSTALL_PROVIDER.call_once(|| {
546        let _ = rustls::crypto::ring::default_provider().install_default();
547    });
548}
549
550fn new_base_client(
551    headers: &HeaderMap,
552    user_agent: &str,
553    timeout: Option<Duration>,
554) -> Result<reqwest::Client, SdkError> {
555    ensure_rustls_provider();
556
557    let mut builder = reqwest::Client::builder()
558        .user_agent(user_agent)
559        .default_headers(headers.clone());
560    if let Some(timeout) = timeout {
561        builder = builder.timeout(timeout);
562    }
563    let client = builder.build()?;
564    Ok(client)
565}
566
567#[cfg(test)]
568mod tests {
569    use super::ensure_rustls_provider;
570
571    #[test]
572    fn installs_rustls_provider() {
573        ensure_rustls_provider();
574        assert!(
575            rustls::crypto::CryptoProvider::get_default().is_some(),
576            "rustls crypto provider should be installed"
577        );
578    }
579}