Skip to main content

crossref_client/
lib.rs

1//! An async client for the [Crossref REST API](https://api.crossref.org/swagger-ui/index.html).
2//!
3//! `crossref-client` is a hard fork of [`crossref-rs`](https://github.com/MattsSe/crossref-rs)
4//! and has diverged substantially from it; changes are not upstreamed.
5//!
6//! When a route answers something this crate did not expect, the api documents
7//! itself in [the swagger UI](https://api.crossref.org/swagger-ui/index.html)
8//! and in [`CrossRef/rest-api-doc`](https://github.com/CrossRef/rest-api-doc),
9//! and its bugs and in-flight changes are tracked in the open on
10//! [crossref's own issue board](https://crossref.atlassian.net/jira/software/c/projects/CR/list/?jql=project%20%3D%20CR%20ORDER%20BY%20cf%5B10019%5D%20ASC).
11//!
12//! The [`Crossref`] client provides methods matching the Crossref API routes:
13
14//! * `works` - `/works` route
15//! * `members` - `/members` route
16//! * `prefixes` - `/prefixes` route
17//! * `funders` - `/funders` route
18//! * `journals` - `/journals` route
19//! * `licenses` - `/licenses` route
20//! * `types` - `/types` route
21//! * `agency` - `/works/{doi}/agency` get DOI minting agency
22//!
23//! ## Usage
24
25//! ### Create a `Crossref` client:
26
27//! ```no_run
28//! # use crossref_client::Crossref;
29//! # async fn run() -> Result<(), crossref_client::Error> {
30//! let client = Crossref::builder().build()?;
31//! # Ok(())
32//! # }
33//! ```
34//!
35//! If you have an [Authorization token for Crossref's Plus service](https://github.com/CrossRef/rest-api-doc#authorization-token-for-plus-service):
36//!
37//! ```no_run
38//! # use crossref_client::Crossref;
39//! # async fn run() -> Result<(), crossref_client::Error> {
40//! let client = Crossref::builder()
41//! .token("token")
42//! .build()?;
43//! # Ok(())
44//! # }
45//! ```
46//!
47//! Encouraged to use the **The Polite Pool**:
48//!
49//! [Good manners = more reliable service](https://github.com/CrossRef/rest-api-doc#good-manners--more-reliable-service)
50//!
51//! To get into Crossref's polite pool include a email address
52//!
53//! ```no_run
54//! # use crossref_client::Crossref;
55//! # async fn run() -> Result<(), crossref_client::Error> {
56//! let client = Crossref::builder()
57//!     .polite("polite@example.com")
58//!     .token("your token")
59//!     .build()?;
60//! # Ok(())
61//! # }
62//! ```
63//!
64//! ### Constructing Queries
65//! Not all components support queries and there are custom available parameters for each route that supports querying.
66//! For each resource components that supports querying there exist a Query struct: `WorksQuery`, `MembersQuery`, `FundersQuery`. The `WorksQuery` also differs from the others by supporting [deep paging with cursors](https://github.com/CrossRef/rest-api-doc#deep-paging-with-cursors) and [field queries](https://github.com/CrossRef/rest-api-doc#works-field-queries).
67//!
68//! Otherwise creating queries works the same for all resource components:
69//!
70//! ```no_run
71//! # use crossref_client::*;
72//! # async fn run() -> crossref_client::Result<()> {
73//! let query = WorksQuery::new("Machine Learning")
74//! // field queries supported for `Works`
75//! .field_query(FieldQuery::author("Some Author"))
76//! // filters are specific for each resource component
77//! .filter(WorksFilter::HasOrcid)
78//! .order(Order::Asc)
79//! .sort(Sort::Score);
80//! # Ok(())
81//! # }
82//! ```
83//!
84//!
85//! ### Get Records
86//!
87//! See [this table](https://github.com/CrossRef/rest-api-doc#resource-components) for a detailed overview of the major components.
88//!
89//! There are 3 available targets:
90//!
91//! * **standalone resource components**: `/works`, `/members`, etc. that return a list list of the corresponding items and can be specified with queries
92//! * **Resource component with identifiers**: `/works/{doi}?<query>`,`/members/{member_id}?<query>`, etc. that returns a single item if found.
93//! * **combined with the `works` route**: The works component can be appended to other resources: `/members/{member_id}/works?<query>` etc. that returns a list of matching `Work` items.
94//!
95//! This resembles in the enums of the resource components, eg. for `Members`:
96//!
97//! ```no_run
98//! # use crossref_client::query::*;
99//! pub enum Members {
100//!     /// target a specific member at `/members/{id}`
101//!     Identifier(String),
102//!     /// target all members that match the query at `/members?query...`
103//!     Query(MembersQuery),
104//!     /// target a `Work` for a specific member at `/members/{id}/works?query..`
105//!     Works(WorksIdentQuery),
106//! }
107//! ```
108//!
109//! All options are supported by the client:
110//!
111//! **Single Item by DOI (ID)**
112//!
113//! Analogous methods exist for all resource components
114//!
115//! ```no_run
116//! # use crossref_client::*;
117//! # async fn run() -> crossref_client::Result<()> {
118//! # let client = Crossref::builder().build()?;
119//! let work = client.work("10.1037/0003-066X.59.1.29").await?;
120//!
121//! let agency = client.work_agency("10.1037/0003-066X.59.1.29").await?;
122//!
123//! let funder = client.funder("funder_id").await?;
124//!
125//! let member = client.member("member_id").await?;
126//! # Ok(())
127//! # }
128//! ```
129//!
130//! **Query**
131//!
132//! ```no_run
133//! # use crossref_client::*;
134//! # async fn run() -> crossref_client::Result<()> {
135//! # let client = Crossref::builder().build()?;
136//! let query = WorksQuery::new("Machine Learning");
137//!
138//! // one page of the matching results
139//! let works = client.works(query).await?;
140//! # Ok(())
141//! # }
142//! ```
143//!
144//! Alternatively insert a free form query term directly
145//!
146//! ```no_run
147//! # use crossref_client::*;
148//! # async fn run() -> crossref_client::Result<()> {
149//! # let client = Crossref::builder().build()?;
150//!
151//! // one page of the matching results
152//! let works = client.works("Machine Learning").await?;
153//! # Ok(())
154//! # }
155//! ```
156//!
157//! **Combining Routes with the `Works` route**
158//!
159//! For each resource component other than `Works` there exist methods to append a `WorksQuery` with the ID option `/members/{member_id}/works?<query>?`
160//!
161//! ```no_run
162//! # use crossref_client::*;
163//! # async fn run() -> crossref_client::Result<()> {
164//! # let client = Crossref::builder().build()?;
165//! let works = client.member_works( WorksQuery::new("machine learning")
166//! .sort(Sort::Score).into_ident("member_id")).await?;
167//! # Ok(())
168//! # }
169//! ```
170//!
171//! This would be the same as using the [`Crossref::works`] method by supplying the combined type
172//!
173//! ```no_run
174//! # use crossref_client::*;
175//! # async fn run() -> crossref_client::Result<()> {
176//! # let client = Crossref::builder().build()?;
177//! let works = client.works(WorksQuery::new("machine learning")
178//!     .sort(Sort::Score)
179//!     .into_combined_query::<Members>("member_id")).await?;
180//! # Ok(())
181//! # }
182//! ```
183//!
184//! ** Deep paging for `Works` **
185//! [Deep paging results](https://github.com/CrossRef/rest-api-doc#deep-paging-with-cursors)
186//! Deep paging is supported for all queries, that return a list of `Work`, `WorkList`.
187//! This function returns a new iterator over pages of `Work`, which is returned as bulk of items as a `WorkList` by crossref.
188//! Usually a single page `WorkList` contains 20 items.
189//!
190//! # Example
191//!
192//! Iterate over all `Works` linked to search term `Machine Learning`
193//!
194//! ```no_run
195//! use crossref_client::{AsyncIterator, Crossref, WorksQuery, Work};
196//! # async fn run() -> Result<(), crossref_client::Error> {
197//! let client = Crossref::builder().build()?;
198//!
199//! let mut pages = client.deep_page(WorksQuery::new("Machine Learning"));
200//! let mut all_works: Vec<Work> = Vec::new();
201//! while let Some(page) = pages.next().await {
202//!     let page = page?;
203//!     all_works.extend(page.items);
204//! }
205//!
206//! # Ok(())
207//! # }
208//! ```
209//!
210//! Which can be simplified to
211//!
212//! ```no_run
213//! use crossref_client::{AsyncIterator, Crossref, WorksQuery, Work};
214//! # async fn run() -> Result<(), crossref_client::Error> {
215//! let client = Crossref::builder().build()?;
216//!
217//! let mut works = client.deep_page("Machine Learning").into_work_iter();
218//! let mut all_works: Vec<Work> = Vec::new();
219//! while let Some(work) = works.next().await {
220//!     let work = work?;
221//!     all_works.push(work);
222//! }
223//!
224//! # Ok(())
225//! # }
226//! ```
227//!
228//!
229//! # Example
230//!
231//! Iterate over all the pages (`WorkList`) of the funder with id `funder id` by using a combined query.
232//! A single `WorkList` usually holds 20 `Work` items.
233//!
234//! ```no_run
235//! use crossref_client::{AsyncIterator, Crossref, Funders, WorksQuery, Work, WorkList};
236//! # async fn run() -> Result<(), crossref_client::Error> {
237//! let client = Crossref::builder().build()?;
238//!
239//! let mut pages = client.deep_page(WorksQuery::default().into_combined_query::<Funders>("funder id"));
240//! let mut all_funder_work_list: Vec<WorkList> = Vec::new();
241//! while let Some(page) = pages.next().await {
242//!     let page = page?;
243//!     all_funder_work_list.push(page);
244//! }
245//!
246//! # Ok(())
247//! # }
248//! ```
249//! # Example
250//!
251//! Iterate over all `Work` items of a specfic funder directly.
252//!
253//! ```no_run
254//! use crossref_client::{AsyncIterator, Crossref, Funders, WorksQuery, Work, WorkList};
255//! # async fn run() -> Result<(), crossref_client::Error> {
256//! let client = Crossref::builder().build()?;
257//!
258//! let mut works = client.deep_page(WorksQuery::default()
259//!         .into_combined_query::<Funders>("funder id"))
260//!         .into_work_iter();
261//! let mut all_works: Vec<Work> = Vec::new();
262//! while let Some(work) = works.next().await {
263//!     let work = work?;
264//!     all_works.push(work);
265//! }
266//!
267//! # Ok(())
268//! # }
269//! ```
270
271#![warn(missing_docs)]
272
273mod error;
274/// client side rate limiting
275pub mod limit;
276/// provides types to construct a specific query
277pub mod query;
278/// provides the response types of the crossref api
279pub mod response;
280
281/// content negotiation
282pub mod cn;
283
284#[doc(inline)]
285pub use self::error::{Error, Result};
286
287#[doc(inline)]
288pub use self::limit::RateLimit;
289
290#[doc(inline)]
291pub use self::cn::CnFormat;
292
293#[doc(inline)]
294pub use self::query::works::{
295    FieldQuery, WorkElement, WorkListQuery, WorkResultControl, Works, WorksFilter, WorksIdentQuery,
296    WorksQuery,
297};
298
299pub use self::query::facet::{Facet, FacetCount};
300pub use self::query::funders::{Funders, FundersFilter, FundersQuery};
301pub use self::query::members::{Members, MembersFilter, MembersQuery};
302#[doc(inline)]
303pub use self::query::{
304    Component, CrossrefQuery, CrossrefRoute, FilterParseError, Order, ResultControl, Sort,
305};
306pub use self::query::{
307    Journals, JournalsQuery, Licenses, LicensesQuery, Prefixes, Type, Types, Visibility,
308    WorksComponent,
309};
310pub use self::response::{
311    CrossrefType, Failure, Failures, Funder, FunderList, Journal, JournalList, LicenseCount,
312    LicenseList, Member, MemberList, MessageType, StyleList, TypeList, Work, WorkAgency, WorkList,
313};
314
315/// The types that appear in the public fields of a [`Work`], re-exported so a
316/// caller of [`Crossref::works`] can name them without reaching into
317/// [`response::work`].
318#[doc(inline)]
319pub use self::response::work::{
320    Affiliation, Agency, Assertion, AssertionGroup, ClinicalTrialNumber, ContentDomain,
321    Contributor, Date, DateField, DateParts, Explanation, FundingBody, ISSN, InstitutionId, Issue,
322    License, PartialDate, Reference, RelatedItems, Relation, Relations, ResourceLink, Review,
323    Update,
324};
325
326pub(crate) use self::response::{Message, Response};
327
328/// The async iterator trait implemented by [`WorkListIterator`].
329///
330/// Re-exported so callers can drive deep paging without depending on
331/// `async-iterator` directly.
332pub use async_iterator::Iterator as AsyncIterator;
333
334use crate::limit::{Limiter, retry_after};
335use crate::response::Prefix;
336use reqwest::{Client, StatusCode};
337use std::sync::Arc;
338
339/// Unwraps the payload a route is expected to answer with, or reports what
340/// crossref sent instead.
341macro_rules! get_item {
342    ($ident:ident, $response:expr) => {{
343        let response = $response;
344        match response.message {
345            Message::$ident(item) => Ok(item),
346            other => Err(Error::UnexpectedItem {
347                expected: MessageType::$ident,
348                got: other.message_type(),
349            }),
350        }
351    }};
352}
353
354macro_rules! impl_combined_works_query {
355    ($($name:ident  $component:ident,)*) => {
356        $(
357        /// Return one page of the components's `Work` that match the query
358        ///
359        pub async fn $name(&self, ident: WorksIdentQuery) -> Result<WorkList> {
360            let resp = self.get_response(&$component::Works(ident)).await?;
361            get_item!(WorkList, resp)
362        })+
363    };
364}
365
366/// The bare body crossref answers a content-negotiation request it cannot
367/// serve with, which is shaped nothing like a `validation-failure`.
368#[derive(serde::Deserialize)]
369struct TransformFailure {
370    /// what went wrong, e.g. `style-not-found`
371    code: String,
372    /// the DOI that was asked for
373    doi: Option<String>,
374    /// the explanation, e.g. `Style [vancouver] does not exist`
375    message: String,
376}
377
378/// Struct for Crossref search API methods
379///
380/// Cloning is cheap and shares the connection pool and the rate limiter, so
381/// concurrent callers should clone one client rather than build several -- see
382/// [`Crossref::rate_limit`].
383#[derive(Debug, Clone)]
384pub struct Crossref {
385    /// use another base url than `api.crossref.org`
386    base_url: String,
387    /// the reqwest client that handles the requests
388    client: Client,
389    /// paces requests against the budget crossref grants, shared between clones
390    limiter: Arc<Limiter>,
391    /// how many times a `429` is retried before giving up
392    max_retries: u32,
393}
394
395impl Crossref {
396    const BASE_URL: &'static str = "https://api.crossref.org";
397
398    /// Constructs a new `CrossrefBuilder`.
399    ///
400    /// This is the same as `Crossref::builder()`.
401    pub fn builder() -> CrossrefBuilder {
402        CrossrefBuilder::new()
403    }
404
405    /// The url every route is appended to, `https://api.crossref.org` unless
406    /// [`CrossrefBuilder::base_url`] said otherwise.
407    pub fn base_url(&self) -> &str {
408        &self.base_url
409    }
410
411    /// The request budget crossref last reported for this client.
412    ///
413    /// Crossref sends the budget on every response and the client paces itself
414    /// against it, so before the first request this is the assumed
415    /// [`RateLimit::CONSERVATIVE`] (or whatever [`CrossrefBuilder::rate_limit`]
416    /// was given) and afterwards it is what crossref actually granted.
417    pub fn rate_limit(&self) -> RateLimit {
418        self.limiter.rate()
419    }
420
421    /// The pool crossref sorted the last request into, from `x-api-pool`.
422    ///
423    /// `polite` if [`CrossrefBuilder::polite`] worked, `plus` for a Plus token,
424    /// otherwise `public`. [`None`] before the first request.
425    pub fn api_pool(&self) -> Option<String> {
426        self.limiter.pool()
427    }
428
429    // generate all functions to query combined endpoints
430    impl_combined_works_query!(funder_works Funders, member_works Members,
431    type_works Types, journal_works Journals, prefix_works Prefixes,);
432
433    /// Transforms the `CrossrefQuery` in the request route and  executes the request
434    ///
435    /// # Errors
436    ///
437    /// If crossref could not resolve the route, a `ResourceNotFound` error is returned.
438    /// Also fails if the json response body could not be parsed into `Response`.
439    /// Fails if there was an error in reqwest executing the request [::reqwest::RequestBuilder::send]
440    async fn get_response<T: CrossrefQuery>(&self, query: &T) -> Result<Response> {
441        let url = query.to_url(&self.base_url)?;
442        let response = self.send(&url).await?;
443
444        // crossref answers an unresolvable route with a plain-text body, which
445        // would otherwise surface as an opaque deserialization failure
446        if response.status() == StatusCode::NOT_FOUND {
447            return Err(Error::ResourceNotFound {
448                resource: Box::new(query.clone().resource_component()),
449            });
450        }
451
452        // deserialized here rather than through `reqwest`'s `json()` so a
453        // shape crossref changed surfaces as `Error::Serde`, which names the
454        // field that failed
455        let body = Self::into_success(response).await?.bytes().await?;
456        serde_json::from_slice(&body).map_err(|error| Error::Serde { error })
457    }
458
459    /// Sends a `GET`, pacing it against the rate limit and retrying a `429`.
460    ///
461    /// Waits for a slot from the shared [`Limiter`] first, then feeds the
462    /// budget crossref reports back into it. A `429` means the budget we
463    /// believed in was wrong, so the whole client backs off -- for as long as
464    /// `retry-after` asks, or exponentially from the reported interval -- and
465    /// the request is sent again up to [`CrossrefBuilder::max_retries`] times.
466    async fn send(&self, url: &str) -> Result<reqwest::Response> {
467        self.send_with(url, |request| request).await
468    }
469
470    /// [`Crossref::send`], with `customize` applied to the request first.
471    async fn send_with(
472        &self,
473        url: &str,
474        customize: impl Fn(reqwest::RequestBuilder) -> reqwest::RequestBuilder,
475    ) -> Result<reqwest::Response> {
476        let mut attempt = 0u32;
477        loop {
478            self.limiter.acquire().await;
479            tracing::debug!(%url, attempt, "crossref request");
480
481            let response = customize(self.client.get(url)).send().await?;
482            self.limiter.observe(response.headers());
483
484            if response.status() != StatusCode::TOO_MANY_REQUESTS {
485                return Ok(response);
486            }
487
488            let limit = self.limiter.rate();
489            let delay = retry_after(response.headers())
490                .unwrap_or_else(|| limit.interval * 2u32.pow(attempt.min(5)));
491            self.limiter.back_off(delay);
492            attempt += 1;
493
494            if attempt > self.max_retries {
495                tracing::warn!(%url, attempt, "crossref rate limited, retries exhausted");
496                return Err(Error::RateLimited {
497                    attempts: attempt,
498                    limit,
499                });
500            }
501            tracing::debug!(%url, attempt, ?delay, "crossref rate limited, retrying");
502        }
503    }
504
505    /// Turns a non-success response into the error crossref described.
506    ///
507    /// Crossref answers a bad filter, sort field or field query with a `400`
508    /// and a `validation-failure` body naming what it did not recognise, and an
509    /// unservable content-negotiation format with a `406` and a bare
510    /// `{code, message}` -- both of which
511    /// [`reqwest::Response::error_for_status`] would throw away.
512    async fn into_success(response: reqwest::Response) -> Result<reqwest::Response> {
513        if response.status().is_success() {
514            return Ok(response);
515        }
516
517        // taken before the body is consumed, so the status is still reportable
518        // if the body turns out not to explain itself
519        let status = response.error_for_status_ref().expect_err("not a success");
520        let body = response.text().await.unwrap_or_default();
521
522        if let Ok(Response {
523            message: Message::ValidationFailure(failures),
524            ..
525        }) = serde_json::from_str::<Response>(&body)
526        {
527            return Err(Error::ValidationFailure { failures });
528        }
529        if let Ok(failure) = serde_json::from_str::<TransformFailure>(&body) {
530            return Err(Error::ValidationFailure {
531                failures: vec![Failure {
532                    type_: failure.code,
533                    value: failure.doi.unwrap_or_default(),
534                    message: failure.message,
535                }]
536                .into(),
537            });
538        }
539        Err(status.into())
540    }
541
542    //fn get_response_blocking<T: CrossrefQuery>(&self, query: &T) -> Result<Response> {
543    //    let resp = self
544    //        .blocking_client
545    //        .get(&query.to_url(&self.base_url)?)
546    //        .send()?
547    //        .text()?;
548    //    if resp.starts_with("Resource not found") {
549    //        Err(Error::ResourceNotFound {
550    //            resource: Box::new(query.clone().resource_component()),
551    //        }
552    //        .into())
553    //    } else {
554    //        Ok(serde_json::from_str(&resp)?)
555    //    }
556    //}
557
558    /// Return the `Work` items that match a certain query.
559    ///
560    /// To search only by query terms use the convenience query method [`Crossref::works`]
561    ///
562    /// # Example
563    ///
564    /// ```no_run
565    /// use crossref_client::{Crossref, WorksQuery, WorksFilter, FieldQuery};
566    /// # async fn run() -> Result<(), crossref_client::Error> {
567    /// let client = Crossref::builder().build()?;
568    ///
569    /// let query = WorksQuery::new("Machine Learning")
570    ///     .filter(WorksFilter::HasOrcid)
571    ///     .order(crossref_client::Order::Asc)
572    ///     .field_query(FieldQuery::author("Some Author"))
573    ///     .sort(crossref_client::Sort::Score);
574    ///
575    /// let works = client.works(query).await?;
576    ///
577    /// # Ok(())
578    /// # }
579    /// ```
580    ///
581    /// # Errors
582    ///
583    /// This method fails if the `works` element expands to a bad route `ResourceNotFound`
584    /// Fails if the response body doesn't have `message` field `MissingMessage`.
585    /// Fails if anything else than a `WorkList` is returned as message `UnexpectedItem`
586    pub async fn works<T: Into<WorkListQuery>>(&self, query: T) -> Result<WorkList> {
587        let resp = self.get_response(&query.into()).await?;
588
589        get_item!(WorkList, resp)
590    }
591
592    /// Return the `Work` that is identified by  the `doi`.
593    ///
594    /// # Errors
595    /// This method fails if the doi could not identified `ResourceNotFound`
596    ///
597    pub async fn work(&self, doi: &str) -> Result<Work> {
598        let resp = self
599            .get_response(&Works::Identifier(doi.to_string()))
600            .await?;
601        get_item!(Work, resp).map(|x| *x)
602    }
603
604    /// [Deep paging results](https://github.com/CrossRef/rest-api-doc#deep-paging-with-cursors)
605    /// Deep paging is supported for all queries, that return a list of `Work`, `WorkList`.
606    /// This function returns a new iterator over pages of `Work`, which is returned as bulk of items as a `WorkList` by crossref.
607    /// Usually a single page `WorkList` contains 20 items.
608    ///
609    /// # Example
610    ///
611    /// Iterate over all `Works` linked to search term `Machine Learning`
612    ///
613    /// ```no_run
614    /// use crossref_client::{AsyncIterator, Crossref, WorksQuery, Work};
615    /// # async fn run() -> Result<(), crossref_client::Error> {
616    /// let client = Crossref::builder().build()?;
617    ///
618    /// let mut pages = client.deep_page(WorksQuery::new("Machine Learning"));
619    /// let mut all_works: Vec<Work> = Vec::new();
620    /// while let Some(page) = pages.next().await {
621    ///     let page = page?;
622    ///     all_works.extend(page.items);
623    /// }
624    ///
625    /// # Ok(())
626    /// # }
627    /// ```
628    ///
629    /// # Example
630    ///
631    /// Iterate over all the pages (`WorkList`) of the funder with id `funder id` by using a combined query.
632    /// A single `WorkList` usually holds 20 `Work` items.
633    ///
634    /// ```no_run
635    /// use crossref_client::{AsyncIterator, Crossref, Funders, WorksQuery, Work, WorkList};
636    /// # async fn run() -> Result<(), crossref_client::Error> {
637    /// let client = Crossref::builder().build()?;
638    ///
639    /// let mut pages = client.deep_page(WorksQuery::default().into_combined_query::<Funders>("funder id"));
640    /// let mut all_funder_work_list: Vec<WorkList> = Vec::new();
641    /// while let Some(page) = pages.next().await {
642    ///     let page = page?;
643    ///     all_funder_work_list.push(page);
644    /// }
645    ///
646    /// # Ok(())
647    /// # }
648    /// ```
649    /// # Example
650    ///
651    /// Iterate over all `Work` items of a specfic funder directly.
652    ///
653    /// ```no_run
654    /// use crossref_client::{AsyncIterator, Crossref, Funders, WorksQuery, Work, WorkList};
655    /// # async fn run() -> Result<(), crossref_client::Error> {
656    /// let client = Crossref::builder().build()?;
657    ///
658    /// let mut works = client.deep_page(WorksQuery::default()
659    ///         .into_combined_query::<Funders>("funder id"))
660    ///         .into_work_iter();
661    /// let mut all_works: Vec<Work> = Vec::new();
662    /// while let Some(work) = works.next().await {
663    ///     let work = work?;
664    ///     all_works.push(work);
665    /// }
666    ///
667    /// # Ok(())
668    /// # }
669    /// ```
670    ///
671    /// # Example
672    ///
673    /// Alternatively deep page without an iterator by handling the cursor directly
674    ///
675    /// ```no_run
676    /// use crossref_client::{Crossref, WorksQuery, WorksFilter};
677    /// # async fn run() -> Result<(), crossref_client::Error> {
678    /// let client = Crossref::builder().build()?;
679    ///
680    /// // request a next-cursor first
681    /// let query = WorksQuery::new("Machine Learning")
682    ///     .new_cursor();
683    ///
684    /// let works = client.works(query.clone()).await?;
685    ///
686    /// // this continues from where this first response stopped
687    /// // if no more work items are available then a empty list will be returned
688    /// let deep_works = client.works(
689    ///     query.next_cursor(&works.next_cursor.unwrap())
690    /// ).await?;
691    /// # Ok(())
692    /// # }
693    /// ```
694    ///
695    pub fn deep_page<T: Into<WorkListQuery>>(&self, query: T) -> WorkListIterator<'_> {
696        WorkListIterator::new(query.into(), self)
697    }
698
699    /// Re-serialize the work identified by `doi` into another format.
700    ///
701    /// Crossref renders the registered metadata itself, so this never goes
702    /// through [`Work`] and the body is returned verbatim -- BibTeX, RIS, RDF
703    /// or a citation formatted in a [CSL style](Crossref::styles).
704    ///
705    /// # Example
706    ///
707    /// ```no_run
708    /// use crossref_client::{CnFormat, Crossref};
709    /// # async fn run() -> Result<(), crossref_client::Error> {
710    /// # let client = Crossref::builder().build()?;
711    /// let bibtex = client
712    ///     .transform("10.1037/0003-066X.59.1.29", &CnFormat::BibTex)
713    ///     .await?;
714    ///
715    /// let citation = client
716    ///     .transform("10.1037/0003-066X.59.1.29", &CnFormat::bibliography("apa"))
717    ///     .await?;
718    /// # Ok(())
719    /// # }
720    /// ```
721    ///
722    /// # Errors
723    ///
724    /// Fails with [`Error::ValidationFailure`] if crossref cannot serve the
725    /// format for this DOI -- an unknown CSL style is the usual cause.
726    pub async fn transform(&self, doi: &str, format: &CnFormat) -> Result<String> {
727        let url = format!("{}/works/{}/transform", self.base_url, doi);
728        let response = self
729            .send_with(&url, |request| {
730                request.header(reqwest::header::ACCEPT, format.accept().as_ref())
731            })
732            .await?;
733
734        Ok(Self::into_success(response).await?.text().await?)
735    }
736
737    /// Return the [CSL styles](https://citationstyles.org) crossref can render
738    /// a citation in, for [`CnFormat::Bibliography`].
739    ///
740    /// Roughly 2 900 of them, in one response.
741    pub async fn styles(&self) -> Result<StyleList> {
742        let response = self.send(&format!("{}/styles", self.base_url)).await?;
743        let body = Self::into_success(response).await?.bytes().await?;
744        let response: Response =
745            serde_json::from_slice(&body).map_err(|error| Error::Serde { error })?;
746
747        get_item!(StyleList, response)
748    }
749
750    /// Return the `Agency` that registers the `Work` identified by  the `doi`.
751    ///
752    /// # Errors
753    /// This method fails if the doi could not identified `ResourceNotFound`
754    ///
755    pub async fn work_agency(&self, doi: &str) -> Result<WorkAgency> {
756        let resp = self.get_response(&Works::Agency(doi.to_string())).await?;
757        get_item!(WorkAgency, resp)
758    }
759
760    /// Return the matching `Funders` items.
761    pub async fn funders(&self, funders: FundersQuery) -> Result<FunderList> {
762        let resp = self.get_response(&Funders::Query(funders)).await?;
763        get_item!(FunderList, resp)
764    }
765
766    /// Return the `Funder` for the `id`
767    pub async fn funder(&self, id: &str) -> Result<Funder> {
768        let resp = self
769            .get_response(&Funders::Identifier(id.to_string()))
770            .await?;
771        get_item!(Funder, resp).map(|x| *x)
772    }
773
774    /// Return the matching `Members` items.
775    pub async fn members(&self, members: MembersQuery) -> Result<MemberList> {
776        let resp = self.get_response(&Members::Query(members)).await?;
777        get_item!(MemberList, resp)
778    }
779
780    /// Return the `Member` for the `id`
781    pub async fn member(&self, member_id: &str) -> Result<Member> {
782        let resp = self
783            .get_response(&Members::Identifier(member_id.to_string()))
784            .await?;
785        get_item!(Member, resp).map(|x| *x)
786    }
787
788    /// Return the `Prefix` for the `id`
789    pub async fn prefix(&self, id: &str) -> Result<Prefix> {
790        let resp = self
791            .get_response(&Prefixes::Identifier(id.to_string()))
792            .await?;
793        get_item!(Prefix, resp)
794    }
795    /// Return a specific `Journal`
796    pub async fn journal(&self, id: &str) -> Result<Journal> {
797        let resp = self
798            .get_response(&Journals::Identifier(id.to_string()))
799            .await?;
800
801        get_item!(Journal, resp).map(|x| *x)
802    }
803
804    /// Return the matching `Journal` items.
805    ///
806    /// # Example
807    ///
808    /// ```no_run
809    /// use crossref_client::{Crossref, JournalsQuery, ResultControl};
810    /// # async fn run() -> Result<(), crossref_client::Error> {
811    /// # let client = Crossref::builder().build()?;
812    /// let journals = client
813    ///     .journals(JournalsQuery::new("Economic Geography").result_control(ResultControl::Rows(10)))
814    ///     .await?;
815    /// # Ok(())
816    /// # }
817    /// ```
818    pub async fn journals(&self, journals: JournalsQuery) -> Result<JournalList> {
819        let resp = self.get_response(&Journals::Query(journals)).await?;
820        get_item!(JournalList, resp)
821    }
822
823    /// Return the licenses works in the crossref metadata are published under,
824    /// each with the number of works that carry it.
825    ///
826    /// # Example
827    ///
828    /// ```no_run
829    /// use crossref_client::{Crossref, LicensesQuery, ResultControl};
830    /// # async fn run() -> Result<(), crossref_client::Error> {
831    /// # let client = Crossref::builder().build()?;
832    /// let licenses = client
833    ///     .licenses(LicensesQuery::new("creative commons").result_control(ResultControl::Rows(10)))
834    ///     .await?;
835    ///
836    /// for license in &licenses.items {
837    ///     println!("{:>8} {}", license.work_count, license.url);
838    /// }
839    /// # Ok(())
840    /// # }
841    /// ```
842    pub async fn licenses(&self, licenses: LicensesQuery) -> Result<LicenseList> {
843        let resp = self.get_response(&Licenses::Query(licenses)).await?;
844        get_item!(LicenseList, resp)
845    }
846
847    /// Return all available `Type`
848    pub async fn types(&self) -> Result<TypeList> {
849        let resp = self.get_response(&Types::All).await?;
850        get_item!(TypeList, resp)
851    }
852
853    /// Return the `Type` for the `id`
854    pub async fn type_(&self, id: &Type) -> Result<CrossrefType> {
855        let resp = self
856            .get_response(&Types::Identifier(id.id().to_string()))
857            .await?;
858        get_item!(Type, resp)
859    }
860
861    /// Get a random set of DOIs
862    ///
863    /// # Example
864    ///
865    /// ```no_run
866    /// use crossref_client::Crossref;
867    /// # async fn run() -> Result<(), crossref_client::Error> {
868    /// # let client = Crossref::builder().build()?;
869    /// // this will return 10 random dois from the crossref api
870    /// let random_dois = client.random_dois(10).await?;
871    /// # Ok(())
872    /// # }
873    /// ```
874    pub async fn random_dois(&self, len: usize) -> Result<Vec<String>> {
875        self.works(WorksQuery::random(len))
876            .await
877            .map(|x| x.items.into_iter().map(|x| x.doi).collect())
878    }
879}
880
881/// A `CrossrefBuilder` can be used to create `Crossref` with additional config.
882///
883/// # Example
884///
885/// ```no_run
886/// use crossref_client::Crossref;
887/// # async fn run() -> Result<(), crossref_client::Error> {
888///
889/// let client = Crossref::builder()
890///     .polite("polite@example.com")
891///     .token("your token")
892///     .build()?;
893/// # Ok(())
894/// # }
895/// ```
896/// Every setter accepts `Option`, so options that are themselves optional --
897/// a CLI flag, a config field -- can be passed straight through:
898///
899/// ```no_run
900/// # use crossref_client::Crossref;
901/// # fn run(email: Option<String>) -> Result<(), crossref_client::Error> {
902/// let client = Crossref::builder().polite(email.as_deref()).build()?;
903/// # Ok(())
904/// # }
905/// ```
906#[derive(Debug, Default)]
907pub struct CrossrefBuilder {
908    /// [Good manners = more reliable service.](https://github.com/CrossRef/rest-api-doc#good-manners--more-reliable-service)
909    ///
910    /// will add a `User-Agent` header by default with with the `email` email.
911    /// crossref can contact you if your script misbehaves
912    /// this will get you directed to the "polite pool"
913    user_agent: Option<String>,
914    /// the token for the Crossref Plus service will be included as `Authorization` header
915    /// This token will ensure that said requests get directed to a pool of machines that are reserved for "Plus" SLA users.
916    plus_token: Option<String>,
917    /// use a different base url than `Crossref::BASE_URL` <https://api.crossref.org>
918    base_url: Option<String>,
919    /// the budget to assume until crossref reports one
920    rate_limit: Option<RateLimit>,
921    /// how many times a `429` is retried
922    max_retries: Option<u32>,
923}
924
925impl CrossrefBuilder {
926    /// How many times a `429` is retried before [`Error::RateLimited`] is
927    /// returned, when the builder was not told otherwise.
928    const DEFAULT_MAX_RETRIES: u32 = 3;
929
930    /// Constructs a new `CrossrefBuilder`.
931    ///
932    /// This is the same as `Crossref::builder()`.
933    pub fn new() -> CrossrefBuilder {
934        CrossrefBuilder::default()
935    }
936
937    /// Be polite: identify yourself by email and get routed to crossref's
938    /// [polite pool](https://api.crossref.org/swagger-ui/index.html#/Etiquette).
939    ///
940    /// Sends a `User-Agent` in the shape crossref asks for, e.g.
941    /// `crossref-client/0.2.0 (https://github.com/…; mailto:you@example.com)`.
942    /// Anonymous requests share a rate-limited pool and are the usual cause of
943    /// `429` responses; check where you landed with
944    /// [`Crossref::api_pool`].
945    ///
946    /// Use [`CrossrefBuilder::user_agent`] instead if you want to send your own
947    /// application's name; include `mailto:<email>` in it to stay in the pool.
948    pub fn polite<'a>(mut self, email: impl Into<Option<&'a str>>) -> Self {
949        if let Some(email) = email.into() {
950            self.user_agent = Some(format!(
951                "{}/{} ({}; mailto:{})",
952                env!("CARGO_PKG_NAME"),
953                env!("CARGO_PKG_VERSION"),
954                env!("CARGO_PKG_REPOSITORY"),
955                email
956            ));
957        }
958        self
959    }
960
961    /// set the user agent directly
962    pub fn user_agent<'a>(mut self, user_agent: impl Into<Option<&'a str>>) -> Self {
963        self.user_agent = user_agent.into().map(str::to_owned);
964        self
965    }
966
967    /// set a crossref plus service  API token
968    pub fn token<'a>(mut self, token: impl Into<Option<&'a str>>) -> Self {
969        self.plus_token = token.into().map(str::to_owned);
970        self
971    }
972
973    /// Send requests somewhere other than `https://api.crossref.org`.
974    ///
975    /// Routes are appended verbatim, so the url must not end in a `/`. Mainly
976    /// useful for pointing the client at a mock or a proxy in tests.
977    pub fn base_url<'a>(mut self, base_url: impl Into<Option<&'a str>>) -> Self {
978        self.base_url = base_url.into().map(str::to_owned);
979        self
980    }
981
982    /// The request budget to assume until crossref reports its own.
983    ///
984    /// Defaults to [`RateLimit::CONSERVATIVE`]. Crossref sends the real budget
985    /// on every response and the client follows it from then on, so this only
986    /// paces the first few requests.
987    pub fn rate_limit(mut self, rate_limit: impl Into<Option<RateLimit>>) -> Self {
988        self.rate_limit = rate_limit.into();
989        self
990    }
991
992    /// How many times a `429` is retried before giving up with
993    /// [`Error::RateLimited`]. Defaults to 3; `0` disables retrying.
994    pub fn max_retries(mut self, max_retries: impl Into<Option<u32>>) -> Self {
995        self.max_retries = max_retries.into();
996        self
997    }
998
999    /// Returns a `Crossref` that uses this `CrossrefBuilder` configuration.
1000    /// # Errors
1001    ///
1002    /// This will fail if TLS backend cannot be initialized see [reqwest::ClientBuilder::build]
1003    pub fn build(self) -> Result<Crossref> {
1004        use reqwest::header;
1005        let mut headers = header::HeaderMap::new();
1006        if let Some(agent) = &self.user_agent {
1007            headers.insert(
1008                header::USER_AGENT,
1009                header::HeaderValue::from_str(agent).map_err(|_| Error::Config {
1010                    msg: format!("failed to create User Agent header for `{}`", agent),
1011                })?,
1012            );
1013        }
1014        if let Some(token) = &self.plus_token {
1015            headers.insert(
1016                header::AUTHORIZATION,
1017                header::HeaderValue::from_str(token).map_err(|_| Error::Config {
1018                    msg: format!("failed to create AUTHORIZATION header for `{}`", token),
1019                })?,
1020            );
1021        }
1022        let client = reqwest::Client::builder()
1023            .default_headers(headers)
1024            .build()
1025            .map_err(|_| Error::Config {
1026                msg: "failed to initialize TLS backend".to_string(),
1027            })?;
1028
1029        Ok(Crossref {
1030            base_url: self
1031                .base_url
1032                .unwrap_or_else(|| Crossref::BASE_URL.to_string()),
1033            client,
1034            limiter: Arc::new(Limiter::new(self.rate_limit.unwrap_or_default())),
1035            max_retries: self.max_retries.unwrap_or(Self::DEFAULT_MAX_RETRIES),
1036        })
1037    }
1038}
1039
1040/// Allows iterating of deep page work request
1041pub struct WorkListIterator<'a> {
1042    /// the query
1043    query: WorkListQuery,
1044    /// performs each request
1045    client: &'a Crossref,
1046    /// whether the iterator should finish next iteration
1047    finish_next_iteration: bool,
1048}
1049
1050impl<'a> WorkListIterator<'a> {
1051    /// Create an iterator that deep pages `query` through `client`.
1052    pub fn new(query: WorkListQuery, client: &'a Crossref) -> Self {
1053        Self {
1054            query,
1055            client,
1056            finish_next_iteration: false,
1057        }
1058    }
1059
1060    /// Flatten the paged results into an iterator over individual [`Work`] items.
1061    ///
1062    /// Pages are fetched lazily, one request at a time, as the buffer drains.
1063    pub fn into_work_iter(self) -> WorkIterator<'a> {
1064        WorkIterator {
1065            pages: self,
1066            buffer: Vec::new().into_iter(),
1067        }
1068    }
1069}
1070
1071/// Yields individual [`Work`] items across the deep paged [`WorkList`] pages.
1072///
1073/// Created by [`WorkListIterator::into_work_iter`].
1074pub struct WorkIterator<'a> {
1075    pages: WorkListIterator<'a>,
1076    buffer: std::vec::IntoIter<Work>,
1077}
1078
1079impl async_iterator::Iterator for WorkIterator<'_> {
1080    type Item = Result<Work>;
1081
1082    async fn next(&mut self) -> Option<Self::Item> {
1083        loop {
1084            if let Some(work) = self.buffer.next() {
1085                return Some(Ok(work));
1086            }
1087            // `WorkListIterator` stops on the first empty page and after an
1088            // error, so this terminates
1089            match self.pages.next().await? {
1090                Ok(page) => self.buffer = page.items.into_iter(),
1091                Err(err) => return Some(Err(err)),
1092            }
1093        }
1094    }
1095}
1096
1097impl async_iterator::Iterator for WorkListIterator<'_> {
1098    type Item = Result<WorkList>;
1099
1100    async fn next(&mut self) -> Option<Self::Item> {
1101        if self.finish_next_iteration {
1102            return None;
1103        }
1104
1105        {
1106            let control = &mut self.query.query_mut().result_control;
1107
1108            // if no result control is set, set a new cursor
1109            if control.is_none() {
1110                *control = Some(WorkResultControl::new_cursor());
1111            }
1112        }
1113
1114        let page = match self.client.get_response(&self.query).await {
1115            Ok(resp) => get_item!(WorkList, resp),
1116            Err(err) => Err(err),
1117        };
1118
1119        let worklist = match page {
1120            Ok(worklist) => worklist,
1121            Err(err) => {
1122                // a transient `429` or an unparsable page used to end the
1123                // iteration silently, which a caller cannot tell apart from
1124                // having crawled everything -- surface it and stop
1125                self.finish_next_iteration = true;
1126                return Some(Err(err));
1127            }
1128        };
1129
1130        if let Some(cursor) = &worklist.next_cursor {
1131            match &mut self.query.query_mut().result_control {
1132                Some(WorkResultControl::Cursor { token, .. }) => {
1133                    // use the received cursor token in next iteration
1134                    *token = Some(cursor.clone())
1135                }
1136                Some(WorkResultControl::Standard(_)) => {
1137                    // standard result control was set, don't deep page and return next iteration
1138                    self.finish_next_iteration = true;
1139                }
1140                _ => (),
1141            }
1142        } else {
1143            // no cursor received, end next iteration
1144            self.finish_next_iteration = true;
1145        }
1146
1147        if worklist.items.is_empty() {
1148            None
1149        } else {
1150            Some(Ok(worklist))
1151        }
1152    }
1153}