#![warn(missing_docs)]
mod error;
pub mod limit;
pub mod query;
pub mod response;
pub mod cn;
#[doc(inline)]
pub use self::error::{Error, Result};
#[doc(inline)]
pub use self::limit::RateLimit;
#[doc(inline)]
pub use self::cn::CnFormat;
#[doc(inline)]
pub use self::query::works::{
FieldQuery, WorkElement, WorkListQuery, WorkResultControl, Works, WorksFilter, WorksIdentQuery,
WorksQuery,
};
pub use self::query::facet::{Facet, FacetCount};
pub use self::query::funders::{Funders, FundersFilter, FundersQuery};
pub use self::query::members::{Members, MembersFilter, MembersQuery};
#[doc(inline)]
pub use self::query::{
Component, CrossrefQuery, CrossrefRoute, FilterParseError, Order, ResultControl, Sort,
};
pub use self::query::{
Journals, JournalsQuery, Licenses, LicensesQuery, Prefixes, Type, Types, Visibility,
WorksComponent,
};
pub use self::response::{
CrossrefType, Failure, Failures, Funder, FunderList, Journal, JournalList, LicenseCount,
LicenseList, Member, MemberList, MessageType, StyleList, TypeList, Work, WorkAgency, WorkList,
};
#[doc(inline)]
pub use self::response::work::{
Affiliation, Agency, Assertion, AssertionGroup, ClinicalTrialNumber, ContentDomain,
Contributor, Date, DateField, DateParts, Explanation, FundingBody, ISSN, InstitutionId, Issue,
License, PartialDate, Reference, RelatedItems, Relation, Relations, ResourceLink, Review,
Update,
};
pub(crate) use self::response::{Message, Response};
pub use async_iterator::Iterator as AsyncIterator;
use crate::limit::{Limiter, retry_after};
use crate::response::Prefix;
use reqwest::{Client, StatusCode};
use std::sync::Arc;
macro_rules! get_item {
($ident:ident, $response:expr) => {{
let response = $response;
match response.message {
Message::$ident(item) => Ok(item),
other => Err(Error::UnexpectedItem {
expected: MessageType::$ident,
got: other.message_type(),
}),
}
}};
}
macro_rules! impl_combined_works_query {
($($name:ident $component:ident,)*) => {
$(
pub async fn $name(&self, ident: WorksIdentQuery) -> Result<WorkList> {
let resp = self.get_response(&$component::Works(ident)).await?;
get_item!(WorkList, resp)
})+
};
}
#[derive(serde::Deserialize)]
struct TransformFailure {
code: String,
doi: Option<String>,
message: String,
}
#[derive(Debug, Clone)]
pub struct Crossref {
base_url: String,
client: Client,
limiter: Arc<Limiter>,
max_retries: u32,
}
impl Crossref {
const BASE_URL: &'static str = "https://api.crossref.org";
pub fn builder() -> CrossrefBuilder {
CrossrefBuilder::new()
}
pub fn base_url(&self) -> &str {
&self.base_url
}
pub fn rate_limit(&self) -> RateLimit {
self.limiter.rate()
}
pub fn api_pool(&self) -> Option<String> {
self.limiter.pool()
}
impl_combined_works_query!(funder_works Funders, member_works Members,
type_works Types, journal_works Journals, prefix_works Prefixes,);
async fn get_response<T: CrossrefQuery>(&self, query: &T) -> Result<Response> {
let url = query.to_url(&self.base_url)?;
let response = self.send(&url).await?;
if response.status() == StatusCode::NOT_FOUND {
return Err(Error::ResourceNotFound {
resource: Box::new(query.clone().resource_component()),
});
}
let body = Self::into_success(response).await?.bytes().await?;
serde_json::from_slice(&body).map_err(|error| Error::Serde { error })
}
async fn send(&self, url: &str) -> Result<reqwest::Response> {
self.send_with(url, |request| request).await
}
async fn send_with(
&self,
url: &str,
customize: impl Fn(reqwest::RequestBuilder) -> reqwest::RequestBuilder,
) -> Result<reqwest::Response> {
let mut attempt = 0u32;
loop {
self.limiter.acquire().await;
tracing::debug!(%url, attempt, "crossref request");
let response = customize(self.client.get(url)).send().await?;
self.limiter.observe(response.headers());
if response.status() != StatusCode::TOO_MANY_REQUESTS {
return Ok(response);
}
let limit = self.limiter.rate();
let delay = retry_after(response.headers())
.unwrap_or_else(|| limit.interval * 2u32.pow(attempt.min(5)));
self.limiter.back_off(delay);
attempt += 1;
if attempt > self.max_retries {
tracing::warn!(%url, attempt, "crossref rate limited, retries exhausted");
return Err(Error::RateLimited {
attempts: attempt,
limit,
});
}
tracing::debug!(%url, attempt, ?delay, "crossref rate limited, retrying");
}
}
async fn into_success(response: reqwest::Response) -> Result<reqwest::Response> {
if response.status().is_success() {
return Ok(response);
}
let status = response.error_for_status_ref().expect_err("not a success");
let body = response.text().await.unwrap_or_default();
if let Ok(Response {
message: Message::ValidationFailure(failures),
..
}) = serde_json::from_str::<Response>(&body)
{
return Err(Error::ValidationFailure { failures });
}
if let Ok(failure) = serde_json::from_str::<TransformFailure>(&body) {
return Err(Error::ValidationFailure {
failures: vec![Failure {
type_: failure.code,
value: failure.doi.unwrap_or_default(),
message: failure.message,
}]
.into(),
});
}
Err(status.into())
}
pub async fn works<T: Into<WorkListQuery>>(&self, query: T) -> Result<WorkList> {
let resp = self.get_response(&query.into()).await?;
get_item!(WorkList, resp)
}
pub async fn work(&self, doi: &str) -> Result<Work> {
let resp = self
.get_response(&Works::Identifier(doi.to_string()))
.await?;
get_item!(Work, resp).map(|x| *x)
}
pub fn deep_page<T: Into<WorkListQuery>>(&self, query: T) -> WorkListIterator<'_> {
WorkListIterator::new(query.into(), self)
}
pub async fn transform(&self, doi: &str, format: &CnFormat) -> Result<String> {
let url = format!("{}/works/{}/transform", self.base_url, doi);
let response = self
.send_with(&url, |request| {
request.header(reqwest::header::ACCEPT, format.accept().as_ref())
})
.await?;
Ok(Self::into_success(response).await?.text().await?)
}
pub async fn styles(&self) -> Result<StyleList> {
let response = self.send(&format!("{}/styles", self.base_url)).await?;
let body = Self::into_success(response).await?.bytes().await?;
let response: Response =
serde_json::from_slice(&body).map_err(|error| Error::Serde { error })?;
get_item!(StyleList, response)
}
pub async fn work_agency(&self, doi: &str) -> Result<WorkAgency> {
let resp = self.get_response(&Works::Agency(doi.to_string())).await?;
get_item!(WorkAgency, resp)
}
pub async fn funders(&self, funders: FundersQuery) -> Result<FunderList> {
let resp = self.get_response(&Funders::Query(funders)).await?;
get_item!(FunderList, resp)
}
pub async fn funder(&self, id: &str) -> Result<Funder> {
let resp = self
.get_response(&Funders::Identifier(id.to_string()))
.await?;
get_item!(Funder, resp).map(|x| *x)
}
pub async fn members(&self, members: MembersQuery) -> Result<MemberList> {
let resp = self.get_response(&Members::Query(members)).await?;
get_item!(MemberList, resp)
}
pub async fn member(&self, member_id: &str) -> Result<Member> {
let resp = self
.get_response(&Members::Identifier(member_id.to_string()))
.await?;
get_item!(Member, resp).map(|x| *x)
}
pub async fn prefix(&self, id: &str) -> Result<Prefix> {
let resp = self
.get_response(&Prefixes::Identifier(id.to_string()))
.await?;
get_item!(Prefix, resp)
}
pub async fn journal(&self, id: &str) -> Result<Journal> {
let resp = self
.get_response(&Journals::Identifier(id.to_string()))
.await?;
get_item!(Journal, resp).map(|x| *x)
}
pub async fn journals(&self, journals: JournalsQuery) -> Result<JournalList> {
let resp = self.get_response(&Journals::Query(journals)).await?;
get_item!(JournalList, resp)
}
pub async fn licenses(&self, licenses: LicensesQuery) -> Result<LicenseList> {
let resp = self.get_response(&Licenses::Query(licenses)).await?;
get_item!(LicenseList, resp)
}
pub async fn types(&self) -> Result<TypeList> {
let resp = self.get_response(&Types::All).await?;
get_item!(TypeList, resp)
}
pub async fn type_(&self, id: &Type) -> Result<CrossrefType> {
let resp = self
.get_response(&Types::Identifier(id.id().to_string()))
.await?;
get_item!(Type, resp)
}
pub async fn random_dois(&self, len: usize) -> Result<Vec<String>> {
self.works(WorksQuery::random(len))
.await
.map(|x| x.items.into_iter().map(|x| x.doi).collect())
}
}
#[derive(Debug, Default)]
pub struct CrossrefBuilder {
user_agent: Option<String>,
plus_token: Option<String>,
base_url: Option<String>,
rate_limit: Option<RateLimit>,
max_retries: Option<u32>,
}
impl CrossrefBuilder {
const DEFAULT_MAX_RETRIES: u32 = 3;
pub fn new() -> CrossrefBuilder {
CrossrefBuilder::default()
}
pub fn polite<'a>(mut self, email: impl Into<Option<&'a str>>) -> Self {
if let Some(email) = email.into() {
self.user_agent = Some(format!(
"{}/{} ({}; mailto:{})",
env!("CARGO_PKG_NAME"),
env!("CARGO_PKG_VERSION"),
env!("CARGO_PKG_REPOSITORY"),
email
));
}
self
}
pub fn user_agent<'a>(mut self, user_agent: impl Into<Option<&'a str>>) -> Self {
self.user_agent = user_agent.into().map(str::to_owned);
self
}
pub fn token<'a>(mut self, token: impl Into<Option<&'a str>>) -> Self {
self.plus_token = token.into().map(str::to_owned);
self
}
pub fn base_url<'a>(mut self, base_url: impl Into<Option<&'a str>>) -> Self {
self.base_url = base_url.into().map(str::to_owned);
self
}
pub fn rate_limit(mut self, rate_limit: impl Into<Option<RateLimit>>) -> Self {
self.rate_limit = rate_limit.into();
self
}
pub fn max_retries(mut self, max_retries: impl Into<Option<u32>>) -> Self {
self.max_retries = max_retries.into();
self
}
pub fn build(self) -> Result<Crossref> {
use reqwest::header;
let mut headers = header::HeaderMap::new();
if let Some(agent) = &self.user_agent {
headers.insert(
header::USER_AGENT,
header::HeaderValue::from_str(agent).map_err(|_| Error::Config {
msg: format!("failed to create User Agent header for `{}`", agent),
})?,
);
}
if let Some(token) = &self.plus_token {
headers.insert(
header::AUTHORIZATION,
header::HeaderValue::from_str(token).map_err(|_| Error::Config {
msg: format!("failed to create AUTHORIZATION header for `{}`", token),
})?,
);
}
let client = reqwest::Client::builder()
.default_headers(headers)
.build()
.map_err(|_| Error::Config {
msg: "failed to initialize TLS backend".to_string(),
})?;
Ok(Crossref {
base_url: self
.base_url
.unwrap_or_else(|| Crossref::BASE_URL.to_string()),
client,
limiter: Arc::new(Limiter::new(self.rate_limit.unwrap_or_default())),
max_retries: self.max_retries.unwrap_or(Self::DEFAULT_MAX_RETRIES),
})
}
}
pub struct WorkListIterator<'a> {
query: WorkListQuery,
client: &'a Crossref,
finish_next_iteration: bool,
}
impl<'a> WorkListIterator<'a> {
pub fn new(query: WorkListQuery, client: &'a Crossref) -> Self {
Self {
query,
client,
finish_next_iteration: false,
}
}
pub fn into_work_iter(self) -> WorkIterator<'a> {
WorkIterator {
pages: self,
buffer: Vec::new().into_iter(),
}
}
}
pub struct WorkIterator<'a> {
pages: WorkListIterator<'a>,
buffer: std::vec::IntoIter<Work>,
}
impl async_iterator::Iterator for WorkIterator<'_> {
type Item = Result<Work>;
async fn next(&mut self) -> Option<Self::Item> {
loop {
if let Some(work) = self.buffer.next() {
return Some(Ok(work));
}
match self.pages.next().await? {
Ok(page) => self.buffer = page.items.into_iter(),
Err(err) => return Some(Err(err)),
}
}
}
}
impl async_iterator::Iterator for WorkListIterator<'_> {
type Item = Result<WorkList>;
async fn next(&mut self) -> Option<Self::Item> {
if self.finish_next_iteration {
return None;
}
{
let control = &mut self.query.query_mut().result_control;
if control.is_none() {
*control = Some(WorkResultControl::new_cursor());
}
}
let page = match self.client.get_response(&self.query).await {
Ok(resp) => get_item!(WorkList, resp),
Err(err) => Err(err),
};
let worklist = match page {
Ok(worklist) => worklist,
Err(err) => {
self.finish_next_iteration = true;
return Some(Err(err));
}
};
if let Some(cursor) = &worklist.next_cursor {
match &mut self.query.query_mut().result_control {
Some(WorkResultControl::Cursor { token, .. }) => {
*token = Some(cursor.clone())
}
Some(WorkResultControl::Standard(_)) => {
self.finish_next_iteration = true;
}
_ => (),
}
} else {
self.finish_next_iteration = true;
}
if worklist.items.is_empty() {
None
} else {
Some(Ok(worklist))
}
}
}