monovm-whois-rust 1.0.0

//! Talking to servers: the only part of the crate that performs I/O.
//!
//! A [`Transport`] turns a [`Query`] into a [`RawResponse`] and does nothing
//! else. It does not decide whether a domain is available, does not parse the
//! record, and does not choose which endpoint to ask — those live in
//! [`detect`](crate::detect), [`parser`](crate::parser) and
//! [`client`](crate::client) respectively.
//!
//! # Composing behaviour
//!
//! Retries, rate limiting and caching are each a transport that wraps another
//! transport, so a caller assembles the policy they want instead of configuring
//! flags on one large object:
//!
//! ```
//! # #[cfg(feature = "blocking")] {
//! use std::time::Duration;
//! use monovm_whois::cache::MemoryCache;
//! use monovm_whois::transport::{
//!     CachingTransport, RetryPolicy, RetryTransport, ThrottlePolicy, ThrottleTransport,
//!     Whois43Transport,
//! };
//!
//! let transport = Whois43Transport::default();
//! let transport = RetryTransport::new(transport, RetryPolicy::default());
//! let transport = ThrottleTransport::new(transport, ThrottlePolicy::per_host(Duration::from_secs(1)));
//! let transport = CachingTransport::new(transport, MemoryCache::with_ttl(Duration::from_secs(300)));
//! # }
//! ```
//!
//! Each layer only knows about the one below it, so the order is the caller's
//! choice and means something: caching outside throttling serves repeats without
//! waiting, caching inside it would wait first.

use std::fmt;
use std::future::Future;
use std::pin::Pin;
use std::sync::Arc;
use std::time::Duration;

use crate::domain::Tld;
use crate::error::{Error, Result};
use crate::registry::Endpoint;

mod caching;
mod retry;
mod throttle;

#[cfg(any(test, feature = "mock"))]
mod mock;
// RDAP needs a runtime to be reachable from; without one there is nothing to compile
// it for.
#[cfg(all(feature = "rdap", any(feature = "blocking", feature = "async")))]
mod rdap;
mod whois43;

pub use caching::CachingTransport;
pub use retry::{RetryPolicy, RetryTransport};
pub use throttle::{ThrottlePolicy, ThrottleTransport};
pub use whois43::referral_host;

#[cfg(any(test, feature = "mock"))]
pub use mock::{MockTransport, Scripted};
#[cfg(all(feature = "rdap", feature = "blocking"))]
pub use rdap::RdapTransport;
#[cfg(feature = "blocking")]
pub use whois43::Whois43Transport;

#[cfg(feature = "async")]
pub use caching::AsyncCachingTransport;
#[cfg(all(feature = "async", feature = "rdap"))]
pub use rdap::AsyncRdapTransport;
#[cfg(feature = "async")]
pub use retry::AsyncRetryTransport;
#[cfg(feature = "async")]
pub use throttle::AsyncThrottleTransport;
#[cfg(feature = "async")]
pub use whois43::AsyncWhois43Transport;

/// A boxed future, as returned by [`AsyncTransport::fetch`].
///
/// Spelled out rather than pulled in from `async-trait` so that the trait stays
/// object-safe without adding a proc-macro dependency.
pub type BoxFuture<'a, T> = Pin<Box<dyn Future<Output = T> + Send + 'a>>;

/// One question, addressed to one endpoint.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Query {
    /// Where to send it.
    pub endpoint: Endpoint,
    /// Exactly what to put on the wire, or into the URL path.
    ///
    /// Already in the form the registry wants — punycode or Unicode, and with
    /// any registry-specific query flags applied. A transport sends this
    /// verbatim; deciding what it should be is the client's job.
    pub wire_name: String,
    /// The suffix being asked about, carried for diagnostics and cache keys.
    pub tld: Tld,
}

impl Query {
    /// Build a query.
    pub fn new(endpoint: Endpoint, wire_name: impl Into<String>, tld: Tld) -> Self {
        Query {
            endpoint,
            wire_name: wire_name.into(),
            tld,
        }
    }

    /// A stable key identifying this exact question.
    pub fn cache_key(&self) -> String {
        format!("{}|{}", self.endpoint.address(), self.wire_name)
    }
}

/// Which protocol produced a response, and therefore how to read it.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum ResponseKind {
    /// Line-oriented text from a port 43 server.
    WhoisText,
    /// A JSON document from an RDAP server.
    RdapJson,
}

/// What a server said, before any interpretation.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RawResponse {
    endpoint: Endpoint,
    kind: ResponseKind,
    text: String,
    elapsed: Duration,
    from_cache: bool,
}

impl RawResponse {
    /// Build a response.
    pub fn new(
        endpoint: Endpoint,
        kind: ResponseKind,
        text: impl Into<String>,
        elapsed: Duration,
    ) -> Self {
        RawResponse {
            endpoint,
            kind,
            text: text.into(),
            elapsed,
            from_cache: false,
        }
    }

    /// The endpoint that answered.
    pub fn endpoint(&self) -> &Endpoint {
        &self.endpoint
    }

    /// Which protocol produced this.
    pub fn kind(&self) -> ResponseKind {
        self.kind
    }

    /// The body, exactly as received.
    pub fn text(&self) -> &str {
        &self.text
    }

    /// How long the round trip took.
    pub fn elapsed(&self) -> Duration {
        self.elapsed
    }

    /// Whether this came from a cache rather than the network.
    pub fn is_cached(&self) -> bool {
        self.from_cache
    }

    /// Mark as served from a cache. Used by [`CachingTransport`].
    pub(crate) fn mark_cached(mut self) -> Self {
        self.from_cache = true;
        self
    }

    /// Whether the body has any non-whitespace content.
    pub fn is_blank(&self) -> bool {
        self.text.trim().is_empty()
    }
}

/// A synchronous conversation with a server.
///
/// The trait itself is always available, so a caller can implement it against a
/// private protocol even in a build with no bundled transports compiled in.
pub trait Transport: fmt::Debug + Send + Sync {
    /// Whether this transport can talk to that endpoint.
    ///
    /// Checked before [`fetch`](Transport::fetch) so a router can dispatch, and
    /// so a caller gets [`Error::NoEndpoint`] rather than a protocol error when
    /// nothing can serve a registry.
    fn supports(&self, endpoint: &Endpoint) -> bool;

    /// Ask the question and return the answer verbatim.
    ///
    /// # Errors
    ///
    /// Network faults as [`Error::Connect`], [`Error::Io`] or [`Error::Timeout`];
    /// an empty body as [`Error::EmptyResponse`]. Note that an HTTP 404 from RDAP
    /// is *not* an error: it is how RDAP says a domain does not exist, and the
    /// body is returned so the detector can read it.
    fn fetch(&self, query: &Query) -> Result<RawResponse>;

    /// A short name for diagnostics, e.g. `whois43` or `retry(whois43)`.
    fn name(&self) -> String;
}

/// An asynchronous conversation with a server.
///
/// Mirrors [`Transport`] exactly; the two are separate traits rather than one
/// generic trait because the sync and async paths have genuinely different
/// signatures, and unifying them would put a runtime dependency in the blocking
/// build.
pub trait AsyncTransport: fmt::Debug + Send + Sync {
    /// Whether this transport can talk to that endpoint.
    fn supports(&self, endpoint: &Endpoint) -> bool;

    /// Ask the question and return the answer verbatim.
    fn fetch<'a>(&'a self, query: &'a Query) -> BoxFuture<'a, Result<RawResponse>>;

    /// A short name for diagnostics.
    fn name(&self) -> String;
}

impl<T: Transport + ?Sized> Transport for Arc<T> {
    fn supports(&self, endpoint: &Endpoint) -> bool {
        (**self).supports(endpoint)
    }

    fn fetch(&self, query: &Query) -> Result<RawResponse> {
        (**self).fetch(query)
    }

    fn name(&self) -> String {
        (**self).name()
    }
}

impl<T: AsyncTransport + ?Sized> AsyncTransport for Arc<T> {
    fn supports(&self, endpoint: &Endpoint) -> bool {
        (**self).supports(endpoint)
    }

    fn fetch<'a>(&'a self, query: &'a Query) -> BoxFuture<'a, Result<RawResponse>> {
        (**self).fetch(query)
    }

    fn name(&self) -> String {
        (**self).name()
    }
}

/// Timeouts shared by every transport.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct TransportConfig {
    /// How long to wait for the connection to be established.
    pub connect_timeout: Duration,
    /// How long to wait for data once connected.
    pub read_timeout: Duration,
    /// Cap on how many bytes to read from one response.
    ///
    /// A WHOIS record is a few kilobytes; a server that streams megabytes is
    /// either broken or hostile, and neither is worth buffering.
    pub max_response_bytes: usize,
}

impl TransportConfig {
    /// 5 s to connect, 10 s to read, 1 MiB cap.
    pub const DEFAULT: TransportConfig = TransportConfig {
        connect_timeout: Duration::from_secs(5),
        read_timeout: Duration::from_secs(10),
        max_response_bytes: 1024 * 1024,
    };

    /// Set the connect timeout.
    pub fn connect_timeout(mut self, timeout: Duration) -> Self {
        self.connect_timeout = timeout;
        self
    }

    /// Set the read timeout.
    pub fn read_timeout(mut self, timeout: Duration) -> Self {
        self.read_timeout = timeout;
        self
    }

    /// Set the response size cap.
    pub fn max_response_bytes(mut self, bytes: usize) -> Self {
        self.max_response_bytes = bytes;
        self
    }
}

impl Default for TransportConfig {
    fn default() -> Self {
        TransportConfig::DEFAULT
    }
}

/// Dispatches to whichever transport can serve an endpoint.
///
/// A registry may publish a port 43 host and an RDAP URL; the client hands both
/// to one router rather than working out which object to call.
///
/// ```
/// # #[cfg(all(feature = "blocking", feature = "rdap"))] {
/// use monovm_whois::registry::Endpoint;
/// use monovm_whois::transport::{RdapTransport, Router, Whois43Transport};
///
/// let router = Router::new()
///     .with(Whois43Transport::default())
///     .with(RdapTransport::new().unwrap());
///
/// assert!(router.handles(&Endpoint::whois("whois.nic.uk")));
/// assert!(router.handles(&Endpoint::rdap("https://rdap.example/")));
/// # }
/// ```
#[derive(Debug, Default, Clone)]
pub struct Router {
    transports: Vec<Arc<dyn Transport>>,
}

impl Router {
    /// An empty router, which supports nothing.
    pub fn new() -> Self {
        Router {
            transports: Vec::new(),
        }
    }

    /// Add a transport. Earlier ones are preferred where both could serve.
    pub fn with(mut self, transport: impl Transport + 'static) -> Self {
        self.transports.push(Arc::new(transport));
        self
    }

    /// Add an already-shared transport.
    pub fn with_shared(mut self, transport: Arc<dyn Transport>) -> Self {
        self.transports.push(transport);
        self
    }

    /// Whether any registered transport can serve this endpoint.
    pub fn handles(&self, endpoint: &Endpoint) -> bool {
        self.transports
            .iter()
            .any(|transport| transport.supports(endpoint))
    }

    /// How many transports are registered.
    pub fn len(&self) -> usize {
        self.transports.len()
    }

    /// Whether no transport is registered.
    pub fn is_empty(&self) -> bool {
        self.transports.is_empty()
    }
}

impl Transport for Router {
    fn supports(&self, endpoint: &Endpoint) -> bool {
        self.handles(endpoint)
    }

    fn fetch(&self, query: &Query) -> Result<RawResponse> {
        for transport in &self.transports {
            if transport.supports(&query.endpoint) {
                return transport.fetch(query);
            }
        }

        Err(Error::NoEndpoint {
            tld: query.tld.clone(),
            detail: format!(
                "no transport handles {}; router has [{}]",
                query.endpoint,
                self.transports
                    .iter()
                    .map(|t| t.name())
                    .collect::<Vec<_>>()
                    .join(", ")
            ),
        })
    }

    fn name(&self) -> String {
        format!(
            "router({})",
            self.transports
                .iter()
                .map(|t| t.name())
                .collect::<Vec<_>>()
                .join("+")
        )
    }
}

/// The asynchronous counterpart of [`Router`].
#[derive(Debug, Default, Clone)]
pub struct AsyncRouter {
    transports: Vec<Arc<dyn AsyncTransport>>,
}

impl AsyncRouter {
    /// An empty router, which supports nothing.
    pub fn new() -> Self {
        AsyncRouter {
            transports: Vec::new(),
        }
    }

    /// Add a transport. Earlier ones are preferred where both could serve.
    pub fn with(mut self, transport: impl AsyncTransport + 'static) -> Self {
        self.transports.push(Arc::new(transport));
        self
    }

    /// Add an already-shared transport.
    pub fn with_shared(mut self, transport: Arc<dyn AsyncTransport>) -> Self {
        self.transports.push(transport);
        self
    }

    /// Whether any registered transport can serve this endpoint.
    pub fn handles(&self, endpoint: &Endpoint) -> bool {
        self.transports
            .iter()
            .any(|transport| transport.supports(endpoint))
    }

    /// How many transports are registered.
    pub fn len(&self) -> usize {
        self.transports.len()
    }

    /// Whether no transport is registered.
    pub fn is_empty(&self) -> bool {
        self.transports.is_empty()
    }
}

impl AsyncTransport for AsyncRouter {
    fn supports(&self, endpoint: &Endpoint) -> bool {
        self.handles(endpoint)
    }

    fn fetch<'a>(&'a self, query: &'a Query) -> BoxFuture<'a, Result<RawResponse>> {
        Box::pin(async move {
            for transport in &self.transports {
                if transport.supports(&query.endpoint) {
                    return transport.fetch(query).await;
                }
            }

            Err(Error::NoEndpoint {
                tld: query.tld.clone(),
                detail: format!("no async transport handles {}", query.endpoint),
            })
        })
    }

    fn name(&self) -> String {
        format!(
            "async-router({})",
            self.transports
                .iter()
                .map(|t| t.name())
                .collect::<Vec<_>>()
                .join("+")
        )
    }
}

/// Decode a server response into text.
///
/// Most registries speak UTF-8; a few still emit Latin-1. Trying UTF-8 first and
/// falling back keeps accented registrant names readable instead of replacing
/// them with `U+FFFD`.
#[cfg(any(feature = "blocking", feature = "async", test))]
pub(crate) fn decode_bytes(bytes: &[u8]) -> String {
    match std::str::from_utf8(bytes) {
        Ok(text) => text.to_string(),
        Err(_) => bytes.iter().map(|&byte| byte as char).collect(),
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn decodes_utf8_and_falls_back_to_latin1() {
        assert_eq!(decode_bytes("Müller".as_bytes()), "Müller");
        // 0xFC is `ü` in Latin-1 and invalid on its own in UTF-8.
        assert_eq!(
            decode_bytes(&[b'M', 0xFC, b'l', b'l', b'e', b'r']),
            "Müller"
        );
        assert_eq!(decode_bytes(b""), "");
    }

    #[test]
    fn cache_key_separates_endpoint_from_name() {
        let query = Query::new(
            Endpoint::whois("whois.nic.uk"),
            "example.co.uk",
            Tld::parse("co.uk").unwrap(),
        );
        assert_eq!(query.cache_key(), "whois.nic.uk|example.co.uk");
    }

    #[test]
    fn blank_detection_ignores_whitespace() {
        let response = |text: &str| {
            RawResponse::new(
                Endpoint::whois("w.example"),
                ResponseKind::WhoisText,
                text,
                Duration::ZERO,
            )
        };
        assert!(response("").is_blank());
        assert!(response(" \r\n\t ").is_blank());
        assert!(!response("No match").is_blank());
    }
}