opencitations-client 0.1.0

An async Rust client for the OpenCitations Index and Meta REST APIs
Documentation
use std::result;
use thiserror::Error as ThisError;

/// A type alias for handling errors throughout this crate.
pub type Result<T> = result::Result<T, Error>;

/// Everything that can go wrong talking to OpenCitations.
///
/// Note what is *not* here: an identifier OpenCitations holds nothing about is
/// not an error. Both apis answer such a request with `200` and an empty list,
/// so a lookup that found nothing comes back as an empty [`Vec`] and a count of
/// zero. See [`Error::NoSuchOperation`] for the case that does fail.
#[derive(Debug, ThisError)]
#[non_exhaustive]
pub enum Error {
    /// an identifier that is not `scheme:value`
    ///
    /// OpenCitations addresses everything by a prefixed identifier -- a bare
    /// `10.1016/j.marpol.2021.104855` means nothing to it, `doi:` in front of
    /// it does. The prefix is required here rather than guessed at, because a
    /// guess that picks the wrong scheme is answered with an empty list and
    /// reads exactly like a work nobody has cited.
    #[error(
        "`{given}` is not a `scheme:value` identifier; write it as `doi:{given}` or `pmid:{given}`"
    )]
    UnprefixedIdentifier {
        /// the identifier as it was written
        given: String,
    },

    /// an identifier whose scheme or value is empty, e.g. `doi:` or `:10.1016`
    #[error("`{given}` is not an identifier: {why}")]
    InvalidIdentifier {
        /// the identifier as it was written
        given: String,
        /// what is wrong with it
        why: &'static str,
    },

    /// a string that is not an Open Citation Identifier
    ///
    /// An OCI is the two OMIDs of the citing and cited work joined by a `-`,
    /// e.g. `06024047477-06220256775`.
    #[error("`{given}` is not an open citation identifier: {why}")]
    InvalidOci {
        /// the identifier as it was written
        given: String,
        /// what is wrong with it
        why: &'static str,
    },

    /// OpenCitations answered a route it does not serve
    ///
    /// Answered with a `404` and a plain-text body rather than json, which is
    /// what an identifier it could not even parse produces -- `citations/foo`
    /// rather than `citations/doi:foo`.
    #[error("opencitations serves no such operation: {message}")]
    NoSuchOperation {
        /// the body it answered with, trimmed
        message: String,
    },

    /// OpenCitations refused the request
    ///
    /// The body is passed through as it arrived, because it is sometimes json
    /// and sometimes plain text and neither shape is documented.
    #[error("opencitations answered {status}: {body}")]
    Api {
        /// the status it answered with
        status: u16,
        /// the body it answered with, trimmed
        body: String,
    },

    /// OpenCitations kept answering `429` until the retry budget ran out
    ///
    /// The client paces itself well inside the documented 180 requests a
    /// minute, so this normally means requests are also being made from
    /// somewhere else on the same address -- another process, or another
    /// [`OpenCitations`](crate::OpenCitations) built separately rather than
    /// cloned.
    #[error("opencitations rate limited the request; gave up after {attempts} attempts")]
    RateLimited {
        /// how many times the request was sent
        attempts: u32,
    },

    /// a response this crate could not read
    ///
    /// Every field of both apis arrives as a string, including the ones that
    /// are plainly numbers and dates, so this is where an unannounced change of
    /// shape surfaces.
    #[error("could not read the {what} in opencitations' answer: {source}")]
    Malformed {
        /// which part of the response was unreadable
        what: &'static str,
        /// the underlying deserialization error
        source: serde_json::Error,
    },

    /// an error that occurred while operating with [reqwest]
    #[error(transparent)]
    ReqWest {
        /// the underlying transport error
        #[from]
        reqwest: reqwest::Error,
    },

    /// the client could not be built
    #[error("{msg}")]
    Config {
        /// what could not be configured
        msg: String,
    },
}