Documentation
¶
Overview ¶
Package ping implements an ICMP(v4/v6)-based IP address (in)validator.
Pinger objects support concurrent IP address validation jobs with maximum goroutine limits. Individual Ping verdicts are streamed as they are decided, to a channel returned when creating a new Pinger object. Here, a [QualifiedAddress] consists of (at least) an IP address as well as the types.Quality state, notably types.Valid and Invalid, but also types.Verifying and (initially) types.Unverified.
+---+
string-->| P +-->ch QualifiedAddress
+---+
⚠ Please note that a Pinger initially emits any newly submitted address before it undergoes verification (with its quality set to “verifying”), as well as later the final verdict. The rationale is that especially interactive clients can more easily manage their display so that all enqueued verifications are early visible.
If needed, a Pinger can read from the addresses it has to verify from an input channel until this input channel is closed.
+---+
ch string-->| P +-->ch QualifiedAddress
+---+
Pingers can be operated in a pipeline in that they read the addresses to be validated from an input channel and then stream the results to the Pinger's output channel.
Acknowledgements ¶
Under its hood, Pinger leverages gammazero/workerpool as the limiting goroutine pool.
Index ¶
- type Pinger
- func (p *Pinger) StopWait()
- func (p *Pinger) Validate(ctx context.Context, addr string)
- func (p *Pinger) ValidateQA(ctx context.Context, addr types.QualifiedAddress)
- func (p *Pinger) ValidateStream(ch <-chan types.QualifiedAddress)
- func (p *Pinger) ValidateStreamContext(ctx context.Context, ch <-chan types.QualifiedAddress)
- type PingerOption
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Pinger ¶
type Pinger struct {
// contains filtered or unexported fields
}
Pinger validates IP addresses by pinging them and then streaming the final types.QualifiedAddress verdicts to a result/output channel (kind of “IT-court TV”). Pingers use a goroutine-limited worker pool.
func New ¶
func New(size int, options ...PingerOption) (*Pinger, <-chan types.QualifiedAddress)
New returns a new Pinger with a maximum worker pool of the specified size as well as a “verdict stream”. The verdict channel will not only send the final IP address verdicts, but also the initial and yet unverified IP addresses as they get submitted for ping court verdicts.
The new pinger defaults to pinging 3 times at intervals of 1s between each ping. The validity threshold defaults to 50(%).
The pinger can be configured during creation using several option:
To operate a Pinger in a network namespace different to that of the OS-level thread of the caller specify the InNetworkNamespace option and pass it a filesystem path that must reference a network namespace (such as "/proc/666/ns/net").
func (*Pinger) StopWait ¶
func (p *Pinger) StopWait()
StopWait waits for all queued tasks to get processed and then finally closes the court TV channel.
func (*Pinger) Validate ¶
Validate the specified IP address by pinging it. The verdict is then sent to the channel returned together with the newly created Pinger. Additionally, an initial notice for the address to be validated is also sent beforehand.
If the specified context gets cancelled the pending address verifications won't be echoed to the verdict stream at all, and in particular not even as invalid. However, spurious verification verdicts might still appear on the verdict stream due to uncontrollable order of verdict sending and context cancellation detection.
Please note that you should use IP address literals instead of DNS names in case you want precise control over the specific IP address to validate. If you instead use DNS names and if the name resolves into multiple IP addresses, then you're effectively validating the DNS name, but not a particular IP address.
An IP address is considered to be invalid if the percentage of successfully received ping replies doesn't reach or cross the Pinger's threshold. This allows for some legroom.
The validation process is automatically aborted when the specified context either meets its deadline or gets cancelled. The IP address is then considered to be Invalid.
func (*Pinger) ValidateQA ¶
func (p *Pinger) ValidateQA(ctx context.Context, addr types.QualifiedAddress)
ValidateQA validates the specified types.QualifiedAddress and works otherwise like [Validate] for a plain address string.
If the specified context gets cancelled the pending address verifications won't be echoed to the verdict stream at all, and in particular not even as invalid. However, spurious verification verdicts might still appear on the verdict stream due to uncontrollable order of verdict sending and context cancellation detection.
The validation process is automatically aborted when the specified context either meets its deadline or gets cancelled. The IP address is then considered to be Invalid.
func (*Pinger) ValidateStream ¶
func (p *Pinger) ValidateStream(ch <-chan types.QualifiedAddress)
ValidateStream reads addresses (with optional attachments) to be validated from a channel until the channel is closed. It does not return until the channel has been closed, so callers typically might run ValidateStream in a separate goroutine.
The input channel transmits types.QualifiedAddress objects, but with the Quality field initially ignored.
func (*Pinger) ValidateStreamContext ¶
func (p *Pinger) ValidateStreamContext(ctx context.Context, ch <-chan types.QualifiedAddress)
ValidateStreamContext reads addresses (with optional attachments) to be validated from a channel until the channel is closed or the specified context gets cancelled. It does not return until the channel has been closed or the context cancelled, so callers typically might run ValidateStream in a separate goroutine.
If the specified context gets cancelled the pending address verifications won't be echoed to the verdict stream at all, and in particular not even as invalid. However, spurious verification verdicts might still appear on the verdict stream due to uncontrollable order of verdict sending and context cancellation detection.
The input channel transmits [QualifiedAddress] objects, but with the Quality field initially ignored.
type PingerOption ¶
type PingerOption func(*Pinger)
PingerOption can be passed to New when creating new Pinger objects.
func AsUnprivileged ¶
func AsUnprivileged() PingerOption
Unprivileged tells the Pinger to carry out unprivileged pings using UDP instead of ICMP packet.
func InNetworkNamespace ¶
func InNetworkNamespace(netnsref string) PingerOption
InNetworkNamespace optionally runs a Pinger inside the network namespace referenced by the specified filesystem path.
func WithCount ¶
func WithCount(count uint) PingerOption
WithCount sets the number of pings for testing reachability of an IP address.
func WithInterval ¶
func WithInterval(interval time.Duration) PingerOption
WithInterval sets the interval between consecutive pings.
func WithThresholdPercentage ¶
func WithThresholdPercentage(threshold uint) PingerOption
WithThresholdPercentage takes a percentage between 0 and 100 that specifies the percentage of successful ping responses required in order to validate the pinged IP address.
Source Files