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
childis the same DNS label sequence as, or a DNS subdomain of,parent. Both are normalized first.a.example.comis a subdomain ofexample.com;example.comis “of” itself;notexample.comis not a This is intentionally a pure DNS-label check, NOT a Public-Suffix-aware operation:is_subdomain_of("a.co.uk", "co.uk")returnstruebecauseco.ukis a parent label sequence, even thoughco.ukis itself a public suffix rather than a registrable domain. Useregistrable_domainwhen you need the eTLD+1 boundary. IP literals are not DNS names; distinct IP literals or comparisons between an IP and a domain returnfalse. - 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.comandwww.example.com→true. Returnsfalseif either host has no registrable domain.