discover

README

discover

discover is a very simple library for doing LAN peer discovery using UDP multicast. It is very useful for making P2P applications and file transferring utilities. Feel free to embed the library to your projects. It is just a single file!

Installation

Make sure you have Go installed on your machine.

$ go get github.com/a1phat0ny/discover

How it works

The Discover function does two things:

1. listen for UDP multicast packets in the group and
2. send (multicast) packets with payload written to the group at the same time.

Why UDP instead of TCP ?

Answer from https://stackoverflow.com/questions/21266008/can-i-use-broadcast-or-multicast-for-tcp

TCP is a protocol for communication between exactly two endpoints. Compared to UDP it features reliable transport, that means, that packets get not only send, but it is expected that the peer acknowledges the receipt of the data and that data will be retransmitted if the acknowledgement is missing. And because Broadcast and Multicast only send but never receive data, the reliability of TCP cannot be implemented on top of these protocols.

Usage

The following code will try to discover the first peer (IncludeSelf set to true which is our own machine in this case) for 5 seconds (default) and print the discovered peers out.

// you can customize the settings
settings := discover.DefaultSettings
settings.Limit = 1
settings.IncludeSelf = true
settings.NotifyFunc = func(p Peer) {
	log.Println("discovered", p)
}
// start discovering
peers, err := discover.Discover(settings)
if err != nil {
	log.Fatalln(err)
}
for _, p := range peers {
	fmt.Printf("[%d] %v\n", i+1, p)
}

Testing

# cd into where the library is located
$ cd discover
# run the test
$ go test

Made with ❤️︎ by a1phat0ny
under MIT license

Documentation

Index

• Variables
• type Discovery
  • func NewDiscovery(settings Settings) *Discovery
• type Peer
  • func Discover(settings Settings) ([]Peer, error)
• type Settings

Variables

var DefaultSettings = Settings{
	MulticastAddress: "239.255.255.250",
	GroupPort:        "9999",
	Limit:            -1,
	Interval:         500 * time.Millisecond,
	Timeout:          5 * time.Second,
	IncludeSelf:      false,
	Payload:          []byte("discover"),
}

DefaultSettings is the default configurations for peer discovering.

Types

type Discovery

type Discovery struct {
	Peers    []Peer
	StopChan chan bool
	Settings Settings
}

Discovery provides additional fields that holds the peer discovery.

func NewDiscovery

func NewDiscovery(settings Settings) *Discovery

NewDiscovery returns a new `Discovery` struct with the specified settings.

type Peer

type Peer string

Peer holds the IP address of a peer (string).

func Discover

func Discover(settings Settings) ([]Peer, error)

Discover does peer discovery by starting a goroutine which listens for incoming packets and handles them and start multicasting packets to the destination (group address) at the same time. Example:

peers, err := discover.Discover(discover.DefaultSettings)

type Settings

type Settings struct {
	// MulticastAddress defaults to 239.255.255.250 (Simple Service Discovery Protocol).
	MulticastAddress string
	// GroupPort defaults to 9999.
	GroupPort string
	// Limit is the max limit of peers to discover. Set to -1 for unlimited.
	Limit int
	// Interval is the time interval between each multicast.
	Interval time.Duration
	// Timeout is the most time given for the job to be done. Set to -1 if no timeout is needed.
	Timeout time.Duration
	// IncludeSelf includes the local address of this machine as discovered peer.
	IncludeSelf bool
	// Payload is the bytes that will be multicasted to group.
	Payload []byte
	// NotifyFunc will be called each time a new peer is discovered.
	NotifyFunc func(Peer)
}

Settings is the configurations that will be passed to `Discovery`.