monovm-whois-rust 1.0.0

//! Deciding what a response actually said.
//!
//! WHOIS has no status codes. "This domain is free", "you are querying too fast"
//! and "I do not serve that suffix" all arrive as prose over the same socket, and
//! telling them apart is guesswork dressed up as parsing. The one mistake that
//! must not happen is reading a non-answer as availability, because that is the
//! error that gets a registered domain offered for sale.
//!
//! # How it works
//!
//! A [`DetectionEngine`] holds an ordered list of [`AvailabilityRule`]s and asks
//! each in turn until one stops abstaining — Chain of Responsibility, with the
//! order carrying the priority. If every rule abstains, the engine returns
//! [`Error::Inconclusive`] rather than picking an answer.
//!
//! ```
//! use monovm_whois::detect::{DetectionEngine, Evidence};
//! use monovm_whois::transport::ResponseKind;
//! use monovm_whois::{Availability, Tld};
//!
//! let tld = Tld::parse("com").unwrap();
//! let engine = DetectionEngine::standard();
//!
//! let evidence = Evidence::new("No match for \"NOTHERE.COM\"", ResponseKind::WhoisText, &tld, None);
//! assert_eq!(engine.decide(&evidence).unwrap().availability, Availability::Available);
//!
//! // A rate-limit notice is not an answer, and must not become one.
//! let throttled = Evidence::new("%% queries limit exceeded", ResponseKind::WhoisText, &tld, None);
//! assert!(engine.decide(&throttled).is_err());
//! ```
//!
//! # Explaining a verdict
//!
//! Every verdict names the rule that produced it and why, and
//! [`DetectionEngine::report`] runs the whole chain to show what each rule thought.
//! Guesswork that cannot be inspected is guesswork nobody can fix.

use std::fmt;

use crate::domain::Availability;
use crate::error::{Error, Refusal, Result};

mod evidence;
pub mod patterns;
mod rules;

pub use evidence::Evidence;
pub use rules::{
    NotFoundRule, RdapRule, RecordlessRule, RefusalRule, RegisteredRule, RegistryMarkerRule,
    TldPatternRule, WithheldRule, WrongServerRule,
};

/// How much weight a verdict deserves.
///
/// Exposed so a caller can hold itself to a higher standard than the crate's
/// default — a registrar's checkout page might accept only `Definitive` and
/// `High`, while a bulk research script is happy with anything.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum Confidence {
    /// Inferred from the absence of evidence. Sound only for registries known to
    /// answer this way, and never a general fallback.
    Low,
    /// Matched a pattern that generalises across registries.
    Medium,
    /// Matched wording curated for this specific registry, or a status value that
    /// only one answer can explain.
    High,
    /// Read from a structured, specified response — an RDAP object or error code.
    /// Not an inference at all.
    Definitive,
}

impl Confidence {
    /// A short lower-case name.
    pub fn as_str(self) -> &'static str {
        match self {
            Confidence::Low => "low",
            Confidence::Medium => "medium",
            Confidence::High => "high",
            Confidence::Definitive => "definitive",
        }
    }
}

impl fmt::Display for Confidence {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(self.as_str())
    }
}

/// What one rule concluded.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Judgement {
    /// The rule reached a conclusion.
    Decided {
        /// What the response says about the domain.
        availability: Availability,
        /// How much the rule stands behind it.
        confidence: Confidence,
        /// Why, in a form a human can check.
        because: String,
    },
    /// The server declined to answer, so the response says nothing about the
    /// domain.
    Refused {
        /// How the refusal was recognised.
        reason: Refusal,
        /// Why the rule thinks so.
        because: String,
    },
    /// The server does not serve this suffix, so its answer is about something
    /// else entirely.
    WrongServer {
        /// Why the rule thinks so.
        because: String,
    },
    /// This rule has nothing to say; ask the next one.
    Abstain,
}

impl Judgement {
    /// A `Decided` judgement.
    pub fn decided(
        availability: Availability,
        confidence: Confidence,
        because: impl Into<String>,
    ) -> Self {
        Judgement::Decided {
            availability,
            confidence,
            because: because.into(),
        }
    }

    /// Whether this judgement ends the chain.
    pub fn is_conclusive(&self) -> bool {
        !matches!(self, Judgement::Abstain)
    }
}

/// One rule in the chain.
///
/// A rule reads the [`Evidence`] and either concludes or abstains. It must not
/// perform I/O, must not depend on any other rule having run, and must abstain
/// rather than guess — the engine handles "nobody knows" better than any
/// individual rule can.
pub trait AvailabilityRule: fmt::Debug + Send + Sync {
    /// A stable identifier, used in verdicts and reports.
    fn name(&self) -> &'static str;

    /// Read the evidence.
    fn evaluate(&self, evidence: &Evidence<'_>) -> Judgement;
}

/// The answer, with its provenance.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Verdict {
    /// What the response says about the domain.
    pub availability: Availability,
    /// How much to trust it.
    pub confidence: Confidence,
    /// Which rule decided.
    pub rule: &'static str,
    /// Why.
    pub because: String,
}

impl fmt::Display for Verdict {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(
            f,
            "{} ({} confidence, {}: {})",
            self.availability, self.confidence, self.rule, self.because
        )
    }
}

/// What every rule thought, whether or not it was consulted.
///
/// The tool to reach for when a lookup returns something surprising: it shows
/// which rule fired and, just as usefully, which rules nearly did.
#[derive(Debug, Clone)]
pub struct DetectionReport {
    /// Every rule's judgement, in the order the engine holds them.
    pub judgements: Vec<(&'static str, Judgement)>,
    /// The verdict the engine would return, or the error it would raise.
    pub outcome: std::result::Result<Verdict, String>,
    /// Length of the response, in bytes after trimming.
    pub response_len: usize,
    /// The first 200 characters of the response.
    pub preview: String,
}

impl DetectionReport {
    /// The rules that reached a conclusion.
    pub fn conclusive(&self) -> impl Iterator<Item = (&'static str, &Judgement)> {
        self.judgements
            .iter()
            .filter(|(_, judgement)| judgement.is_conclusive())
            .map(|(name, judgement)| (*name, judgement))
    }

    /// Whether more than one rule reached a conclusion, and they disagree.
    ///
    /// Not an error — later rules are meant to be shadowed by earlier ones — but a
    /// good place to look when a suffix keeps producing the wrong answer.
    pub fn has_disagreement(&self) -> bool {
        let mut availabilities = self
            .conclusive()
            .filter_map(|(_, judgement)| match judgement {
                Judgement::Decided { availability, .. } => Some(*availability),
                _ => None,
            });

        let Some(first) = availabilities.next() else {
            return false;
        };
        availabilities.any(|other| other != first)
    }
}

impl fmt::Display for DetectionReport {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match &self.outcome {
            Ok(verdict) => writeln!(f, "verdict: {verdict}")?,
            Err(problem) => writeln!(f, "verdict: none ({problem})")?,
        }
        writeln!(f, "response: {} bytes", self.response_len)?;

        for (name, judgement) in &self.judgements {
            match judgement {
                Judgement::Abstain => writeln!(f, "  {name:<16} abstained")?,
                Judgement::Decided {
                    availability,
                    confidence,
                    because,
                } => writeln!(f, "  {name:<16} {availability} [{confidence}] {because}")?,
                Judgement::Refused { reason, because } => {
                    writeln!(f, "  {name:<16} refused: {reason} ({because})")?
                }
                Judgement::WrongServer { because } => {
                    writeln!(f, "  {name:<16} wrong server ({because})")?
                }
            }
        }

        Ok(())
    }
}

/// An ordered chain of rules.
///
/// [`standard`](DetectionEngine::standard) is the chain this crate uses. A caller
/// who needs different behaviour composes their own rather than passing flags:
///
/// ```
/// use monovm_whois::detect::{DetectionEngine, NotFoundRule, RefusalRule, WrongServerRule};
///
/// // Only the checks that cannot produce a false "available", plus one that can.
/// let engine = DetectionEngine::new()
///     .rule(WrongServerRule)
///     .rule(RefusalRule)
///     .rule(NotFoundRule);
/// assert_eq!(engine.len(), 3);
/// ```
#[derive(Debug)]
pub struct DetectionEngine {
    rules: Vec<Box<dyn AvailabilityRule>>,
}

impl DetectionEngine {
    /// An empty chain, which concludes nothing.
    pub fn new() -> Self {
        DetectionEngine { rules: Vec::new() }
    }

    /// The chain used by default.
    ///
    /// Order matters: the rules that can invalidate a whole response run first,
    /// structured answers next, and the generic text patterns last, with every
    /// "registered" check ahead of the "available" check that its wording would
    /// otherwise trip.
    pub fn standard() -> Self {
        DetectionEngine::new()
            .rule(WrongServerRule)
            .rule(RefusalRule)
            .rule(RdapRule)
            .rule(RegistryMarkerRule)
            .rule(WithheldRule)
            .rule(RegisteredRule::new())
            .rule(NotFoundRule)
            .rule(TldPatternRule)
            .rule(RecordlessRule)
    }

    /// Append a rule.
    pub fn rule(mut self, rule: impl AvailabilityRule + 'static) -> Self {
        self.rules.push(Box::new(rule));
        self
    }

    /// Append a boxed rule.
    pub fn boxed_rule(mut self, rule: Box<dyn AvailabilityRule>) -> Self {
        self.rules.push(rule);
        self
    }

    /// How many rules are in the chain.
    pub fn len(&self) -> usize {
        self.rules.len()
    }

    /// Whether the chain is empty.
    pub fn is_empty(&self) -> bool {
        self.rules.is_empty()
    }

    /// The rule names, in order.
    pub fn rule_names(&self) -> Vec<&'static str> {
        self.rules.iter().map(|rule| rule.name()).collect()
    }

    /// Ask each rule in turn and return the first conclusion.
    ///
    /// # Errors
    ///
    /// [`Error::Refused`] or [`Error::UnsupportedTld`] when a rule established that
    /// the response is not an answer, and [`Error::Inconclusive`] when every rule
    /// abstained. None of these is reported as an availability, which is the point:
    /// the caller is told the question was not answered instead of being handed a
    /// guess.
    pub fn decide(&self, evidence: &Evidence<'_>) -> Result<Verdict> {
        for rule in &self.rules {
            match rule.evaluate(evidence) {
                Judgement::Abstain => continue,
                Judgement::Decided {
                    availability,
                    confidence,
                    because,
                } => {
                    return Ok(Verdict {
                        availability,
                        confidence,
                        rule: rule.name(),
                        because,
                    })
                }
                // `because` names the pattern that fired, which is diagnostic rather
                // than user-facing — it belongs in a report, not concatenated into a
                // field called `server`. Reach for `report` to see it.
                Judgement::Refused { reason, .. } => {
                    return Err(Error::Refused {
                        server: endpoint_label(evidence),
                        reason,
                    })
                }
                Judgement::WrongServer { because } => {
                    return Err(Error::NoEndpoint {
                        tld: evidence.tld().clone(),
                        detail: format!(
                            "the server answered about a different namespace: {because}"
                        ),
                    })
                }
            }
        }

        Err(Error::Inconclusive {
            domain: format!("a .{} name", evidence.tld()),
            consulted: endpoint_label(evidence),
            detail: format!(
                "no rule recognised the response ({} bytes): {}",
                evidence.len(),
                evidence.preview(120)
            ),
        })
    }

    /// Run every rule and record what each one thought.
    ///
    /// Unlike [`decide`](DetectionEngine::decide) this does not stop at the first
    /// conclusion, so the result shows both the winning rule and the ones it
    /// shadowed.
    pub fn report(&self, evidence: &Evidence<'_>) -> DetectionReport {
        let judgements: Vec<(&'static str, Judgement)> = self
            .rules
            .iter()
            .map(|rule| (rule.name(), rule.evaluate(evidence)))
            .collect();

        let outcome = self.decide(evidence).map_err(|error| error.to_string());

        DetectionReport {
            judgements,
            outcome,
            response_len: evidence.len(),
            preview: evidence.preview(200),
        }
    }
}

impl Default for DetectionEngine {
    fn default() -> Self {
        DetectionEngine::standard()
    }
}

/// A label for whatever answered, for error messages.
fn endpoint_label(evidence: &Evidence<'_>) -> String {
    match evidence.registry() {
        Some(registry) => registry
            .endpoints()
            .first()
            .map(|endpoint| endpoint.address())
            .unwrap_or_else(|| format!(".{} registry", evidence.tld())),
        None => format!("the .{} server", evidence.tld()),
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::domain::Tld;
    use crate::registry::Registry;
    use crate::transport::ResponseKind;

    fn decide(text: &str, tld: &str) -> Result<Verdict> {
        let tld = Tld::parse(tld).unwrap();
        let evidence = Evidence::new(text, ResponseKind::WhoisText, &tld, None);
        DetectionEngine::standard().decide(&evidence)
    }

    #[test]
    fn the_standard_chain_runs_the_documented_rules_in_order() {
        assert_eq!(
            DetectionEngine::standard().rule_names(),
            [
                "wrong-server",
                "refusal",
                "rdap",
                "registry-marker",
                "withheld",
                "registered",
                "not-found",
                "tld-pattern",
                "recordless",
            ]
        );
    }

    #[test]
    fn an_available_response_is_recognised() {
        let verdict = decide("No match for \"NOTHERE.COM\".", "com").unwrap();
        assert_eq!(verdict.availability, Availability::Available);
    }

    #[test]
    fn a_registered_record_is_recognised() {
        let record = "\
Domain Name: EXAMPLE.COM
Registrar: Example Registrar, LLC
Domain Status: clientTransferProhibited
Name Server: NS1.EXAMPLE.COM
";
        let verdict = decide(record, "com").unwrap();
        assert_eq!(verdict.availability, Availability::Registered);
        assert_eq!(verdict.confidence, Confidence::High);
    }

    #[test]
    fn a_refusal_is_an_error_not_an_availability() {
        for response in [
            "%% queries limit exceeded",
            "Requests of this client are not permitted",
            "The WHOIS service has been retired; please use our RDAP service",
        ] {
            let error = decide(response, "com").unwrap_err();
            assert!(
                matches!(error, Error::Refused { .. }),
                "for {response:?}: got {error:?}"
            );
        }
    }

    #[test]
    fn the_wrong_server_is_an_error_not_an_availability() {
        let response = "% This is the RIPE Database query service.\n%ERROR:101: no entries found\n";
        let error = decide(response, "example").unwrap_err();
        assert!(matches!(error, Error::NoEndpoint { .. }), "got {error:?}");
    }

    #[test]
    fn an_unrecognisable_response_is_inconclusive() {
        let error = decide("something nobody has ever written", "com").unwrap_err();
        match error {
            Error::Inconclusive { detail, .. } => {
                assert!(detail.contains("something nobody"), "{detail}")
            }
            other => panic!("got {other:?}"),
        }
    }

    #[test]
    fn an_empty_chain_concludes_nothing() {
        let tld = Tld::parse("com").unwrap();
        let evidence = Evidence::new("No match for x", ResponseKind::WhoisText, &tld, None);
        let engine = DetectionEngine::new();

        assert!(engine.is_empty());
        assert!(engine.decide(&evidence).is_err());
    }

    #[test]
    fn a_curated_marker_beats_the_generic_tables() {
        let tld = Tld::parse("example").unwrap();
        let registry = Registry::builder([tld.clone()])
            .available_marker("nothing here")
            .build();
        let evidence = Evidence::new(
            "Nothing here for that name",
            ResponseKind::WhoisText,
            &tld,
            Some(&registry),
        );

        let verdict = DetectionEngine::standard().decide(&evidence).unwrap();
        assert_eq!(verdict.rule, "registry-marker");
        assert_eq!(verdict.confidence, Confidence::High);
    }

    #[test]
    fn rdap_beats_the_text_rules() {
        let tld = Tld::parse("com").unwrap();
        let json = r#"{"objectClassName":"domain","ldhName":"example.com"}"#;
        let evidence = Evidence::new(json, ResponseKind::RdapJson, &tld, None);

        let verdict = DetectionEngine::standard().decide(&evidence).unwrap();
        assert_eq!(verdict.rule, "rdap");
        assert_eq!(verdict.confidence, Confidence::Definitive);
    }

    #[test]
    fn a_report_shows_the_shadowed_rules_too() {
        let tld = Tld::parse("com").unwrap();
        let record = "Domain Name: EXAMPLE.COM\nRegistrar: Example\nStatus: active\n";
        let evidence = Evidence::new(record, ResponseKind::WhoisText, &tld, None);

        let report = DetectionEngine::standard().report(&evidence);
        assert_eq!(report.judgements.len(), 9);
        assert!(report.outcome.is_ok());
        assert!(report.conclusive().count() >= 1);
        // Rendering must not panic and must name the winner.
        assert!(report.to_string().contains("registered"));
    }

    #[test]
    fn a_report_survives_an_inconclusive_response() {
        let tld = Tld::parse("com").unwrap();
        let evidence = Evidence::new("???", ResponseKind::WhoisText, &tld, None);

        let report = DetectionEngine::standard().report(&evidence);
        assert!(report.outcome.is_err());
        assert_eq!(report.conclusive().count(), 0);
        assert!(!report.has_disagreement());
        assert!(report.to_string().contains("verdict: none"));
    }

    #[test]
    fn confidence_is_ordered_from_guess_to_fact() {
        assert!(Confidence::Definitive > Confidence::High);
        assert!(Confidence::High > Confidence::Medium);
        assert!(Confidence::Medium > Confidence::Low);
    }

    #[test]
    fn a_verdict_explains_itself() {
        let verdict = decide("No match for \"NOTHERE.COM\".", "com").unwrap();
        let rendered = verdict.to_string();

        assert!(rendered.contains("available"), "{rendered}");
        assert!(rendered.contains(verdict.rule), "{rendered}");
        assert!(!verdict.because.is_empty());
    }
}