Skip to main content

Crate psl2

Crate psl2 

Source
Expand description

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:

assert_eq!(psl2::registrable_domain("食狮.公司.cn").as_deref(), Some("xn--85x722f.xn--55qx5d.cn"));

§no_std and no_alloc

The crate is #![no_std]. Its core lookup is allocation-free: pass an already-lowercased ASCII/punycode hostname to lookup and read back borrowed slices via Domain:

let d = psl2::lookup("www.example.co.uk").unwrap();
assert_eq!(d.suffix(), "co.uk");
assert_eq!(d.registrable_domain(), Some("example.co.uk"));
assert_eq!(d.subdomain(), Some("www"));

Cargo features:

With no features the crate compiles on bare-metal targets with no allocator, exposing only lookup, Domain, Type, and psl_version.

§Migrating from the psl crate

The compat module offers a psl-shaped API (compat::domain_str, compat::suffix_str, and &[u8] variants returning byte-slice Domain/Suffix values) for an easier port.

§How it differs from psl

  • Fast builds & fast lookups. The list is pre-normalized to ASCII at publish time and embedded as a flattened reversed-label trie (include_bytes!), walked from the TLD inward with no allocation. There is no build.rs and no procedural-macro codegen.
  • Built-in IDNA and a clean &str API with ICANN / private / unknown classification.
  • no_std + no_alloc core, and always current (CI republishes when 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 Domain::is_private / Domain::is_icann if you need to tell the two sections apart.

Modules§

compat
A thin, psl-crate-compatible API to ease migration.

Structs§

Domain
The result of an allocation-free lookup, borrowing the input hostname.
Info
The result of analyze, owning the normalized hostname.

Enums§

Type
Which section of the Public Suffix List a rule comes from.

Functions§

analyze
Analyze any hostname against the Public Suffix List, normalizing it first.
is_public_suffix
true if domain is itself a public suffix (and so cannot own cookies).
lookup
Look up an already-normalized hostname against the Public Suffix List, without allocating.
psl_version
The upstream Public Suffix List version (a UTC timestamp string) this build of psl2 was generated from.
registrable_domain
The registrable domain (eTLD + 1) of a hostname, e.g. example.co.uk.
subdomain
The subdomain (the labels left of the registrable domain) of a hostname, e.g. www for www.example.co.uk.
suffix
The public suffix of a hostname, e.g. co.uk for www.example.co.uk.