publicsuffix

Documentation

Overview

Package publicsuffix provides a domain name parser based on data from the public suffix list http://publicsuffix.org/. A public suffix is one under which Internet users can directly register names.

Index

• Constants
• Variables
• func Domain(name string) (string, error)
• func DomainFromListWithOptions(l *List, name string, options *FindOptions) (string, error)
• func Labels(name string) []string
• func ToASCII(s string) (string, error)
• func ToUnicode(s string) (string, error)
• type DomainName
  • func Parse(name string) (*DomainName, error)
  • func ParseFromListWithOptions(l *List, name string, options *FindOptions) (*DomainName, error)
  • func (d *DomainName) String() string
• type FindOptions
• type List
  • func NewList() *List
  • func NewListFromFile(path string, options *ParserOption) (*List, error)
  • func NewListFromString(src string, options *ParserOption) (*List, error)
  • func (l *List) AddRule(r *Rule) error
  • func (l *List) Find(name string, options *FindOptions) *Rule
  • func (l *List) Load(r io.Reader, options *ParserOption) ([]Rule, error)
  • func (l *List) LoadFile(path string, options *ParserOption) ([]Rule, error)
  • func (l *List) LoadString(src string, options *ParserOption) ([]Rule, error)
  • func (l *List) Size() int
• type ParserOption
• type Rule
  • func DefaultRules() [9669]Rule
  • func MustNewRule(content string) *Rule
  • func NewRule(content string) (*Rule, error)
  • func NewRuleUnicode(content string) (*Rule, error)
  • func (r *Rule) Decompose(name string) (result [2]string)
  • func (r *Rule) Match(name string) bool

Constants

const (
	// Version identifies the current library version.
	// This is a pro forma convention given that Go dependencies
	// tends to be fetched directly from the repo.
	Version = "0.30.2"

	// NormalType represents a normal rule such as "com"
	NormalType = 1
	// WildcardType represents a wildcard rule such as "*.com"
	WildcardType = 2
	// ExceptionType represents an exception to a wildard rule
	ExceptionType = 3
)

const ListVersion = "PSL version d8a01c (Fri Mar  1 18:17:09 2024)"

Variables

var CookieJarList cookiejar.PublicSuffixList = cookiejarList{DefaultList}

CookieJarList implements the cookiejar.PublicSuffixList interface.

var DefaultFindOptions = &FindOptions{IgnorePrivate: false, DefaultRule: DefaultRule}

DefaultFindOptions are the default options used to perform the lookup of rules in the list.

var DefaultList = NewList()

DefaultList is the default List and it is used by Parse and Domain.

var DefaultParserOptions = &ParserOption{PrivateDomains: true, ASCIIEncoded: false}

DefaultParserOptions are the default options used to parse a Public Suffix list.

var DefaultRule = MustNewRule("*")

DefaultRule is the default Rule that represents "*".

Functions

func Domain

func Domain(name string) (string, error)

Domain extract and return the domain name from the input using the default (Public Suffix) List.

Examples:

publicsuffix.Domain("example.com")
// example.com
publicsuffix.Domain("www.example.com")
// example.com
publicsuffix.Domain("www.example.co.uk")
// example.co.uk

func DomainFromListWithOptions

func DomainFromListWithOptions(l *List, name string, options *FindOptions) (string, error)

DomainFromListWithOptions extract and return the domain name from the input using the (Public Suffix) list passed as argument.

Examples:

list := NewList()

publicsuffix.DomainFromListWithOptions(list, "example.com")
// example.com
publicsuffix.DomainFromListWithOptions(list, "www.example.com")
// example.com
publicsuffix.DomainFromListWithOptions(list, "www.example.co.uk")
// example.co.uk

func Labels

func Labels(name string) []string

Labels decomposes given domain name into labels, corresponding to the dot-separated tokens.

func ToASCII

func ToASCII(s string) (string, error)

ToASCII is a wrapper for idna.ToASCII.

This wrapper exists because idna.ToASCII backward-compatibility was broken twice in few months and I can't call this package directly anymore. The wrapper performs some terrible-but-necessary before-after replacements to make sure an already ASCII input always results in the same output even if passed through ToASCII.

See golang/net@67957fd0b1, golang/net@f2499483f9, golang/net@78ebe5c8b6, and weppos/publicsuffix-go#66.

func ToUnicode

func ToUnicode(s string) (string, error)

ToUnicode is a wrapper for idna.ToUnicode.

See ToASCII for more details about why this wrapper exists.

Types

type DomainName

type DomainName struct {
	TLD  string
	SLD  string
	TRD  string
	Rule *Rule
}

DomainName represents a domain name.

func Parse

func Parse(name string) (*DomainName, error)

Parse decomposes the name into TLD, SLD, TRD using the default (Public Suffix) List, and returns the result as a DomainName

Examples:

list := NewList()

publicsuffix.Parse("example.com")
// &DomainName{"com", "example"}
publicsuffix.Parse("www.example.com")
// &DomainName{"com", "example", "www"}
publicsuffix.Parse("www.example.co.uk")
// &DomainName{"co.uk", "example"}

func ParseFromListWithOptions

func ParseFromListWithOptions(l *List, name string, options *FindOptions) (*DomainName, error)

ParseFromListWithOptions decomposes the name into TLD, SLD, TRD using the (Public Suffix) list passed as argument, and returns the result as a DomainName

Examples:

list := NewList()

publicsuffix.ParseFromListWithOptions(list, "example.com")
// &DomainName{"com", "example"}
publicsuffix.ParseFromListWithOptions(list, "www.example.com")
// &DomainName{"com", "example", "www"}
publicsuffix.ParseFromListWithOptions(list, "www.example.co.uk")
// &DomainName{"co.uk", "example"}

func (*DomainName) String

func (d *DomainName) String() string

String joins the components of the domain name into a single string. Empty labels are skipped.

Examples:

DomainName{"com", "example"}.String()
// example.com
DomainName{"com", "example", "www"}.String()
// www.example.com

type FindOptions

type FindOptions struct {
	// Set to true to ignore the rules within the "Private" section of the Public Suffix List.
	IgnorePrivate bool

	// The default rule to use when no rule matches the input.
	// The format Public Suffix algorithm states that the rule "*" should be used when no other rule matches,
	// but some consumers may have different needs.
	DefaultRule *Rule
}

FindOptions are the options you can use to customize the way a Rule is searched within the list.

type List

type List struct {
	// contains filtered or unexported fields
}

List represents a Public Suffix List.

func NewList

func NewList() *List

NewList creates a new empty list.

func NewListFromFile

func NewListFromFile(path string, options *ParserOption) (*List, error)

NewListFromFile parses a string that represents a Public Suffix source and returns a List initialized with the rules in the source.

func NewListFromString

func NewListFromString(src string, options *ParserOption) (*List, error)

NewListFromString parses a string that represents a Public Suffix source and returns a List initialized with the rules in the source.

func (*List) AddRule

func (l *List) AddRule(r *Rule) error

AddRule adds a new rule to the list.

The exact position of the rule into the list is unpredictable. The list may be optimized internally for lookups, therefore the algorithm will decide the best position for the new rule.

func (*List) Find

func (l *List) Find(name string, options *FindOptions) *Rule

Find and returns the most appropriate rule for the domain name.

func (*List) Load

func (l *List) Load(r io.Reader, options *ParserOption) ([]Rule, error)

Load parses and loads a set of rules from an io.Reader into the current list.

func (*List) LoadFile

func (l *List) LoadFile(path string, options *ParserOption) ([]Rule, error)

LoadFile parses and loads a set of rules from a File into the current list.

func (*List) LoadString

func (l *List) LoadString(src string, options *ParserOption) ([]Rule, error)

LoadString parses and loads a set of rules from a String into the current list.

func (*List) Size

func (l *List) Size() int

Size returns the size of the list, which is the number of rules.

type ParserOption

type ParserOption struct {
	// Set to false to skip the private domains when parsing.
	// Default to true, which means the private domains are included.
	PrivateDomains bool

	// Set to false if the input is encoded in U-labels (Unicode)
	// as opposite to A-labels.
	// Default to false, which means the list is containing Unicode domains.
	// This is the default because the original PSL currently contains Unicode.
	ASCIIEncoded bool
}

ParserOption are the options you can use to customize the way a List is parsed from a file or a string.

type Rule

type Rule struct {
	Type    int
	Value   string
	Length  int
	Private bool
}

Rule represents a single rule in a Public Suffix List.

func DefaultRules

func DefaultRules() [9669]Rule

func MustNewRule

func MustNewRule(content string) *Rule

MustNewRule is like NewRule, but panics if the content cannot be parsed.

func NewRule

func NewRule(content string) (*Rule, error)

NewRule parses the rule content, creates and returns a Rule.

The content of the rule MUST be encoded in ASCII (A-labels).

func NewRuleUnicode

func NewRuleUnicode(content string) (*Rule, error)

NewRuleUnicode is like NewRule, but expects the content to be encoded in Unicode (U-labels).

func (*Rule) Decompose

func (r *Rule) Decompose(name string) (result [2]string)

Decompose takes a name as input and decomposes it into a tuple of <TRD+SLD, TLD>, according to the rule definition and type.

func (*Rule) Match

func (r *Rule) Match(name string) bool

Match checks if the rule matches the name.

A domain name is said to match a rule if and only if all of the following conditions are met:

• When the domain and rule are split into corresponding labels, that the domain contains as many or more labels than the rule.
• Beginning with the right-most labels of both the domain and the rule, and continuing for all labels in the rule, one finds that for every pair, either they are identical, or that the label from the rule is "*".

See https://publicsuffix.org/list/