README
¶
Network state monitoring
import "github.com/OpenPrinting/go-mfp/internal/netstate"
This package provides mechanisms for monitoring changes in network connectivity state.
Documentation
¶
Index ¶
- type Addr
- func (addr Addr) Addr() netip.Addr
- func (addr Addr) Interface() NetIf
- func (addr Addr) Is4() bool
- func (addr Addr) Less(addr2 Addr) bool
- func (addr Addr) Narrower(addr2 Addr) bool
- func (addr Addr) Overlaps(addr2 Addr) bool
- func (addr Addr) SameInterface(addr2 Addr) bool
- func (addr Addr) Similar(addr2 Addr) bool
- func (addr Addr) String() string
- func (addr Addr) Unmasked() Addr
- func (addr Addr) Wider(addr2 Addr) bool
- type Event
- type EventAddAddress
- type EventAddInterface
- type EventAddPrimaryAddress
- type EventDelAddress
- type EventDelInterface
- type EventDelPrimaryAddress
- type EventError
- type NetIf
- type NetIfFlags
- type Notifier
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Addr ¶
Addr represents a single IP address with a mask, assigned to a network interface.
Unlike net.IP or net.IPAddr, Addr is a comparable value type (it supports == and can be used as a map key) and is immutable.
An interface may have multiple addresses that can belong to the same or different IP networks. Addresses are grouped by their IP network membership. Within each group, exactly one address is marked as Primary.
In other words:
- If all interface addresses belong to different IP networks, they will all be marked as Primary.
- If multiple interface addresses belong to the same IP network, only one of them will be chosen as Primary.
Two addresses are considered to belong to the same IP network if their address ranges (taking the mask into account) overlap. You can use Addr.Overlaps to test whether any two addresses overlap.
Strictly speaking, ranges covered by two overlapping addresses either equal, if masks are the same, or nest, if mask of the "inner" address is narrower that mask of the "outer" address.
Use Addr.Narrower to determine which of two overlapping addresses has the narrower mas
func AddrFromIPNet ¶
AddrFromIPNet makes address from the net.IPNet
func (Addr) Addr ¶
Addr returns IP address.
If address is a link-local IPv6 address, it comes with the appropriate zone.
func (Addr) Less ¶
Less orders Addr for sorting.
The sorting order is following:
- if addresses belongs to different interfaces, they are sorted by net.Interface.Index, in acceding order
- if interface indices are the same, but name differ, addresses are sorted by interface name, in acceding order
- otherwise, if addresses belong to the different address families, they are sorted by address family, IPv4 first
- otherwise, if IP addresses not the same, they are sorted by IP address, in lexicographical acceding order
- otherwise, if masks are different, addresses are sorted by network mask, the narrowed first
- otherwise, addresses are equal
func (Addr) Narrower ¶
Narrower reports whether addr is narrower that addr2.
It means the following:
- addr and addr2 overlap (see [Addr.Overlap] for definition).
- mask of addr is narrower (contains more leading ones and less trailing zeroes) that mask of addr2
func (Addr) Overlaps ¶
Overlaps reports whether two addresses overlap.
Overlapped addressed are addresses for which all following is true:
- they belong to the same network interface
- they belong to the same address family, both either IP4 or IP6
- their address range, taking Mask into account, overlap
func (Addr) SameInterface ¶
SameInterface reports if two addresses belong to the same network interface.
Note, we consider two interfaces equal if they have equal net.Interface.Index and net.Interface.Name. Other parts of the net.Interface considered interface parameters, not interface identity.
func (Addr) Similar ¶
Similar reports whether two addresses are the same, ignoring difference in address mask
type Event ¶
type Event interface {
// String returns string representation of the Event,
// for logging.
String() string
// contains filtered or unexported methods
}
Event is the common interface of all events.
There are 7 types of events:
- EventAddInterface and EventDelInterface generated when network interface is added or deleted.
- EventAddAddress and EventDelAddress generated when IP address is added or deleted.
- EventAddPrimaryAddress and EventDelPrimaryAddress generated when primary address is added or deleted or when existent address changes its status. See Addr description for definition of the primary address.
- EventError is generated when some error occurs. Errors are not fatal and EventError intended only for logging. This is not guaranteed that all errors will be reported this way, but this mechanism attempts to be as informative as possible.
When address is added, events will come in the following order:
- EventAddInterface
- EventAddAddress, that used previously added interface.
- EventAddPrimaryAddress, that used previously added address.
When address is deleted, events will come in reverse order.
If address changes its IP mask, a pair of EventDelAddress/EventAddAddress events will be generated. EventDelAddress will be generated BEFORE the corresponding EventAddAddress.
If changed address was a primary address, the appropriate EventDelPrimaryAddress will be generated before EventAddAddress, and EventAddPrimaryAddress may be generated too, if result some another address became primary.
Please notice, that primary addresses will be reported twice, using EventAddAddress/EventDelAddress events and using EventAddPrimaryAddress/EventDelPrimaryAddress events.
type EventAddAddress ¶
type EventAddAddress struct {
Addr Addr // Added address
}
EventAddAddress is fired when new IP address added to some interface.
See Event description for details.
func (EventAddAddress) String ¶
func (e EventAddAddress) String() string
String returns string representation of EventAddInterface, for logging.
type EventAddInterface ¶
type EventAddInterface struct {
Interface NetIf // Added interface
}
EventAddInterface is fired when new interface added to the system.
See Event description for details.
func (EventAddInterface) String ¶
func (e EventAddInterface) String() string
String returns string representation of EventAddInterface, for logging.
type EventAddPrimaryAddress ¶
type EventAddPrimaryAddress struct {
Addr Addr // Added address
}
EventAddPrimaryAddress is fired when primary IP address added to some interface or when existing address changes its status to Primary.
See Event description for details.
func (EventAddPrimaryAddress) String ¶
func (e EventAddPrimaryAddress) String() string
String returns string representation of EventAddPrimaryAddress, for logging.
type EventDelAddress ¶
type EventDelAddress struct {
Addr Addr // Deleted address
}
EventDelAddress is fired when IP address is removed.
See Event description for details.
func (EventDelAddress) String ¶
func (e EventDelAddress) String() string
String returns string representation of EventDelAddress, for logging.
type EventDelInterface ¶
type EventDelInterface struct {
Interface NetIf // Deleted interface
}
EventDelInterface is fired when network interface is removed from the system.
See Event description for details.
func (EventDelInterface) String ¶
func (e EventDelInterface) String() string
String returns string representation of EventDelInterface, for logging.
type EventDelPrimaryAddress ¶
type EventDelPrimaryAddress struct {
Addr Addr // Deleted address
}
EventDelPrimaryAddress is fired when Primary IP address is removed or looses its status of the Primary address.
See Event description for details.
func (EventDelPrimaryAddress) String ¶
func (e EventDelPrimaryAddress) String() string
String returns string representation of EventDelPrimaryAddress, for logging.
type EventError ¶
type EventError struct {
Err error // The error
}
EventError is fired when some error occurs.
See Event description for details.
func (EventError) String ¶
func (e EventError) String() string
String returns string representation of EventError, for logging.
type NetIf ¶
type NetIf struct {
// contains filtered or unexported fields
}
NetIf represents a network interface.
Unline net.Interface, NetIf is comparable (it supports == and can be used as a map index) and immutable.
func MakeNetIf ¶
func MakeNetIf(index int, name string, flags NetIfFlags) NetIf
MakeNetIf makes NetIf from index and name.
func NetIfFromInterface ¶
NetIfFromInterface makes NetIf from net.Interface
func (NetIf) AsInterface ¶
AsInterface returns net.Interface that corresponds to NetIf.
This function may fail, for example, because actual interface has disappear from the network stack.
type NetIfFlags ¶
type NetIfFlags int
NetIfFlags contains network interface flags
const ( NetIfBroadcast NetIfFlags = 1 << iota NetIfLoopback NetIfMulticast )
NetIfFlags bits:
func (NetIfFlags) All ¶
func (flags NetIfFlags) All(mask NetIfFlags) bool
All returns true if all flags, specified by mask, are set.
func (NetIfFlags) Any ¶
func (flags NetIfFlags) Any(mask NetIfFlags) bool
Any returns true if any of the flags, specified by mask, are set.
func (NetIfFlags) String ¶
func (flags NetIfFlags) String() string
String returns string representation of the NetIfFlags, for debugging.
type Notifier ¶
type Notifier struct {
// contains filtered or unexported fields
}
Notifier monitors system connectivity to the network (available network interfaces and assigned IP addresses) and generates [Event]s, when network state changes.
Notifier provides the Notifier.Get methods to receive these Events.
If network state changes faster, that Notifier user reads Events, related Events may collide. For example if some network interface was added and then disappeared, in theory Event receiver should get two events: EventAddInterface followed by EventDelInterface. Actually, depending on how fast is the Event receiver, it will get either both of these events, or none. Two opposing events may annihilate. In any case, Event receiver's view to the network state will be eventually consistent with the actual network state.
This is safe to use Notifier with multiple goroutines.
Source Files