use std::time::{Duration, Instant, SystemTime};
use reqwest::header::{HeaderValue, ACCEPT, AUTHORIZATION, CONTENT_TYPE, RETRY_AFTER, USER_AGENT};
use reqwest::{Method, StatusCode};
use serde::de::DeserializeOwned;
use serde::Serialize;
use serde_json::Value;
use tokio::time;
use url::Url;
use zeroize::Zeroizing;
use super::{
CallerResource, CompanyId, CompanyOfficerPage, CompanyPage, CompanyResource, DocumentId,
DocumentResource, Envelope, Problem, ResolutionResource, ResolveCompanyRequest,
SearchCompaniesRequest,
};
use crate::config::{is_loopback_url, Credential, EffectiveConfig};
use crate::error::CgdError;
const RESPONSE_LIMIT_BYTES: usize = 16 * 1024 * 1024;
const USER_AGENT_VALUE: &str = concat!("cgd/", env!("CARGO_PKG_VERSION"));
const REQUEST_ID_HEADER: &str = "x-request-id";
const MAX_SAFE_READ_ATTEMPTS: u8 = 2;
const RETRY_BASE_DELAY: Duration = Duration::from_millis(100);
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
struct RetryPolicy {
max_attempts: u8,
}
impl RetryPolicy {
const IDEMPOTENT_READ: Self = Self {
max_attempts: MAX_SAFE_READ_ATTEMPTS,
};
const fn max_attempts(self) -> u8 {
self.max_attempts
}
const fn permits_retry(self) -> bool {
self.max_attempts > 1
}
}
#[derive(Debug)]
struct BufferedResponse {
status: StatusCode,
request_id: Option<String>,
retry_after: Option<HeaderValue>,
bytes: Vec<u8>,
}
#[derive(Debug)]
pub struct ApiResponse<T> {
pub value: T,
pub raw: Value,
pub request_id: Option<String>,
}
#[derive(Clone)]
pub struct CoragridClient {
http: reqwest::Client,
base_url: Url,
credential: Option<Credential>,
timeout: Duration,
}
impl std::fmt::Debug for CoragridClient {
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
formatter
.debug_struct("CoragridClient")
.field("base_url", &self.base_url)
.field("credential", &self.credential)
.field("timeout", &self.timeout)
.finish_non_exhaustive()
}
}
impl CoragridClient {
pub fn new(config: &EffectiveConfig) -> Result<Self, CgdError> {
let connect_timeout = config.timeout.min(Duration::from_secs(10));
let mut builder = reqwest::Client::builder()
.redirect(reqwest::redirect::Policy::none())
.connect_timeout(connect_timeout)
.gzip(true)
.user_agent(USER_AGENT_VALUE);
if is_loopback_url(&config.api_base_url) {
builder = builder.no_proxy();
}
let http = builder.build().map_err(|error| {
CgdError::Internal(format!("cannot initialize the HTTPS client: {error}"))
})?;
Ok(Self {
http,
base_url: config.api_base_url.clone(),
credential: config.credential.clone(),
timeout: config.timeout,
})
}
pub async fn caller(&self) -> Result<ApiResponse<Envelope<CallerResource>>, CgdError> {
self.send(Method::GET, "v1/me", None, RetryPolicy::IDEMPOTENT_READ)
.await
}
pub async fn resolve(
&self,
request: &ResolveCompanyRequest,
) -> Result<ApiResponse<Envelope<ResolutionResource>>, CgdError> {
self.send(
Method::POST,
"v1/companies/resolve",
Some(serialize_body(request)?),
RetryPolicy::IDEMPOTENT_READ,
)
.await
}
pub async fn get_company(
&self,
company_id: &CompanyId,
) -> Result<ApiResponse<Envelope<CompanyResource>>, CgdError> {
self.send(
Method::GET,
&format!("v1/companies/{company_id}"),
None,
RetryPolicy::IDEMPOTENT_READ,
)
.await
}
pub async fn get_company_officers(
&self,
company_id: &CompanyId,
limit: u16,
) -> Result<ApiResponse<CompanyOfficerPage>, CgdError> {
self.send(
Method::GET,
&format!("v1/companies/{company_id}/officers?limit={limit}"),
None,
RetryPolicy::IDEMPOTENT_READ,
)
.await
}
pub async fn get_document_metadata(
&self,
document_id: &DocumentId,
) -> Result<ApiResponse<Envelope<DocumentResource>>, CgdError> {
self.send(
Method::GET,
&format!("v1/documents/{document_id}"),
None,
RetryPolicy::IDEMPOTENT_READ,
)
.await
}
pub async fn search(
&self,
request: &SearchCompaniesRequest,
) -> Result<ApiResponse<CompanyPage>, CgdError> {
self.send(
Method::POST,
"v1/companies/search",
Some(serialize_body(request)?),
RetryPolicy::IDEMPOTENT_READ,
)
.await
}
async fn send<T>(
&self,
method: Method,
path: &str,
body: Option<Vec<u8>>,
retry_policy: RetryPolicy,
) -> Result<ApiResponse<T>, CgdError>
where
T: DeserializeOwned,
{
let credential = self.credential.as_ref().ok_or_else(|| {
CgdError::Authentication(
"authentication required; set CORAGRID_API_KEY or CORAGRID_ACCESS_TOKEN, or configure credential_ref"
.to_owned(),
)
})?;
let url = self.base_url.join(path).map_err(|error| {
CgdError::Internal(format!("cannot construct the Coragrid API URL: {error}"))
})?;
let deadline = Instant::now() + self.timeout;
let operation = self.execute(method, url, body, credential, retry_policy, deadline);
match time::timeout_at(time::Instant::from_std(deadline), operation).await {
Ok(result) => result,
Err(_) => Err(CgdError::Timeout(format!(
"Coragrid API request exceeded {}",
humantime::format_duration(self.timeout)
))),
}
}
async fn execute<T>(
&self,
method: Method,
url: Url,
body: Option<Vec<u8>>,
credential: &Credential,
retry_policy: RetryPolicy,
deadline: Instant,
) -> Result<ApiResponse<T>, CgdError>
where
T: DeserializeOwned,
{
let attempts = retry_policy.max_attempts();
for attempt in 1..=attempts {
let bearer = Zeroizing::new(format!("Bearer {}", credential.bearer()));
let mut authorization = HeaderValue::from_str(&bearer).map_err(|_| {
CgdError::Authentication("the configured credential is malformed".to_owned())
})?;
authorization.set_sensitive(true);
let mut request = self
.http
.request(method.clone(), url.clone())
.header(ACCEPT, "application/json, application/problem+json")
.header(USER_AGENT, USER_AGENT_VALUE)
.header(AUTHORIZATION, authorization);
if let Some(body) = body.as_ref() {
request = request
.header(CONTENT_TYPE, "application/json")
.body(body.clone());
}
let response = match request.send().await {
Ok(response) => response,
Err(error)
if retry_policy.permits_retry() && attempt < attempts && error.is_connect() =>
{
let delay = jittered_backoff(attempt);
if sleep_within_deadline(delay, deadline).await {
continue;
}
return Err(CgdError::Transport(format!(
"cannot reach the Coragrid API: {error}"
)));
}
Err(error) if error.is_timeout() => {
return Err(CgdError::Timeout(
"Coragrid API request timed out".to_owned(),
));
}
Err(error) => {
return Err(CgdError::Transport(format!(
"cannot reach the Coragrid API: {error}"
)));
}
};
let response = match buffer_response(response).await {
Ok(response) => response,
Err(error)
if retry_policy.permits_retry()
&& attempt < attempts
&& matches!(error, CgdError::Transport(_)) =>
{
let delay = jittered_backoff(attempt);
if sleep_within_deadline(delay, deadline).await {
continue;
}
return Err(error);
}
Err(error) => return Err(error),
};
if retry_policy.permits_retry()
&& attempt < attempts
&& response_is_retryable(&response)
{
let delay = response
.retry_after
.as_ref()
.and_then(|value| parse_retry_after(value, SystemTime::now()))
.unwrap_or_else(|| jittered_backoff(attempt));
if sleep_within_deadline(delay, deadline).await {
continue;
}
}
return decode_response(response);
}
Err(CgdError::Internal(
"HTTP retry loop ended without a response".to_owned(),
))
}
}
fn response_is_retryable(response: &BufferedResponse) -> bool {
if !matches!(
response.status,
StatusCode::REQUEST_TIMEOUT
| StatusCode::TOO_MANY_REQUESTS
| StatusCode::BAD_GATEWAY
| StatusCode::SERVICE_UNAVAILABLE
| StatusCode::GATEWAY_TIMEOUT
) {
return false;
}
serde_json::from_slice::<Problem>(&response.bytes)
.is_ok_and(|problem| problem.retryable && problem.status == response.status.as_u16())
}
fn parse_retry_after(value: &HeaderValue, now: SystemTime) -> Option<Duration> {
let value = value.to_str().ok()?.trim();
if let Ok(seconds) = value.parse::<u64>() {
return Some(Duration::from_secs(seconds));
}
let retry_at = httpdate::parse_http_date(value).ok()?;
Some(retry_at.duration_since(now).unwrap_or(Duration::ZERO))
}
fn jittered_backoff(attempt: u8) -> Duration {
let exponent = u32::from(attempt.saturating_sub(1));
let base_millis = u64::try_from(RETRY_BASE_DELAY.as_millis())
.unwrap_or(u64::MAX)
.saturating_mul(2_u64.saturating_pow(exponent));
let lower = base_millis / 2;
let upper = base_millis.saturating_add(base_millis / 2).max(lower);
Duration::from_millis(rand::random_range(lower..=upper))
}
async fn sleep_within_deadline(delay: Duration, deadline: Instant) -> bool {
let remaining = deadline.saturating_duration_since(Instant::now());
if remaining <= delay {
return false;
}
time::sleep(delay).await;
true
}
fn serialize_body<T: Serialize>(value: &T) -> Result<Vec<u8>, CgdError> {
serde_json::to_vec(value)
.map_err(|error| CgdError::Internal(format!("cannot encode API request: {error}")))
}
async fn buffer_response(mut response: reqwest::Response) -> Result<BufferedResponse, CgdError> {
let status = response.status();
let request_id = response
.headers()
.get(REQUEST_ID_HEADER)
.and_then(|value| value.to_str().ok())
.map(str::to_owned);
let retry_after = response.headers().get(RETRY_AFTER).cloned();
if let Some(length) = response.content_length()
&& length > RESPONSE_LIMIT_BYTES as u64
{
return Err(CgdError::Decode(format!(
"Coragrid API response exceeds the {} MiB safety limit",
RESPONSE_LIMIT_BYTES / (1024 * 1024)
)));
}
let mut bytes = Vec::new();
while let Some(chunk) = response.chunk().await.map_err(|error| {
CgdError::Transport(format!("cannot read the Coragrid API response: {error}"))
})? {
if bytes.len().saturating_add(chunk.len()) > RESPONSE_LIMIT_BYTES {
return Err(CgdError::Decode(format!(
"Coragrid API response exceeds the {} MiB safety limit",
RESPONSE_LIMIT_BYTES / (1024 * 1024)
)));
}
bytes.extend_from_slice(&chunk);
}
Ok(BufferedResponse {
status,
request_id,
retry_after,
bytes,
})
}
fn decode_response<T>(response: BufferedResponse) -> Result<ApiResponse<T>, CgdError>
where
T: DeserializeOwned,
{
let BufferedResponse {
status,
request_id,
bytes,
..
} = response;
if !status.is_success() {
if let Ok(problem) = serde_json::from_slice::<Problem>(&bytes) {
if problem.status != status.as_u16() {
return Err(CgdError::Decode(format!(
"RFC 9457 problem status {} does not match HTTP status {}",
problem.status,
status.as_u16()
)));
}
if request_id
.as_deref()
.is_some_and(|request_id| request_id != problem.request_id)
{
return Err(CgdError::Decode(
"RFC 9457 problem request ID does not match the response header".to_owned(),
));
}
return Err(CgdError::Api(Box::new(problem)));
}
let detail = request_id
.as_deref()
.map(|request_id| format!(" (request {request_id})"))
.unwrap_or_default();
return Err(match status.as_u16() {
400 | 413 | 422 => {
CgdError::Usage(format!("Coragrid API rejected the request{detail}"))
}
401 => {
CgdError::Authentication(format!("Coragrid API rejected the credential{detail}"))
}
403 => CgdError::Permission(format!("Coragrid API denied access{detail}")),
404 => CgdError::NotFound(format!("Coragrid resource was not found{detail}")),
409 => CgdError::Conflict(format!("Coragrid resource conflict{detail}")),
429 => CgdError::RateLimited(format!("Coragrid API rate limit reached{detail}")),
408 | 504 => CgdError::Timeout(format!("Coragrid API request timed out{detail}")),
500..=503 => {
CgdError::Unavailable(format!("Coragrid API is temporarily unavailable{detail}"))
}
_ => CgdError::Internal(format!(
"Coragrid API returned unexpected HTTP {}{detail}",
status.as_u16()
)),
});
}
let raw: Value = serde_json::from_slice(&bytes)
.map_err(|error| CgdError::Decode(format!("API response is not valid JSON: {error}")))?;
let value: T = serde_json::from_value(raw.clone()).map_err(|error| {
CgdError::Decode(format!(
"API response does not match the supported public contract: {error}"
))
})?;
Ok(ApiResponse {
value,
raw,
request_id,
})
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn retry_after_accepts_delta_seconds_and_http_dates() {
let now = SystemTime::UNIX_EPOCH + Duration::from_secs(1_700_000_000);
assert_eq!(
parse_retry_after(&HeaderValue::from_static("7"), now),
Some(Duration::from_secs(7))
);
let retry_at = now + Duration::from_secs(11);
let date = HeaderValue::from_str(&httpdate::fmt_http_date(retry_at)).unwrap();
assert_eq!(parse_retry_after(&date, now), Some(Duration::from_secs(11)));
}
#[test]
fn response_retry_requires_matching_retryable_problem() {
let response = |retryable: bool, problem_status: u16| BufferedResponse {
status: StatusCode::SERVICE_UNAVAILABLE,
request_id: None,
retry_after: None,
bytes: serde_json::to_vec(&Problem {
r#type: "https://coragrid.com/problems/dependency-unavailable".to_owned(),
title: "Service temporarily unavailable".to_owned(),
status: problem_status,
detail: "temporary".to_owned(),
instance: "/v1/companies/search".to_owned(),
request_id: "req_014d2pf2dbsqqg28t5cy4tqkff".to_owned(),
code: "dependency_unavailable".to_owned(),
retryable,
})
.unwrap(),
};
assert!(response_is_retryable(&response(true, 503)));
assert!(!response_is_retryable(&response(false, 503)));
assert!(!response_is_retryable(&response(true, 502)));
}
#[test]
fn problem_status_and_request_id_must_match_the_http_envelope() {
let problem = |status: u16, request_id: &str| Problem {
r#type: "https://coragrid.com/problems/not-found".to_owned(),
title: "Resource not found".to_owned(),
status,
detail: "not found".to_owned(),
instance: "/v1/companies/co_example".to_owned(),
request_id: request_id.to_owned(),
code: "not_found".to_owned(),
retryable: false,
};
let response = |problem: Problem| BufferedResponse {
status: StatusCode::NOT_FOUND,
request_id: Some("req_014d2pf2dbsqqg28t5cy4tqkff".to_owned()),
retry_after: None,
bytes: serde_json::to_vec(&problem).unwrap(),
};
assert!(matches!(
decode_response::<Value>(response(problem(503, "req_014d2pf2dbsqqg28t5cy4tqkff"))),
Err(CgdError::Decode(_))
));
assert!(matches!(
decode_response::<Value>(response(problem(404, "req_014d2pf2dbsqqg28t5cy4tqkfg"))),
Err(CgdError::Decode(_))
));
}
}