Version: v0.1.8 Latest Latest

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

Go to latest
Published: Mar 1, 2021 License: BSD-3-Clause Imports: 7 Imported by: 3



Package netstate implements utilities for retrieving and filtering network interface state.

There are routines to obtain the available set of of network addresess, for determining changes to those addresses, and for selecting from amongst them according to some set of policies. Polices are implemented by applying simple predicates (functions with names of the form Is<condition>) to filter or find the first matching address from a list of addresses. The intent is to make it easy to create policies that do things like 'find the first IPv4 unicast address that is globally routable, failing that use a private IPv4 address, and failing that, an IPv6 address'.

A simple usage would be:

state, _ := netstate.GetAccessibleIPs()
ipv4 := state.Filter(netstate.IsPublicUnicastIPv4)
// ipv4 will contain all of the public IPv4 addresses, if any.

The example policy described above would be implemented using a series of calls to Filter with appropriate predicates.

In some cases, it may be necessary to take IP routing information into account and hence the interface hosting the address. The interface hosting each address is provided via NetworkInterface. GetAllAddresses and GetAccessibleIPs return instances of Address that provide access to the network address and the network interface that hosts it.

GetAll and GetAccessibleIPs cache the state of the network interfaces and routing information. This cache is invalidated by the Invalidate function which must be called whenever the network changes state (e.g. in response to dhcp changes).

Although most commercial networking hardware supports IPv6, some consumer devices and more importantly many ISPs do not, so routines are provided to allow developers to easily distinguish between the two and to use whichever is appropriate for their product/situation.

The term 'accessible' is used to refer to any non-loopback IP address. The term 'public' is used to refer to any globally routable IP address.

All IPv6 addresses are intended to be 'public', but any starting with fc00::/7 (RFC4193) are reserved for private use, but the go net libraries do not appear to recognise this. Similarly fe80::/10 (RFC 4291) are reserved for 'site-local' usage, but again this is not implemented in the go libraries. Any developer who needs to distinguish these cases will need to write their own routines to test for them.

When using the go net package it is important to remember that IPv6 addresses subsume IPv4 and hence in many cases the same internal representation is used for both, thus testing for the length of the IP address is unreliable. The reliable test is to use the net.To4() which will return a non-nil result if can be used as an IPv4 one. Any address can be used as an IPv6 and hence the only reliable way to test for an IPv6 address that is not an IPv4 one also is for the To4 call to return nil for it.



This section is empty.


View Source
var (
	ErrUnsupportedProtocol   = errors.New("unsupported protocol")
	ErrFailedToParseIPAddr   = errors.New("failed to parse IP address")
	ErrUnspecifiedIPAddr     = errors.New("unspecified (i.e. zero) IP address")
	ErrFailedToFindInterface = errors.New("failed to find a network interface")
View Source
var (
	// ErrNotAnIPProtocol is returned when the requested protocol is not from
	// theIP family.
	ErrNotAnIPProtocol = errors.New("requested protocol is not from the IP family")


func AsIP

func AsIP(a net.Addr) net.IP

AsIP returns its argument as a net.IP if that's possible.

func AsIPAddr

func AsIPAddr(a net.Addr) *net.IPAddr

AsIPAddr returns its argument as a net.IPAddr if that's possible. If the address is an IP in host:port notation it will use the host portion only.

func InvalidateCache

func InvalidateCache()

InvalidateCache invalidates any cached network state.

func IsAccessibleIP

func IsAccessibleIP(a Address) bool

IsAccessible returns true if its argument is an accessible (non-loopback) IP address.

func IsDefaultRoute

func IsDefaultRoute(r *route.IPRoute) bool

IsDefaultRoute returns true if the supplied IPRoute is a default route.

func IsGloballyRoutableIP

func IsGloballyRoutableIP(ip net.IP) bool

IsGloballyRoutableIP returns true if the argument is a globally routable IP address.

func IsIPProtocol

func IsIPProtocol(n string) bool

IsIPProtocol returns true if its parameter is one of the allowed network/protocol values for IP. It considers the vanadium specific websockect protocols (wsh, wsh4, wsh6) as being IP.

func IsLoopbackIP

func IsLoopbackIP(a Address) bool

IsLoopback returns true if its argument is a loopback IP address

func IsOnDefaultRoute

func IsOnDefaultRoute(a Address) bool

IsOnDefaultRoute returns true for addresses that are on an interface that has a default route set for the supplied address.

func IsPublicUnicastIP

func IsPublicUnicastIP(a Address) bool

IsPublicUnicastIP returns true if its argument is a global routable IPv4 or 6 address.

func IsPublicUnicastIPv4

func IsPublicUnicastIPv4(a Address) bool

IsPublicUnicastIPv4 returns true if its argument is a globally routable, public IPv4 unicast address.

func IsPublicUnicastIPv6

func IsPublicUnicastIPv6(a Address) bool

IsUnicastIPv6 returns true if its argument is a globally routable IP6 address

func IsUnicastIP

func IsUnicastIP(a Address) bool

IsUnicastIP returns true if its argument is a unicast IP address.

func IsUnicastIPv4

func IsUnicastIPv4(a Address) bool

IsUnicastIPv4 returns true if its argument is a unicast IP4 address

func IsUnicastIPv6

func IsUnicastIPv6(a Address) bool

IsUnicastIPv6 returns true if its argument is a unicast IPv6 address

func IsUnspecifiedIP

func IsUnspecifiedIP(a Address) bool

IsUnspecified returns true if its argument is an unspecified IP address

func NewNetAddr

func NewNetAddr(network, protocol string) net.Addr

NewNetAddr creates a net.Addr from the supplied network and protocol.

func PossibleAddresses

func PossibleAddresses(protocol, addr string, chooser AddressChooser) ([]net.Addr, bool, error)

PossibleAddresses returns the set of addresses that can be used to reach the specified host and that satisfy whatever policy is implemented by the supplied AddressChooser. It also returns an indication of whether the supplied host is unspecified or not. An unspecified host can be used over any network interface on the host. If the supplied address contains a port in then all of the returned addresses will also contain that port.

The returned net.Addr's need have the exact same protocol as that passed in as a parameter, rather, the chooser should return net.Addr's that can be used for that protocol. Using tcp as a parameter for example will generally result in net.Addr's whose Network method returns "ip" or "ip6".

If the chooser fails to find any appropriate addresses then the protocol, addr parameters will be returned as net.Addr (and if possible as a netstate.Address).

PossibleAddress currently only supports IP addresses.

func SameMachine

func SameMachine(addr net.Addr) (bool, error)

SameMachine returns true if the provided addr is on the host executing this function.


type AddrList

type AddrList []Address

AddrList is a slice of Addresses.

func ConvertToAddresses

func ConvertToAddresses(addrs []net.Addr) AddrList

ConvertToAddresses attempts to convert a slice of net.Addr's into an AddrList. It does so as follows: - using type assertion if the net.Addr instance is also an instance

of Address.

- using AddressFromAddr. - filling in just the address portion of Address without any interface


func FindAdded

func FindAdded(a, b AddrList) AddrList

FindAdded returns the set addresses that are present in b, but not in a - i.e. have been added.

func FindRemoved

func FindRemoved(a, b AddrList) AddrList

FindRemoved returns the set of addresses that are present in a, but not in b - i.e. have been removed.

func GetAccessibleIPs

func GetAccessibleIPs() (AddrList, error)

GetAccessibleIPs returns all of the accessible IP addresses on the device - i.e. excluding loopback and unspecified addresses. The IP addresses returned will be host addresses.

func GetAllAddresses

func GetAllAddresses() (AddrList, <-chan struct{}, error)

GetAllAddresses gets all of the available addresses on the device, including loopback addresses, non-IP protocols etc. The IP interface addresses returned are in CIDR form. GetAllAddressses caches the state of network interfaces and route tables to avoid expensive system calls (for routing information), the cache is invalidated by the Invalidate function which should be called whenever the network state may have changed (e.g. following a dhcp change). The returned chan is closed when the returned AddrList has become stale.

func (AddrList) AsNetAddrs

func (al AddrList) AsNetAddrs() []net.Addr

AsNetAddrs returns al as a slice of net.Addrs by changing the type of the slice that contains them and not by copying them.

func (AddrList) Filter

func (al AddrList) Filter(predicate AddressPredicate) AddrList

Filter returns all of the addresses for which the predicate function is true.

func (AddrList) Map

func (al AddrList) Map(mapper Mapper) AddrList

Map will apply the Mapper function to all of the items in its receiver and return a new AddrList containing all of the non-nil results from said calls.

func (AddrList) String

func (al AddrList) String() string

type Address

type Address interface {
	// Address returns the network address this instance represents.
	Interface() NetworkInterface
	DebugString() string

Address represents a network address and the interface that hosts it.

func AddressFromAddr

func AddressFromAddr(addr net.Addr) (Address, error)

AddressFromAddr creates an instance of Address given the suppied net.Addr. It will search through the available network interfaces to find the interface that hosts this address. It currently supports only IP protocols.

func AddressFromIP

func AddressFromIP(ip net.IP) (Address, error)

AddressFromIP creates an instance of Address given the supplied IP address. It will search through the available network interfaces to find the interface that hosts this IP address.

func WithIPHost

func WithIPHost(a Address) Address

WithIPHost returns an instance of Address with the network address component being an instance with a net.Addr that contains an IP host address (as opposed to a network CIDR for example).

func WithIPHostAndPort

func WithIPHostAndPort(a Address, port string) Address

WithIPHostAndPort returns an instance of Address with the network address component being an instance of net.Addr that contains an IP host and port in : notation.

type AddressChooser

type AddressChooser interface {
	ChooseAddresses(protocol string, candidates []net.Addr) ([]net.Addr, error)

AddressChooser determines the preferred addresses to publish with the mount table when one is not otherwise specified.

type AddressChooserFunc

type AddressChooserFunc func(protocol string, candidates []net.Addr) ([]net.Addr, error)

AddressChooserFunc is a convenience for implementations that wish to supply a function literal implementation of AddressChooser.

func (AddressChooserFunc) ChooseAddresses

func (f AddressChooserFunc) ChooseAddresses(protocol string, candidates []net.Addr) ([]net.Addr, error)

ChooseAddresses applies AddressChooserFunc.

type AddressPredicate

type AddressPredicate func(a Address) bool

AddressPredicate defines the function signature for predicate functions to be used with AddrList

type IPNetworkInterface

type IPNetworkInterface interface {
	IPRoutes() IPRouteList

IPNetworkInterface represents a network interface supporting IP protocols.

type IPRouteList

type IPRouteList []route.IPRoute

IPRouteList is a slice of IPRoutes as returned by the netconfig package.

func (IPRouteList) Filter

func (rl IPRouteList) Filter(predicate RoutePredicate) IPRouteList

Filter returns all of the routes for which the predicate function is true.

func (IPRouteList) String

func (rl IPRouteList) String() string

type InterfaceList

type InterfaceList []NetworkInterface

InterfaceList represents a list of network interfaces.

func GetAllInterfaces

func GetAllInterfaces() (InterfaceList, error)

GetAllInterfaces returns a list of all of the network interfaces on this device. It uses the same cache as GetAllAddresses.

func (InterfaceList) String

func (ifcl InterfaceList) String() string

type Mapper

type Mapper func(a Address) Address

type NetworkInterface

type NetworkInterface interface {
	// Addrs returns the addresses hosted by this interface.
	Addrs() []net.Addr
	// Index returns the index of this interface.
	Index() int
	// Name returns the name of this interface, e.g., "en0", "lo0", "eth0.100"
	Name() string
	// MTU returns the maximum transmission unit
	MTU() int
	// HardwareAddr returns the hardware address in IEEE MAC-48, EUI-48 and EUI-64 form
	HardwareAddr() net.HardwareAddr
	// Flags returns the flags for the interface e.g., FlagUp, FlagLoopback, FlagMulticast
	Flags() net.Flags
	// Networks returns the set of networks accessible over this interface.
	Networks() []net.Addr
	// String returns a string representation of the interface.
	String() string

Network interface represents a network interface.

type RoutePredicate

type RoutePredicate func(r *route.IPRoute) bool

RoutePredicate defines the function signature for predicate functions to be used with RouteList

type RouteTable

type RouteTable map[int]IPRouteList

RouteTable represents the set of currently available network interfaces and the routes on each such interface. It is index by the index number of each interface.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL