An OCaml library for parsing and querying the Mozilla Public Suffix List (PSL) to determine public suffixes and registrable domains. This library implements the algorithm specified at publicsuffix.org and provides efficient lookups using a pre-compiled trie data structure.

Key Features#

Complete PSL Support: Handles ICANN and private domain sections
Full Rule Coverage: Supports normal rules, wildcard rules (e.g., *.uk), and exception rules (e.g., !parliament.uk)
Efficient Lookups: Pre-compiled trie structure for fast domain matching
Punycode Support: Automatic handling of internationalized domain names via the punycode library
Type Safety: Uses the domain-name library for validated domain representations

Usage#

let psl = Publicsuffix.v ()

(* Determine the registrable domain (public suffix + one label). *)
let () =
  match Publicsuffix.registrable_domain psl "www.example.com" with
  | Ok r -> assert (r = "example.com")
  | Error _ -> failwith "expected registrable"

(* Find the public suffix. *)
let () =
  match Publicsuffix.public_suffix psl "www.example.com" with
  | Ok s -> assert (s = "com")
  | Error _ -> failwith "expected suffix"

(* Check if a domain is itself a public suffix. *)
let () =
  match Publicsuffix.is_public_suffix psl "com" with
  | Ok b -> assert b
  | Error _ -> failwith "expected ok"

For domains with wildcards and exceptions:

(* Wildcard rule: *.uk. *)
let () =
  match Publicsuffix.public_suffix psl "example.uk" with
  | Ok s -> assert (s = "uk")
  | Error _ -> ()

(* Exception rule: !parliament.uk. *)
let () =
  match Publicsuffix.registrable_domain psl "parliament.uk" with
  | Ok r -> assert (r = "parliament.uk")
  | Error _ -> ()

Installation#

Install with opam:

$ opam install publicsuffix

If opam cannot find the package, it may not yet be released in the public opam-repository. Add the overlay repository, then install it:

$ opam repo add samoht https://tangled.org/gazagnaire.org/opam-overlay.git
$ opam update
$ opam install publicsuffix

Updating the Public Suffix List Data#

The data/public_suffix_list.dat file contains the PSL data, which is compiled into the library at build time. To update to the latest version:

$ curl -o data/public_suffix_list.dat https://publicsuffix.org/list/public_suffix_list.dat
$ opam exec -- dune build

Documentation#

API documentation is available via:

opam install publicsuffix
odig doc publicsuffix

Or build locally:

$ opam exec -- dune build @doc

Technical Standards#

This library is built on the following Internet standards:

RFC 1034 - Domain Names: Concepts and Facilities
RFC 1035 - Domain Names: Implementation and Specification
RFC 3492 - Punycode: A Bootstring encoding of Unicode for IDNA
RFC 5890 - IDNA: Definitions and Document Framework
RFC 5891 - IDNA: Protocol

RFC specifications are available in the spec/ directory for reference.

Licence#

ISC

Configure Feed