monovm-whois-rust 1.0.0

//! The runtime-independent half of a lookup.
//!
//! Everything here is a pure function of data already in hand: which endpoints to
//! try and in what order, what to put on the wire, what a response means, and
//! whether a referral is worth following. The blocking and asynchronous clients
//! share all of it and differ only in how they wait for a socket — which keeps the
//! two from drifting apart, and makes the interesting decisions testable without a
//! network.

use crate::domain::Tld;
use crate::error::{Error, Result};
use crate::registry::{Endpoint, EndpointKind, Registry, Resolution};
use crate::transport::Query;

// Referral chasing, response interpretation and failure aggregation are steps in a
// client's lookup sequence, so they exist only when a client does. Endpoint ordering
// and the policy types above are useful on their own and are not gated.
#[cfg(any(feature = "blocking", feature = "async"))]
use crate::detect::{DetectionEngine, Evidence, Verdict};
#[cfg(any(feature = "blocking", feature = "async"))]
use crate::registry::WhoisEndpoint;
#[cfg(any(feature = "blocking", feature = "async"))]
use crate::transport::{referral_host, RawResponse};

/// Which protocol to try first when a registry publishes both.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum Preference {
    /// Port 43 first, RDAP as a fallback.
    ///
    /// The default. Port 43 needs no TLS handshake, so it is the faster of the two,
    /// and the curated availability wording in this crate's data was written
    /// against those servers. RDAP still covers the registries that have no port 43
    /// service at all.
    #[default]
    Whois,

    /// RDAP first, port 43 as a fallback.
    ///
    /// Worth choosing when correctness matters more than latency: RDAP answers with
    /// a structured object and a real 404, so a verdict from it is
    /// [`Confidence::Definitive`](crate::detect::Confidence::Definitive) rather than
    /// a judgement about wording.
    Rdap,

    /// Whatever order the registry definition lists.
    RegistryOrder,

    /// Port 43 only.
    WhoisOnly,

    /// RDAP only.
    RdapOnly,
}

impl Preference {
    /// Order a registry's endpoints, dropping any this preference excludes.
    pub fn order(self, registry: &Registry) -> Vec<Endpoint> {
        let whois = || registry.endpoints_matching(EndpointKind::Whois).cloned();
        let rdap = || registry.endpoints_matching(EndpointKind::Rdap).cloned();

        match self {
            Preference::Whois => whois().chain(rdap()).collect(),
            Preference::Rdap => rdap().chain(whois()).collect(),
            Preference::RegistryOrder => registry.endpoints().to_vec(),
            Preference::WhoisOnly => whois().collect(),
            Preference::RdapOnly => rdap().collect(),
        }
    }
}

/// How far to chase a thin registry's referral.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct ReferralPolicy {
    /// How many referrals to follow. `0` disables chasing.
    pub max_hops: u8,
    /// Whether to follow a referral even when the registry answer already looks
    /// complete.
    pub always: bool,
}

impl ReferralPolicy {
    /// Follow one referral, and only from a registry that answered thinly.
    ///
    /// One hop is enough for the gTLD structure that makes referrals necessary:
    /// registry points at registrar, and the registrar is authoritative. More hops
    /// mostly find loops.
    pub const DEFAULT: ReferralPolicy = ReferralPolicy {
        max_hops: 1,
        always: false,
    };

    /// Do not follow referrals.
    pub const NONE: ReferralPolicy = ReferralPolicy {
        max_hops: 0,
        always: false,
    };

    /// Follow up to `hops` referrals whenever one is offered.
    pub fn eager(hops: u8) -> Self {
        ReferralPolicy {
            max_hops: hops,
            always: true,
        }
    }

    /// Whether chasing is enabled at all.
    pub fn is_enabled(self) -> bool {
        self.max_hops > 0
    }
}

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

/// The endpoints to try for one name, in order.
#[derive(Debug, Clone)]
pub struct Plan {
    /// The registry match this plan came from.
    pub resolution: Resolution,
    /// Endpoints to attempt, best first.
    pub attempts: Vec<Endpoint>,
    /// What to send, in the form the registry wants.
    pub wire_name: String,
}

impl Plan {
    /// Work out how to look a resolved name up.
    ///
    /// # Errors
    ///
    /// [`Error::NoEndpoint`] when the preference excludes everything the registry
    /// publishes — asking for [`Preference::RdapOnly`] against a registry with only
    /// a port 43 service, say. The error names what was dropped, since otherwise
    /// this looks like an unsupported TLD.
    pub fn build(resolution: Resolution, preference: Preference) -> Result<Self> {
        let attempts = preference.order(&resolution.registry);

        if attempts.is_empty() {
            let available: Vec<String> = resolution
                .registry
                .endpoints()
                .iter()
                .map(Endpoint::to_string)
                .collect();

            return Err(Error::NoEndpoint {
                tld: resolution.tld.clone(),
                detail: if available.is_empty() {
                    "the registry definition lists no endpoint".to_string()
                } else {
                    format!(
                        "{preference:?} excludes every endpoint the registry has: {}",
                        available.join(", ")
                    )
                },
            });
        }

        let wire_name = resolution.wire_form();
        Ok(Plan {
            resolution,
            attempts,
            wire_name,
        })
    }

    /// The suffix being looked up.
    pub fn tld(&self) -> &Tld {
        &self.resolution.tld
    }

    /// A query for one of the planned endpoints.
    pub fn query(&self, endpoint: &Endpoint) -> Query {
        Query::new(
            endpoint.clone(),
            self.wire_name.clone(),
            self.resolution.tld.clone(),
        )
    }

    /// Every planned query, in order.
    pub fn queries(&self) -> Vec<Query> {
        self.attempts
            .iter()
            .map(|endpoint| self.query(endpoint))
            .collect()
    }
}

/// Whether to ask a registrar's server as well, and which one.
///
/// Returns `None` when there is nothing to follow: no referral in the record, the
/// policy says not to, the hop budget is spent, the referral points back somewhere
/// already visited, or the registry answer was already complete.
#[cfg(any(feature = "blocking", feature = "async"))]
pub fn next_referral(
    response: &RawResponse,
    registry: &Registry,
    policy: ReferralPolicy,
    visited: &[WhoisEndpoint],
) -> Option<WhoisEndpoint> {
    if !policy.is_enabled() || visited.len() > policy.max_hops as usize {
        return None;
    }

    // A referral costs a round trip. Spend it when the registry is known to answer
    // thinly, or when the caller asked for it unconditionally.
    if !policy.always && !registry.is_thin() {
        return None;
    }

    let host = referral_host(response.text())?;
    let endpoint = WhoisEndpoint::parse(&host).ok()?;

    // Do not loop back to a server already asked, including the one that just
    // answered — several registrars point at the registry that referred us.
    if visited
        .iter()
        .any(|seen| seen.host().eq_ignore_ascii_case(endpoint.host()))
    {
        return None;
    }

    Some(endpoint)
}

/// Read one response, in the light of which registry produced it.
#[cfg(any(feature = "blocking", feature = "async"))]
pub fn interpret(
    engine: &DetectionEngine,
    response: &RawResponse,
    resolution: &Resolution,
) -> Result<Verdict> {
    let evidence = Evidence::from_response(
        response,
        &resolution.tld,
        Some(resolution.registry.as_ref()),
    );
    engine.decide(&evidence)
}

/// Combine the failures from every attempted endpoint into one error.
///
/// A caller that tried three endpoints and got three different failures needs all
/// three to diagnose anything, and the last one is not usually the informative one.
#[cfg(any(feature = "blocking", feature = "async"))]
pub fn combined_failure(name: &str, mut failures: Vec<(Endpoint, Error)>) -> Error {
    // A definite answer that happens to arrive as an error — a refusal, a wrong
    // server — is more useful than a connection failure, so surface it if present.
    if let Some(index) = failures
        .iter()
        .position(|(_, error)| matches!(error, Error::Refused { .. }))
    {
        return failures.swap_remove(index).1;
    }

    let consulted = failures
        .iter()
        .map(|(endpoint, _)| endpoint.address())
        .collect::<Vec<_>>()
        .join(", ");
    let detail = failures
        .iter()
        .map(|(endpoint, error)| format!("{}: {error}", endpoint.address()))
        .collect::<Vec<_>>()
        .join("; ");

    Error::Inconclusive {
        domain: name.to_string(),
        consulted: if consulted.is_empty() {
            "no endpoint".to_string()
        } else {
            consulted
        },
        detail,
    }
}

#[cfg(test)]
mod tests {
    use std::sync::Arc;
    use std::time::Duration;

    use super::*;
    use crate::domain::DomainName;
    use crate::registry::Registry;
    use crate::transport::ResponseKind;

    fn resolution(registry: Registry) -> Resolution {
        let tld = Tld::parse("com").unwrap();
        let name = DomainName::parse("example.com").unwrap();
        Resolution {
            queried: name.clone(),
            registrable: name,
            tld,
            registry: Arc::new(registry),
        }
    }

    fn both_protocols() -> Registry {
        Registry::builder([Tld::parse("com").unwrap()])
            .endpoint(Endpoint::whois("whois.verisign-grs.com"))
            .endpoint(Endpoint::rdap("https://rdap.verisign.com/com/v1/"))
            .build()
    }

    fn response(text: &str) -> RawResponse {
        RawResponse::new(
            Endpoint::whois("whois.verisign-grs.com"),
            ResponseKind::WhoisText,
            text,
            Duration::ZERO,
        )
    }

    // ------------------------------------------------------------- preference

    #[test]
    fn preference_orders_and_filters_endpoints() {
        let registry = both_protocols();

        let whois_first = Preference::Whois.order(&registry);
        assert!(whois_first[0].is_whois());
        assert!(whois_first[1].is_rdap());

        let rdap_first = Preference::Rdap.order(&registry);
        assert!(rdap_first[0].is_rdap());
        assert!(rdap_first[1].is_whois());

        assert_eq!(Preference::WhoisOnly.order(&registry).len(), 1);
        assert!(Preference::WhoisOnly.order(&registry)[0].is_whois());
        assert!(Preference::RdapOnly.order(&registry)[0].is_rdap());
        assert_eq!(
            Preference::RegistryOrder.order(&registry),
            registry.endpoints()
        );
    }

    #[test]
    fn the_default_preference_is_whois_first() {
        assert_eq!(Preference::default(), Preference::Whois);
    }

    // -------------------------------------------------------------------- plan

    #[test]
    fn a_plan_lists_the_endpoints_to_try() {
        let plan = Plan::build(resolution(both_protocols()), Preference::Whois).unwrap();

        assert_eq!(plan.attempts.len(), 2);
        assert_eq!(plan.wire_name, "example.com");
        assert_eq!(plan.tld().ascii(), "com");
        assert_eq!(plan.queries().len(), 2);
    }

    #[test]
    fn a_plan_that_excludes_everything_says_so() {
        let whois_only = Registry::builder([Tld::parse("com").unwrap()])
            .endpoint(Endpoint::whois("whois.example"))
            .build();

        let error = Plan::build(resolution(whois_only), Preference::RdapOnly).unwrap_err();
        match error {
            Error::NoEndpoint { detail, .. } => {
                assert!(detail.contains("RdapOnly"), "{detail}");
                assert!(detail.contains("whois.example"), "{detail}");
            }
            other => panic!("got {other:?}"),
        }
    }

    #[test]
    fn a_registry_with_no_endpoint_says_so() {
        let empty = Registry::builder([Tld::parse("com").unwrap()]).build();
        let error = Plan::build(resolution(empty), Preference::Whois).unwrap_err();

        match error {
            Error::NoEndpoint { detail, .. } => assert!(detail.contains("no endpoint"), "{detail}"),
            other => panic!("got {other:?}"),
        }
    }

    #[test]
    fn the_wire_name_follows_the_registrys_idn_preference() {
        let tld = Tld::parse("de").unwrap();
        let name = DomainName::parse("münchen.de").unwrap();
        let registry = Registry::builder([tld.clone()])
            .endpoint(Endpoint::whois("whois.denic.de"))
            .idn_form(crate::registry::IdnForm::Unicode)
            .build();

        let plan = Plan::build(
            Resolution {
                queried: name.clone(),
                registrable: name,
                tld,
                registry: Arc::new(registry),
            },
            Preference::Whois,
        )
        .unwrap();

        assert_eq!(plan.wire_name, "münchen.de");
    }

    // ---------------------------------------------------------------- referral
    //
    // Referral chasing and failure aggregation exist to serve a client, and are
    // compiled only when one is — so their tests are gated the same way.
    #[cfg(any(feature = "blocking", feature = "async"))]
    mod client_driven {
        use super::*;

        const THIN_ANSWER: &str = "\
Domain Name: EXAMPLE.COM
Registrar: Example Registrar, LLC
Registrar WHOIS Server: whois.example-registrar.com
";

        #[test]
        fn a_thin_registry_referral_is_followed() {
            let registry = Registry::builder([Tld::parse("com").unwrap()])
                .thin(true)
                .build();
            let visited = vec![WhoisEndpoint::new("whois.verisign-grs.com", 43)];

            let next = next_referral(
                &response(THIN_ANSWER),
                &registry,
                ReferralPolicy::DEFAULT,
                &visited,
            );
            assert_eq!(next.unwrap().host(), "whois.example-registrar.com");
        }

        #[test]
        fn a_thick_registry_referral_is_not_followed_by_default() {
            let thick = Registry::builder([Tld::parse("com").unwrap()]).build();

            assert!(
                next_referral(&response(THIN_ANSWER), &thick, ReferralPolicy::DEFAULT, &[])
                    .is_none()
            );
            // Unless the caller asks for it unconditionally.
            assert!(next_referral(
                &response(THIN_ANSWER),
                &thick,
                ReferralPolicy::eager(1),
                &[]
            )
            .is_some());
        }

        #[test]
        fn referral_chasing_can_be_switched_off() {
            let thin = Registry::builder([Tld::parse("com").unwrap()])
                .thin(true)
                .build();
            assert!(
                next_referral(&response(THIN_ANSWER), &thin, ReferralPolicy::NONE, &[]).is_none()
            );
            assert!(!ReferralPolicy::NONE.is_enabled());
        }

        #[test]
        fn the_hop_budget_is_respected() {
            let thin = Registry::builder([Tld::parse("com").unwrap()])
                .thin(true)
                .build();
            // Two servers already asked exceeds a one-hop budget.
            let visited = vec![
                WhoisEndpoint::new("whois.verisign-grs.com", 43),
                WhoisEndpoint::new("whois.first-registrar.com", 43),
            ];

            assert!(next_referral(
                &response(THIN_ANSWER),
                &thin,
                ReferralPolicy::DEFAULT,
                &visited
            )
            .is_none());
        }

        #[test]
        fn a_referral_loop_is_not_followed() {
            let thin = Registry::builder([Tld::parse("com").unwrap()])
                .thin(true)
                .build();
            let visited = vec![WhoisEndpoint::new("whois.example-registrar.com", 43)];

            assert!(
                next_referral(
                    &response(THIN_ANSWER),
                    &thin,
                    ReferralPolicy::DEFAULT,
                    &visited
                )
                .is_none(),
                "a referral back to a server already asked must not be followed"
            );
        }

        #[test]
        fn a_record_with_no_referral_ends_the_chain() {
            let thin = Registry::builder([Tld::parse("com").unwrap()])
                .thin(true)
                .build();
            let complete = response("Domain Name: EXAMPLE.DE\nStatus: connect\n");

            assert!(next_referral(&complete, &thin, ReferralPolicy::DEFAULT, &[]).is_none());
        }

        // ------------------------------------------------------- combined failure

        #[test]
        fn a_refusal_outranks_a_connection_failure() {
            let failures = vec![
                (
                    Endpoint::whois("a.example"),
                    Error::Connect {
                        server: "a.example".into(),
                        source: std::io::Error::other("no route"),
                    },
                ),
                (
                    Endpoint::rdap("https://b.example/"),
                    Error::Refused {
                        server: "b.example".into(),
                        reason: crate::error::Refusal::RateLimited,
                    },
                ),
            ];

            let combined = combined_failure("example.com", failures);
            assert!(
                matches!(combined, Error::Refused { .. }),
                "a definite refusal is more useful than a transport failure: got {combined:?}"
            );
        }

        #[test]
        fn transport_failures_are_reported_together() {
            let failures = vec![
                (
                    Endpoint::whois("a.example"),
                    Error::Timeout {
                        server: "a.example".into(),
                        elapsed: Duration::from_secs(5),
                    },
                ),
                (
                    Endpoint::rdap("https://b.example/"),
                    Error::Http {
                        url: "https://b.example/".into(),
                        status: 500,
                    },
                ),
            ];

            match combined_failure("example.com", failures) {
                Error::Inconclusive {
                    consulted, detail, ..
                } => {
                    assert!(consulted.contains("a.example"), "{consulted}");
                    assert!(consulted.contains("b.example"), "{consulted}");
                    assert!(detail.contains("500"), "{detail}");
                }
                other => panic!("got {other:?}"),
            }
        }

        #[test]
        fn no_failures_at_all_still_produces_a_usable_error() {
            match combined_failure("example.com", Vec::new()) {
                Error::Inconclusive { consulted, .. } => assert_eq!(consulted, "no endpoint"),
                other => panic!("got {other:?}"),
            }
        }
    }
}