publicsuffix

Documentation

Overview

Package publicsuffix provides a public suffix list based on data from https://publicsuffix.org/

A public suffix is one under which Internet users can directly register names. It is related to, but different from, a TLD (top level domain).

"com" is a TLD (top level domain). Top level means it has no dots.

"com" is also a public suffix. Amazon and Google have registered different siblings under that domain: "amazon.com" and "google.com".

"au" is another TLD, again because it has no dots. But it's not "amazon.au". Instead, it's "amazon.com.au".

"com.au" isn't an actual TLD, because it's not at the top level (it has dots). But it is an eTLD (effective TLD), because that's the branching point for domain name registrars.

Another name for "an eTLD" is "a public suffix". Often, what's more of interest is the eTLD+1, or one more label than the public suffix. For example, browsers partition read/write access to HTTP cookies according to the eTLD+1. Web pages served from "amazon.com.au" can't read cookies from "google.com.au", but web pages served from "maps.google.com" can share cookies from "www.google.com", so you don't have to sign into Google Maps separately from signing into Google Web Search. Note that all four of those domains have 3 labels and 2 dots. The first two domains are each an eTLD+1, the last two are not (but share the same eTLD+1: "google.com").

All of these domains have the same eTLD+1:

• "www.books.amazon.co.uk"
• "books.amazon.co.uk"
• "amazon.co.uk"

Specifically, the eTLD+1 is "amazon.co.uk", because the eTLD is "co.uk".

There is no closed form algorithm to calculate the eTLD of a domain. Instead, the calculation is data driven. This package provides a pre-compiled snapshot of Mozilla's PSL (Public Suffix List) data at https://publicsuffix.org/

Index

• Variables
• func EffectiveTLDPlusOne(domain string) (string, error)
• func PublicSuffix(domain string) (publicSuffix string, icann bool)

Examples

• PublicSuffix (Manager)

Variables

var List cookiejar.PublicSuffixList = list{}

List implements the cookiejar.PublicSuffixList interface by calling the PublicSuffix function.

Functions

func EffectiveTLDPlusOne

func EffectiveTLDPlusOne(domain string) (string, error)

EffectiveTLDPlusOne returns the effective top level domain plus one more label. For example, the eTLD+1 for "foo.bar.golang.org" is "golang.org".

func PublicSuffix

func PublicSuffix(domain string) (publicSuffix string, icann bool)

PublicSuffix returns the public suffix of the domain using a copy of the publicsuffix.org database compiled into the library.

icann is whether the public suffix is managed by the Internet Corporation for Assigned Names and Numbers. If not, the public suffix is either a privately managed domain (and in practice, not a top level domain) or an unmanaged top level domain (and not explicitly mentioned in the publicsuffix.org list). For example, "foo.org" and "foo.co.uk" are ICANN domains, "foo.dyndns.org" and "foo.blogspot.co.uk" are private domains and "cromulent" is an unmanaged top level domain.

Use cases for distinguishing ICANN domains like "foo.com" from private domains like "foo.appspot.com" can be found at https://wiki.mozilla.org/Public_Suffix_List/Use_Cases

Example (Manager)

This example demonstrates looking up several domains' eTLDs (effective Top Level Domains) in the PSL (Public Suffix List) snapshot. For each eTLD, the example also determines whether the eTLD is ICANN managed, privately managed, or unmanaged (not explicitly in the PSL).

See https://publicsuffix.org/ for the underlying PSL data.

package main

import (
	"fmt"
	"strings"

	"golang.org/x/net/publicsuffix"
)

func main() {
	domains := []string{
		"amazon.co.uk",
		"books.amazon.co.uk",
		"www.books.amazon.co.uk",
		"amazon.com",
		"",
		"example0.debian.net",
		"example1.debian.org",
		"",
		"golang.dev",
		"golang.net",
		"play.golang.org",
		"gophers.in.space.museum",
		"",
		"0emm.com",
		"a.0emm.com",
		"b.c.d.0emm.com",
		"",
		"there.is.no.such-tld",
		"",
		// Examples from the PublicSuffix function's documentation.
		"foo.org",
		"foo.co.uk",
		"foo.dyndns.org",
		"foo.blogspot.co.uk",
		"cromulent",
	}

	for _, domain := range domains {
		if domain == "" {
			fmt.Println(">")
			continue
		}
		eTLD, icann := publicsuffix.PublicSuffix(domain)

		// Only ICANN managed domains can have a single label. Privately
		// managed domains must have multiple labels.
		manager := "Unmanaged"
		if icann {
			manager = "ICANN Managed"
		} else if strings.IndexByte(eTLD, '.') >= 0 {
			manager = "Privately Managed"
		}

		fmt.Printf("> %24s%16s  is  %s\n", domain, eTLD, manager)
	}

}

Output:

>             amazon.co.uk           co.uk  is  ICANN Managed
>       books.amazon.co.uk           co.uk  is  ICANN Managed
>   www.books.amazon.co.uk           co.uk  is  ICANN Managed
>               amazon.com             com  is  ICANN Managed
>
>      example0.debian.net      debian.net  is  Privately Managed
>      example1.debian.org             org  is  ICANN Managed
>
>               golang.dev             dev  is  ICANN Managed
>               golang.net             net  is  ICANN Managed
>          play.golang.org             org  is  ICANN Managed
>  gophers.in.space.museum    space.museum  is  ICANN Managed
>
>                 0emm.com             com  is  ICANN Managed
>               a.0emm.com      a.0emm.com  is  Privately Managed
>           b.c.d.0emm.com      d.0emm.com  is  Privately Managed
>
>     there.is.no.such-tld        such-tld  is  Unmanaged
>
>                  foo.org             org  is  ICANN Managed
>                foo.co.uk           co.uk  is  ICANN Managed
>           foo.dyndns.org      dyndns.org  is  Privately Managed
>       foo.blogspot.co.uk  blogspot.co.uk  is  Privately Managed
>                cromulent       cromulent  is  Unmanaged