Skip to content

Latest commit

 

History

History
139 lines (95 loc) · 4.6 KB

README.md

File metadata and controls

139 lines (95 loc) · 4.6 KB

Node Discovery

Build Status GoDoc

Simple decentralized discovery library written in Go

Description

Node Discovery is a Go library useful to create connected applications that need to be discovered into a local network. This solution is compatible with multicast enabled networks, it is adapted to home environment where no infrastructure platforms are available (such as DNS).

This package is based on nodes sharing periodically information between them. Each node can:

  • Register service URLs that will be exchanged to others
  • Subscribe to service events (when a service join or leave the cluster).

The exchanges is based on the Node Discovery Protocol. More information on this norm can be found here.

This software has been tested with the following operating systems:

  • linux/amd64

It must also be compatible with the other operating systems supported by the Golang language.

Installation

In a simple way, just use go get:

$ go get github.com/StarburstComputing/node-discovery

In your code, import the package:

import "github.com/StarburstComputing/node-discovery"

Quickstart

Some examples are available into the examples directory.

To test one of the examples:

# We start here the simple_discovery example
$ go run examples/simple_discovery.go

Examples can also be run into a Docker container. Assuming docker and docker-compose are installed in your environment, examples can be started with this command:

# We start here 3 instances of the simple-discovery example
$ docker-compose scale simple-discovery=3

The docker way allows you to test multiple nodes without having multiple devices.

Using the Node Discovery package

Basics

First of all, you must create a NodeDiscover object using the Listen() function:

myNodeDiscovery := discovery.Listen()

Listen() arguments are functional options. The following options are proposed by the API:

  • MulticastOpt: Use multicast UDP connection with a custom address and port. By default, the discovery node will create a multicast UDP network on 224.0.42.1:5432.
  • CustomConnectionOpt: Specify a custom connection and address to create discovery network. This option can be used for non-UDP multicast network use.
  • HeartbeatOpt: Change the default heartbeat frequency (default: 1s)
  • LeaveTimeoutOpt: Change the timeout for an inactive service (default: 10s)

You can also create your own option function by passing a custom NodeDiscoverOpt. See the source code and this post for more details.

At the end of the program, don't forget to close the connection:

myNodeDiscovery.Close()

Register services

Services are simple URLs. Each node can register as many URLs as they want using the Register() method:

serviceURL, _ := url.Parse("http://my-service.com:5542")
myNodeDiscovery.Register(serviceURL)

A service can be unregistered with the Unregister() method.

Subscribe to service events

Each node can receive a event when a service:

  • Join the network
  • Leave the network (after unregistration or timeout)

In this Go implementation, events are managed with channels. The Subscribe() method accepts channel object and events will populate the subscribed channels:

subCh := make(chan discovery.NodeEvent)
myNodeDiscovery.Subscribe(subCh)

To remove subscription, use Unsubscribe() method.

When an event is emitted, a NodeEvent structure is created with the following fields:

  • Type: Kind of event (Join or Leave)
  • Service: The URL of the related service

Logging

Node Discovery uses Logrus as log manager. You can use your custom log manager by calling SetLogger() function. The given logger must implement the logrus.FieldLogger interface.

How to contribute

This project is open-source (Apache 2.0 license), feel free to report bugs and contribute! To propose a change, please open a Pull Request, follow the Go standard and write unit tests related to your changes.

If you want to develop into the software, we recommend to use Glide instead of the go get solution:

$ git clone https://github.com/StarburstComputing/node-discovery
$ glide install