netstate

package
v0.1.17 Latest Latest
Warning

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

 Go to latest Published: Dec 17, 2023 License: BSD-3-Clause Imports: 7 Imported by: 3

Documentation

Overview

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.

Index

Constants

This section is empty.

Variables

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")
)

Functions

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.

Types

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 information.

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.
	net.Addr
	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 {
	NetworkInterface
	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.

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.