monovm-whois-rust

Domain WHOIS and RDAP lookups for Rust, with availability detection you can audit.

A ground-up Rust design: RDAP, structured record parsing, referral chasing, rate limiting, caching, and verdicts that explain themselves.

use monovm_whois::WhoisClient;

let client = WhoisClient::new()?;
let lookup = client.lookup("example.com")?;

println!("{} is {}", lookup.domain, lookup.availability());

if let Some(record) = &lookup.record {
    println!("registrar: {:?}", record.registrar);
    println!("expires:   {:?}", record.expires);
    println!("locked:    {}", record.is_transfer_locked());
}
# Ok::<(), monovm_whois::Error>(())

Install

[dependencies]
monovm-whois-rust = "1"

The library is imported as monovm_whois. Async instead of blocking:

monovm-whois-rust = { version = "1", default-features = false, features = ["async", "rdap", "parser"] }

The command line tool (installs the monovm-whois binary):

cargo install monovm-whois-rust --features cli

The problem this crate is about

WHOIS has no status codes. A registry saying this domain is free, one saying you are querying too fast, and one saying I do not serve that suffix all send prose over the same socket — and every one of them can contain the word "available".

Libraries in this space overwhelmingly resolve that ambiguity the same way: anything not recognisably a record is treated as availability. The consequence is that a rate-limited registry reports its entire zone as free to register, and a stale server mapping that lands a query on a regional IP registry does the same.

This crate never reports an unanswered query as an answer:

use monovm_whois::{Error, Refusal};

# fn demo(client: &monovm_whois::WhoisClient) {
match client.lookup("example.com") {
    Ok(lookup)                                                  => { /* a real verdict */ }
    Err(Error::Refused { reason: Refusal::RateLimited, .. })     => { /* back off */ }
    Err(Error::Inconclusive { detail, .. })                      => { /* unparseable */ }
    Err(other)                                                   => { /* network, input, … */ }
}
# }

There is deliberately no Availability::Unknown. An uncertain answer that renders as "available" is the one outcome a caller must not be handed.

What you get

Examples

Bulk availability, and bare names

A name with no suffix is checked under a list of popular ones — the "is this brand free?" search:

use monovm_whois::{Checker, WhoisClient};

let checker = Checker::new(WhoisClient::new()?)
    .with_popular_tlds(["com", "net", "io", "co.uk"])?;

let report = checker.check(["monovm", "example.com"]);

println!("{report}");
println!("free: {:?}", report.available());

// Failures are entries, not silence: a lookup that could not be answered is
// reported as such rather than folded into "taken".
for (domain, error) in report.failures() {
    eprintln!("{domain}: {error}");
}
# Ok::<(), monovm_whois::Error>(())

Concurrent lookups

use monovm_whois::AsyncWhoisClient;

# async fn demo() -> Result<(), monovm_whois::Error> {
let client = AsyncWhoisClient::builder()
    .concurrency(32)
    .build()?;

for (domain, outcome) in client.lookup_many(["example.com", "example.net"]).await {
    match outcome {
        Ok(lookup) => println!("{domain}: {}", lookup.availability()),
        Err(error) => eprintln!("{domain}: {error}"),
    }
}
# Ok(())
# }

Why did it say that?

# fn demo(client: &monovm_whois::WhoisClient) -> Result<(), monovm_whois::Error> {
println!("{}", client.explain("example.com")?);
# Ok(())
# }

example.com — registered (high confidence, registered: status field matched "status[\s._\-]*:\s*active")
consulted: whois.verisign-grs.com, whois.example-registrar.com
verdict: registered (high confidence, registered: status field matched …)
response: 2214 bytes
  wrong-server     abstained
  refusal          abstained
  rdap             abstained
  registry-marker  abstained
  withheld         abstained
  registered       registered [high] status field matched …
  not-found        abstained
  tld-pattern      abstained
  recordless       abstained

Configuring it

use std::time::Duration;
use monovm_whois::client::{Preference, ReferralPolicy};
use monovm_whois::WhoisClient;

let client = WhoisClient::builder()
    // RDAP first: its 404 makes availability a fact rather than an inference.
    .prefer(Preference::Rdap)
    .referrals(ReferralPolicy::eager(2))
    .memory_cache(Duration::from_secs(600))
    .throttle_per_host(Duration::from_millis(500))
    .connect_timeout(Duration::from_secs(3))
    .build()?;
# Ok::<(), monovm_whois::Error>(())

Architecture

Six layers, each with one job and no knowledge of the others. Every one is a trait with a bundled implementation, so any of them can be replaced without forking:

              ┌──────────────────────────────────────────┐
              │  client — composes the lookup sequence   │
              └────┬─────────┬──────────┬────────┬───────┘
                   │         │          │        │
        ┌──────────▼──┐  ┌───▼──────┐ ┌─▼─────┐ ┌▼────────┐
        │  registry   │  │transport │ │detect │ │ parser  │
        │ who serves  │  │ the only │ │ what  │ │ record  │
        │ this suffix │  │   I/O    │ │it said│ │ as data │
        └──────┬──────┘  └────┬─────┘ └───────┘ └─────────┘
               │              │
        RegistryProvider   Transport ← cache, retry, throttle (decorators)
               │
        ┌──────▼──────────────────────────────────────────┐
        │  domain — validated values: DomainName, Tld     │
        └─────────────────────────────────────────────────┘

Patterns used, and what each one buys:

SOLID, concretely:

• S — Whois43Transport opens sockets and nothing else; deciding what the bytes mean is detect's job, and parsing them is parser's.
• O — a new detection rule, transport, cache or registry source is a new type. No existing file changes.
• L — every Transport is substitutable, MockTransport included; that is what makes the test suite run without a network.
• I — ResponseCache has three methods, RecordParser two. Nothing implements what it does not need.
• D — WhoisClient depends on dyn RegistryProvider / dyn Transport, never on a concrete type.

Features

Command line

monovm-whois example.com                  # availability
monovm-whois monovm --tlds com,net,io     # a bare name across several suffixes
monovm-whois example.com --record         # the parsed registration
monovm-whois example.com --raw            # the server's own text
monovm-whois example.com --explain        # why the verdict is what it is
monovm-whois example.com --json           # machine-readable
monovm-whois --list-tlds                  # every suffix this build supports

Exit status reflects whether the questions were answered. A domain that turns out to be taken exits zero; a registry that refused to answer exits non-zero.

Registry data

Two bundled sources, layered:

• data/registries.json — 289 curated registry definitions covering 873 suffixes: WHOIS hosts, the exact wording each server uses for an unregistered name, and per-registry quirks. Regenerate from an upstream definition list with python data/build_registries.py path/to/dist.whois.json; that script also applies this crate's corrections to hosts such a list has left behind and adds registries it never covered, so a regeneration does not lose them.
• data/rdap-bootstrap.json — a snapshot of IANA's RDAP bootstrap registry, covering about 1200 suffixes.

Point at your own file, or stack it over the bundled data:

use monovm_whois::registry::{JsonRegistry, LayerStrategy, LayeredRegistry, default_provider};
use monovm_whois::WhoisClient;

let registry = LayeredRegistry::new(LayerStrategy::Override)
    .shared_layer(default_provider())
    .layer(JsonRegistry::from_path("my-overrides.json")?);

let client = WhoisClient::builder().registry(registry).build()?;
# Ok::<(), monovm_whois::Error>(())

With the iana-bootstrap feature, refresh the RDAP list from IANA rather than shipping a snapshot that ages.

Testing

The suite runs offline: MockTransport scripts responses, and fixtures hold real recorded records from a range of registries.

cargo test                          # offline, the default
cargo test --all-features
cargo test -- --ignored             # the live-network tests, opt-in

The network tests are #[ignore] on purpose. A test that fails because a registry is having a bad afternoon teaches nobody anything.

They are still worth running occasionally: survey_the_popular_suffixes sweeps 40 suffixes and prints which answered and how. Its last run answered 35 and got none of them wrong; the wordings it found that no table had — AFNIC's %% NOT FOUND, auDA's bare Available, JPRS's bracketed field keys — are in the CHANGELOG and pinned by fixtures.

License

MIT. See LICENSE.