use std::fmt;
use std::sync::Arc;
use std::time::{Duration, Instant};
use bytes::Bytes;
use serde::de::DeserializeOwned;
use url::Url;
use crate::auth::{AuthStrategy, BearerAuth, StaticTokenProvider, TokenProvider};
use crate::config::Config;
use crate::deadline::Deadline;
use crate::error::{Error, ErrorCode, parse_retry_after_header};
use crate::hooks::{Hooks, NoopHooks, OperationInfo, OperationResult, RequestInfo, RequestResult};
use crate::http::header::{ACCEPT, CONTENT_TYPE, USER_AGENT};
use crate::http::{
Body, HeaderMap, HeaderValue, HttpClient, Request, Response as HttpResponse, StatusCode,
};
use crate::operation::Operation;
use crate::pagination::Page;
use crate::retry::{backoff_with_jitter, effective_attempts};
use crate::route::{Representation, Route};
use crate::security::{is_same_origin, require_secure_endpoint};
use crate::services::campfire_index::CampfireIndex;
use crate::version::default_user_agent;
#[derive(Clone)]
pub struct Client {
shared: Arc<Shared>,
}
#[derive(Clone)]
pub struct AccountClient {
shared: Arc<Shared>,
account_id: String,
}
pub(crate) struct Shared {
pub(crate) config: Config,
pub(crate) base_url: Url,
pub(crate) http: Arc<dyn HttpClient>,
pub(crate) auth: Arc<dyn AuthStrategy>,
pub(crate) user_agent: String,
pub(crate) hooks: Arc<dyn Hooks>,
pub(crate) campfires: CampfireIndex,
}
#[derive(Clone)]
#[non_exhaustive]
pub struct Response {
pub status: StatusCode,
pub headers: HeaderMap,
pub body: Bytes,
pub url: Url,
}
impl fmt::Debug for Response {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("Response")
.field("status", &self.status)
.field("headers", &crate::security::redact_headers(&self.headers))
.field("body", &self.body)
.field("url", &self.url)
.finish()
}
}
impl Response {
pub fn json<T: DeserializeOwned>(&self) -> Result<T, Error> {
serde_json::from_slice(&self.body).map_err(|error| {
let mut mapped = Error::malformed_response(error.to_string());
if let Some(request_id) = self.header("x-request-id") {
mapped = mapped.with_request_id(request_id);
}
mapped
})
}
pub fn header(&self, name: &str) -> Option<&str> {
self.headers.get(name).and_then(|value| value.to_str().ok())
}
}
pub struct ClientBuilder {
config: Config,
auth: Option<Arc<dyn AuthStrategy>>,
http: Option<Arc<dyn HttpClient>>,
user_agent: String,
hooks: Arc<dyn Hooks>,
auth_given: u8,
#[cfg(all(test, feature = "reqwest"))]
campfire_clock: Option<crate::services::campfire_index::Clock>,
}
impl ClientBuilder {
pub fn new(config: Config) -> ClientBuilder {
ClientBuilder {
config,
auth: None,
http: None,
user_agent: default_user_agent(),
hooks: Arc::new(NoopHooks),
auth_given: 0,
#[cfg(all(test, feature = "reqwest"))]
campfire_clock: None,
}
}
#[cfg(all(test, feature = "reqwest"))]
pub(crate) fn campfire_clock(
mut self,
clock: crate::services::campfire_index::Clock,
) -> ClientBuilder {
self.campfire_clock = Some(clock);
self
}
pub fn access_token(self, token: impl Into<String>) -> ClientBuilder {
self.token_provider(StaticTokenProvider::new(token.into()))
}
pub fn token_provider(self, provider: impl TokenProvider + 'static) -> ClientBuilder {
self.auth_strategy(BearerAuth::new(provider))
}
pub fn auth_strategy(mut self, strategy: impl AuthStrategy + 'static) -> ClientBuilder {
self.auth_given += 1;
self.auth = Some(Arc::new(strategy));
self
}
pub fn http_client(mut self, http: impl HttpClient + 'static) -> ClientBuilder {
self.http = Some(Arc::new(http));
self
}
pub fn user_agent(mut self, user_agent: impl Into<String>) -> ClientBuilder {
self.user_agent = user_agent.into();
self
}
pub fn hooks(mut self, hooks: impl Hooks + 'static) -> ClientBuilder {
self.hooks = Arc::new(hooks);
self
}
pub fn operation_deadline(mut self, deadline: Duration) -> ClientBuilder {
self.config.operation_deadline = Some(deadline);
self
}
pub fn build(self) -> Result<Client, Error> {
if self.auth_given > 1 {
return Err(Error::usage(
"Provide either auth or access_token, not both",
));
}
let auth = self
.auth
.ok_or_else(|| Error::usage("Either auth or access_token is required"))?;
let base_url = parse_base_url(&self.config.base_url)?;
self.config.validate()?;
let http = match self.http {
Some(http) => http,
None => shipped_http_client(self.config.timeout)?,
};
#[cfg(all(test, feature = "reqwest"))]
let campfires = match self.campfire_clock {
Some(clock) => CampfireIndex::with_clock(clock),
None => CampfireIndex::new(),
};
#[cfg(not(all(test, feature = "reqwest")))]
let campfires = CampfireIndex::new();
Ok(Client {
shared: Arc::new(Shared {
config: self.config,
base_url,
http,
auth,
user_agent: self.user_agent,
hooks: self.hooks,
campfires,
}),
})
}
}
impl Client {
pub fn builder(config: Config) -> ClientBuilder {
ClientBuilder::new(config)
}
pub fn config(&self) -> &Config {
&self.shared.config
}
pub fn base_url(&self) -> &Url {
&self.shared.base_url
}
pub fn for_account(&self, account_id: impl Into<String>) -> AccountClient {
AccountClient {
shared: self.shared.clone(),
account_id: account_id.into(),
}
}
}
impl fmt::Debug for Client {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("Client")
.field("base_url", &self.shared.base_url)
.finish_non_exhaustive()
}
}
impl fmt::Debug for AccountClient {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("AccountClient")
.field("base_url", &self.shared.base_url)
.field("account_id", &self.account_id)
.finish_non_exhaustive()
}
}
impl AccountClient {
pub fn account_id(&self) -> &str {
&self.account_id
}
pub fn config(&self) -> &Config {
&self.shared.config
}
pub fn base_url(&self) -> &Url {
&self.shared.base_url
}
pub fn max_pages(&self) -> usize {
self.shared.config.max_pages
}
pub(crate) fn shared(&self) -> &Arc<Shared> {
&self.shared
}
pub(crate) fn campfire_index(&self) -> &CampfireIndex {
&self.shared.campfires
}
pub fn client(&self) -> Client {
Client {
shared: self.shared.clone(),
}
}
pub fn operation(&self, route: &'static Route, params: &[&dyn fmt::Display]) -> Operation {
Operation::for_route(route, params)
}
pub async fn send<T: DeserializeOwned>(&self, operation: Operation) -> Result<T, Error> {
self.run(operation, |response| response.json()).await
}
pub(crate) fn deadline(&self) -> Deadline {
Deadline::starting_now(self.shared.config.operation_deadline)
}
pub async fn send_unit(&self, operation: Operation) -> Result<(), Error> {
self.run(operation, |_| Ok(())).await
}
pub async fn send_page<T: DeserializeOwned>(
&self,
operation: Operation,
) -> Result<Page<T>, Error> {
let route = operation.route;
let info = operation.info.clone();
let pinned = operation.pins_a_page();
self.run(operation, |response| {
Ok(Page::new(response.json()?, &response, route, info, pinned))
})
.await
}
pub async fn run<T>(
&self,
operation: Operation,
decode: impl FnOnce(Response) -> Result<T, Error>,
) -> Result<T, Error> {
let deadline = self.deadline();
self.observe(&operation, async {
self.dispatch(&operation, &deadline).await.and_then(decode)
})
.await
}
pub(crate) fn follow_up<T>(&self, page: &Page<T>, next: &Url) -> Result<Operation, Error> {
self.follow_up_at(page.route(), page.info(), page.origin(), next)
}
#[allow(clippy::unused_self)]
pub(crate) fn follow_up_at(
&self,
route: &'static Route,
info: &OperationInfo,
origin: &Url,
next: &Url,
) -> Result<Operation, Error> {
if !is_same_origin(next, origin) {
return Err(Error::usage(format!(
"pagination Link header points to a different origin: {}",
crate::security::redact_url(next)
)));
}
Ok(Operation::at(route, info.clone(), next.clone()))
}
pub async fn execute(&self, operation: Operation) -> Result<Response, Error> {
let deadline = self.deadline();
self.observe(&operation, self.dispatch(&operation, &deadline))
.await
}
pub(crate) async fn observe<T>(
&self,
operation: &Operation,
work: impl std::future::Future<Output = Result<T, Error>>,
) -> Result<T, Error> {
let started = Instant::now();
let hooks = self.shared.hooks.clone();
crate::hooks::guarded(|| hooks.on_operation_start(&operation.info));
let outcome = work.await;
let result = OperationResult {
error: outcome.as_ref().err(),
duration: started.elapsed(),
};
crate::hooks::guarded(|| hooks.on_operation_end(&operation.info, &result));
outcome
}
#[cfg(feature = "tracing")]
async fn dispatch(
&self,
operation: &Operation,
deadline: &Deadline,
) -> Result<Response, Error> {
use tracing::Instrument;
let span = tracing::info_span!(
"basecamp.operation",
operation = operation.route.id,
service = operation.route.service,
http.status = tracing::field::Empty,
request_id = tracing::field::Empty,
);
self.attempts(operation, deadline).instrument(span).await
}
#[cfg(not(feature = "tracing"))]
async fn dispatch(
&self,
operation: &Operation,
deadline: &Deadline,
) -> Result<Response, Error> {
self.attempts(operation, deadline).await
}
#[allow(clippy::too_many_lines)]
async fn attempts(
&self,
operation: &Operation,
deadline: &Deadline,
) -> Result<Response, Error> {
let route = operation.route;
let retry = &route.metadata.retry;
let eligible = route.retry_eligible();
let attempts = if eligible {
effective_attempts(self.shared.config.max_retries, retry.max_attempts)
} else {
1
};
let budget = if eligible {
attempts
} else {
effective_attempts(self.shared.config.max_retries, u32::MAX)
};
let url = self.url_for(operation)?;
let hooks = &self.shared.hooks;
let mut refreshed = false;
let mut attempt: u32 = 1;
let mut retry_index: u32 = 0;
loop {
let generation = self.shared.auth.generation();
let request = deadline.bound(self.prepare(operation, &url)).await?;
let info = RequestInfo {
method: operation.method.clone(),
url: url.clone(),
attempt,
};
crate::hooks::guarded(|| hooks.on_request_start(&info));
let sent_at = Instant::now();
let sent = deadline.bound(self.shared.http.send(request)).await;
let duration = sent_at.elapsed();
match sent {
Err(error) => {
crate::hooks::guarded(|| {
hooks.on_request_end(
&info,
&RequestResult {
status: None,
duration,
error: Some(&error),
retry_after: None,
},
);
});
if eligible
&& attempt < attempts
&& !error.is_timeout()
&& !error.is_deadline_exceeded()
{
let delay =
backoff_with_jitter(retry, retry_index, self.shared.config.max_jitter);
crate::hooks::guarded(|| hooks.on_retry(&info, attempt + 1, &error, delay));
deadline.wait(delay).await?;
retry_index += 1;
attempt += 1;
} else {
return Err(error);
}
}
Ok(response) => {
let status = response.status();
let retry_after =
parse_retry_after_header(response.headers(), jiff::Timestamp::now());
#[cfg(feature = "tracing")]
{
let span = tracing::Span::current();
span.record("http.status", status.as_u16());
if let Some(id) = response
.headers()
.get("x-request-id")
.and_then(|v| v.to_str().ok())
{
span.record("request_id", id);
}
}
if status == StatusCode::UNAUTHORIZED
&& !refreshed
&& attempt < budget
&& self.shared.auth.refreshable()
{
let cause = Error::from_response(status, response.headers(), &[]);
crate::hooks::guarded(|| {
hooks.on_request_end(
&info,
&RequestResult {
status: Some(status),
duration,
error: Some(&cause),
retry_after,
},
);
});
refreshed = true;
let renewed =
match deadline.bound(self.shared.auth.refresh(generation)).await {
Ok(renewed) => renewed,
Err(cause) if cause.is_deadline_exceeded() => return Err(cause),
Err(cause) => {
return Err(Error::new(
ErrorCode::AuthRequired,
"credentials could not be refreshed",
)
.with_status(401)
.with_source(cause));
}
};
if renewed {
crate::hooks::guarded(|| {
hooks.on_retry(&info, attempt + 1, &cause, Duration::ZERO);
});
attempt += 1;
continue;
}
return Err(self.finish_failure(operation, response, deadline).await);
}
if eligible && attempt < attempts && retry.retry_on.contains(&status.as_u16()) {
let cause = Error::from_response(status, response.headers(), &[]);
crate::hooks::guarded(|| {
hooks.on_request_end(
&info,
&RequestResult {
status: Some(status),
duration,
error: Some(&cause),
retry_after,
},
);
});
let delay = match retry_after {
Some(seconds) => Duration::from_secs(u64::from(seconds)),
None => backoff_with_jitter(
retry,
retry_index,
self.shared.config.max_jitter,
),
};
crate::hooks::guarded(|| hooks.on_retry(&info, attempt + 1, &cause, delay));
deadline.wait(delay).await?;
retry_index += 1;
attempt += 1;
continue;
}
let finished = self
.finish(operation, url.clone(), response, deadline)
.await;
crate::hooks::guarded(|| {
hooks.on_request_end(
&info,
&RequestResult {
status: Some(status),
duration,
error: finished.as_ref().err(),
retry_after,
},
);
});
match finished {
Err(error)
if eligible
&& attempt < attempts
&& error.code() == ErrorCode::Network
&& !error.is_timeout()
&& !error.is_deadline_exceeded() =>
{
let delay = backoff_with_jitter(
retry,
retry_index,
self.shared.config.max_jitter,
);
crate::hooks::guarded(|| {
hooks.on_retry(&info, attempt + 1, &error, delay);
});
deadline.wait(delay).await?;
retry_index += 1;
attempt += 1;
}
finished => return finished,
}
}
}
}
}
pub(crate) fn url_for(&self, operation: &Operation) -> Result<Url, Error> {
let mut url = if let Some(url) = &operation.url {
if !is_same_origin(url, &self.shared.base_url) {
return Err(Error::usage("absolute URL must be same-origin as base_url"));
}
url.clone()
} else {
let path = operation.path.trim_start_matches('/');
let mut url = self.shared.base_url.clone();
let prefix = self.shared.base_url.path().trim_end_matches('/');
let account = account_segment(&self.account_id)?;
url.set_path(&format!("{prefix}/{account}/{path}"));
url
};
if !operation.query.is_empty() {
url.query_pairs_mut().extend_pairs(&operation.query);
}
Ok(url)
}
async fn prepare(&self, operation: &Operation, url: &Url) -> Result<Request<Bytes>, Error> {
let mut request = Request::builder()
.method(operation.method.clone())
.uri(url.as_str())
.body(Bytes::new())
.map_err(|error| Error::usage(format!("request could not be built: {error}")))?;
let headers = request.headers_mut();
headers.insert(USER_AGENT, header_value(&self.shared.user_agent)?);
headers.insert(ACCEPT, HeaderValue::from_static("application/json"));
if let Some(body) = &operation.body {
headers.insert(CONTENT_TYPE, header_value(&body.content_type)?);
*request.body_mut() = body.bytes.clone();
}
self.shared.auth.authenticate(&mut request).await?;
Ok(request)
}
async fn finish(
&self,
operation: &Operation,
url: Url,
response: HttpResponse<Body>,
deadline: &Deadline,
) -> Result<Response, Error> {
let status = response.status();
if !status.is_success() {
return Err(self.finish_failure(operation, response, deadline).await);
}
let headers = response.headers().clone();
let limit = self.shared.config.max_response_body_bytes;
let body = deadline
.bound(
response
.into_body()
.collect(limit, || Error::response_too_large(limit)),
)
.await?;
if operation.route.response == Representation::Json
&& body.is_empty()
&& status != StatusCode::NO_CONTENT
{
let mut error = Error::malformed_response("empty body");
if let Some(id) = headers.get("x-request-id").and_then(|v| v.to_str().ok()) {
error = error.with_request_id(id);
}
return Err(error);
}
Ok(Response {
status,
headers,
body,
url,
})
}
async fn finish_failure(
&self,
_operation: &Operation,
response: HttpResponse<Body>,
deadline: &Deadline,
) -> Error {
let status = response.status();
let headers = response.headers().clone();
let read = response
.into_body()
.collect(crate::error::MAX_ERROR_BODY_BYTES, || {
Error::response_too_large(crate::error::MAX_ERROR_BODY_BYTES)
});
match deadline.bound(read).await {
Ok(body) => Error::from_response(status, &headers, &body),
Err(error) if error.is_deadline_exceeded() => error,
Err(_) => Error::from_response(status, &headers, &[]),
}
}
}
#[cfg(feature = "reqwest")]
fn shipped_http_client(timeout: Duration) -> Result<Arc<dyn HttpClient>, Error> {
Ok(Arc::new(crate::http::ReqwestClient::with_timeout(timeout)?))
}
#[cfg(not(feature = "reqwest"))]
fn shipped_http_client(_timeout: Duration) -> Result<Arc<dyn HttpClient>, Error> {
Err(Error::usage(
"no HTTP client: supply one with ClientBuilder::http_client, or enable the reqwest feature",
))
}
fn account_segment(account_id: &str) -> Result<String, Error> {
let trimmed = account_id.trim_matches('.');
if account_id.is_empty() || trimmed.is_empty() {
return Err(Error::usage(format!(
"account id {account_id:?} is not a path segment"
)));
}
Ok(percent_encoding::utf8_percent_encode(account_id, ACCOUNT_SEGMENT).to_string())
}
const ACCOUNT_SEGMENT: &percent_encoding::AsciiSet = &percent_encoding::NON_ALPHANUMERIC
.remove(b'-')
.remove(b'_')
.remove(b'.')
.remove(b'~');
fn parse_base_url(base_url: &str) -> Result<Url, Error> {
let mut url = Url::parse(base_url.trim_end_matches('/'))
.map_err(|error| Error::usage(format!("base URL {base_url}: {error}")))?;
if url.cannot_be_a_base() || url.host_str().is_none() {
return Err(Error::usage(format!("base URL {base_url} has no host")));
}
require_secure_endpoint(&url).map_err(|_| Error::usage("base URL must use HTTPS"))?;
url.set_query(None);
url.set_fragment(None);
Ok(url)
}
pub(crate) fn header_value(value: &str) -> Result<HeaderValue, Error> {
HeaderValue::from_str(value)
.map_err(|_| Error::usage(format!("{value:?} is not a valid header value")))
}
impl From<ErrorCode> for Error {
fn from(code: ErrorCode) -> Error {
Error::new(code, code.as_str())
}
}