use std::fmt;
use std::sync::Arc;
use std::time::Duration;
use reqwest::header::{ACCEPT, AUTHORIZATION, CONTENT_TYPE, HeaderMap, HeaderValue, USER_AGENT};
use reqwest::{Method, Url};
use rustls_platform_verifier::BuilderVerifierExt;
use serde::de::DeserializeOwned;
use zeroize::Zeroizing;
use crate::base_url::BaseUrl;
use crate::clock::{Clock, SystemClock};
use crate::error::{Error, ErrorKind};
use crate::models::ModelList;
use crate::request::Request;
use crate::response::Response;
use crate::retry::{RetryPolicy, server_delay};
use crate::secret::ApiKey;
use crate::throttle::Throttle;
use crate::transport::{Reply, ReplyMeta, Transport};
const REQUEST_ID_HEADER: &str = "x-typesafe-request-id";
const MAX_RESPONSE_BYTES: usize = 32 * 1024 * 1024;
const CONNECT_TIMEOUT: Duration = Duration::from_secs(10);
const BODY_LOG_TARGET: &str = "jev_client::http::body";
#[derive(Clone)]
pub struct HttpTransport {
client: reqwest::Client,
base_url: BaseUrl,
api_key: ApiKey,
authorization: HeaderValue,
retry: RetryPolicy,
clock: Arc<dyn Clock>,
log_bodies: bool,
throttle: Option<Arc<Throttle>>,
}
impl HttpTransport {
#[must_use]
pub fn builder(api_key: ApiKey) -> HttpTransportBuilder {
HttpTransportBuilder {
api_key,
base_url: BaseUrl::default(),
retry: RetryPolicy::default(),
clock: Arc::new(SystemClock),
user_agent: None,
log_bodies: false,
}
}
#[must_use]
pub const fn base_url(&self) -> &BaseUrl {
&self.base_url
}
#[must_use]
pub const fn retry_policy(&self) -> &RetryPolicy {
&self.retry
}
#[must_use]
pub fn with_throttle(mut self, throttle: Arc<Throttle>) -> Self {
self.throttle = Some(throttle);
self
}
async fn call<T: DeserializeOwned>(
&self,
method: Method,
path: &str,
body: Option<Vec<u8>>,
) -> Result<Reply<T>, Error> {
let url = self.base_url.endpoint(path).map_err(|error| {
Error::new(ErrorKind::InvalidRequest, error.to_string()).with_source(error)
})?;
if self.base_url.sends_key_in_clear() {
tracing::warn!(%url, "sending the API key over unencrypted HTTP");
}
let started = self.clock.now();
let mut retry = 0;
loop {
let attempt = retry + 1;
if let Some(throttle) = &self.throttle {
throttle.wait(self.clock.as_ref()).await;
}
let outcome = self
.attempt::<T>(&method, &url, body.as_deref(), attempt)
.await;
let failure = match outcome {
Ok((parsed, request_id, raw_body)) => {
if let Some(throttle) = &self.throttle {
throttle.speed_up();
}
let latency = self.clock.now().duration_since(started);
let meta = ReplyMeta::new(request_id, latency, attempt);
return Ok(Reply::new(parsed, meta).with_raw_body(raw_body));
}
Err(failure) => failure,
};
let delay = self
.retry
.delay(retry, failure.retry_after(), fastrand::f64());
if let (Some(throttle), ErrorKind::RateLimit | ErrorKind::Overloaded) =
(&self.throttle, failure.kind())
{
throttle.slow_down(self.clock.now(), delay);
}
if retry >= self.retry.max_retries || !self.should_retry(&failure) {
if failure.is_retryable() {
tracing::debug!(attempt, "giving up: no retries left");
}
return Err(failure.with_attempts(attempt));
}
tracing::debug!(
attempt,
max_retries = self.retry.max_retries,
delay_ms = delay.as_millis(),
server_requested = failure.retry_after().is_some(),
reason = %failure_label(&failure),
"retrying"
);
self.clock.sleep(delay).await;
retry += 1;
}
}
fn should_retry(&self, failure: &Error) -> bool {
match (failure.kind(), failure.status()) {
(ErrorKind::Timeout, _) => self.retry.retry_timeouts,
(ErrorKind::Connection, _) => self.retry.retry_connection_errors,
(_, Some(status)) => self.retry.retries_status(status),
_ => false,
}
}
async fn attempt<T: DeserializeOwned>(
&self,
method: &Method,
url: &Url,
body: Option<&[u8]>,
attempt: u32,
) -> Result<(T, Option<String>, String), Error> {
tracing::debug!(%method, %url, attempt, "sending request");
if let (true, Some(body)) = (self.log_bodies, body) {
let body = self.api_key.scrub(&String::from_utf8_lossy(body));
tracing::debug!(target: BODY_LOG_TARGET, %body, "request body");
}
let mut builder = self
.client
.request(method.clone(), url.clone())
.header(AUTHORIZATION, self.authorization.clone())
.header(ACCEPT, HeaderValue::from_static("application/json"));
if let Some(body) = body {
builder = builder
.header(CONTENT_TYPE, HeaderValue::from_static("application/json"))
.body(body.to_vec());
}
let sent = self.clock.now();
let response = builder
.send()
.await
.map_err(|error| self.transport_error(error))?;
let status = response.status();
let request_id = request_id(response.headers());
let retry_after = server_delay(response.headers(), self.clock.wall_time());
let bytes = read_capped(response).await.map_err(|error| match error {
ReadError::Transport(error) => self
.transport_error(error)
.with_request_id(request_id.clone()),
ReadError::TooLarge => Error::new(
ErrorKind::InvalidResponse,
format!("the response is larger than {MAX_RESPONSE_BYTES} bytes"),
)
.with_status(status.as_u16())
.with_request_id(request_id.clone()),
})?;
let bytes = self.api_key.scrub_bytes(bytes);
tracing::debug!(
%method,
%url,
status = status.as_u16(),
elapsed_ms = self.clock.now().duration_since(sent).as_millis(),
request_id = request_id.as_deref().unwrap_or("-"),
attempt,
"received response"
);
if self.log_bodies {
let body = String::from_utf8_lossy(&bytes);
tracing::debug!(target: BODY_LOG_TARGET, %body, "response body");
}
if !status.is_success() {
return Err(Error::from_response(status.as_u16(), &bytes, |text| {
self.api_key.scrub(text)
})
.with_request_id(request_id)
.with_retry_after(retry_after));
}
match serde_json::from_slice::<T>(&bytes) {
Ok(parsed) => Ok((
parsed,
request_id,
String::from_utf8_lossy(&bytes).into_owned(),
)),
Err(error) => Err(
Error::new(ErrorKind::InvalidResponse, describe_json_error(&error))
.with_status(status.as_u16())
.with_request_id(request_id),
),
}
}
fn transport_error(&self, error: reqwest::Error) -> Error {
let kind = if error.is_timeout() {
ErrorKind::Timeout
} else if error.is_builder() {
ErrorKind::InvalidRequest
} else {
ErrorKind::Connection
};
let message = match kind {
ErrorKind::Timeout => format!("no response within {:?}", self.retry.timeout),
_ => self.api_key.scrub(&root_cause(&error)),
};
Error::new(kind, message).with_source(error.without_url())
}
}
impl Transport for HttpTransport {
async fn evaluate(&self, request: &Request) -> Result<Reply<Response>, Error> {
let body = serde_json::to_vec(request).map_err(|error| {
Error::new(
ErrorKind::InvalidRequest,
format!("the request could not be serialised: {error}"),
)
.with_source(error)
})?;
self.call(Method::POST, "v1/systemone", Some(body)).await
}
async fn list_models(&self) -> Result<Reply<ModelList>, Error> {
self.call(Method::GET, "v1/models", None).await
}
}
impl fmt::Debug for HttpTransport {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("HttpTransport")
.field("base_url", &self.base_url)
.field("api_key", &self.api_key)
.field("retry", &self.retry)
.field("log_bodies", &self.log_bodies)
.field("throttle", &self.throttle)
.finish_non_exhaustive()
}
}
pub struct HttpTransportBuilder {
api_key: ApiKey,
base_url: BaseUrl,
retry: RetryPolicy,
clock: Arc<dyn Clock>,
user_agent: Option<String>,
log_bodies: bool,
}
impl HttpTransportBuilder {
#[must_use]
pub fn base_url(mut self, base_url: BaseUrl) -> Self {
self.base_url = base_url;
self
}
#[must_use]
pub fn retry_policy(mut self, retry: RetryPolicy) -> Self {
self.retry = retry;
self
}
#[must_use]
pub fn user_agent(mut self, product: impl Into<String>) -> Self {
self.user_agent = Some(product.into());
self
}
#[must_use]
pub const fn log_bodies(mut self, enabled: bool) -> Self {
self.log_bodies = enabled;
self
}
#[must_use]
pub fn clock(mut self, clock: Arc<dyn Clock>) -> Self {
self.clock = clock;
self
}
pub fn build(self) -> Result<HttpTransport, Error> {
let invalid = |what: &str, error: &dyn fmt::Display| {
Error::new(ErrorKind::InvalidRequest, format!("{what}: {error}"))
};
let own_agent = concat!("jev-client/", env!("CARGO_PKG_VERSION"));
let user_agent = self.user_agent.map_or_else(
|| own_agent.to_owned(),
|product| format!("{product} {own_agent}"),
);
let user_agent = HeaderValue::from_str(&user_agent)
.map_err(|error| invalid("invalid user agent", &error))?;
let bearer = Zeroizing::new(format!("Bearer {}", self.api_key.expose()));
let mut authorization = HeaderValue::from_str(&bearer).map_err(|_| {
Error::new(
ErrorKind::InvalidRequest,
"the API key cannot be sent in a header",
)
})?;
authorization.set_sensitive(true);
let provider = Arc::new(rustls::crypto::ring::default_provider());
let tls = rustls::ClientConfig::builder_with_provider(provider)
.with_safe_default_protocol_versions()
.map_err(|error| invalid("TLS could not be initialised", &error))?
.with_platform_verifier()
.map_err(|error| {
invalid(
"the system certificate verifier could not be initialised",
&error,
)
})?
.with_no_client_auth();
let client = reqwest::Client::builder()
.tls_backend_preconfigured(tls)
.https_only(self.base_url.is_https())
.redirect(reqwest::redirect::Policy::none())
.default_headers(HeaderMap::from_iter([(USER_AGENT, user_agent)]))
.timeout(self.retry.timeout)
.connect_timeout(CONNECT_TIMEOUT.min(self.retry.timeout))
.build()
.map_err(|error| invalid("the HTTP client could not be built", &error))?;
Ok(HttpTransport {
client,
base_url: self.base_url,
api_key: self.api_key,
authorization,
retry: self.retry,
clock: self.clock,
log_bodies: self.log_bodies,
throttle: None,
})
}
}
impl fmt::Debug for HttpTransportBuilder {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("HttpTransportBuilder")
.field("base_url", &self.base_url)
.field("api_key", &self.api_key)
.field("retry", &self.retry)
.field("user_agent", &self.user_agent)
.field("log_bodies", &self.log_bodies)
.finish_non_exhaustive()
}
}
fn failure_label(failure: &Error) -> String {
failure.status().map_or_else(
|| format!("{:?}", failure.kind()),
|status| format!("HTTP {status}"),
)
}
fn request_id(headers: &HeaderMap) -> Option<String> {
let value = headers.get(REQUEST_ID_HEADER)?.to_str().ok()?.trim();
(!value.is_empty()).then(|| value.to_owned())
}
enum ReadError {
Transport(reqwest::Error),
TooLarge,
}
async fn read_capped(mut response: reqwest::Response) -> Result<Vec<u8>, ReadError> {
if response
.content_length()
.is_some_and(|length| length > MAX_RESPONSE_BYTES as u64)
{
return Err(ReadError::TooLarge);
}
let mut body = Vec::new();
while let Some(chunk) = response.chunk().await.map_err(ReadError::Transport)? {
if body.len() + chunk.len() > MAX_RESPONSE_BYTES {
return Err(ReadError::TooLarge);
}
body.extend_from_slice(&chunk);
}
Ok(body)
}
fn describe_json_error(error: &serde_json::Error) -> String {
use serde_json::error::Category;
let problem = match error.classify() {
Category::Syntax => "the body is not valid JSON",
Category::Eof => "the body ends unexpectedly",
Category::Data => "the body is JSON but not in the documented shape",
Category::Io => "the body could not be read",
};
format!(
"{problem} (line {}, column {})",
error.line(),
error.column()
)
}
fn root_cause(error: &(dyn std::error::Error + 'static)) -> String {
let mut cause = error;
while let Some(next) = cause.source() {
cause = next;
}
cause.to_string()
}