tlds

Documentation

Overview

Package tlds provides utilities for fetching, caching, parsing, and filtering IANA TLD lists.

Index

• func FilterByLength(tlds []string, minLen, maxLen int) []string
• func Limit(tlds []string, n int) []string
• func Parse(raw string) []string
• func ParseCustom(csv string) []string
• func ReadCache(path string, maxAge time.Duration) (content string, fresh bool, err error)
• func RegistrableDomain(domain string) (string, error)
• func Sort(tlds []string, mode string) []string
• func Suffix(domain string) (suffix string, icann bool)
• func Top25() []string
• func WriteCache(path, data string) error

Functions

func FilterByLength

func FilterByLength(tlds []string, minLen, maxLen int) []string

FilterByLength returns the subset of tlds whose character length is within [minLen, maxLen]. A value of 0 for minLen or maxLen means no constraint on that bound.

func Limit

func Limit(tlds []string, n int) []string

Limit returns the first n TLDs from the slice. If n <= 0 or n >= len(tlds), all entries are returned.

func Parse

func Parse(raw string) []string

Parse parses an IANA TLD list in its standard text format. Lines starting with '#' are treated as comments and skipped. Blank lines are skipped. All entries are lowercased.

func ParseCustom

func ParseCustom(csv string) []string

ParseCustom splits a comma-separated list of TLDs, trims whitespace from each entry, lowercases it, and discards empty tokens.

func ReadCache

func ReadCache(path string, maxAge time.Duration) (content string, fresh bool, err error)

ReadCache reads a cache file at path and reports whether it is fresh. maxAge is the maximum acceptable file age; 0 means always stale. If the file does not exist, ("", false, nil) is returned.

func RegistrableDomain

func RegistrableDomain(domain string) (string, error)

RegistrableDomain returns the registrable portion of a domain (eTLD+1). For "foo.co.uk" it returns "foo.co.uk"; for "mail.google.com", "google.com". Returns an error for inputs with no registrable form (empty labels, suffix-only inputs).

func Sort

func Sort(tlds []string, mode string) []string

Sort returns a sorted copy of tlds according to mode:

• "alpha" — alphabetical order
• "length" — ascending character length (stable, preserves original order for ties)
• anything else — original order preserved

func Suffix

func Suffix(domain string) (suffix string, icann bool)

Suffix returns the public suffix of a domain (e.g. "co.uk" for "foo.co.uk") from the Public Suffix List embedded via x/net/publicsuffix.

The icann return is true only when the suffix comes from the ICANN section of the PSL. It is false for unknown TLDs (PSL's default rule treats the last label as the suffix) and for PSL private suffixes like "github.io" (public for cookie scoping, not registrable via a registrar).

Callers that validate user input MUST check icann. Callers that only need the suffix for display or RDAP routing can discard it.

func Top25

func Top25() []string

Top25 returns a copy of the 25 most popular TLDs.

func WriteCache

func WriteCache(path, data string) error

WriteCache writes data to the file at path, creating any missing parent directories as needed.