README
¶
urlegit
URLegit is a library for validating URLs.
Summary
URL validation is complex and very specific to the task at hand. This library's goal is to provide a toolkit for making pre-flight checks against a URL easier.
Usage
package main
import (
"fmt"
"github.com/xmidt-org/urlegit"
)
func main() {
c, err := urlegit.New(
urlegit.OnlyScheme("https"),
urlegit.ForbidSpecialUseDomains(),
)
if err != nil {
panic(err)
}
url := "https://github.com"
fmt.Printf("Is %q allowed? %t\n", url, c.Legit(url))
// Output:
// Is "https://github.com" allowed? true
}
Resources
- https://www.w3.org/Addressing/URL/5_BNF.html
- https://datatracker.ietf.org/doc/html/rfc1738
- https://www.iana.org/assignments/special-use-domain-names/special-use-domain-names.xhtml
- https://www.iana.org/assignments/iana-ipv4-special-registry/iana-ipv4-special-registry.xhtml
- https://www.iana.org/assignments/iana-ipv6-special-registry/iana-ipv6-special-registry.xhtml
Footnotes
This library originally started of in xmidt-org/ancla as webhook URL validation code. Here is a perma link to that code.
Documentation
¶
Overview ¶
Example ¶
package main
import (
"fmt"
"github.com/xmidt-org/urlegit"
)
func main() {
c, err := urlegit.New(
urlegit.OnlyAllowSchemes("https"),
urlegit.ForbidSpecialUseDomains(),
)
if err != nil {
panic(err)
}
url := "https://github.com"
fmt.Printf("Is %q allowed? %t\n", url, c.Legit(url))
}
Output: Is "https://github.com" allowed? true
Index ¶
- Variables
- type Checker
- type HostVador
- type IPVador
- type Option
- func CustomHostVador(h HostVador) Option
- func CustomIPVador(i IPVador) Option
- func CustomSchemeVador(s SchemeVador) Option
- func Error(err error) Option
- func ForbidAnyIPs() Option
- func ForbidDomainNames(domains ...string) Option
- func ForbidLoopback() Option
- func ForbidSpecialUseDomains() Option
- func ForbidSubnet(subnet string, resolver ...Resolver) Option
- func ForbidSubnets(subnets []string, resolver ...Resolver) Option
- func OnlyAllowSchemes(s ...string) Option
- func WithResolver(r Resolver) Option
- type Resolver
- type SchemeVador
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ( ErrSchemeNotAllowed = fmt.Errorf("scheme not allowed") ErrHostnameEmpty = fmt.Errorf("hostname is empty") ErrLoopback = fmt.Errorf("loopback address") ErrDomainNotAllowed = fmt.Errorf("domain not allowed") ErrRootDomainNotAllowed = fmt.Errorf("root domain not allowed") ErrInvalidInput = fmt.Errorf("invalid input") ErrSubnetNotAllowed = fmt.Errorf("subnet not allowed") ErrIPNotAllowed = fmt.Errorf("IPs not allowed") )
Functions ¶
This section is empty.
Types ¶
type Checker ¶
type Checker struct {
// contains filtered or unexported fields
}
Checker is a URL validator.
func Must ¶
Must returns a new Checker with the provided options applied. If an error occurs, it panics.
func (*Checker) Legit ¶
Legit returns true if the provided string is a valid URL based on the provided options.
func (*Checker) Text ¶
Text returns an error if the provided string is not a valid URL based on the provided options.
type Option ¶
Option is an option for a Checker.
func CustomHostVador ¶ added in v0.1.0
CustomHostVador returns an Option that will use the given HostVador to validate hosts.
func CustomIPVador ¶ added in v0.1.0
CustomIPVador returns an Option that will use the given IPVador to validate IPs.
func CustomSchemeVador ¶ added in v0.1.0
func CustomSchemeVador(s SchemeVador) Option
CustomSchemeVador returns an Option that will use the given SchemeVador to validate schemes.
func ForbidAnyIPs ¶ added in v0.1.0
func ForbidAnyIPs() Option
ForbidAnyIPs returns an Option that disallows any IP addresses using only rules that do not result in a network call. Note that this does not apply to hostnames that are resolved to an IP address when a resolver is provided.
func ForbidDomainNames ¶
ForbidDomainNames returns an Option that disallows the provided domain names. This is a case-insensitive match, and where the domain name is mached against the hostname starting from the end. The character '*' matches everything in the single subdomain it is used.
Example: hostname "www.example.com." will match any of the following domains:
- "*."
- "*.*."
- "*.*.*."
- "com."
- "*.com."
- "example.*."
- "example.com."
- "www.example.com."
- "*.example.com."
- etc...
But will not match:
- "foo.www.example.com."
- "*.www.example.com."
- etc...
func ForbidLoopback ¶
func ForbidLoopback() Option
ForbidLoopback returns an Option that disallows loopback addresses using only rules that do not result in a network call.
func ForbidSpecialUseDomains ¶
func ForbidSpecialUseDomains() Option
ForbidSpecialUseDomains returns an Option that disallows the use of special use domains. See https://www.iana.org/assignments/special-use-domain-names/special-use-domain-names.xhtml
func ForbidSubnet ¶
ForbidSubnet returns an Option that disallows the provided subnet addresses using only rules that do not result in a network call, unless a resolver is provided. If a resolver is provided, it will be used to resolve the hostname and check the returned IP addresses for loopback addresses. If the subnet is invalid then the Option will return an error.
func ForbidSubnets ¶
func OnlyAllowSchemes ¶ added in v0.1.0
OnlyAllowSchemes returns an Option that allows any of the provided schemes. Multiple Schemes() options are allowed, but they are applied seprately.
Scheme validation is case-insensitive.
func WithResolver ¶ added in v0.1.0
WithResolver returns an Option that will use the given Resolver to resolve hostnames into IP addresses.
type Resolver ¶
Resolver is a function that returns a list of IP addresses for a given host.
To use the default go resolver, use the net.LookupIP function.
type SchemeVador ¶ added in v0.1.0
SchemeVador is a function that validates a scheme.
Source Files