Skip to main content

jev/
client.rs

1//! `Client`: the async HTTP client, retry loop, and request-building logic.
2
3use std::{
4    sync::Arc,
5    time::{Duration, Instant},
6};
7
8use reqwest::header::{AUTHORIZATION, HeaderValue};
9use secrecy::{ExposeSecret, SecretString};
10use tracing::{debug, instrument, warn};
11
12use crate::{
13    answer::Answers,
14    cases::{Case, CaseResult},
15    config::{Config, Surface},
16    error::Error,
17    model::Model,
18    provider::Provider,
19    question::Questions,
20    state::State,
21    typed::{Choice, ChoiceOptions, Decision, Noul, Score, ScoreLevels},
22    util::estimate_tokens,
23    wire::{DecisionRequest, Response, ResponseMeta, TraceConfig},
24};
25
26/// Maximum bytes read from a response body before parsing.
27///
28/// This bounds memory use against a hostile or misbehaving gateway; it is well
29/// above any legitimate Jev response, which is a small JSON object.
30const MAX_RESPONSE_BODY_BYTES: usize = 10 * 1024 * 1024;
31
32/// Environment variable read first by [`Client::from_env`].
33const ENV_API_KEY: &str = "JEV_API_KEY";
34/// Optional environment variable selecting the hosted provider.
35const ENV_PROVIDER: &str = "JEV_PROVIDER";
36/// Optional environment variable overriding the API base URL.
37const ENV_BASE_URL: &str = "JEV_BASE_URL";
38
39/// Maximum API key length, in bytes, before building an authorization header.
40const MAX_API_KEY_BYTES: usize = 4096;
41
42/// A typed decision plus the response envelope: id, model snapshot, usage, and cost.
43///
44/// [`Client::decide`] is the 90% API and deliberately drops this envelope;
45/// [`Client::decide_with`] returns `Decided<D>` for callers that record cost or the
46/// dated model snapshot.
47#[derive(Debug, Clone, PartialEq)]
48pub struct Decided<D> {
49    /// The typed decision.
50    pub value: D,
51    /// The response envelope: id, model snapshot, usage, cost, latency.
52    pub meta: ResponseMeta,
53}
54
55/// Per-call request options for [`Client::decide_with`] and [`Client::raw`].
56///
57/// Fields left unset fall back to the [`Client`]'s configured defaults
58/// (`with_model`, `with_session_id`, `with_user`).
59#[derive(Debug, Clone)]
60pub struct RequestOptions<'a> {
61    state: State,
62    questions: Option<&'a Questions>,
63    model: Option<Model>,
64    session_id: Option<String>,
65    user: Option<String>,
66    trace: Option<TraceConfig>,
67}
68
69impl<'a> RequestOptions<'a> {
70    /// Starts a `RequestOptions` for the given state.
71    #[must_use]
72    pub fn new(state: impl Into<State>) -> Self {
73        RequestOptions {
74            state: state.into(),
75            questions: None,
76            model: None,
77            session_id: None,
78            user: None,
79            trace: None,
80        }
81    }
82
83    /// Sets the questions to send. Required for [`Client::raw`]; ignored by
84    /// [`Client::decide_with`], which always uses `D::questions()`.
85    #[must_use]
86    pub fn with_questions(mut self, questions: &'a Questions) -> Self {
87        self.questions = Some(questions);
88        self
89    }
90
91    /// Overrides the client's configured model for this call only.
92    #[must_use]
93    pub fn with_model(mut self, model: Model) -> Self {
94        self.model = Some(model);
95        self
96    }
97
98    /// Sets a session identifier grouping this request with related ones
99    /// (Decisions surface only; dropped on System One).
100    #[must_use]
101    pub fn with_session_id(mut self, session_id: impl Into<String>) -> Self {
102        self.session_id = Some(session_id.into());
103        self
104    }
105
106    /// Sets an application-defined user identifier (Decisions surface only; dropped
107    /// on System One).
108    #[must_use]
109    pub fn with_user(mut self, user: impl Into<String>) -> Self {
110        self.user = Some(user.into());
111        self
112    }
113
114    /// Sets opaque trace configuration (Decisions surface only; dropped on System One).
115    #[must_use]
116    pub fn with_trace(mut self, trace: TraceConfig) -> Self {
117        self.trace = Some(trace);
118        self
119    }
120}
121
122/// Async client for the Jev decision model.
123///
124/// `Client` is cheap to clone (an `Arc`-backed `reqwest::Client` plus one more
125/// `Arc`), so it drops straight into shared application state — a `OnceLock`,
126/// `Arc<Client>`, or framework extension.
127///
128/// # Examples
129///
130/// ```no_run
131/// # async fn run() -> Result<(), jev::Error> {
132/// use jev::Client;
133///
134/// let client = Client::from_env()?;
135/// let questions = jev::Questions::builder()
136///     .noul("refund", "Is the customer asking for money back?")
137///     .build()
138///     .unwrap();
139/// let response = client.ask("a support ticket about a refund", &questions).await?;
140/// println!("{}", response.answers.noul("refund")?);
141/// # Ok(())
142/// # }
143/// ```
144#[derive(Clone)]
145pub struct Client {
146    http: reqwest::Client,
147    api_key: Option<SecretString>,
148    config: Arc<Config>,
149}
150
151impl std::fmt::Debug for Client {
152    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
153        let api_key: &dyn std::fmt::Debug = if self.api_key.is_some() {
154            &"[REDACTED]"
155        } else {
156            &"none"
157        };
158        f.debug_struct("Client")
159            .field("provider", &self.provider())
160            .field("api_base", &self.api_base())
161            .field("model", &self.config.model)
162            .field("surface", &self.surface())
163            .field("api_key", api_key)
164            // `http` is deliberately omitted: `reqwest::Client`'s own `Debug` output
165            // is an internal connection-pool dump, not useful application diagnostics.
166            .finish_non_exhaustive()
167    }
168}
169
170impl Client {
171    /// Builds an `OpenRouter` client with the supplied API key and its own connection
172    /// pool, using whichever TLS backend feature is enabled (`rustls-tls` by default).
173    ///
174    /// # Errors
175    ///
176    /// Returns [`Error::Invalid`] when neither the `rustls-tls` nor `native-tls`
177    /// feature is enabled: with no TLS backend compiled in, this constructor cannot
178    /// build an HTTPS-capable `reqwest::Client`. Use [`Client::with_http`] with a
179    /// caller-supplied client in that configuration.
180    /// Also returns [`Error::Invalid`] for an empty key, a key over 4096 bytes,
181    /// or a key containing whitespace or non-ASCII characters.
182    ///
183    /// # Examples
184    ///
185    /// ```no_run
186    /// # fn run(key: String) -> Result<(), jev::Error> {
187    /// let client = jev::Client::new(key)?;
188    /// assert_eq!(client.provider(), jev::Provider::OpenRouter);
189    /// # Ok(())
190    /// # }
191    /// ```
192    pub fn new(api_key: impl Into<SecretString>) -> Result<Self, Error> {
193        Self::openrouter(api_key)
194    }
195
196    /// Builds an `OpenRouter` client directly from an `OpenRouter` API key.
197    ///
198    /// # Errors
199    ///
200    /// Returns the construction and key-validation errors documented by [`Client::new`].
201    ///
202    /// # Examples
203    ///
204    /// ```no_run
205    /// # fn run(key: String) -> Result<(), jev::Error> {
206    /// let client = jev::Client::openrouter(key)?;
207    /// assert_eq!(client.api_base().as_str(), "https://openrouter.ai/");
208    /// # Ok(())
209    /// # }
210    /// ```
211    pub fn openrouter(api_key: impl Into<SecretString>) -> Result<Self, Error> {
212        Self::for_provider(Provider::OpenRouter, api_key)
213    }
214
215    /// Builds a `TypeSafe` AI client directly from a `TypeSafe` API key.
216    ///
217    /// Uses `https://api.typesafe.ai/v1/systemone` and `TypeSafe` model IDs
218    /// (`jev-1.13.0` for the pinned default, `jev-latest` for [`Model::Latest`]).
219    ///
220    /// # Errors
221    ///
222    /// Returns the construction and key-validation errors documented by [`Client::new`].
223    ///
224    /// # Examples
225    ///
226    /// ```no_run
227    /// # fn run(key: String) -> Result<(), jev::Error> {
228    /// let client = jev::Client::typesafe(key)?;
229    /// assert_eq!(client.provider(), jev::Provider::TypeSafe);
230    /// # Ok(())
231    /// # }
232    /// ```
233    pub fn typesafe(api_key: impl Into<SecretString>) -> Result<Self, Error> {
234        Self::for_provider(Provider::TypeSafe, api_key)
235    }
236
237    /// Builds a client with a provider chosen at runtime and its matching API key.
238    ///
239    /// # Errors
240    ///
241    /// Returns the construction and key-validation errors documented by [`Client::new`].
242    ///
243    /// # Examples
244    ///
245    /// ```no_run
246    /// # fn run(key: String) -> Result<(), jev::Error> {
247    /// let client = jev::Client::for_provider(jev::Provider::TypeSafe, key)?;
248    /// # Ok(())
249    /// # }
250    /// ```
251    pub fn for_provider(
252        provider: Provider,
253        api_key: impl Into<SecretString>,
254    ) -> Result<Self, Error> {
255        let config = Config {
256            provider,
257            ..Config::default()
258        };
259        Self::from_config(build_http_client(config.timeout)?, api_key, config)
260    }
261
262    /// Builds a client that sends no `Authorization` header at all, for a System
263    /// One-compatible backend a caller hosts themselves.
264    ///
265    /// Some self-hosted backends (a local model server, a proxy that injects its
266    /// own credentials, a demo endpoint that takes no key) neither expect nor accept
267    /// a bearer token; every other `Client` constructor sends one unconditionally.
268    /// `base_url` may use `http://` for a loopback address without the opt-in
269    /// [`Client::with_api_base`] otherwise requires, since a backend a caller hosts
270    /// on their own machine is exactly the case that check exists to allow.
271    ///
272    /// # Errors
273    ///
274    /// Returns [`Error::Invalid`] when neither the `rustls-tls` nor `native-tls`
275    /// feature is enabled (see [`Client::new`]), or when `base_url` fails to parse
276    /// or uses a non-`https`, non-loopback scheme.
277    ///
278    /// # Examples
279    ///
280    /// ```
281    /// use jev::Client;
282    ///
283    /// # fn run() -> Result<(), jev::Error> {
284    /// let client = Client::without_api_key("http://127.0.0.1:8099")?;
285    /// # let _ = client;
286    /// # Ok(())
287    /// # }
288    /// ```
289    pub fn without_api_key(base_url: &str) -> Result<Self, Error> {
290        let http = build_http_client(Config::default().timeout)?;
291        let client = Self {
292            http,
293            api_key: None,
294            config: Arc::new(Config::default()),
295        };
296        client.with_api_base(base_url)
297    }
298
299    /// Builds a client that shares a caller-owned `reqwest::Client` and connection
300    /// pool. This is the right choice inside a service that already owns an HTTP
301    /// client, and the only way to supply a custom TLS configuration (for example a
302    /// pinned internal CA), or to build with neither TLS feature enabled.
303    /// The key is validated before sending each request.
304    pub fn with_http(http: reqwest::Client, api_key: impl Into<SecretString>) -> Self {
305        Self {
306            http,
307            api_key: Some(api_key.into()),
308            config: Arc::new(Config::default()),
309        }
310    }
311
312    /// Builds a client from a caller-supplied HTTP client, API key, and [`Config`],
313    /// for the config-file path.
314    ///
315    /// # Errors
316    ///
317    /// Returns [`Error::Invalid`] if the API key fails the validation documented
318    /// by [`Client::new`].
319    ///
320    /// # Examples
321    ///
322    /// ```no_run
323    /// # fn run(key: String) -> Result<(), jev::Error> {
324    /// let config = jev::Config { provider: jev::Provider::TypeSafe, ..Default::default() };
325    /// let client = jev::Client::from_config(reqwest::Client::new(), key, config)?;
326    /// assert_eq!(client.provider(), jev::Provider::TypeSafe);
327    /// # Ok(())
328    /// # }
329    /// ```
330    pub fn from_config(
331        http: reqwest::Client,
332        api_key: impl Into<SecretString>,
333        config: Config,
334    ) -> Result<Self, Error> {
335        let api_key = api_key.into();
336        validate_api_key(&api_key)?;
337        Ok(Self {
338            http,
339            api_key: Some(api_key),
340            config: Arc::new(config),
341        })
342    }
343
344    /// Builds a client from environment variables, with an optional `JEV_BASE_URL`.
345    ///
346    /// `JEV_PROVIDER=openrouter|typesafe` selects the service explicitly; the key
347    /// comes from `JEV_API_KEY` or that provider's `OPENROUTER_API_KEY` /
348    /// `TYPESAFE_API_KEY`. A key belonging to the other provider is never used.
349    /// Without `JEV_PROVIDER`, keys are tried in this order: `JEV_API_KEY`
350    /// (`OpenRouter`), `OPENROUTER_API_KEY`, then `TYPESAFE_API_KEY` (`TypeSafe`).
351    ///
352    /// # Errors
353    ///
354    /// Returns [`Error::MissingApiKey`] when no matching key is set, or
355    /// [`Error::Invalid`] for an unknown provider, an invalid key, or an invalid
356    /// `JEV_BASE_URL` (see [`Client::with_api_base`]).
357    ///
358    /// # Examples
359    ///
360    /// ```no_run
361    /// # fn run() -> Result<(), jev::Error> {
362    /// // Configure TYPESAFE_API_KEY and JEV_PROVIDER=typesafe in your environment.
363    /// let client = jev::Client::from_env()?;
364    /// # Ok(())
365    /// # }
366    /// ```
367    pub fn from_env() -> Result<Self, Error> {
368        let (provider, api_key) = credentials_from_env(|name| std::env::var(name).ok())?;
369        let mut client = Self::for_provider(provider, api_key)?;
370        if let Ok(base_url) = std::env::var(ENV_BASE_URL) {
371            client = client.with_api_base(&base_url)?;
372        }
373        Ok(client)
374    }
375
376    /// Selects the hosted provider while preserving custom HTTP and base URL settings.
377    ///
378    /// Supply the selected provider's key at construction. `TypeSafe` always uses
379    /// System One; `OpenRouter` uses the configured surface.
380    ///
381    /// # Examples
382    ///
383    /// ```no_run
384    /// # fn run(key: String) -> Result<(), jev::Error> {
385    /// let client = jev::Client::with_http(reqwest::Client::new(), key)
386    ///     .with_provider(jev::Provider::TypeSafe);
387    /// # Ok(())
388    /// # }
389    /// ```
390    #[must_use]
391    pub fn with_provider(mut self, provider: Provider) -> Self {
392        self.config_mut().provider = provider;
393        self
394    }
395
396    /// The hosted provider configured for this client.
397    ///
398    /// # Examples
399    ///
400    /// ```
401    /// let client = jev::Client::with_http(reqwest::Client::new(), "key");
402    /// assert_eq!(client.provider(), jev::Provider::OpenRouter);
403    /// ```
404    #[must_use]
405    pub fn provider(&self) -> Provider {
406        self.config.provider
407    }
408
409    /// The effective HTTP surface. `TypeSafe` always uses System One.
410    fn surface(&self) -> Surface {
411        self.provider().surface(self.config.surface)
412    }
413
414    /// Overrides the model sent on every request made by this client.
415    #[must_use]
416    pub fn with_model(mut self, model: Model) -> Self {
417        self.config_mut().model = model;
418        self
419    }
420
421    /// Overrides the `OpenRouter` HTTP surface. `TypeSafe` always uses System One.
422    #[must_use]
423    pub fn with_surface(mut self, surface: Surface) -> Self {
424        self.config_mut().surface = surface;
425        self
426    }
427
428    /// Overrides the API base URL (scheme + host).
429    ///
430    /// # Errors
431    ///
432    /// Returns [`Error::Invalid`] when `base_url` fails to parse, or uses a scheme
433    /// other than `https` (`http` is accepted only for local mocks; see the crate's
434    /// security posture docs).
435    pub fn with_api_base(mut self, base_url: &str) -> Result<Self, Error> {
436        let url = url::Url::parse(base_url).map_err(|e| Error::Invalid {
437            field: "api_base".to_string(),
438            reason: e.to_string(),
439        })?;
440        if url.scheme() != "https" && !is_local_http_opt_in(&url) {
441            return Err(Error::Invalid {
442                field: "api_base".to_string(),
443                reason: "must use https (http is only accepted for loopback addresses)".to_string(),
444            });
445        }
446        self.config_mut().api_base = Some(url);
447        Ok(self)
448    }
449
450    /// Overrides the per-request timeout (an overall deadline across all retry attempts).
451    #[must_use]
452    pub fn with_timeout(mut self, timeout: Duration) -> Self {
453        self.config_mut().timeout = timeout;
454        self
455    }
456
457    /// Overrides the retry policy.
458    #[must_use]
459    pub fn with_retry(mut self, retry: crate::config::RetryConfig) -> Self {
460        self.config_mut().retry = retry;
461        self
462    }
463
464    /// Enables or disables the pre-flight context-size estimate.
465    #[must_use]
466    pub fn with_context_check(mut self, enabled: bool) -> Self {
467        self.config_mut().context_check = enabled;
468        self
469    }
470
471    /// Sets a default session identifier applied to every request unless overridden
472    /// per-call by [`RequestOptions::with_session_id`].
473    #[must_use]
474    pub fn with_session_id(mut self, session_id: impl Into<String>) -> Self {
475        self.config_mut().default_session_id = Some(session_id.into());
476        self
477    }
478
479    /// Sets a default user identifier applied to every request unless overridden
480    /// per-call by [`RequestOptions::with_user`].
481    #[must_use]
482    pub fn with_user(mut self, user: impl Into<String>) -> Self {
483        self.config_mut().default_user = Some(user.into());
484        self
485    }
486
487    /// Sets the named probability thresholds this client carries for callers that
488    /// want to read them back via [`Client::thresholds`].
489    #[must_use]
490    pub fn with_thresholds(mut self, thresholds: crate::config::Thresholds) -> Self {
491        self.config_mut().thresholds = thresholds;
492        self
493    }
494
495    /// The configured probability thresholds.
496    #[must_use]
497    pub fn thresholds(&self) -> &crate::config::Thresholds {
498        &self.config.thresholds
499    }
500
501    /// The effective API base URL.
502    #[must_use]
503    pub fn api_base(&self) -> url::Url {
504        self.config.api_base.clone().unwrap_or_else(|| {
505            url::Url::parse(self.provider().api_base()).unwrap_or_else(|_| unreachable_url())
506        })
507    }
508
509    /// Typed path: sends `D::questions()`, parses the answers back into `D`.
510    ///
511    /// This is the 90% API. It deliberately drops the response envelope (id, usage,
512    /// cost); use [`Client::decide_with`] when that data is needed.
513    ///
514    /// # Errors
515    ///
516    /// Any [`Error`] from the underlying request, or from [`Decision::from_answers`]
517    /// if the server's answers do not match `D`'s shape.
518    pub async fn decide<D: Decision>(&self, state: impl Into<State>) -> Result<D, Error> {
519        Ok(self
520            .decide_with::<D>(RequestOptions::new(state))
521            .await?
522            .value)
523    }
524
525    /// Typed path with per-call knobs (session, user, trace, model override).
526    ///
527    /// # Errors
528    ///
529    /// Any [`Error`] from the underlying request, or from [`Decision::from_answers`].
530    pub async fn decide_with<D: Decision>(
531        &self,
532        options: RequestOptions<'_>,
533    ) -> Result<Decided<D>, Error> {
534        let questions = D::questions();
535        let (response, latency) = self.send(options, questions).await?;
536        let meta = ResponseMeta::from_response(&response, latency);
537        let value = D::from_answers(&response.answers)?;
538        Ok(Decided { value, meta })
539    }
540
541    /// Dynamic path: sends caller-supplied `questions`, returns the raw answer map.
542    ///
543    /// # Errors
544    ///
545    /// Any [`Error`] from the underlying request.
546    pub async fn ask(
547        &self,
548        state: impl Into<State>,
549        questions: &Questions,
550    ) -> Result<Response, Error> {
551        self.send(RequestOptions::new(state), questions)
552            .await
553            .map(|(response, _)| response)
554    }
555
556    /// Single-question convenience: asks one `noul` question and returns the typed
557    /// [`Noul`] answer directly, without a [`Decision`] struct.
558    ///
559    /// For a one-off yes/no gate that does not warrant its own struct. For more than
560    /// one question in a single request, or to keep the question and its criteria
561    /// next to a named type, use `#[derive(Decision)]` or [`Client::ask`] instead.
562    ///
563    /// # Errors
564    ///
565    /// [`Error::Invalid`] if `instructions` fails [`Questions`]'s validation (empty,
566    /// oversized); otherwise any [`Error`] from the underlying request.
567    ///
568    /// # Examples
569    ///
570    /// ```no_run
571    /// # async fn run(client: &jev::Client) -> Result<(), jev::Error> {
572    /// let is_refund = client.noul("Please refund my order.", "Is this a refund request?").await?;
573    /// println!("{is_refund}"); // Display: "yes, 88% sure"
574    /// # Ok(())
575    /// # }
576    /// ```
577    pub async fn noul(
578        &self,
579        state: impl Into<State>,
580        instructions: impl Into<crate::guidance::Guidance>,
581    ) -> Result<Noul, Error> {
582        const KEY: &str = "noul";
583        let questions = Questions::builder().noul(KEY, instructions).build()?;
584        let response = self.ask(state, &questions).await?;
585        Noul::try_new(response.answers.noul(KEY)?)
586    }
587
588    /// Single-question convenience: asks one `choice` question over `T::options()`
589    /// and returns the typed [`Choice<T>`] answer directly, without a [`Decision`]
590    /// struct.
591    ///
592    /// `T` supplies both the wire criteria (`T::options()`) and the typed result, the
593    /// same as a `Choice<T>` field on a `#[derive(Decision)]` struct would.
594    ///
595    /// # Errors
596    ///
597    /// [`Error::Invalid`] if `instructions` fails validation; [`Error::UnknownChoice`]
598    /// if the server picks an option outside `T`; otherwise any [`Error`] from the
599    /// underlying request.
600    ///
601    /// # Examples
602    ///
603    /// ```no_run
604    /// use jev::ChoiceOptions;
605    ///
606    /// #[derive(Debug, Clone, Copy, PartialEq, Eq, ChoiceOptions)]
607    /// enum Team {
608    ///     /// Billing issues.
609    ///     Payments,
610    ///     /// UI issues.
611    ///     Frontend,
612    /// }
613    ///
614    /// # async fn run(client: &jev::Client) -> Result<(), jev::Error> {
615    /// let team = client.choice::<Team>("a checkout ticket", "Which team owns this?").await?;
616    /// println!("{:?}", team.value());
617    /// # Ok(())
618    /// # }
619    /// ```
620    pub async fn choice<T: ChoiceOptions>(
621        &self,
622        state: impl Into<State>,
623        instructions: impl Into<crate::guidance::Guidance>,
624    ) -> Result<Choice<T>, Error> {
625        const KEY: &str = "choice";
626        let questions = Questions::builder()
627            .choice(KEY, instructions, T::options().to_vec())
628            .build()?;
629        let response = self.ask(state, &questions).await?;
630        let answer = response.answers.choice(KEY)?;
631        Choice::try_new(
632            KEY,
633            &answer.choice,
634            answer.confidence,
635            answer.probabilities.clone(),
636        )
637    }
638
639    /// Single-question convenience: asks one `score` question over `T::levels()` and
640    /// returns the typed [`Score<T>`] answer directly, without a [`Decision`] struct.
641    ///
642    /// # Errors
643    ///
644    /// [`Error::Invalid`] if `instructions` fails validation; [`Error::ScoreRange`] if
645    /// the server's score falls outside `T`'s levels; otherwise any [`Error`] from the
646    /// underlying request.
647    ///
648    /// # Examples
649    ///
650    /// ```no_run
651    /// use jev::ScoreLevels;
652    ///
653    /// #[derive(Debug, Clone, Copy, PartialEq, Eq, ScoreLevels)]
654    /// enum Urgency {
655    ///     /// Can wait.
656    ///     Low,
657    ///     /// Blocking revenue.
658    ///     High,
659    /// }
660    ///
661    /// # async fn run(client: &jev::Client) -> Result<(), jev::Error> {
662    /// let urgency = client.score::<Urgency>("a checkout ticket", "How urgent is this?").await?;
663    /// println!("{:?}", urgency.nearest());
664    /// # Ok(())
665    /// # }
666    /// ```
667    pub async fn score<T: ScoreLevels>(
668        &self,
669        state: impl Into<State>,
670        instructions: impl Into<crate::guidance::Guidance>,
671    ) -> Result<Score<T>, Error> {
672        const KEY: &str = "score";
673        let questions = Questions::builder()
674            .score(KEY, instructions, T::levels().to_vec())
675            .build()?;
676        let response = self.ask(state, &questions).await?;
677        let answer = response.answers.score(KEY)?;
678        Score::try_new(
679            KEY,
680            answer.score,
681            answer.confidence,
682            answer.probabilities.clone(),
683        )
684    }
685
686    /// Runs one predefined [`Case`]: builds its questions, sends its state, and
687    /// returns the response tagged with the case's `id`.
688    ///
689    /// This is the config-file counterpart of [`Client::ask`]: `ask` takes questions
690    /// assembled in code, `run_case` takes both the state and the questions from a
691    /// [`Case`] loaded via [`crate::CaseSet::from_yaml_str`] /
692    /// [`crate::CaseSet::from_json_str`] / [`crate::CaseSet::from_file`]. For many
693    /// cases at once with bounded concurrency, see [`crate::run_cases`] (the `batch`
694    /// feature).
695    ///
696    /// # Errors
697    ///
698    /// [`Error::Invalid`] if `case.questions` fails validation (this should not
699    /// happen for a `Case` obtained from a successfully loaded [`crate::CaseSet`],
700    /// which validates eagerly at load time); otherwise any [`Error`] from the
701    /// underlying request.
702    ///
703    /// # Examples
704    ///
705    /// ```no_run
706    /// # async fn run(client: &jev::Client, case: &jev::Case) -> Result<(), jev::Error> {
707    /// let result = client.run_case(case).await?;
708    /// println!("{}: {:?}", result.id, result.response.answers);
709    /// # Ok(())
710    /// # }
711    /// ```
712    pub async fn run_case(&self, case: &Case) -> Result<CaseResult, Error> {
713        let questions = case.build_questions()?;
714        let response = self.ask(case.state.clone(), &questions).await?;
715        Ok(CaseResult {
716            id: case.id.clone(),
717            response,
718        })
719    }
720
721    /// Escape hatch: full request in ([`RequestOptions::with_questions`] required),
722    /// full [`Response`] out.
723    ///
724    /// # Errors
725    ///
726    /// [`Error::Invalid`] if `options` has no questions set; otherwise any [`Error`]
727    /// from the underlying request.
728    pub async fn raw(&self, options: RequestOptions<'_>) -> Result<Response, Error> {
729        let questions = options.questions.ok_or_else(|| Error::Invalid {
730            field: "questions".to_string(),
731            reason: "Client::raw requires RequestOptions::with_questions".to_string(),
732        })?;
733        self.send(options, questions)
734            .await
735            .map(|(response, _)| response)
736    }
737
738    /// Mutable access to this client's private `Config` copy, cloning the `Arc`'s
739    /// contents on first write (copy-on-write via `Arc::make_mut`).
740    fn config_mut(&mut self) -> &mut Config {
741        Arc::make_mut(&mut self.config)
742    }
743
744    /// Sends one decision request, applying the context-size guard and the retry
745    /// loop, and returns the parsed response plus the measured latency.
746    #[instrument(
747        skip(self, options, questions),
748        fields(
749            model,
750            provider = ?self.provider(),
751            surface = ?self.surface(),
752            questions = questions.len(),
753            attempt,
754            request_id,
755            input_tokens,
756            cost,
757            latency_ms
758        )
759    )]
760    async fn send(
761        &self,
762        options: RequestOptions<'_>,
763        questions: &Questions,
764    ) -> Result<(Response, Duration), Error> {
765        let model = options.model.unwrap_or_else(|| self.config.model.clone());
766        let wire_model = self
767            .provider()
768            .wire_id(&model, self.config.surface)
769            .into_owned();
770        tracing::Span::current().record("model", tracing::field::display(&wire_model));
771
772        let session_id = options
773            .session_id
774            .or_else(|| self.config.default_session_id.clone());
775        let user = options.user.or_else(|| self.config.default_user.clone());
776        let trace = options.trace;
777
778        if self.config.context_check {
779            Self::check_context_size(&model, &options.state, questions)?;
780        }
781
782        let url = self.request_url();
783        let start = Instant::now();
784        let result = self
785            .send_with_retry(
786                &url,
787                &wire_model,
788                &options.state,
789                questions,
790                session_id,
791                user,
792                trace,
793            )
794            .await;
795        let latency = start.elapsed();
796        tracing::Span::current().record(
797            "latency_ms",
798            u64::try_from(latency.as_millis()).unwrap_or(u64::MAX),
799        );
800
801        let response = result?;
802        tracing::Span::current().record("input_tokens", response.usage.input_tokens);
803        if let Some(cost) = response.usage.cost {
804            tracing::Span::current().record("cost", cost);
805        }
806        warn_on_low_confidence(&response.answers);
807
808        Ok((response, latency))
809    }
810
811    /// The context-size guard: rejects a request before spending a billed round trip
812    /// when the serialized payload is clearly too large for the model's context.
813    ///
814    /// This is a cheap heuristic (bytes / 4), not a tokenizer; the server remains
815    /// authoritative. Disable with `Client::with_context_check(false)`.
816    fn check_context_size(
817        model: &Model,
818        state: &State,
819        questions: &Questions,
820    ) -> Result<(), Error> {
821        let Some(limit) = model.context_tokens() else {
822            return Ok(());
823        };
824        let questions_bytes = serde_json::to_string(questions).map_or(usize::MAX, |s| s.len());
825        let estimated = estimate_tokens(state.byte_len() + questions_bytes);
826        if estimated > limit {
827            return Err(Error::StateTooLarge { estimated, limit });
828        }
829        Ok(())
830    }
831
832    /// The full URL for this client's configured surface.
833    fn request_url(&self) -> url::Url {
834        let mut url = self.api_base();
835        url.set_path(self.provider().path(self.config.surface));
836        url
837    }
838
839    /// Runs the bounded retry loop around a single logical request.
840    #[allow(clippy::too_many_arguments)]
841    async fn send_with_retry(
842        &self,
843        url: &url::Url,
844        wire_model: &str,
845        state: &State,
846        questions: &Questions,
847        session_id: Option<String>,
848        user: Option<String>,
849        trace: Option<TraceConfig>,
850    ) -> Result<Response, Error> {
851        let retry = self.config.retry;
852        let max_attempts = effective_max_attempts(retry.max_attempts);
853
854        let attempt_fut = async {
855            let mut last_err: Option<Error> = None;
856            for attempt in 1..=max_attempts {
857                tracing::Span::current().record("attempt", attempt);
858                let outcome = self
859                    .send_once(
860                        url,
861                        wire_model,
862                        state,
863                        questions,
864                        session_id.as_deref(),
865                        user.as_deref(),
866                        trace.as_ref(),
867                    )
868                    .await;
869
870                match outcome {
871                    Ok(response) => return Ok(response),
872                    Err(err) => {
873                        let retry_after = retry_after_from_error(&err);
874                        let retryable = err.is_retryable();
875                        last_err = Some(err);
876                        if !retryable || attempt == max_attempts {
877                            break;
878                        }
879                        sleep_before_retry(retry, attempt, retry_after).await;
880                    }
881                }
882            }
883            // `max_attempts >= 1` (enforced by `effective_max_attempts`), so the loop
884            // above always runs at least once and `last_err` is always `Some` here.
885            Err(last_err.unwrap_or(Error::Invalid {
886                field: "retry".to_string(),
887                reason: "retry loop exited without a result".to_string(),
888            }))
889        };
890
891        run_with_deadline(self.config.timeout, attempt_fut).await
892    }
893
894    /// Sends exactly one HTTP request and parses its response, without retrying.
895    #[allow(clippy::too_many_arguments)]
896    async fn send_once(
897        &self,
898        url: &url::Url,
899        wire_model: &str,
900        state: &State,
901        questions: &Questions,
902        session_id: Option<&str>,
903        user: Option<&str>,
904        trace: Option<&TraceConfig>,
905    ) -> Result<Response, Error> {
906        let (session_id, user, trace) =
907            drop_unsupported_fields(self.surface(), session_id, user, trace);
908
909        let request = DecisionRequest {
910            model: wire_model,
911            state,
912            questions,
913            session_id,
914            user,
915            trace,
916        };
917        let body = serde_json::to_vec(&request).map_err(|e| Error::Invalid {
918            field: "request".to_string(),
919            reason: e.to_string(),
920        })?;
921
922        let mut request = self
923            .http
924            .post(url.clone())
925            .header(reqwest::header::CONTENT_TYPE, "application/json");
926        if let Some(api_key) = &self.api_key {
927            validate_api_key(api_key)?;
928            let mut authorization =
929                HeaderValue::from_str(&format!("Bearer {}", api_key.expose_secret())).map_err(
930                    |_| Error::Invalid {
931                        field: "api_key".to_string(),
932                        reason: "cannot be encoded as an authorization header".to_string(),
933                    },
934                )?;
935            authorization.set_sensitive(true);
936            request = request.header(AUTHORIZATION, authorization);
937        }
938        let http_response = request.body(body).send().await?;
939
940        let status = http_response.status();
941        let retry_after_secs = parse_retry_after(http_response.headers());
942        let bytes = read_capped_body(http_response).await?;
943
944        if !status.is_success() {
945            let text = String::from_utf8_lossy(&bytes);
946            return Err(Error::from_api_response(
947                status.as_u16(),
948                &text,
949                retry_after_secs,
950            ));
951        }
952
953        serde_json::from_slice(&bytes).map_err(|e| Error::Parse(e.to_string()))
954    }
955}
956
957/// Resolves credentials without mutating process environment (including in tests).
958fn credentials_from_env(
959    get: impl Fn(&str) -> Option<String>,
960) -> Result<(Provider, SecretString), Error> {
961    if let Some(name) = get(ENV_PROVIDER) {
962        let provider = name.parse::<Provider>()?;
963        let key = get(ENV_API_KEY)
964            .or_else(|| get(provider.api_key_env()))
965            .ok_or(Error::MissingApiKey)?;
966        return Ok((provider, SecretString::from(key)));
967    }
968    if let Some(key) = get(ENV_API_KEY) {
969        return Ok((Provider::OpenRouter, SecretString::from(key)));
970    }
971    for provider in [Provider::OpenRouter, Provider::TypeSafe] {
972        if let Some(key) = get(provider.api_key_env()) {
973            return Ok((provider, SecretString::from(key)));
974        }
975    }
976    Err(Error::MissingApiKey)
977}
978
979/// Rejects invalid credentials without putting the secret in diagnostics.
980fn validate_api_key(key: &SecretString) -> Result<(), Error> {
981    let key = key.expose_secret();
982    if key.is_empty() || key.len() > MAX_API_KEY_BYTES || !key.bytes().all(|b| b.is_ascii_graphic())
983    {
984        return Err(Error::Invalid {
985            field: "api_key".to_string(),
986            reason: "must contain 1..=4096 printable ASCII bytes without whitespace".to_string(),
987        });
988    }
989    Ok(())
990}
991
992/// A `Client::new`/`Client::from_config`-friendly `reqwest::Client` builder.
993///
994/// Returns [`Error::Invalid`] when neither TLS feature is enabled, since a client
995/// built this way cannot make an HTTPS request without one.
996fn build_http_client(timeout: Duration) -> Result<reqwest::Client, Error> {
997    #[cfg(any(feature = "rustls-tls", feature = "native-tls"))]
998    {
999        log_tls_backend();
1000        reqwest::Client::builder()
1001            .timeout(timeout)
1002            .build()
1003            .map_err(Error::Http)
1004    }
1005    #[cfg(not(any(feature = "rustls-tls", feature = "native-tls")))]
1006    {
1007        let _ = timeout;
1008        Err(Error::Invalid {
1009            field: "tls".to_string(),
1010            reason: "Client::new requires the `rustls-tls` or `native-tls` feature; use \
1011                     Client::with_http with a caller-supplied client instead"
1012                .to_string(),
1013        })
1014    }
1015}
1016
1017/// Names the effective TLS backend once, at `debug!` level, when both TLS features
1018/// are enabled (Cargo feature unification can legitimately request both).
1019#[cfg(any(feature = "rustls-tls", feature = "native-tls"))]
1020fn log_tls_backend() {
1021    #[cfg(feature = "rustls-tls")]
1022    {
1023        debug!(
1024            backend = "rustls",
1025            "using rustls TLS backend (preferred when both are enabled)"
1026        );
1027    }
1028    #[cfg(all(not(feature = "rustls-tls"), feature = "native-tls"))]
1029    {
1030        debug!(backend = "native-tls", "using native-tls TLS backend");
1031    }
1032}
1033
1034/// Clamps `max_attempts` to at least `1`, and to `1` unconditionally when the
1035/// `retry` feature is disabled (no backoff machinery is compiled in).
1036fn effective_max_attempts(configured: u32) -> u32 {
1037    #[cfg(feature = "retry")]
1038    {
1039        configured.max(1)
1040    }
1041    #[cfg(not(feature = "retry"))]
1042    {
1043        let _ = configured;
1044        1
1045    }
1046}
1047
1048/// Runs `fut` under an overall deadline, mapping expiry to [`Error::Timeout`].
1049///
1050/// Without the `retry` feature, `tokio::time` is not pulled in as a dependency of
1051/// this crate's own retry loop; the per-attempt `reqwest` timeout (set at client
1052/// construction) is the only bound in that configuration.
1053async fn run_with_deadline<F, T>(timeout: Duration, fut: F) -> Result<T, Error>
1054where
1055    F: std::future::Future<Output = Result<T, Error>>,
1056{
1057    #[cfg(feature = "retry")]
1058    {
1059        let start = Instant::now();
1060        match tokio::time::timeout(timeout, fut).await {
1061            Ok(result) => result,
1062            Err(_) => Err(Error::Timeout {
1063                elapsed_ms: u64::try_from(start.elapsed().as_millis()).unwrap_or(u64::MAX),
1064            }),
1065        }
1066    }
1067    #[cfg(not(feature = "retry"))]
1068    {
1069        let _ = timeout;
1070        fut.await
1071    }
1072}
1073
1074/// Sleeps before the next retry attempt, honouring `Retry-After` when present.
1075#[cfg(feature = "retry")]
1076async fn sleep_before_retry(
1077    retry: crate::config::RetryConfig,
1078    attempt: u32,
1079    retry_after: Option<Duration>,
1080) {
1081    let backoff = compute_backoff(retry, attempt, retry_after);
1082    tokio::time::sleep(backoff).await;
1083}
1084
1085#[cfg(not(feature = "retry"))]
1086async fn sleep_before_retry(
1087    _retry: crate::config::RetryConfig,
1088    _attempt: u32,
1089    _retry_after: Option<Duration>,
1090) {
1091}
1092
1093/// Computes the backoff before the next attempt: `Retry-After` takes precedence
1094/// (clamped to `max_backoff`); otherwise exponential backoff with full jitter,
1095/// capped at `max_backoff`.
1096#[cfg(feature = "retry")]
1097fn compute_backoff(
1098    retry: crate::config::RetryConfig,
1099    attempt: u32,
1100    retry_after: Option<Duration>,
1101) -> Duration {
1102    if let Some(retry_after) = retry_after {
1103        return retry_after.min(retry.max_backoff);
1104    }
1105    let exponent = attempt.saturating_sub(1).min(20); // bound the shift to avoid overflow
1106    let ceiling = retry
1107        .initial_backoff
1108        .saturating_mul(1u32.checked_shl(exponent).unwrap_or(u32::MAX))
1109        .min(retry.max_backoff);
1110    full_jitter(ceiling)
1111}
1112
1113/// Full-jitter backoff: a uniformly random duration in `0..=ceiling`.
1114#[cfg(feature = "retry")]
1115fn full_jitter(ceiling: Duration) -> Duration {
1116    if ceiling.is_zero() {
1117        return ceiling;
1118    }
1119    // A dependency-free, non-cryptographic jitter source is sufficient here: backoff
1120    // timing has no security property, only a fairness one (avoiding a thundering
1121    // herd), and pulling in `rand` for it would cost more than it is worth.
1122    let nanos = Instant::now().elapsed().as_nanos() ^ u128::from(std::process::id());
1123    #[allow(clippy::cast_precision_loss)]
1124    let fraction = (nanos % 1_000_000) as f64 / 1_000_000.0;
1125    Duration::from_secs_f64(ceiling.as_secs_f64() * fraction)
1126}
1127
1128/// Extracts the `retry_after_secs` carried by [`Error::RateLimited`], if any.
1129fn retry_after_from_error(err: &Error) -> Option<Duration> {
1130    match err {
1131        Error::RateLimited {
1132            retry_after_secs: Some(secs),
1133        } => Some(Duration::from_secs(*secs)),
1134        _ => None,
1135    }
1136}
1137
1138/// Parses a `Retry-After` header, in either the seconds form or the HTTP-date form.
1139fn parse_retry_after(headers: &reqwest::header::HeaderMap) -> Option<u64> {
1140    let raw = headers.get(reqwest::header::RETRY_AFTER)?.to_str().ok()?;
1141    if let Ok(secs) = raw.trim().parse::<u64>() {
1142        return Some(secs);
1143    }
1144    parse_http_date_seconds_from_now(raw.trim())
1145}
1146
1147/// Parses an RFC 7231 IMF-fixdate (`Sun, 06 Nov 1994 08:49:37 GMT`) and returns the
1148/// number of seconds from now until that instant, saturating at zero if it is past.
1149fn parse_http_date_seconds_from_now(s: &str) -> Option<u64> {
1150    let epoch_secs = parse_imf_fixdate(s)?;
1151    let now = std::time::SystemTime::now()
1152        .duration_since(std::time::UNIX_EPOCH)
1153        .ok()?
1154        .as_secs();
1155    let now_i64 = now.cast_signed();
1156    Some(epoch_secs.saturating_sub(now_i64).max(0).cast_unsigned())
1157}
1158
1159/// Parses `"Sun, 06 Nov 1994 08:49:37 GMT"` into Unix seconds. Returns `None` for any
1160/// other format; this SDK does not need to accept the obsolete RFC 850 / ANSI C forms.
1161fn parse_imf_fixdate(s: &str) -> Option<i64> {
1162    // "Sun, 06 Nov 1994 08:49:37 GMT"
1163    let s = s.strip_suffix(" GMT")?;
1164    let (_weekday, rest) = s.split_once(", ")?;
1165    let mut parts = rest.split(' ');
1166    let day: i64 = parts.next()?.parse().ok()?;
1167    let month = month_from_abbrev(parts.next()?)?;
1168    let year: i64 = parts.next()?.parse().ok()?;
1169    let time = parts.next()?;
1170    let mut time_parts = time.split(':');
1171    let hour: i64 = time_parts.next()?.parse().ok()?;
1172    let minute: i64 = time_parts.next()?.parse().ok()?;
1173    let second: i64 = time_parts.next()?.parse().ok()?;
1174
1175    let days = days_from_civil(year, month, day);
1176    Some(days * 86_400 + hour * 3_600 + minute * 60 + second)
1177}
1178
1179/// Maps a three-letter month abbreviation to `1..=12`.
1180fn month_from_abbrev(s: &str) -> Option<i64> {
1181    const MONTHS: [&str; 12] = [
1182        "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec",
1183    ];
1184    #[allow(clippy::cast_possible_wrap)] // MONTHS.len() == 12; the position always fits in i64
1185    MONTHS.iter().position(|m| *m == s).map(|i| i as i64 + 1)
1186}
1187
1188/// Days since the Unix epoch for a civil (Gregorian) date, via Howard Hinnant's
1189/// `days_from_civil` algorithm. Valid for all proleptic Gregorian dates.
1190fn days_from_civil(year: i64, month: i64, day: i64) -> i64 {
1191    let y = if month <= 2 { year - 1 } else { year };
1192    let era = if y >= 0 { y } else { y - 399 } / 400;
1193    let yoe = y - era * 400;
1194    let mp = (month + 9) % 12;
1195    let doy = (153 * mp + 2) / 5 + day - 1;
1196    let doe = yoe * 365 + yoe / 4 - yoe / 100 + doy;
1197    era * 146_097 + doe - 719_468
1198}
1199
1200/// Reads a response body up to [`MAX_RESPONSE_BODY_BYTES`], erroring instead of
1201/// exhausting memory on an oversized or malformed gateway response.
1202async fn read_capped_body(mut response: reqwest::Response) -> Result<Vec<u8>, Error> {
1203    let mut buf = Vec::new();
1204    while let Some(chunk) = response.chunk().await? {
1205        if buf.len() + chunk.len() > MAX_RESPONSE_BODY_BYTES {
1206            return Err(Error::Parse(format!(
1207                "response body exceeds {MAX_RESPONSE_BODY_BYTES} byte cap"
1208            )));
1209        }
1210        buf.extend_from_slice(&chunk);
1211    }
1212    Ok(buf)
1213}
1214
1215/// Clears fields the System One surface does not define, logging the drop.
1216fn drop_unsupported_fields<'a>(
1217    surface: Surface,
1218    session_id: Option<&'a str>,
1219    user: Option<&'a str>,
1220    trace: Option<&'a TraceConfig>,
1221) -> (Option<&'a str>, Option<&'a str>, Option<&'a TraceConfig>) {
1222    if surface == Surface::SystemOne {
1223        if session_id.is_some() || user.is_some() || trace.is_some() {
1224            debug!(
1225                dropped_session_id = session_id.is_some(),
1226                dropped_user = user.is_some(),
1227                dropped_trace = trace.is_some(),
1228                "System One surface does not support session_id/user/trace; dropping"
1229            );
1230        }
1231        (None, None, None)
1232    } else {
1233        (session_id, user, trace)
1234    }
1235}
1236
1237/// Fires a `warn!` when any returned `choice`/`score` confidence is below `0.5`, so
1238/// miscalibrated gates surface in dashboards without extra application code.
1239fn warn_on_low_confidence(answers: &Answers) {
1240    const LOW_CONFIDENCE: f64 = 0.5;
1241    for (key, answer) in answers {
1242        let confidence = match answer {
1243            crate::answer::Answer::Choice(c) => c.confidence,
1244            crate::answer::Answer::Score(s) => s.confidence,
1245            crate::answer::Answer::Noul(_) | crate::answer::Answer::Other { .. } => None,
1246        };
1247        if let Some(confidence) = confidence
1248            && confidence < LOW_CONFIDENCE
1249        {
1250            warn!(question = key, confidence, "low-confidence answer");
1251        }
1252    }
1253}
1254
1255/// Whether `url` points at a loopback address, the only case `with_api_base` accepts
1256/// a non-`https` scheme for (local mocks such as `wiremock`).
1257fn is_local_http_opt_in(url: &url::Url) -> bool {
1258    matches!(url.host_str(), Some("localhost" | "127.0.0.1" | "[::1]"))
1259}
1260
1261/// Infallible fallback for the default API base URL, used only if the literal
1262/// constant ever failed to parse (which `cargo test` guards against).
1263fn unreachable_url() -> url::Url {
1264    // Safety net, not a real fallible path: the provider bases are literal constants
1265    // covered by `test_should_parse_default_api_base`.
1266    url::Url::parse("https://openrouter.ai").unwrap_or_else(|_| {
1267        // `data:` URLs always parse; this line is unreachable in practice.
1268        url::Url::parse("data:,").expect("`data:,` is always a valid URL")
1269    })
1270}
1271
1272#[cfg(test)]
1273mod tests {
1274    use rstest::rstest;
1275    use secrecy::SecretString;
1276    use wiremock::{
1277        Mock, MockServer, ResponseTemplate,
1278        matchers::{method, path},
1279    };
1280
1281    use super::*;
1282    use crate::CaseSet;
1283
1284    #[cfg(any(feature = "rustls-tls", feature = "native-tls"))]
1285    #[test]
1286    fn test_should_create_provider_clients_directly_with_keys() {
1287        let default = Client::new("key").unwrap();
1288        assert_eq!(default.provider(), Provider::OpenRouter);
1289        let openrouter = Client::openrouter(String::from("key")).unwrap();
1290        assert_eq!(
1291            openrouter.request_url().as_str(),
1292            "https://openrouter.ai/api/alpha/decisions"
1293        );
1294        let typesafe = Client::typesafe(SecretString::from("typesafe-super-secret")).unwrap();
1295        assert_eq!(
1296            typesafe.request_url().as_str(),
1297            "https://api.typesafe.ai/v1/systemone"
1298        );
1299        assert!(!format!("{typesafe:?}").contains("typesafe-super-secret"));
1300        assert!(format!("{typesafe:?}").contains("[REDACTED]"));
1301    }
1302
1303    #[test]
1304    fn test_should_apply_provider_from_yaml_config() {
1305        let config: Config = serde_norway::from_str("provider: typesafe\n").unwrap();
1306        let client = Client::from_config(reqwest::Client::new(), "key", config).unwrap();
1307        assert_eq!(client.provider(), Provider::TypeSafe);
1308        assert_eq!(client.surface(), Surface::SystemOne);
1309        assert_eq!(
1310            client.request_url().as_str(),
1311            "https://api.typesafe.ai/v1/systemone"
1312        );
1313    }
1314
1315    #[test]
1316    fn test_should_preserve_custom_base_and_isolate_cloned_provider_settings() {
1317        let openrouter = Client::with_http(reqwest::Client::new(), "key")
1318            .with_api_base("http://127.0.0.1:8099")
1319            .unwrap();
1320        let typesafe = openrouter.clone().with_provider(Provider::TypeSafe);
1321        assert_eq!(openrouter.request_url().path(), "/api/alpha/decisions");
1322        assert_eq!(
1323            typesafe.request_url().as_str(),
1324            "http://127.0.0.1:8099/v1/systemone"
1325        );
1326    }
1327
1328    #[rstest]
1329    #[case(vec![("JEV_API_KEY", "generic")], Provider::OpenRouter, "generic")]
1330    #[case(vec![("OPENROUTER_API_KEY", "router")], Provider::OpenRouter, "router")]
1331    #[case(vec![("TYPESAFE_API_KEY", "direct")], Provider::TypeSafe, "direct")]
1332    #[case(vec![("OPENROUTER_API_KEY", "router"), ("TYPESAFE_API_KEY", "direct")], Provider::OpenRouter, "router")]
1333    #[case(vec![("JEV_API_KEY", "generic"), ("OPENROUTER_API_KEY", "router"), ("TYPESAFE_API_KEY", "direct")], Provider::OpenRouter, "generic")]
1334    #[case(vec![("JEV_PROVIDER", "typesafe"), ("TYPESAFE_API_KEY", "direct"), ("OPENROUTER_API_KEY", "router")], Provider::TypeSafe, "direct")]
1335    #[case(vec![("JEV_PROVIDER", "typesafe"), ("JEV_API_KEY", "generic"), ("TYPESAFE_API_KEY", "direct")], Provider::TypeSafe, "generic")]
1336    #[case(vec![("JEV_PROVIDER", "openrouter"), ("JEV_API_KEY", "generic"), ("OPENROUTER_API_KEY", "router")], Provider::OpenRouter, "generic")]
1337    fn test_should_resolve_matching_environment_credentials(
1338        #[case] variables: Vec<(&str, &str)>,
1339        #[case] expected_provider: Provider,
1340        #[case] expected_key: &str,
1341    ) {
1342        let (provider, key) = credentials_from_env(|name| {
1343            variables
1344                .iter()
1345                .find(|(variable, _)| *variable == name)
1346                .map(|(_, value)| (*value).to_string())
1347        })
1348        .unwrap();
1349        assert_eq!(provider, expected_provider);
1350        assert_eq!(key.expose_secret(), expected_key);
1351    }
1352
1353    #[rstest]
1354    #[case(vec![])]
1355    #[case(vec![("JEV_PROVIDER", "typesafe"), ("OPENROUTER_API_KEY", "router")])]
1356    #[case(vec![("JEV_PROVIDER", "openrouter"), ("TYPESAFE_API_KEY", "direct")])]
1357    fn test_should_reject_missing_or_wrong_provider_environment_key(
1358        #[case] variables: Vec<(&str, &str)>,
1359    ) {
1360        let result = credentials_from_env(|name| {
1361            variables
1362                .iter()
1363                .find(|(variable, _)| *variable == name)
1364                .map(|(_, value)| (*value).to_string())
1365        });
1366        assert!(matches!(result, Err(Error::MissingApiKey)));
1367    }
1368
1369    #[test]
1370    fn test_should_reject_unknown_environment_provider() {
1371        let result = credentials_from_env(|name| match name {
1372            "JEV_PROVIDER" => Some("unknown".to_string()),
1373            "JEV_API_KEY" => Some("key".to_string()),
1374            _ => None,
1375        });
1376        assert!(matches!(result, Err(Error::Invalid { field, .. }) if field == "provider"));
1377    }
1378
1379    #[rstest]
1380    #[case(String::new())]
1381    #[case(" ".to_string())]
1382    #[case("key\r\nInjected: value".to_string())]
1383    #[case("含中文的key".to_string())]
1384    #[case("x".repeat(MAX_API_KEY_BYTES + 1))]
1385    fn test_should_reject_invalid_keys_without_exposing_them(#[case] key: String) {
1386        let result = Client::from_config(reqwest::Client::new(), key, Config::default());
1387        assert!(matches!(result, Err(Error::Invalid { ref field, .. }) if field == "api_key"));
1388        let error = result.unwrap_err();
1389        assert_eq!(
1390            error.to_string(),
1391            "invalid api_key: must contain 1..=4096 printable ASCII bytes without whitespace"
1392        );
1393    }
1394
1395    #[test]
1396    fn test_should_accept_key_at_maximum_byte_length() {
1397        assert!(validate_api_key(&SecretString::from("x".repeat(MAX_API_KEY_BYTES))).is_ok());
1398    }
1399
1400    #[tokio::test]
1401    async fn test_should_run_case_and_tag_result_with_case_id() {
1402        let server = MockServer::start().await;
1403        Mock::given(method("POST"))
1404            .and(path("/api/alpha/decisions"))
1405            .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
1406                "model": "typesafe/jev-1.13",
1407                "usage": {"input_tokens": 1, "output_tokens": 1},
1408                "answers": {"refund": {"type": "noul", "noul": 0.9}}
1409            })))
1410            .mount(&server)
1411            .await;
1412
1413        let client = Client::with_http(reqwest::Client::new(), SecretString::from("key"))
1414            .with_api_base(&server.uri())
1415            .unwrap();
1416
1417        let cases = CaseSet::from_json_str(
1418            r#"{"cases": [{
1419                "id": "ticket-001",
1420                "state": "a refund ticket",
1421                "questions": {
1422                    "refund": {"type": "noul", "instructions": "Refund?"}
1423                }
1424            }]}"#,
1425        )
1426        .unwrap();
1427        let case = cases.iter().next().unwrap();
1428
1429        let result = client.run_case(case).await.unwrap();
1430        assert_eq!(result.id, "ticket-001");
1431        assert_eq!(result.response.answers.noul("refund").unwrap(), 0.9);
1432    }
1433
1434    #[test]
1435    fn test_should_redact_api_key_in_debug_output() {
1436        let client = Client::with_http(
1437            reqwest::Client::new(),
1438            SecretString::from("sk-super-secret"),
1439        );
1440        let debug = format!("{client:?}");
1441        assert!(!debug.contains("sk-super-secret"));
1442        assert!(debug.contains("REDACTED"));
1443    }
1444
1445    #[test]
1446    fn test_should_report_no_api_key_in_debug_output_for_without_api_key() {
1447        let client = Client::without_api_key("http://127.0.0.1:8099").unwrap();
1448        let debug = format!("{client:?}");
1449        assert!(debug.contains("none"));
1450        assert!(!debug.contains("REDACTED"));
1451    }
1452
1453    #[test]
1454    fn test_should_return_invalid_when_no_tls_feature_and_new_called() {
1455        #[cfg(not(any(feature = "rustls-tls", feature = "native-tls")))]
1456        {
1457            let result = Client::new(SecretString::from("key"));
1458            assert!(matches!(result, Err(Error::Invalid { .. })));
1459        }
1460    }
1461
1462    #[test]
1463    fn test_should_parse_default_api_base() {
1464        for provider in [Provider::OpenRouter, Provider::TypeSafe] {
1465            assert!(url::Url::parse(provider.api_base()).is_ok());
1466        }
1467    }
1468
1469    #[test]
1470    fn test_should_reject_non_https_api_base() {
1471        let client = Client::with_http(reqwest::Client::new(), SecretString::from("key"));
1472        assert!(client.with_api_base("http://example.com").is_err());
1473    }
1474
1475    #[test]
1476    fn test_should_accept_loopback_http_api_base_for_local_mocks() {
1477        let client = Client::with_http(reqwest::Client::new(), SecretString::from("key"));
1478        assert!(client.with_api_base("http://127.0.0.1:8080").is_ok());
1479        let client = Client::with_http(reqwest::Client::new(), SecretString::from("key"));
1480        assert!(client.with_api_base("http://localhost:8080").is_ok());
1481    }
1482
1483    #[test]
1484    fn test_should_build_request_url_per_surface() {
1485        let client = Client::with_http(reqwest::Client::new(), SecretString::from("key"))
1486            .with_api_base("http://127.0.0.1:9999")
1487            .unwrap();
1488        assert_eq!(client.request_url().path(), "/api/alpha/decisions");
1489        let client = client.with_surface(Surface::SystemOne);
1490        assert_eq!(client.request_url().path(), "/api/v1/systemone");
1491    }
1492
1493    #[test]
1494    fn test_should_parse_retry_after_seconds() {
1495        let mut headers = reqwest::header::HeaderMap::new();
1496        headers.insert(reqwest::header::RETRY_AFTER, "120".parse().unwrap());
1497        assert_eq!(parse_retry_after(&headers), Some(120));
1498    }
1499
1500    #[test]
1501    fn test_should_parse_retry_after_http_date() {
1502        // Fixed historical date: the wait time will be zero (it is in the past), but
1503        // parsing itself must succeed rather than falling through to `None`.
1504        let epoch = parse_imf_fixdate("Sun, 06 Nov 1994 08:49:37 GMT").unwrap();
1505        assert_eq!(epoch, 784_111_777);
1506    }
1507
1508    #[test]
1509    fn test_should_return_none_for_unparsable_retry_after() {
1510        let mut headers = reqwest::header::HeaderMap::new();
1511        headers.insert(reqwest::header::RETRY_AFTER, "not-a-date".parse().unwrap());
1512        assert_eq!(parse_retry_after(&headers), None);
1513    }
1514
1515    #[test]
1516    fn test_should_drop_decisions_only_fields_on_system_one() {
1517        let trace = TraceConfig::new(serde_json::json!({}));
1518        let (session, user, trace) =
1519            drop_unsupported_fields(Surface::SystemOne, Some("s"), Some("u"), Some(&trace));
1520        assert_eq!(session, None);
1521        assert_eq!(user, None);
1522        assert_eq!(trace, None);
1523    }
1524
1525    #[test]
1526    fn test_should_keep_decisions_only_fields_on_decisions_surface() {
1527        let trace = TraceConfig::new(serde_json::json!({}));
1528        let (session, user, trace) =
1529            drop_unsupported_fields(Surface::Decisions, Some("s"), Some("u"), Some(&trace));
1530        assert_eq!(session, Some("s"));
1531        assert_eq!(user, Some("u"));
1532        assert!(trace.is_some());
1533    }
1534
1535    #[test]
1536    #[cfg(feature = "retry")]
1537    fn test_should_compute_backoff_from_retry_after_clamped_to_max() {
1538        let retry =
1539            crate::config::RetryConfig::default().with_max_backoff(Duration::from_millis(500));
1540        let backoff = compute_backoff(retry, 1, Some(Duration::from_secs(10)));
1541        assert_eq!(backoff, Duration::from_millis(500));
1542    }
1543
1544    #[test]
1545    #[cfg(feature = "retry")]
1546    fn test_should_compute_backoff_within_exponential_ceiling() {
1547        let retry = crate::config::RetryConfig::default()
1548            .with_initial_backoff(Duration::from_millis(100))
1549            .with_max_backoff(Duration::from_secs(10));
1550        for attempt in 1..=5 {
1551            let backoff = compute_backoff(retry, attempt, None);
1552            let ceiling = retry.initial_backoff * 2u32.pow(attempt - 1);
1553            assert!(backoff <= ceiling.min(retry.max_backoff));
1554        }
1555    }
1556
1557    #[test]
1558    #[cfg(feature = "retry")]
1559    fn test_should_cap_backoff_at_max_backoff_for_large_attempt_numbers() {
1560        let retry = crate::config::RetryConfig::default()
1561            .with_initial_backoff(Duration::from_millis(100))
1562            .with_max_backoff(Duration::from_secs(2));
1563        let backoff = compute_backoff(retry, 50, None);
1564        assert!(backoff <= Duration::from_secs(2));
1565    }
1566
1567    #[test]
1568    fn test_should_force_single_attempt_without_retry_feature() {
1569        #[cfg(not(feature = "retry"))]
1570        assert_eq!(effective_max_attempts(5), 1);
1571        #[cfg(feature = "retry")]
1572        assert_eq!(effective_max_attempts(5), 5);
1573    }
1574
1575    #[test]
1576    fn test_should_never_return_zero_max_attempts() {
1577        assert!(effective_max_attempts(0) >= 1);
1578    }
1579}