1use 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
26const MAX_RESPONSE_BODY_BYTES: usize = 10 * 1024 * 1024;
31
32const ENV_API_KEY: &str = "JEV_API_KEY";
34const ENV_PROVIDER: &str = "JEV_PROVIDER";
36const ENV_BASE_URL: &str = "JEV_BASE_URL";
38
39const MAX_API_KEY_BYTES: usize = 4096;
41
42#[derive(Debug, Clone, PartialEq)]
48pub struct Decided<D> {
49 pub value: D,
51 pub meta: ResponseMeta,
53}
54
55#[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 #[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 #[must_use]
86 pub fn with_questions(mut self, questions: &'a Questions) -> Self {
87 self.questions = Some(questions);
88 self
89 }
90
91 #[must_use]
93 pub fn with_model(mut self, model: Model) -> Self {
94 self.model = Some(model);
95 self
96 }
97
98 #[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 #[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 #[must_use]
116 pub fn with_trace(mut self, trace: TraceConfig) -> Self {
117 self.trace = Some(trace);
118 self
119 }
120}
121
122#[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 .finish_non_exhaustive()
167 }
168}
169
170impl Client {
171 pub fn new(api_key: impl Into<SecretString>) -> Result<Self, Error> {
193 Self::openrouter(api_key)
194 }
195
196 pub fn openrouter(api_key: impl Into<SecretString>) -> Result<Self, Error> {
212 Self::for_provider(Provider::OpenRouter, api_key)
213 }
214
215 pub fn typesafe(api_key: impl Into<SecretString>) -> Result<Self, Error> {
234 Self::for_provider(Provider::TypeSafe, api_key)
235 }
236
237 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 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 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 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 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 #[must_use]
391 pub fn with_provider(mut self, provider: Provider) -> Self {
392 self.config_mut().provider = provider;
393 self
394 }
395
396 #[must_use]
405 pub fn provider(&self) -> Provider {
406 self.config.provider
407 }
408
409 fn surface(&self) -> Surface {
411 self.provider().surface(self.config.surface)
412 }
413
414 #[must_use]
416 pub fn with_model(mut self, model: Model) -> Self {
417 self.config_mut().model = model;
418 self
419 }
420
421 #[must_use]
423 pub fn with_surface(mut self, surface: Surface) -> Self {
424 self.config_mut().surface = surface;
425 self
426 }
427
428 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 #[must_use]
452 pub fn with_timeout(mut self, timeout: Duration) -> Self {
453 self.config_mut().timeout = timeout;
454 self
455 }
456
457 #[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 #[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 #[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 #[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 #[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 #[must_use]
497 pub fn thresholds(&self) -> &crate::config::Thresholds {
498 &self.config.thresholds
499 }
500
501 #[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 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 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 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 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 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 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 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 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 fn config_mut(&mut self) -> &mut Config {
741 Arc::make_mut(&mut self.config)
742 }
743
744 #[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 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 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 #[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 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 #[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
957fn 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
979fn 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
992fn 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#[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
1034fn 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
1048async 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#[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#[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); 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#[cfg(feature = "retry")]
1115fn full_jitter(ceiling: Duration) -> Duration {
1116 if ceiling.is_zero() {
1117 return ceiling;
1118 }
1119 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
1128fn 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
1138fn 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
1147fn 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
1159fn parse_imf_fixdate(s: &str) -> Option<i64> {
1162 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
1179fn 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.iter().position(|m| *m == s).map(|i| i as i64 + 1)
1186}
1187
1188fn 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
1200async 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
1215fn 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
1237fn 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
1255fn is_local_http_opt_in(url: &url::Url) -> bool {
1258 matches!(url.host_str(), Some("localhost" | "127.0.0.1" | "[::1]"))
1259}
1260
1261fn unreachable_url() -> url::Url {
1264 url::Url::parse("https://openrouter.ai").unwrap_or_else(|_| {
1267 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 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}