netutil

package
v0.11.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 26, 2022 License: Unlicense Imports: 12 Imported by: 38

Documentation

Overview

Package netutil contains common utilities for IP, MAC, and other kinds of network addresses.

Index

Examples

Constants

View Source 
const (
	// ErrAddrIsEmpty is the underlying error returned from validation
	// functions when an address is empty.
	ErrAddrIsEmpty errors.Error = "address is empty"

	// ErrLabelIsEmpty is the underlying error returned from validation
	// functions when a domain name label is empty.
	ErrLabelIsEmpty errors.Error = "label is empty"

	// ErrNotAReversedIP is the underlying error returned from validation
	// functions when a domain name is not a full reversed IP address.
	ErrNotAReversedIP errors.Error = "not a full reversed ip address"

	// ErrNotAReversedSubnet is the underlying error returned from validation
	// functions when a domain name is not a valid reversed IP network.
	ErrNotAReversedSubnet errors.Error = "not a reversed ip network"
)
View Source 
const (
	IPv4BitLen = net.IPv4len * 8
	IPv6BitLen = net.IPv6len * 8
)

Bit lengths of IP addresses.

View Source 
const MaxDomainLabelLen = 63

MaxDomainLabelLen is the maximum allowed length of a domain name label according to RFC 1035.

View Source 
const MaxDomainNameLen = 253

MaxDomainNameLen is the maximum allowed length of a full domain name according to RFC 1035.

See also: https://stackoverflow.com/a/32294443/1892060.

View Source 
const MaxServiceLabelLen = 16

MaxServiceLabelLen is the maximum allowed length of a service name label according to RFC 6335.

Variables

This section is empty.

Functions

func CloneIP deprecated 

func CloneIP(ip net.IP) (clone net.IP)

CloneIP returns a clone of an IP address that doesn't share the same underlying array with it.

Deprecated: use slices.Clone.

func CloneIPNet added in v0.10.6 

func CloneIPNet(n *net.IPNet) (clone *net.IPNet)

CloneIPNet returns a deep clone of n.

func CloneIPs 

func CloneIPs(ips []net.IP) (clone []net.IP)

CloneIPs returns a deep clone of ips.

func CloneMAC deprecated 

func CloneMAC(mac net.HardwareAddr) (clone net.HardwareAddr)

CloneMAC returns a clone of a MAC address.

Deprecated: use slices.Clone.

func CloneURL 

func CloneURL(u *url.URL) (clone *url.URL)

CloneURL returns a deep clone of u. The User pointer of clone is the same, since a *url.Userinfo is effectively an immutable value.

func IPAndPortFromAddr 

func IPAndPortFromAddr(addr net.Addr) (ip net.IP, port int)

IPAndPortFromAddr returns the IP address and the port from addr. If addr is neither a *net.TCPAddr nor a *net.UDPAddr, it returns nil and 0.

func IPFromReversedAddr 

func IPFromReversedAddr(arpa string) (ip net.IP, err error)

IPFromReversedAddr tries to convert a full reversed ARPA address to a normal IP address. arpa can be domain name or an FQDN.

Any error returned will have the underlying type of *AddrError.

Example 
package main

import (
	"fmt"

	"github.com/AdguardTeam/golibs/netutil"
)

func main() {
	ip, err := netutil.IPFromReversedAddr("4.3.2.1.in-addr.arpa")
	if err != nil {
		panic(err)
	}

	fmt.Println(ip)

	a := `4.3.2.1.d.c.b.a.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa`
	ip, err = netutil.IPFromReversedAddr(a)
	if err != nil {
		panic(err)
	}

	fmt.Println(ip)

}

Output:


1.2.3.4
::abcd:1234

func IPNetToPrefix added in v0.11.0 

func IPNetToPrefix(subnet *net.IPNet, fam AddrFamily) (p netip.Prefix, err error)

IPNetToPrefix is a helper that converts a *net.IPNet into a netip.Prefix. subnet should not be nil. fam must be either AddrFamilyIPv4 or AddrFamilyIPv6.

See also IPNetToPrefixNoMapped.

Example 
package main

import (
	"fmt"
	"net"

	"github.com/AdguardTeam/golibs/netutil"
)

func main() {
	_, n, _ := net.ParseCIDR("1.2.3.0/24")
	pref, err := netutil.IPNetToPrefix(n, netutil.AddrFamilyIPv4)
	fmt.Printf("%q, error: %v\n", pref, err)

	pref, err = netutil.IPNetToPrefix(n, netutil.AddrFamilyIPv6)
	fmt.Printf("%q, error: %v\n", pref, err)

	_, n, _ = net.ParseCIDR("1234::/72")
	pref, err = netutil.IPNetToPrefix(n, netutil.AddrFamilyIPv4)
	fmt.Printf("%q, error: %v\n", pref, err)

	pref, err = netutil.IPNetToPrefix(n, netutil.AddrFamilyIPv6)
	fmt.Printf("%q, error: %v\n", pref, err)

}

Output:

"1.2.3.0/24", error: <nil>
"::ffff:1.2.3.0/24", error: <nil>
"invalid Prefix", error: bad ip for subnet 1234::/72: bad ipv4 net.IP 1234::
"1234::/72", error: <nil>

func IPNetToPrefixNoMapped added in v0.11.0 

func IPNetToPrefixNoMapped(subnet *net.IPNet) (p netip.Prefix, err error)

IPNetToPrefixNoMapped is like IPNetToPrefix but it detects the address family automatically by assuming that every IPv6-mapped IPv4 address is actually an IPv4 address. Do not use IPNetToPrefixNoMapped where this assumption isn't safe.

Example 
package main

import (
	"fmt"
	"net"

	"github.com/AdguardTeam/golibs/netutil"
)

func main() {
	_, n, _ := net.ParseCIDR("1.2.3.0/24")
	pref, err := netutil.IPNetToPrefixNoMapped(n)
	fmt.Printf("%q, error: %v\n", pref, err)

	n = &net.IPNet{
		IP:   net.IP{1, 2, 3, 0},
		Mask: net.CIDRMask(24, 32),
	}
	pref, err = netutil.IPNetToPrefixNoMapped(n)
	fmt.Printf("%q, error: %v\n", pref, err)

	_, n, _ = net.ParseCIDR("1234::/72")
	pref, err = netutil.IPNetToPrefixNoMapped(n)
	fmt.Printf("%q, error: %v\n", pref, err)

}

Output:

"1.2.3.0/24", error: <nil>
"1.2.3.0/24", error: <nil>
"1234::/72", error: <nil>

func IPToAddr added in v0.11.0 

func IPToAddr(ip net.IP, fam AddrFamily) (addr netip.Addr, err error)

IPToAddr converts a net.IP into a netip.Addr of the given family and returns a meaningful error. ip should not be nil. fam must be either AddrFamilyIPv4 or AddrFamilyIPv6.

See also IPToAddrNoMapped.

Example 
package main

import (
	"fmt"
	"net"

	"github.com/AdguardTeam/golibs/netutil"
)

func main() {
	ip := net.ParseIP("1.2.3.4")
	addr, err := netutil.IPToAddr(ip, netutil.AddrFamilyIPv4)
	fmt.Printf("%q, error: %v\n", addr, err)

	addr, err = netutil.IPToAddr(ip, netutil.AddrFamilyIPv6)
	fmt.Printf("%q, error: %v\n", addr, err)

	ip = net.ParseIP("1234::5678")
	addr, err = netutil.IPToAddr(ip, netutil.AddrFamilyIPv4)
	fmt.Printf("%q, error: %v\n", addr, err)

	addr, err = netutil.IPToAddr(ip, netutil.AddrFamilyIPv6)
	fmt.Printf("%q, error: %v\n", addr, err)

}

Output:

"1.2.3.4", error: <nil>
"::ffff:1.2.3.4", error: <nil>
"invalid IP", error: bad ipv4 net.IP 1234::5678
"1234::5678", error: <nil>

func IPToAddrNoMapped added in v0.11.0 

func IPToAddrNoMapped(ip net.IP) (addr netip.Addr, err error)

IPToAddrNoMapped is like IPToAddr but it detects the address family automatically by assuming that every IPv6-mapped IPv4 address is actually an IPv4 address. Do not use IPToAddrNoMapped where this assumption isn't safe.

Example 
package main

import (
	"fmt"
	"net"

	"github.com/AdguardTeam/golibs/netutil"
)

func main() {
	ip := net.ParseIP("1.2.3.4")
	addr, err := netutil.IPToAddrNoMapped(ip)
	fmt.Printf("%q, error: %v\n", addr, err)

	ip = net.IP{1, 2, 3, 4}
	addr, err = netutil.IPToAddrNoMapped(ip)
	fmt.Printf("%q, error: %v\n", addr, err)

	ip = net.ParseIP("1234::5678")
	addr, err = netutil.IPToAddrNoMapped(ip)
	fmt.Printf("%q, error: %v\n", addr, err)

}

Output:

"1.2.3.4", error: <nil>
"1.2.3.4", error: <nil>
"1234::5678", error: <nil>

func IPToReversedAddr 

func IPToReversedAddr(ip net.IP) (arpa string, err error)

IPToReversedAddr returns the reversed ARPA address of ip suitable for reverse DNS (PTR) record lookups. This is a modified version of function ReverseAddr from package github.com/miekg/dns package that accepts an IP.

Any error returned will have the underlying type of *AddrError.

Example 
package main

import (
	"fmt"
	"net"

	"github.com/AdguardTeam/golibs/netutil"
)

func main() {
	arpa, err := netutil.IPToReversedAddr(net.IP{1, 2, 3, 4})
	if err != nil {
		panic(err)
	}

	fmt.Println(arpa)

	ip := net.ParseIP("::abcd:1234")
	arpa, err = netutil.IPToReversedAddr(ip)
	if err != nil {
		panic(err)
	}

	fmt.Println(arpa)

}

Output:


4.3.2.1.in-addr.arpa
4.3.2.1.d.c.b.a.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa

func IPv4Localhost added in v0.11.0 

func IPv4Localhost() (ip netip.Addr)

IPv4Localhost returns the IPv4 localhost address "127.0.0.1".

Example 
package main

import (
	"fmt"

	"github.com/AdguardTeam/golibs/netutil"
)

func main() {
	fmt.Println(netutil.IPv4Localhost())

}

Output:

127.0.0.1

func IPv4Zero added in v0.9.2 

func IPv4Zero() (ip net.IP)

IPv4Zero returns a new unspecified (aka empty or null) IPv4 address, 0.0.0.0. It has the same name as the variable in package net, but the result always has four bytes.

Example 
package main

import (
	"fmt"

	"github.com/AdguardTeam/golibs/netutil"
)

func main() {
	fmt.Println(netutil.IPv4Zero())

}

Output:


0.0.0.0

func IPv4allrouter added in v0.9.3 

func IPv4allrouter() (ip net.IP)

IPv4allrouter returns a new all routers IPv4 address, 224.0.0.2. It has the same name as the variable in package net, but the result always has four bytes.

func IPv4allsys added in v0.9.3 

func IPv4allsys() (ip net.IP)

IPv4allsys returns a new all systems (aka all hosts) IPv4 address, 224.0.0.1. It has the same name as the variable in package net, but the result always has four bytes.

func IPv4bcast added in v0.9.3 

func IPv4bcast() (ip net.IP)

IPv4bcast returns a new limited broadcast IPv4 address, 255.255.255.255. It has the same name as the variable in package net, but the result always has four bytes.

func IPv6Localhost added in v0.11.0 

func IPv6Localhost() (ip netip.Addr)

IPv6Localhost returns the IPv6 localhost address "::1".

Example 
package main

import (
	"fmt"

	"github.com/AdguardTeam/golibs/netutil"
)

func main() {
	fmt.Println(netutil.IPv6Localhost())

}

Output:

::1

func IPv6Zero added in v0.9.2 

func IPv6Zero() (ip net.IP)

IPv6Zero returns a new unspecified (aka empty or null) IPv6 address, [::]. It has the same name as the variable in package net.

Example 
package main

import (
	"fmt"

	"github.com/AdguardTeam/golibs/netutil"
)

func main() {
	fmt.Println(netutil.IPv6Zero())

}

Output:


::

func IsLocallyServed added in v0.10.8 

func IsLocallyServed(ip net.IP) (ok bool)

IsLocallyServed checks if ip belongs to any network defined by RFC 6303: 

10.0.0.0/8
127.0.0.0/8
169.254.0.0/16
172.16.0.0/12
192.0.2.0/24
192.168.0.0/16
198.51.100.0/24
203.0.113.0/24
255.255.255.255/32

::/128
::1/128
2001:db8::/32
fd00::/8
fe80::/10

It may also be used as a SubnetSetFunc.

func IsSpecialPurpose added in v0.10.8 

func IsSpecialPurpose(ip net.IP) (ok bool)

IsSpecialPurpose checks if ip belongs to any network defined by IANA Special-Purpose Address Registry: 

0.0.0.0/8          "This host on this network".
10.0.0.0/8         Private-Use.
100.64.0.0/10      Shared Address Space.
127.0.0.0/8        Loopback.
169.254.0.0/16     Link Local.
172.16.0.0/12      Private-Use.
192.0.0.0/24       IETF Protocol Assignments.
192.0.0.0/29       DS-Lite.
192.0.2.0/24       Documentation (TEST-NET-1)
192.88.99.0/24     6to4 Relay Anycast.
192.168.0.0/16     Private-Use.
198.18.0.0/15      Benchmarking.
198.51.100.0/24    Documentation (TEST-NET-2).
203.0.113.0/24     Documentation (TEST-NET-3).
240.0.0.0/4        Reserved.
255.255.255.255/32 Limited Broadcast.

::/128            Unspecified Address.
::1/128           Loopback Address.
64:ff9b::/96      IPv4-IPv6 Translation Address.
64:ff9b:1::/48    IPv4-IPv6 Translation Address.
100::/64          Discard-Only Address Block.
2001::/23         IETF Protocol Assignments.
2001::/32         TEREDO.
2001:1::1/128     Port Control Protocol Anycast.
2001:1::2/128     Traversal Using Relays around NAT Anycast.
2001:2::/48       Benchmarking.
2001:3::/32       AMT.
2001:4:112::/48   AS112-v6.
2001:10::/28      ORCHID.
2001:20::/28      ORCHIDv2.
2001:db8::/32     Documentation.
2002::/16         6to4.
2620:4f:8000::/48 Direct Delegation AS112 Service.
fc00::/7          Unique-Local.
fe80::/10         Linked-Scoped Unicast.

See https://www.iana.org/assignments/iana-ipv4-special-registry and https://www.iana.org/assignments/iana-ipv6-special-registry.

It may also be used as a SubnetSetFunc.

func IsValidHostInnerRune 

func IsValidHostInnerRune(r rune) (ok bool)

IsValidHostInnerRune returns true if r is a valid inner—that is, neither initial nor final—rune for a hostname label.

func IsValidHostOuterRune 

func IsValidHostOuterRune(r rune) (ok bool)

IsValidHostOuterRune returns true if r is a valid initial or final rune for a hostname label.

func JoinHostPort 

func JoinHostPort(host string, port int) (hostport string)

JoinHostPort is a convenient wrapper for net.JoinHostPort with port of type int. As opposed to net.JoinHostPort it also trims the host from square brackets if any. This may be useful when passing url.URL.Host field containing an IPv6 address.

Example 
package main

import (
	"fmt"

	"github.com/AdguardTeam/golibs/netutil"
)

func main() {
	fmt.Println(netutil.JoinHostPort("example.com", 12345))

}

Output:


example.com:12345

func ParseIP 

func ParseIP(s string) (ip net.IP, err error)

ParseIP is a wrapper around net.ParseIP that returns a useful error.

Any error returned will have the underlying type of *AddrError.

Example 
package main

import (
	"fmt"

	"github.com/AdguardTeam/golibs/netutil"
)

func main() {
	ip, err := netutil.ParseIP("1.2.3.4")
	fmt.Println(ip, err)

	ip, err = netutil.ParseIP("1234::cdef")
	fmt.Println(ip, err)

	ip, err = netutil.ParseIP("!!!")
	fmt.Println(ip, err)

}

Output:


1.2.3.4 <nil>
1234::cdef <nil>
<nil> bad ip address "!!!"

func ParseIPv4 

func ParseIPv4(s string) (ip net.IP, err error)

ParseIPv4 is a wrapper around net.ParseIP that makes sure that the parsed IP is an IPv4 address and returns a useful error.

Any error returned will have the underlying type of either *AddrError.

Example 
package main

import (
	"fmt"

	"github.com/AdguardTeam/golibs/netutil"
)

func main() {
	ip, err := netutil.ParseIPv4("1.2.3.4")
	fmt.Println(ip, err)

	ip, err = netutil.ParseIPv4("1234::cdef")
	fmt.Println(ip, err)

	ip, err = netutil.ParseIPv4("!!!")
	fmt.Println(ip, err)

}

Output:


1.2.3.4 <nil>
<nil> bad ipv4 address "1234::cdef"
<nil> bad ipv4 address "!!!"

func ParseSubnet added in v0.10.3 

func ParseSubnet(s string) (n *net.IPNet, err error)

ParseSubnet parses a subnet which can be either a CIDR or a single IP. In the latter case, n is a single-IP subnet. It also keeps the original parsed IP address inside n.

If s contains a CIDR with an IP address that is an IPv4-mapped IPv6 address, the behavior is undefined.

Any error returned will have the underlying type of either *AddrError.

Example 
package main

import (
	"fmt"
	"net"

	"github.com/AdguardTeam/golibs/netutil"
)

func main() {
	ip := net.IP{1, 2, 3, 4}
	otherIP := net.IP{1, 2, 3, 5}

	n, err := netutil.ParseSubnet("1.2.3.4")
	fmt.Println(n, err)
	fmt.Printf("%s is in %s: %t\n", ip, n, n.Contains(ip))
	fmt.Printf("%s is in %s: %t\n", otherIP, n, n.Contains(otherIP))

	n, err = netutil.ParseSubnet("1.2.3.4/16")
	fmt.Println(n, err)
	fmt.Printf("%s is in %s: %t\n", ip, n, n.Contains(ip))
	fmt.Printf("%s is in %s: %t\n", otherIP, n, n.Contains(otherIP))

}

Output:


1.2.3.4/32 <nil>
1.2.3.4 is in 1.2.3.4/32: true
1.2.3.5 is in 1.2.3.4/32: false
1.2.3.4/16 <nil>
1.2.3.4 is in 1.2.3.4/16: true
1.2.3.5 is in 1.2.3.4/16: true

func ParseSubnets added in v0.10.8 

func ParseSubnets(ss ...string) (ns []*net.IPNet, err error)

ParseSubnets returns the slice of *net.IPNet parsed from ss.

Example 
package main

import (
	"fmt"

	"github.com/AdguardTeam/golibs/netutil"
)

func main() {
	ns, err := netutil.ParseSubnets("1.2.3.4", "1.2.3.4/16")
	fmt.Println("error:   ", err)
	fmt.Println("networks:", ns)

	fmt.Println()

	ns, err = netutil.ParseSubnets()
	fmt.Println("error:   ", err)
	fmt.Println("networks:", ns)

	fmt.Println()

	ns, err = netutil.ParseSubnets("4.3.2.1/32", "5.5.5.5/33")
	fmt.Println("error:   ", err)
	fmt.Println("networks:", ns)

}

Output:


error:    <nil>
networks: [1.2.3.4/32 1.2.3.4/16]

error:    <nil>
networks: []

error:    parsing network at index 1: bad cidr address "5.5.5.5/33"
networks: []

func SingleIPSubnet added in v0.10.3 

func SingleIPSubnet(ip net.IP) (n *net.IPNet)

SingleIPSubnet returns an IP network that only contains ip. If ip is not a valid IPv4 or IPv6 address, n is nil.

Example 
package main

import (
	"fmt"
	"net"

	"github.com/AdguardTeam/golibs/netutil"
)

func main() {
	ip4 := net.IP{1, 2, 3, 4}
	otherIP4 := net.IP{1, 2, 3, 5}

	n := netutil.SingleIPSubnet(ip4)
	fmt.Printf("%s is in %s: %t\n", ip4, n, n.Contains(ip4))
	fmt.Printf("%s is in %s: %t\n", otherIP4, n, n.Contains(otherIP4))

	ip6 := net.ParseIP("1234::cdef")
	otherIP6 := net.ParseIP("1234::cdff")

	n = netutil.SingleIPSubnet(ip6)
	fmt.Printf("%s is in %s: %t\n", ip6, n, n.Contains(ip6))
	fmt.Printf("%s is in %s: %t\n", otherIP6, n, n.Contains(otherIP6))

}

Output:


1.2.3.4 is in 1.2.3.4/32: true
1.2.3.5 is in 1.2.3.4/32: false
1234::cdef is in 1234::cdef/128: true
1234::cdff is in 1234::cdef/128: false

func SplitHost 

func SplitHost(hostport string) (host string, err error)

SplitHost is a wrapper for net.SplitHostPort for cases when the hostport may or may not contain a port.

Example 
package main

import (
	"fmt"

	"github.com/AdguardTeam/golibs/netutil"
)

func main() {
	host, err := netutil.SplitHost("example.com:12345")
	if err != nil {
		panic(err)
	}

	fmt.Println(host)

	host, err = netutil.SplitHost("example.org")
	if err != nil {
		panic(err)
	}

	fmt.Println(host)

	_, err = netutil.SplitHost("[BAD:!")
	fmt.Println(err)

}

Output:


example.com
example.org
address [BAD:!: missing ']' in address

func SplitHostPort 

func SplitHostPort(hostport string) (host string, port int, err error)

SplitHostPort is a convenient wrapper for net.SplitHostPort with port of type int.

Example 
package main

import (
	"fmt"

	"github.com/AdguardTeam/golibs/netutil"
)

func main() {
	host, port, err := netutil.SplitHostPort("example.com:12345")
	if err != nil {
		panic(err)
	}

	fmt.Printf("%T(%[1]v)\n", host)
	fmt.Printf("%T(%[1]v)\n", port)

}

Output:


string(example.com)
int(12345)

func Subdomains added in v0.9.3 

func Subdomains(domain string) (sub []string)

Subdomains returns all subdomains of domain, starting from domain itself. domain must be a valid, non-fully-qualified domain name. If domain is empty, Subdomains returns nil.

Example 
package main

import (
	"fmt"

	"github.com/AdguardTeam/golibs/netutil"
)

func main() {
	fmt.Printf("%#v\n", netutil.Subdomains("subsub.sub.domain.tld"))

	fmt.Println()

	fmt.Printf("%#v\n", netutil.Subdomains(""))

}

Output:


[]string{"subsub.sub.domain.tld", "sub.domain.tld", "domain.tld", "tld"}

[]string(nil)

func SubnetFromReversedAddr added in v0.10.5 

func SubnetFromReversedAddr(arpa string) (subnet *net.IPNet, err error)

SubnetFromReversedAddr tries to convert a reversed ARPA address to an IP network. arpa can be domain name or an FQDN.

Any error returned will have the underlying type of *AddrError.

Example 
package main

import (
	"fmt"

	"github.com/AdguardTeam/golibs/netutil"
)

func main() {
	subnet, err := netutil.SubnetFromReversedAddr("10.in-addr.arpa")
	if err != nil {
		panic(err)
	}

	fmt.Println(subnet)

	subnet, err = netutil.SubnetFromReversedAddr("0.10.in-addr.arpa")
	if err != nil {
		panic(err)
	}

	fmt.Println(subnet)

	subnet, err = netutil.SubnetFromReversedAddr("3.2.1.d.c.b.a.ip6.arpa")
	if err != nil {
		panic(err)
	}

	fmt.Println(subnet)

}

Output:


10.0.0.0/8
10.0.0.0/16
abcd:1230::/28
Example (DomainOnly) 
package main

import (
	"fmt"

	"github.com/AdguardTeam/golibs/netutil"
)

func main() {
	a := `in-addr.arpa`
	_, err := netutil.SubnetFromReversedAddr(a)

	fmt.Println(err)

}

Output:


bad arpa domain name "in-addr.arpa": not a reversed ip network

func ValidateDomainName 

func ValidateDomainName(name string) (err error)

ValidateDomainName validates the domain name in accordance to RFC 952, RFC 1035, and with RFC 1123's inclusion of digits at the start of the host. It doesn't validate against two or more hyphens to allow punycode and internationalized domains.

Any error returned will have the underlying type of *AddrError.

func ValidateDomainNameLabel 

func ValidateDomainNameLabel(label string) (err error)

ValidateDomainNameLabel returns an error if label is not a valid label of a domain name. An empty label is considered invalid.

Any error returned will have the underlying type of *AddrError.

func ValidateIP added in v0.9.2 

func ValidateIP(ip net.IP) (err error)

ValidateIP returns an error if ip is not a valid IPv4 or IPv6 address.

Any error returned will have the underlying type of *AddrError.

func ValidateMAC 

func ValidateMAC(mac net.HardwareAddr) (err error)

ValidateMAC returns an error if mac is not a valid EUI-48, EUI-64, or 20-octet InfiniBand link-layer address.

Any error returned will have the underlying type of *AddrError.

func ValidateSRVDomainName added in v0.10.4 

func ValidateSRVDomainName(name string) (err error)

ValidateSRVDomainName validates of domain name assuming it belongs to the superset of service domain names in accordance to RFC 2782 and RFC 6763. It doesn't validate against two or more hyphens to allow punycode and internationalized domains.

Any error returned will have the underlying type of *AddrError.

func ValidateServiceNameLabel added in v0.10.4 

func ValidateServiceNameLabel(label string) (err error)

ValidateServiceNameLabel returns an error if label is not a valid label of a service domain name. An empty label is considered invalid.

Any error returned will have the underlying type of *AddrError.

func ZeroPrefix added in v0.11.0 

func ZeroPrefix(fam AddrFamily) (n netip.Prefix)

ZeroPrefix returns an IP subnet with prefix 0 and all bytes of the IP address set to 0. fam must be either AddrFamilyIPv4 or AddrFamilyIPv6.

Example 
package main

import (
	"fmt"

	"github.com/AdguardTeam/golibs/netutil"
)

func main() {
	fmt.Println(netutil.ZeroPrefix(netutil.AddrFamilyIPv4))
	fmt.Println(netutil.ZeroPrefix(netutil.AddrFamilyIPv6))

	// Invalid value for [netutil.AddrFamily].
	func() {
		defer func() { fmt.Println(recover()) }()

		fmt.Println(netutil.ZeroPrefix(1234))
	}()

}

Output:

0.0.0.0/0
::/0
netutil.ZeroPrefix: bad address family 1234

Types

type AddrError 

type AddrError struct {
	// Err is the underlying error, if any.
	Err error

	// Kind is the kind of address or address part.
	Kind AddrKind

	// Addr is the text of the invalid address.
	Addr string
}

AddrError is the underlying type of errors returned from validation functions when a domain name is invalid.

func (*AddrError) Error 

func (err *AddrError) Error() (msg string)

Error implements the error interface for *AddrError.

func (*AddrError) Unwrap 

func (err *AddrError) Unwrap() (unwrapped error)

Unwrap implements the errors.Wrapper interface for *AddrError. It returns err.Err.

type AddrFamily added in v0.11.0 

type AddrFamily uint16

AddrFamily is the type for IANA address family numbers. 

const (
	AddrFamilyNone AddrFamily = 0
	AddrFamilyIPv4 AddrFamily = 1
	AddrFamilyIPv6 AddrFamily = 2
)

An incomplete list of IANA address family numbers.

See https://www.iana.org/assignments/address-family-numbers/address-family-numbers.xhtml.

func AddrFamilyFromRRType added in v0.11.0 

func AddrFamilyFromRRType(rr uint16) (fam AddrFamily)

AddrFamilyFromRRType returns an AddrFamily appropriate for the DNS resource record type rr. That is, AddrFamilyIPv4 for DNS type A (1), AddrFamilyIPv6 for DNS type AAAA (28), and AddrFamilyNone otherwise.

Example 
package main

import (
	"fmt"

	"github.com/AdguardTeam/golibs/netutil"
)

func main() {
	// DNS type A.
	fmt.Println(netutil.AddrFamilyFromRRType(1))

	// DNS type AAAA.
	fmt.Println(netutil.AddrFamilyFromRRType(28))

	// Other DNS type.
	fmt.Println(netutil.AddrFamilyFromRRType(1234))

}

Output:

ipv4
ipv6
none

func (AddrFamily) String added in v0.11.0 

func (f AddrFamily) String() (s string)

String implements the fmt.Stringer interface for AddrFamily.

Example 
package main

import (
	"fmt"

	"github.com/AdguardTeam/golibs/netutil"
)

func main() {
	fmt.Println(netutil.AddrFamilyIPv4, netutil.AddrFamilyIPv6)

	// An empty family.
	var fam netutil.AddrFamily
	fmt.Println(fam)

	// An unsupported family.
	fam = netutil.AddrFamily(1234)
	fmt.Println(fam)

}

Output:

ipv4 ipv6
none
!bad_addr_fam_1234

type AddrKind 

type AddrKind string

AddrKind is the kind of address or address part used for error reporting. 

const (
	AddrKindARPA     AddrKind = "arpa domain name"
	AddrKindCIDR     AddrKind = "cidr address"
	AddrKindHostPort AddrKind = "hostport address"
	AddrKindIP       AddrKind = "ip address"
	AddrKindIPPort   AddrKind = "ipport address"
	AddrKindIPv4     AddrKind = "ipv4 address"
	AddrKindLabel    AddrKind = "domain name label"
	AddrKindSRVLabel AddrKind = "service name label"
	AddrKindMAC      AddrKind = "mac address"
	AddrKindName     AddrKind = "domain name"
	AddrKindSRVName  AddrKind = "service domain name"
)

Kinds of addresses for AddrError.

type HostPort 

type HostPort struct {
	Host string
	Port int
}

HostPort is a convenient type for addresses that contain a hostname and a port, like "example.com:12345", "1.2.3.4:56789", or "[1234::cdef]:12345".

func CloneHostPorts 

func CloneHostPorts(hps []*HostPort) (clone []*HostPort)

CloneHostPorts returns a deep copy of hps.

func ParseHostPort 

func ParseHostPort(addr string) (hp *HostPort, err error)

ParseHostPort parses a HostPort from addr. Any error returned will have the underlying type of *AddrError.

func (*HostPort) Clone 

func (hp *HostPort) Clone() (clone *HostPort)

Clone returns a clone of hp.

func (HostPort) MarshalText 

func (hp HostPort) MarshalText() (b []byte, err error)

MarshalText implements the encoding.TextMarshaler interface for HostPort.

Example 
package main

import (
	"encoding/json"
	"os"

	"github.com/AdguardTeam/golibs/netutil"
)

func main() {
	resp := struct {
		Hosts []netutil.HostPort `json:"hosts"`
	}{
		Hosts: []netutil.HostPort{{
			Host: "example.com",
			Port: 12345,
		}, {
			Host: "example.org",
			Port: 23456,
		}},
	}

	err := json.NewEncoder(os.Stdout).Encode(resp)
	if err != nil {
		panic(err)
	}

	respPtrs := struct {
		HostPtrs []*netutil.HostPort `json:"host_ptrs"`
	}{
		HostPtrs: []*netutil.HostPort{{
			Host: "example.com",
			Port: 12345,
		}, {
			Host: "example.org",
			Port: 23456,
		}},
	}

	err = json.NewEncoder(os.Stdout).Encode(respPtrs)
	if err != nil {
		panic(err)
	}

}

Output:


{"hosts":["example.com:12345","example.org:23456"]}
{"host_ptrs":["example.com:12345","example.org:23456"]}

func (HostPort) String 

func (hp HostPort) String() (s string)

String implements the fmt.Stringer interface for *HostPort.

Example 
package main

import (
	"fmt"

	"github.com/AdguardTeam/golibs/netutil"
)

func main() {
	hp := &netutil.HostPort{
		Host: "example.com",
		Port: 12345,
	}

	fmt.Println(hp)

	hp.Host = "1234::cdef"
	fmt.Println(hp)

	hp.Port = 0
	fmt.Println(hp)

	hp.Host = ""
	fmt.Println(hp)

}

Output:


example.com:12345
[1234::cdef]:12345
[1234::cdef]:0
:0

func (*HostPort) UnmarshalText 

func (hp *HostPort) UnmarshalText(b []byte) (err error)

UnmarshalText implements the encoding.TextUnmarshaler interface for *HostPort. Any error returned will have the underlying type of *AddrError.

Example 
package main

import (
	"encoding/json"
	"fmt"
	"strings"

	"github.com/AdguardTeam/golibs/netutil"
)

func main() {
	resp := &struct {
		Hosts []netutil.HostPort `json:"hosts"`
	}{}

	r := strings.NewReader(`{"hosts":["example.com:12345","example.org:23456"]}`)
	err := json.NewDecoder(r).Decode(resp)
	if err != nil {
		panic(err)
	}

	fmt.Printf("%#v\n", resp.Hosts[0])
	fmt.Printf("%#v\n", resp.Hosts[1])

	respPtrs := &struct {
		HostPtrs []*netutil.HostPort `json:"host_ptrs"`
	}{}

	r = strings.NewReader(`{"host_ptrs":["example.com:12345","example.org:23456"]}`)
	err = json.NewDecoder(r).Decode(respPtrs)
	if err != nil {
		panic(err)
	}

	fmt.Printf("%#v\n", respPtrs.HostPtrs[0])
	fmt.Printf("%#v\n", respPtrs.HostPtrs[1])
	fmt.Println()

	r = strings.NewReader(`{"host_ptrs":["example.com:99999","example.org:99999"]}`)
	err = json.NewDecoder(r).Decode(respPtrs)

	isOutOfRange := err.Error() == `bad hostport address "example.com:99999": `+
		`parsing port: strconv.ParseUint: parsing "99999": value out of range`
	fmt.Printf("got the expected error: %t", isOutOfRange)

}

Output:


netutil.HostPort{Host:"example.com", Port:12345}
netutil.HostPort{Host:"example.org", Port:23456}
&netutil.HostPort{Host:"example.com", Port:12345}
&netutil.HostPort{Host:"example.org", Port:23456}

got the expected error: true

type IPMap deprecated 

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

IPMap is a map of IP addresses.

Deprecated: Use map[netip.Addr]T instead.

func NewIPMap 

func NewIPMap(hint int) (m *IPMap)

NewIPMap returns a new empty IP map using hint as a size hint for the underlying map.

It is not safe for concurrent use, just like the usual Go maps aren't.

func (*IPMap) Clear added in v0.10.1 

func (m *IPMap) Clear()

Clear clears the map but retains its allocated storage. Calling Clear on a nil *IPMap has no effect, just like calling delete in a loop on an empty map doesn't.

func (*IPMap) Del 

func (m *IPMap) Del(ip net.IP)

Del deletes ip from the map. Calling Del on a nil *IPMap has no effect, just like delete on an empty map doesn't.

func (*IPMap) Get 

func (m *IPMap) Get(ip net.IP) (v any, ok bool)

Get returns the value from the map. Calling Get on a nil *IPMap returns nil and false, just like indexing on an empty map does.

func (*IPMap) Len 

func (m *IPMap) Len() (n int)

Len returns the length of the map. A nil *IPMap has a length of zero, just like an empty map.

func (*IPMap) Range 

func (m *IPMap) Range(f func(ip net.IP, v any) (cont bool))

Range calls f with a copy of the key and the value for each key-value pair present in the map in an undefined order. If cont is false, range stops the iteration. Calling Range on a nil *IPMap has no effect, just like ranging over a nil map.

func (*IPMap) Set 

func (m *IPMap) Set(ip net.IP, v any)

Set sets the value. Set panics if the m is a nil *IPMap, just like a nil map does.

func (*IPMap) ShallowClone 

func (m *IPMap) ShallowClone() (sclone *IPMap)

ShallowClone returns a shallow clone of the map.

func (*IPMap) String 

func (m *IPMap) String() (s string)

String implements the fmt.Stringer interface for *IPMap.

type IPPort deprecated 

type IPPort struct {
	IP   net.IP
	Port int
}

IPPort is a convenient type for network addresses that contain an IP address and a port, like "1.2.3.4:56789" or "[1234::cdef]:12345".

Deprecated: use netip.AddrPort.

func CloneIPPorts 

func CloneIPPorts(ipps []*IPPort) (clone []*IPPort)

CloneIPPorts returns a deep copy of ipps.

func IPPortFromAddr 

func IPPortFromAddr(a net.Addr) (ipp *IPPort)

IPPortFromAddr returns an *IPPort from a if its underlying type is either *net.TCPAddr or *net.UDPAddr. Otherwise, it returns nil.

func ParseIPPort 

func ParseIPPort(addr string) (ipp *IPPort, err error)

ParseIPPort parses an *IPPort from addr. Any error returned will have the underlying type of *AddrError.

func (*IPPort) Clone 

func (ipp *IPPort) Clone() (clone *IPPort)

Clone returns a clone of ipp.

func (IPPort) MarshalText 

func (ipp IPPort) MarshalText() (b []byte, err error)

MarshalText implements the encoding.TextMarshaler interface for IPPort.

Example 
package main

import (
	"encoding/json"
	"net"
	"os"

	"github.com/AdguardTeam/golibs/netutil"
)

func main() {
	ip4 := net.ParseIP("1.2.3.4")
	ip6 := net.ParseIP("1234::cdef")

	resp := struct {
		IPs []netutil.IPPort `json:"ips"`
	}{
		IPs: []netutil.IPPort{{
			IP:   ip4,
			Port: 12345,
		}, {
			IP:   ip6,
			Port: 23456,
		}},
	}

	err := json.NewEncoder(os.Stdout).Encode(resp)
	if err != nil {
		panic(err)
	}

	respPtrs := struct {
		IPPtrs []*netutil.IPPort `json:"ip_ptrs"`
	}{
		IPPtrs: []*netutil.IPPort{{
			IP:   ip4,
			Port: 12345,
		}, {
			IP:   ip6,
			Port: 23456,
		}},
	}

	err = json.NewEncoder(os.Stdout).Encode(respPtrs)
	if err != nil {
		panic(err)
	}

}

Output:


{"ips":["1.2.3.4:12345","[1234::cdef]:23456"]}
{"ip_ptrs":["1.2.3.4:12345","[1234::cdef]:23456"]}

func (IPPort) String 

func (ipp IPPort) String() (s string)

String implements the fmt.Stringer interface for *IPPort.

Example 
package main

import (
	"fmt"
	"net"

	"github.com/AdguardTeam/golibs/netutil"
)

func main() {
	ip4 := net.ParseIP("1.2.3.4")
	ip6 := net.ParseIP("1234::cdef")

	ipp := &netutil.IPPort{
		IP:   ip4,
		Port: 12345,
	}

	fmt.Println(ipp)

	ipp.IP = ip6
	fmt.Println(ipp)

	ipp.Port = 0
	fmt.Println(ipp)

	ipp.IP = nil
	fmt.Println(ipp)

}

Output:


1.2.3.4:12345
[1234::cdef]:12345
[1234::cdef]:0
:0

func (*IPPort) TCP 

func (ipp *IPPort) TCP() (a *net.TCPAddr)

TCP returns a *net.TCPAddr with a clone of ipp's IP address and its port.

Example 
package main

import (
	"fmt"
	"net"

	"github.com/AdguardTeam/golibs/netutil"
)

func main() {
	ipp := &netutil.IPPort{
		IP:   net.IP{1, 2, 3, 4},
		Port: 12345,
	}

	fmt.Printf("%#v\n", ipp.TCP())

}

Output:


&net.TCPAddr{IP:net.IP{0x1, 0x2, 0x3, 0x4}, Port:12345, Zone:""}

func (*IPPort) UDP 

func (ipp *IPPort) UDP() (a *net.UDPAddr)

UDP returns a *net.UDPAddr with a clone of ipp's IP address and its port.

Example 
package main

import (
	"fmt"
	"net"

	"github.com/AdguardTeam/golibs/netutil"
)

func main() {
	ipp := &netutil.IPPort{
		IP:   net.IP{1, 2, 3, 4},
		Port: 12345,
	}

	fmt.Printf("%#v\n", ipp.UDP())

}

Output:


&net.UDPAddr{IP:net.IP{0x1, 0x2, 0x3, 0x4}, Port:12345, Zone:""}

func (*IPPort) UnmarshalText 

func (ipp *IPPort) UnmarshalText(b []byte) (err error)

UnmarshalText implements the encoding.TextUnmarshaler interface for *IPPort. Any error returned will have the underlying type of *AddrError.

Example 
package main

import (
	"encoding/json"
	"fmt"
	"strings"

	"github.com/AdguardTeam/golibs/netutil"
)

func main() {
	resp := &struct {
		IPs []netutil.IPPort `json:"ips"`
	}{}

	r := strings.NewReader(`{"ips":["1.2.3.4:12345","[1234::cdef]:23456"]}`)
	err := json.NewDecoder(r).Decode(resp)
	if err != nil {
		panic(err)
	}

	fmt.Printf("%v\n", resp.IPs)

	respPtrs := &struct {
		IPPtrs []*netutil.IPPort `json:"ip_ptrs"`
	}{}

	r = strings.NewReader(`{"ip_ptrs":["1.2.3.4:12345","[1234::cdef]:23456"]}`)
	err = json.NewDecoder(r).Decode(respPtrs)
	if err != nil {
		panic(err)
	}

	fmt.Printf("%v\n", respPtrs.IPPtrs)

}

Output:


[1.2.3.4:12345 [1234::cdef]:23456]
[1.2.3.4:12345 [1234::cdef]:23456]
Example (Errors) 
package main

import (
	"encoding/json"
	"fmt"
	"strings"

	"github.com/AdguardTeam/golibs/netutil"
)

func main() {
	resp := &struct {
		IPs netutil.IPPort `json:"ip"`
	}{}

	r := strings.NewReader(`{"ip":"1.2.3.4:a"}`)
	err := json.NewDecoder(r).Decode(resp)

	isBadPort := err.Error() == `bad ipport address "1.2.3.4:a": `+
		`parsing port: strconv.ParseUint: parsing "a": invalid syntax`
	fmt.Printf("bad port causes an error: %t", isBadPort)

	fmt.Println()

	r = strings.NewReader(`{"ip":"1.2.3.4.5:12345"}`)
	err = json.NewDecoder(r).Decode(resp)

	isBadIP := err.Error() == `bad ipport address "1.2.3.4.5:12345": `+
		`bad ip address "1.2.3.4.5"`
	fmt.Printf("bad ip causes an error:   %t", isBadIP)

}

Output:


bad port causes an error: true
bad ip causes an error:   true

type LengthError 

type LengthError struct {
	// Kind is the kind of address or address part.
	Kind AddrKind

	// Allowed are the allowed lengths for this kind of address.  If allowed
	// is empty, Max should be non-zero.
	Allowed []int

	// Max is the maximum length for this part or address kind.  If Max is
	// zero, Allowed should be non-empty.
	Max int

	// Length is the length of the provided address.
	Length int
}

LengthError is the underlying type of errors returned from validation functions when an address or a part of an address has a bad length.

func (*LengthError) Error 

func (err *LengthError) Error() (msg string)

Error implements the error interface for *LengthError.

type RuneError 

type RuneError struct {
	// Kind is the kind of address or address part.
	Kind AddrKind

	// Rune is the invalid rune.
	Rune rune
}

RuneError is the underlying type of errors returned from validation functions when a rune in the address is invalid.

func (*RuneError) Error 

func (err *RuneError) Error() (msg string)

Error implements the error interface for *RuneError.

type SliceSubnetSet added in v0.10.8 

type SliceSubnetSet []*net.IPNet

SliceSubnetSet is the SubnetSet that checks the address through a slice of *net.IPNet.

func (SliceSubnetSet) Contains added in v0.10.8 

func (s SliceSubnetSet) Contains(ip net.IP) (ok bool)

Contains implements the SubnetSet interface for SliceSubnetSet.

type SubnetSet added in v0.10.8 

type SubnetSet interface {
	// Contains returns true if ip is contained by any of networks the set
	// contains.  ip must be only accessed for reading.
	Contains(ip net.IP) (ok bool)
}

SubnetSet contains the set of IP networks to match the IP address.

Example (Func) 
package main

import (
	"fmt"
	"net"

	"github.com/AdguardTeam/golibs/netutil"
)

func main() {
	s := netutil.SubnetSetFunc(func(ip net.IP) (ok bool) {
		return len(ip) > 0 && ip[0] == 0xFF
	})

	fmt.Println("contains 255.0.0.1:", s.Contains(net.IP{255, 0, 0, 1}))
	fmt.Println("contains 254.0.0.1:", s.Contains(net.IP{254, 0, 0, 1}))
	fmt.Println("contains ff00:::1: ", s.Contains(net.ParseIP("ff00::1")))
	fmt.Println("contains ff:::1:   ", s.Contains(net.ParseIP("ff::1")))

}

Output:


contains 255.0.0.1: true
contains 254.0.0.1: false
contains ff00:::1:  true
contains ff:::1:    false
Example (Single) 
package main

import (
	"fmt"
	"net"

	"github.com/AdguardTeam/golibs/netutil"
)

func main() {
	var s netutil.SubnetSet
	_, s, err := net.ParseCIDR("1.2.3.4/16")
	if err != nil {
		panic(err)
	}

	fmt.Println("contains 1.2.3.4:", s.Contains(net.IP{1, 2, 3, 4}))
	fmt.Println("contains 4.3.2.1:", s.Contains(net.IP{4, 3, 2, 1}))

}

Output:


contains 1.2.3.4: true
contains 4.3.2.1: false
Example (Slice) 
package main

import (
	"fmt"
	"net"

	"github.com/AdguardTeam/golibs/netutil"
)

func main() {
	nets, err := netutil.ParseSubnets("1.2.3.0/24", "ffff:12ab::/16")
	if err != nil {
		panic(err)
	}

	s := netutil.SliceSubnetSet(nets)

	fmt.Println("contains 1.2.3.4:      ", s.Contains(net.IP{1, 2, 3, 4}))
	fmt.Println("contains 4.3.2.1:      ", s.Contains(net.IP{4, 3, 2, 1}))
	fmt.Println("contains ffff:12ab::10:", s.Contains(net.ParseIP("ffff:12ab::10")))
	fmt.Println("contains 12ab:ffff::10:", s.Contains(net.ParseIP("12ab:ffff::10")))

	fmt.Println()

	s = netutil.SliceSubnetSet{}
	fmt.Println("contains 1.2.3.4:      ", s.Contains(net.IP{1, 2, 3, 4}))
	fmt.Println("contains ffff:12ab::10:", s.Contains(net.ParseIP("ffff:12ab::10")))

	fmt.Println()

	s = netutil.SliceSubnetSet{{
		IP:   make(net.IP, net.IPv4len),
		Mask: make(net.IPMask, net.IPv4len),
	}, {
		IP:   make(net.IP, net.IPv6len),
		Mask: make(net.IPMask, net.IPv6len),
	}}
	fmt.Println("contains 1.2.3.4:      ", s.Contains(net.IP{1, 2, 3, 4}))
	fmt.Println("contains ffff:12ab::10:", s.Contains(net.ParseIP("ffff:12ab::10")))
	fmt.Println("contains <nil>:        ", s.Contains(nil))

}

Output:


contains 1.2.3.4:       true
contains 4.3.2.1:       false
contains ffff:12ab::10: true
contains 12ab:ffff::10: false

contains 1.2.3.4:       false
contains ffff:12ab::10: false

contains 1.2.3.4:       true
contains ffff:12ab::10: true
contains <nil>:         false

type SubnetSetFunc added in v0.10.8 

type SubnetSetFunc func(ip net.IP) (ok bool)

SubnetSetFunc is a function determining if ip belongs to the set of subnets.

func (SubnetSetFunc) Contains added in v0.10.8 

func (f SubnetSetFunc) Contains(ip net.IP) (ok bool)

Contains implements the SubnetSet interface for SubnetSetFunc. The ip is not required to be valid or non-nil so that f is responsible for the validation.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.