is-valid-domain
A Go library and CLI tool for validating domain names against the Public Suffix List (PSL).
This package provides domain validation functionality that determines whether a domain is VALID (a registered domain), SUBDOMAIN (a subdomain of a registered domain), or INVALID (not a valid domain).
- Public Suffix List support
- Wildcard + exception rules
- Batch validation
- Offline support (embedded PSL)
- Single binary
- Fast (as i have not tested with all alternatives, i cant say it is the fastest)
Overview
This package provides domain validation functionality that determines whether a domain is:
- VALID - A registered domain
- SUBDOMAIN - A subdomain of a registered domain
- INVALID - Not a valid domain
Quick Install (Linux/macOS)
curl -sSL https://raw.githubusercontent.com/gopios/is-valid-domain/master/installer.sh | bash
Or specify a version:
curl -sSL https://raw.githubusercontent.com/gopios/is-valid-domain/master/installer.sh | bash -s v1.0.5
Manual Download
Download the binary for your platform from GitHub Releases:
# Linux x86_64 wget https://github.com/gopios/is-valid-domain/releases/download/v1.0.5/ivd-v1.0.5-linux-amd64 sudo mv ivd-v1.0.5-linux-amd64 /usr/local/bin/ivd sudo chmod +x /usr/local/bin/ivd # macOS Apple Silicon wget https://github.com/gopios/is-valid-domain/releases/download/v1.0.5/ivd-v1.0.5-darwin-arm64 sudo mv ivd-v1.0.5-darwin-arm64 /usr/local/bin/ivd sudo chmod +x /usr/local/bin/ivd
As a Go package
go get github.com/gopios/is-valid-domain
Types
type ValidationResult int
const (
Invalid ValidationResult = 0
Valid ValidationResult = 1
Subdomain ValidationResult = 2
)Methods
NewWithPSL() *Validator
Creates a new validator instance and automatically loads the embedded Public Suffix List. Recommended for most use cases.
New() *Validator
Creates a new validator instance without loading any PSL data. Use this if you want to load custom PSL data.
LoadFromFile(path string) error
Loads Public Suffix List data from a file.
LoadFromReader(r io.Reader) error
Loads Public Suffix List data from an io.Reader.
Validate(domain string) ValidationResult
Validates a single domain name.
ValidateBatch(domains []string) map[string]ValidationResult
Validates multiple domains and returns a map of results.
SuffixCount() int
Returns the total number of loaded suffixes (exact + wildcard + exception).
Library Usage
package main
import (
"fmt"
ivd "github.com/gopios/is-valid-domain"
)
func main() {
// Create validator with embedded PSL data (recommended)
validator := ivd.NewWithPSL()
// Validate single domain
result := validator.Validate("example.com")
fmt.Printf("example.com: %v\n", result) // Output: example.com: VALID
// Validate multiple domains
domains := []string{"example.com", "sub.example.com", "invalid..com"}
results := validator.ValidateBatch(domains)
for domain, result := range results {
fmt.Printf("%s: %v\n", domain, result)
}
}Advanced Usage (Custom PSL Data)
package main
import (
"fmt"
"strings"
ivd "github.com/gopios/is-valid-domain"
)
func main() {
// Create validator and load custom PSL data
validator := ivd.New()
// Load from string
pslData := "com\norg\n!example.com"
if err := validator.LoadFromReader(strings.NewReader(pslData)); err != nil {
panic(err)
}
// Load from file
// if err := validator.LoadFromFile("custom_psl.dat"); err != nil {
// panic(err)
// }
result := validator.Validate("example.com")
fmt.Printf("example.com: %v\n", result)
}CLI Usage
Single Domain Validation
ivd example.com # Output: 2 ivd invalid..com # Output: 0
Batch Validation
Create a file with domains (one per line):
domains.txt example.com invalid..com test.org
Run batch validation:
ivd -batch domains.txt # Output: # 2 # 0 # 2
Exit Codes
The CLI returns the following numeric values:
0- INVALID1- VALID2- SUBDOMAIN
- Fast validation using hash maps for O(1) lookups
- Efficient batch processing
- Minimal memory footprint
- Embedded PSL data for standalone operation
This library uses the Public Suffix List maintained by Mozilla. The PSL is an inclusive list of domain suffixes that users can rely on for privacy and security purposes.