Skip to main content

typesafe_ai/
ureq_client.rs

1use std::fmt;
2use std::io::Read;
3use std::thread;
4use std::time::Instant;
5
6use http::header::AUTHORIZATION;
7
8use crate::transport::{RawResponse, ValidatedConfig, is_retryable, retry_delay};
9use crate::{
10    ClientConfig, Error, EvaluationEvent, EvaluationFailure, Request, Response, SyncClient,
11};
12
13/// Errors returned by [`UreqClient`].
14pub type UreqError = Error<ureq::Error>;
15
16/// Blocking TypeSafe client backed by ureq.
17///
18/// ```no_run
19/// use typesafe_ai::{Question, Request, UreqClient};
20///
21/// # fn evaluate() -> Result<(), Box<dyn std::error::Error>> {
22/// let client = UreqClient::new(std::env::var("TYPESAFE_API_KEY")?)?;
23/// let request = Request::new("Please refund duplicate charge 1042.")
24///     .with_question("is_billing", Question::noul("Is this a billing request?"));
25/// let response = client.evaluate(&request)?;
26/// # let _ = response;
27/// # Ok(())
28/// # }
29/// ```
30#[derive(Clone)]
31pub struct UreqClient {
32    agent: ureq::Agent,
33    config: ValidatedConfig,
34}
35
36impl UreqClient {
37    /// Creates a client with [`ClientConfig::default`].
38    ///
39    /// The API key is marked sensitive and omitted from the client's debug output.
40    pub fn new(api_key: impl Into<String>) -> Result<Self, UreqError> {
41        Self::with_config(api_key, ClientConfig::default())
42    }
43
44    /// Creates a client with explicit shared configuration.
45    pub fn with_config(
46        api_key: impl Into<String>,
47        config: ClientConfig,
48    ) -> Result<Self, UreqError> {
49        let config = ValidatedConfig::new(api_key.into(), config)
50            .map_err(Error::with_transport::<ureq::Error>)?;
51        let agent_config = ureq::Agent::config_builder()
52            .http_status_as_error(false)
53            .max_redirects(0)
54            .timeout_global(Some(config.timeout))
55            .build();
56        Ok(Self {
57            agent: ureq::Agent::new_with_config(agent_config),
58            config,
59        })
60    }
61
62    /// Creates a client around an existing ureq agent.
63    ///
64    /// Custom transport and resolver behavior from the agent is preserved. TypeSafe's
65    /// status, redirect, and timeout policies are applied to each request.
66    pub fn with_agent(
67        api_key: impl Into<String>,
68        config: ClientConfig,
69        agent: ureq::Agent,
70    ) -> Result<Self, UreqError> {
71        Ok(Self {
72            agent,
73            config: ValidatedConfig::new(api_key.into(), config)
74                .map_err(Error::with_transport::<ureq::Error>)?,
75        })
76    }
77
78    /// Evaluates every question in `request` against its shared state.
79    ///
80    /// The request is validated before any HTTP exchange. HTTP 429 and 529 responses are
81    /// retried according to [`ClientConfig::max_retries`].
82    pub fn evaluate(&self, request: &Request) -> Result<Response, UreqError> {
83        SyncClient::evaluate(self, request)
84    }
85
86    /// Creates a lazy iterator over attempt failures and the terminal result.
87    ///
88    /// Construction performs no validation, waiting, or HTTP work. Each call to `next`
89    /// drives at most one HTTP attempt and yields failures before any retry delay. See
90    /// [`SyncClient::evaluate_events`] for retry timing and interruption behavior.
91    ///
92    /// ```no_run
93    /// use typesafe_ai::{UreqClient, Request};
94    ///
95    /// # fn observe(client: &UreqClient, request: &Request) {
96    /// for event in client.evaluate_events(request) {
97    ///     println!("{event:?}");
98    /// }
99    /// # }
100    /// ```
101    pub fn evaluate_events(
102        &self,
103        request: &Request,
104    ) -> impl Iterator<Item = EvaluationEvent<ureq::Error>> {
105        let mut validated = false;
106        let mut done = false;
107        let mut retries = 0_u32;
108        let mut retry_deadline: Option<Instant> = None;
109
110        std::iter::from_fn(move || {
111            if done {
112                return None;
113            }
114            if !validated {
115                validated = true;
116                if let Err(error) = request.validate() {
117                    done = true;
118                    return Some(EvaluationEvent::Failed(EvaluationFailure {
119                        error: error.with_transport::<ureq::Error>(),
120                        attempt: 0,
121                        retry_delay: None,
122                    }));
123                }
124            }
125            if let Some(deadline) = retry_deadline.take() {
126                thread::sleep(deadline.saturating_duration_since(Instant::now()));
127            }
128
129            let attempt = u64::from(retries) + 1;
130            let raw = match self.send_attempt(request) {
131                Ok(raw) => raw,
132                Err(error) => {
133                    done = true;
134                    return Some(EvaluationEvent::Failed(EvaluationFailure {
135                        error,
136                        attempt,
137                        retry_delay: None,
138                    }));
139                }
140            };
141            if raw.status.is_success() {
142                done = true;
143                return Some(match raw.into_response::<ureq::Error>() {
144                    Ok(response) => EvaluationEvent::Success(response),
145                    Err(error) => EvaluationEvent::Failed(EvaluationFailure {
146                        error,
147                        attempt,
148                        retry_delay: None,
149                    }),
150                });
151            }
152
153            let should_retry = is_retryable(raw.status) && retries < self.config.max_retries;
154            let delay = should_retry
155                .then(|| retry_delay(&raw.headers, retries))
156                .flatten();
157            if let Some(delay) = delay {
158                retries += 1;
159                retry_deadline = Some(Instant::now() + delay);
160            } else {
161                done = true;
162            }
163            Some(EvaluationEvent::Failed(EvaluationFailure {
164                error: raw.into_api_error::<ureq::Error>(attempt),
165                attempt,
166                retry_delay: delay,
167            }))
168        })
169    }
170
171    fn send_attempt(&self, request: &Request) -> Result<RawResponse, UreqError> {
172        let mut response = self
173            .agent
174            .post(self.config.endpoint.as_str())
175            .config()
176            .http_status_as_error(false)
177            .max_redirects(0)
178            .timeout_global(Some(self.config.timeout))
179            .build()
180            .header(AUTHORIZATION, self.config.authorization.clone())
181            .send_json(request)
182            .map_err(|error| map_transport_error(error, self.config.timeout))?;
183        let status = response.status();
184        let headers = response.headers().clone();
185        let mut body = Vec::new();
186        response
187            .body_mut()
188            .as_reader()
189            .read_to_end(&mut body)
190            .map_err(|error| map_transport_error(ureq::Error::from(error), self.config.timeout))?;
191        Ok(RawResponse {
192            status,
193            headers,
194            body,
195        })
196    }
197}
198
199fn map_transport_error(error: ureq::Error, timeout: std::time::Duration) -> UreqError {
200    match error {
201        ureq::Error::Timeout(_) => Error::Timeout { timeout },
202        error => Error::Transport(error),
203    }
204}
205
206impl SyncClient for UreqClient {
207    type TransportError = ureq::Error;
208
209    fn evaluate_events(
210        &self,
211        request: &Request,
212    ) -> impl Iterator<Item = EvaluationEvent<Self::TransportError>> {
213        UreqClient::evaluate_events(self, request)
214    }
215}
216
217impl fmt::Debug for UreqClient {
218    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
219        formatter
220            .debug_struct("UreqClient")
221            .field("endpoint", &self.config.endpoint)
222            .field("authorization", &"<redacted>")
223            .field("max_retries", &self.config.max_retries)
224            .field("timeout", &self.config.timeout)
225            .finish_non_exhaustive()
226    }
227}