Skip to main content

Crate dnsname

Crate dnsname 

Source
Expand description

dnsname: canonical registrable-domain (eTLD+1) and public-suffix resolution for the Santh fleet.

Before this crate, eTLD+1 was computed three different ways across the tree: some crates called the psl crate directly (gossan, wafrift), while others hand-rolled a “last two labels” heuristic (scald, sear, daylight) that is wrong for multi-label public suffixes (example.co.uk → the heuristic returns co.uk, this crate returns example.co.uk). This is the one place that owns the Public Suffix List lookup, so every consumer agrees and the bug is fixed once.

§What this is NOT

This is the registrable domain (eTLD+1), not a host-cache-key normalizer. scanclient::urlutil::registrable_domain is a different operation (lowercase host with www. stripped, full host retained) and is intentionally left alone (do not route it here).

§Inputs

All functions take a bare host ("a.b.example.co.uk"), not a URL. Strip the scheme/port/path before calling. Input is normalized: surrounding whitespace and surrounding FQDN dots are removed and the host is ASCII-lowercased. Input containing ASCII whitespace or control bytes anywhere is rejected: such strings can never be DNS names. IP literals (IPv4 and IPv6, standard forms including bracketed [::1] and zone-scoped fe80::1%eth0 as parsed by std::net::IpAddr) have no registrable domain or public suffix and return None from registrable_domain and public_suffix; note that non-standard IP spellings Rust’s parser rejects (hex octets like 0x7f.0.0.1, collapsed forms like 127.1) are a known gap and still resolve as ordinary unknown-TLD names. Punycode/IDNA is the caller’s responsibility; pass an A-label (xn--…) host if the source is internationalized.

§Public Suffix List snapshot

This crate bundles the PSL snapshot that ships with the pinned psl crate version (2.1.218 at the time of writing). It does not load a runtime Tier-B data file, so the snapshot ages with the dependency. Keep psl pinned in Cargo.toml and bump it deliberately after verifying the new PSL list; dnsname::tests::psl_dependency_is_pinned enforces the exact pin.

Re-exports§

pub use self::registrable_domain as etld_plus_one;
pub use self::registrable_domain as apex_domain;

Functions§

is_subdomain_of
Whether child is the same DNS label sequence as, or a DNS subdomain of, parent. Both are normalized first. a.example.com is a subdomain of example.com; example.com is “of” itself; notexample.com is not a This is intentionally a pure DNS-label check, NOT a Public-Suffix-aware operation: is_subdomain_of("a.co.uk", "co.uk") returns true because co.uk is a parent label sequence, even though co.uk is itself a public suffix rather than a registrable domain. Use registrable_domain when you need the eTLD+1 boundary. IP literals are not DNS names; distinct IP literals or comparisons between an IP and a domain return false.
public_suffix
The effective top-level domain (public suffix) of host, e.g. a.example.co.uk → co.uk, example.com → com.
registrable_domain
The registrable domain (eTLD+1) of host, e.g. a.b.example.co.uk → example.co.uk, example.com → example.com.
same_registrable_domain
Whether two hosts share the same registrable domain (same organization), e.g. mail.example.com and www.example.com → true. Returns false if either host has no registrable domain.