psl2 0.1.0

//! `psl2` — a modern alternative to the [`psl`] crate for working with
//! Mozilla's [Public Suffix List].
//!
//! It answers the practical question *"is this hostname a registrable domain
//! (one that can own cookies), or is it a public suffix?"* — e.g. `example.jp`
//! is registrable, while `co.jp` is a public suffix.
//!
//! ```
//! // The public suffix ("effective TLD"):
//! assert_eq!(psl2::suffix("www.example.co.uk").as_deref(), Some("co.uk"));
//!
//! // The registrable domain (eTLD + 1) — the cookie domain:
//! assert_eq!(
//!     psl2::registrable_domain("www.example.co.uk").as_deref(),
//!     Some("example.co.uk")
//! );
//!
//! // A bare public suffix has no registrable domain:
//! assert_eq!(psl2::registrable_domain("co.uk"), None);
//! assert!(psl2::is_public_suffix("co.uk"));
//! ```
//!
//! Unicode / internationalized domains are handled transparently (the `idna`
//! feature, enabled by default); inputs and outputs are normalized to
//! ASCII/punycode:
//!
//! ```
//! # #[cfg(feature = "idna")] {
//! assert_eq!(psl2::registrable_domain("食狮.公司.cn").as_deref(), Some("xn--85x722f.xn--55qx5d.cn"));
//! # }
//! ```
//!
//! # How it differs from `psl`
//!
//! * **Fast builds.** The list is pre-normalized to ASCII at *publish* time and
//!   embedded as plain data ([`include_str!`]). There is no `build.rs` and no
//!   procedural-macro codegen, so depending on `psl2` adds almost nothing to
//!   your compile time.
//! * **Built-in IDNA.** Queries are normalized for you; you do not have to
//!   punycode-encode input first.
//! * **Clean `&str` API** with explicit ICANN / private / unknown
//!   classification.
//! * **Always current.** CI republishes the crate whenever the upstream list
//!   changes (see [`psl_version`]).
//!
//! # A note on "surprising" suffixes
//!
//! The list's PRIVATE section contains organizationally-delegated suffixes such
//! as `blogspot.com`, `github.io`, and `s3.amazonaws.com`. These *are* public
//! suffixes, so `registrable_domain("blogspot.com")` is `None` and
//! `registrable_domain("foo.blogspot.com")` is `Some("foo.blogspot.com")`.
//! This matches browser cookie behavior, but can be surprising. Use
//! [`Info::is_private`] / [`Info::is_icann`] if you need to tell the two
//! sections apart:
//!
//! ```
//! let info = psl2::analyze("foo.blogspot.com").unwrap();
//! assert_eq!(info.suffix(), "blogspot.com");
//! assert!(info.is_private()); // delegated, not an ICANN registry suffix
//! ```
//!
//! [`psl`]: https://crates.io/crates/psl
//! [Public Suffix List]: https://publicsuffix.org/

#![forbid(unsafe_code)]
#![warn(missing_docs)]

use std::collections::HashMap;
use std::sync::OnceLock;

/// The embedded, pre-normalized Public Suffix List.
///
/// Generated by `xtask` from `list/public_suffix_list.dat`. Each non-comment
/// line is `<section><kind><space><ascii-rule>`.
static DATA: &str = include_str!("list.txt");

/// Which section of the Public Suffix List a rule comes from.
///
/// The ICANN section covers real registry TLDs; the PRIVATE section covers
/// suffixes delegated by private organizations (e.g. `github.io`,
/// `s3.amazonaws.com`). Browsers honor both for cookie scoping, but some
/// callers only care about the ICANN boundary — this lets you choose.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub enum Type {
    /// A rule from the ICANN section of the list.
    Icann,
    /// A rule from the PRIVATE section of the list.
    Private,
}

struct Db {
    /// Ordinary rules, e.g. `com`, `co.uk` -> section.
    rules: HashMap<&'static str, Type>,
    /// Wildcard rules `*.Y`, keyed by `Y` (e.g. `ck` for `*.ck`) -> section.
    wildcards: HashMap<&'static str, Type>,
    /// Exception rules `!X`, keyed by `X` (e.g. `www.ck`) -> section.
    exceptions: HashMap<&'static str, Type>,
}

fn db() -> &'static Db {
    static DB: OnceLock<Db> = OnceLock::new();
    DB.get_or_init(|| {
        let mut rules = HashMap::new();
        let mut wildcards = HashMap::new();
        let mut exceptions = HashMap::new();

        for line in DATA.lines() {
            let bytes = line.as_bytes();
            if bytes.is_empty() || bytes[0] == b'#' || line.len() < 4 {
                continue;
            }
            let ty = if bytes[0] == b'P' {
                Type::Private
            } else {
                Type::Icann
            };
            let value = &line[3..];
            match bytes[1] {
                b'N' => {
                    rules.insert(value, ty);
                }
                b'W' => {
                    wildcards.insert(value, ty);
                }
                b'E' => {
                    exceptions.insert(value, ty);
                }
                _ => {}
            }
        }

        Db {
            rules,
            wildcards,
            exceptions,
        }
    })
}

/// The result of analyzing a hostname against the Public Suffix List.
///
/// All accessors return substrings of the normalized (lowercased,
/// ASCII/punycode) form of the input, retrievable via [`Info::as_ascii`].
#[derive(Clone, Debug)]
pub struct Info {
    ascii: String,
    /// Byte offset in `ascii` where the public suffix begins.
    suffix_off: usize,
    /// Byte offset in `ascii` where the registrable domain begins, if any.
    domain_off: Option<usize>,
    /// Section of the matched rule, or `None` when no rule matched (the
    /// implicit `*` default rule for unknown TLDs).
    typ: Option<Type>,
}

impl Info {
    /// The fully normalized (lowercased, ASCII/punycode) form of the input.
    #[inline]
    pub fn as_ascii(&self) -> &str {
        &self.ascii
    }

    /// The public suffix ("effective TLD"), e.g. `co.uk` for
    /// `www.example.co.uk`.
    #[inline]
    pub fn suffix(&self) -> &str {
        &self.ascii[self.suffix_off..]
    }

    /// The registrable domain (public suffix plus one more label), e.g.
    /// `example.co.uk`. This is the domain that can set cookies.
    ///
    /// Returns `None` when the input is itself a public suffix and therefore
    /// has no registrable domain (e.g. `co.uk`).
    #[inline]
    pub fn registrable_domain(&self) -> Option<&str> {
        self.domain_off.map(|o| &self.ascii[o..])
    }

    /// The subdomain: the labels to the left of the registrable domain, e.g.
    /// `www` for `www.example.co.uk` and `a.b` for `a.b.example.co.uk`.
    ///
    /// Returns `None` when there is no subdomain — either because the input is
    /// itself a public suffix, or because it is exactly a registrable domain
    /// (e.g. `example.co.uk`).
    #[inline]
    pub fn subdomain(&self) -> Option<&str> {
        match self.domain_off {
            // `d - 1` drops the dot that separates the subdomain from the
            // registrable domain.
            Some(d) if d > 0 => Some(&self.ascii[..d - 1]),
            _ => None,
        }
    }

    /// `true` if the input is itself a public suffix (it has no registrable
    /// domain). Such names cannot own cookies.
    #[inline]
    pub fn is_public_suffix(&self) -> bool {
        self.domain_off.is_none()
    }

    /// The section of the matched rule, or `None` if the suffix was derived
    /// from the implicit default rule (an unknown TLD).
    #[inline]
    pub fn typ(&self) -> Option<Type> {
        self.typ
    }

    /// `true` if the suffix matched a rule in the ICANN section.
    #[inline]
    pub fn is_icann(&self) -> bool {
        self.typ == Some(Type::Icann)
    }

    /// `true` if the suffix matched a rule in the PRIVATE section.
    #[inline]
    pub fn is_private(&self) -> bool {
        self.typ == Some(Type::Private)
    }

    /// `true` if a real rule matched, i.e. the suffix is a known/listed
    /// public suffix rather than the implicit `*` default for unknown TLDs.
    #[inline]
    pub fn is_known(&self) -> bool {
        self.typ.is_some()
    }
}

/// Normalize an input hostname to lowercase ASCII/punycode, or `None` if it is
/// not a usable hostname.
fn normalize(domain: &str) -> Option<String> {
    let d = domain.trim();
    // Accept a single fully-qualified trailing dot.
    let d = d.strip_suffix('.').unwrap_or(d);
    if d.is_empty() {
        return None;
    }
    let ascii = to_ascii(d)?;
    // Reject empty labels (leading dot, trailing dot, or `..`).
    if ascii.is_empty() || ascii.starts_with('.') || ascii.ends_with('.') || ascii.contains("..") {
        return None;
    }
    Some(ascii)
}

#[cfg(feature = "idna")]
#[inline]
fn to_ascii(domain: &str) -> Option<String> {
    idna::domain_to_ascii(domain).ok()
}

#[cfg(not(feature = "idna"))]
#[inline]
fn to_ascii(domain: &str) -> Option<String> {
    // Without the `idna` feature we only accept hostnames that are already
    // ASCII; we still lowercase them so matching is case-insensitive.
    if domain.is_ascii() {
        Some(domain.to_ascii_lowercase())
    } else {
        None
    }
}

/// Analyze a hostname against the Public Suffix List.
///
/// Returns `None` only if the input cannot be normalized into a hostname
/// (empty, malformed, or — without the `idna` feature — non-ASCII).
///
/// ```
/// let info = psl2::analyze("www.example.co.uk").unwrap();
/// assert_eq!(info.suffix(), "co.uk");
/// assert_eq!(info.registrable_domain(), Some("example.co.uk"));
/// assert!(info.is_icann());
/// ```
pub fn analyze(domain: &str) -> Option<Info> {
    let ascii = normalize(domain)?;
    let db = db();

    // Byte offsets of each label start within `ascii`.
    let mut offs = vec![0usize];
    for (i, b) in ascii.bytes().enumerate() {
        if b == b'.' {
            offs.push(i + 1);
        }
    }
    let n = offs.len();

    // Prevailing rule selection per the PSL algorithm:
    //   * an exception rule always wins if one matches;
    //   * otherwise the matching rule with the most labels wins;
    //   * otherwise the implicit `*` rule applies (a single-label suffix).
    // We track the best non-exception match and the best exception match by
    // the number of labels in the rule.
    let mut best: Option<(usize, Type)> = None; // (rule label count, section)
    let mut exception: Option<(usize, Type)> = None;

    for i in 0..n {
        let cand = &ascii[offs[i]..]; // labels i..n  => (n - i) labels
        let rule_labels = n - i;

        if let Some(&ty) = db.exceptions.get(cand) {
            if exception.is_none_or(|(c, _)| rule_labels > c) {
                exception = Some((rule_labels, ty));
            }
        }
        if let Some(&ty) = db.rules.get(cand) {
            if best.is_none_or(|(c, _)| rule_labels > c) {
                best = Some((rule_labels, ty));
            }
        }
        // Wildcard `*.Y`: the `*` consumes label `i`, and `Y` is labels i+1..n.
        if i + 1 < n {
            let y = &ascii[offs[i + 1]..];
            if let Some(&ty) = db.wildcards.get(y) {
                if best.is_none_or(|(c, _)| rule_labels > c) {
                    best = Some((rule_labels, ty));
                }
            }
        }
    }

    // Number of labels in the resulting public suffix.
    let (suffix_labels, typ) = if let Some((c, ty)) = exception {
        // An exception rule's suffix is the rule minus its leftmost label.
        (c - 1, Some(ty))
    } else if let Some((c, ty)) = best {
        (c, Some(ty))
    } else {
        // Implicit `*` default rule: the suffix is the rightmost label.
        (1, None)
    };

    let suffix_idx = n - suffix_labels;
    let suffix_off = offs[suffix_idx];
    let domain_off = if suffix_idx >= 1 {
        Some(offs[suffix_idx - 1])
    } else {
        None
    };

    Some(Info {
        ascii,
        suffix_off,
        domain_off,
        typ,
    })
}

/// The public suffix ("effective TLD") of a hostname, e.g. `co.uk` for
/// `www.example.co.uk`.
///
/// Returns the normalized ASCII/punycode form. `None` only if the input is not
/// a usable hostname.
#[inline]
pub fn suffix(domain: &str) -> Option<String> {
    analyze(domain).map(|i| i.suffix().to_owned())
}

/// The registrable domain (eTLD + 1) of a hostname, e.g. `example.co.uk`.
///
/// This is the domain that can own cookies. Returns `None` if the input is not
/// a usable hostname, or is itself a public suffix.
#[inline]
pub fn registrable_domain(domain: &str) -> Option<String> {
    analyze(domain).and_then(|i| i.registrable_domain().map(str::to_owned))
}

/// `true` if `domain` is itself a public suffix (and so cannot own cookies).
///
/// Returns `false` for inputs that are not usable hostnames.
#[inline]
pub fn is_public_suffix(domain: &str) -> bool {
    analyze(domain).is_some_and(|i| i.is_public_suffix())
}

/// The subdomain (the labels to the left of the registrable domain) of a
/// hostname, e.g. `www` for `www.example.co.uk`.
///
/// Returns `None` if the input is not a usable hostname, is a public suffix, or
/// is exactly a registrable domain with no subdomain.
#[inline]
pub fn subdomain(domain: &str) -> Option<String> {
    analyze(domain).and_then(|i| i.subdomain().map(str::to_owned))
}

/// The upstream Public Suffix List version (a UTC timestamp string) that this
/// build of `psl2` was generated from.
pub fn psl_version() -> &'static str {
    DATA.lines()
        .find_map(|l| l.strip_prefix("# PSL VERSION:"))
        .map(str::trim)
        .unwrap_or("unknown")
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn basic_suffixes() {
        assert_eq!(suffix("example.com").as_deref(), Some("com"));
        assert_eq!(suffix("www.example.co.uk").as_deref(), Some("co.uk"));
        assert_eq!(
            registrable_domain("www.example.co.uk").as_deref(),
            Some("example.co.uk")
        );
    }

    #[test]
    fn bare_suffix_has_no_registrable_domain() {
        assert_eq!(registrable_domain("co.uk"), None);
        assert!(is_public_suffix("co.uk"));
        assert!(is_public_suffix("com"));
        assert!(!is_public_suffix("example.com"));
    }

    #[test]
    fn wildcard_and_exception() {
        // *.ck => foo.ck is a public suffix
        assert!(is_public_suffix("foo.ck"));
        assert_eq!(
            registrable_domain("a.b.test.ck").as_deref(),
            Some("b.test.ck")
        );
        // !www.ck exception => www.ck is registrable
        assert_eq!(registrable_domain("www.ck").as_deref(), Some("www.ck"));
        assert_eq!(suffix("www.ck").as_deref(), Some("ck"));
    }

    #[test]
    fn unknown_tld_uses_default_rule() {
        let info = analyze("foo.nonexistenttld").unwrap();
        assert_eq!(info.suffix(), "nonexistenttld");
        assert_eq!(info.registrable_domain(), Some("foo.nonexistenttld"));
        assert!(!info.is_known());
        assert_eq!(info.typ(), None);
    }

    #[test]
    fn classification() {
        assert!(analyze("example.com").unwrap().is_icann());
    }

    #[test]
    fn subdomains() {
        assert_eq!(subdomain("www.example.co.uk").as_deref(), Some("www"));
        assert_eq!(subdomain("a.b.example.co.uk").as_deref(), Some("a.b"));
        // Exactly a registrable domain: no subdomain.
        assert_eq!(subdomain("example.co.uk"), None);
        // A bare public suffix: no subdomain.
        assert_eq!(subdomain("co.uk"), None);
    }

    #[test]
    fn private_suffixes() {
        let info = analyze("foo.blogspot.com").unwrap();
        assert_eq!(info.suffix(), "blogspot.com");
        assert!(info.is_private());
        assert!(!info.is_icann());
        assert_eq!(registrable_domain("blogspot.com"), None);
    }

    #[test]
    fn malformed_inputs() {
        assert!(analyze("").is_none());
        assert!(analyze(".").is_none());
        assert!(analyze("..").is_none());
        assert!(analyze(".com").is_none());
        assert!(analyze("a..b").is_none());
        // Empty trailing label must not yield a `Some("")` suffix (cf. the
        // upstream `psl` crate's inconsistency on "." / "com..").
        assert!(analyze("com..").is_none());
        assert_ne!(suffix("."), Some(String::new()));
    }

    #[test]
    fn trailing_dot_and_case() {
        assert_eq!(
            registrable_domain("WwW.Example.COM.").as_deref(),
            Some("example.com")
        );
    }

    #[test]
    fn version_is_present() {
        assert!(!psl_version().is_empty());
    }
}