reachable

README

reachable

Network reachability functions for client side Go network code

Package reachable adds utility methods to notify when a network connection to a remote host is up or down. This is intended for long-running programs on systems that might have intermittent network access (e.g. laptops, phones, remote embedded systems, etc).

Quick Start

    // check if google.com is reachable every 5 minutes
    reachable.DefaultInterval = time.Minute*5
    reachable.Start("google.com")
    defer reachable.Stop()

    // ...

    // about to do network stuff...
    if !reachable.NetworkIsReachable() {
        log.Println("no network available!")
    }

Monitoring multiple hosts

This package may also be used to monitor multiple hosts by setting up separate Checker instances:

    // these will be updated whenever you need them later
    googleIsUp := true
    bingIsUp := true

    c1 := Checker{
        Hostport: "google.com:443",
        Notifier: func(r bool) {
           googleIsUp = r
        },
    }

    c2 := Checker{
        Hostport: "bing.com",
        Notifier: func(r bool) {
           bingIsUp = r
        },
    }

    // start goroutines that check for reachability
    c1.Start()
    c2.Start()

    // ...

License

MIT

Documentation

Overview

Package reachable adds utility methods to notify when a network connection to a remote host is up or down. This is intended for long-running programs on systems that might have intermittent network access (e.g. laptops, phones, remote embedded systems, etc).

// check if google.com is reachable every 5 minutes
reachable.DefaultInterval = time.Minute*5
reachable.Start("google.com")
defer reachable.Stop()

...

// about to do network stuff...
if !reachable.NetworkIsReachable() {
  log.Println("no network available!")
}

This package may also be used to monitor multiple hosts by setting up separate Checker instances:

// these will be updated whenever you need them
googleIsUp := true
bingIsUp := true

c1 := Checker{
    Hostport:"google.com:443",
    Notifier: func(r bool) {
       googleIsUp = r
    },
}
c2 := Checker{
    Hostport:"bing.com",
    Notifier: func(r bool) {
       bingIsUp = r
    },
}

// start goroutines that check for reachability
c1.Start()
c2.Start()

...

Index

• Variables
• func NetworkIsReachable() bool
• func Start(hostname string)
• func Stop()
• type Checker
  • func (c *Checker) Start()
  • func (c *Checker) Stop()

Variables

var (
	// DefaultInterval is the polling interval when network checks are made.
	DefaultInterval = time.Minute

	// DefaultTimeout specifies how long the TCP connection attempt should wait
	// before timing out. This should be adjusted for high-latency connections.
	DefaultTimeout = time.Second * 3
)

Functions

func NetworkIsReachable

func NetworkIsReachable() bool

NetworkIsReachable returns true when the package is able to reach the configured host. Start("example.com") must be called for this to be valid. If Start is not called, the default value is true.

func Start

func Start(hostname string)

Start begins the default Checker instance with the DefaultInterval and enables updates for the NetworkIsReachable function.

func Stop

func Stop()

Stop the global instance and reset NetworkIsReachable to true.

Types

type Checker

type Checker struct {
	// Hostport contains the hostname and port to contact to verify
	// connectivity. If no port is provided, assumes default port 80.
	Hostport string

	// Interval to poll for network access. If zero or negative, uses DefaultInterval.
	Interval time.Duration

	// Notifier is the user-specified callback for reachability notifications.
	Notifier func(bool)
	// contains filtered or unexported fields
}

Checker is a reachability checker that notifies calling code when a given host and port is reachable via the network.

func (*Checker) Start

func (c *Checker) Start()

Start begins Checker polling in a background goroutine.

func (*Checker) Stop

func (c *Checker) Stop()

Stop tells the background goroutine to stop checking.