peers

README

Peers

Provides support for identifying other peer processes to communicate with in the network.

Package peers provides helpers for defining and synchronizing remote peers on a network. The package essentially surrounds JSON files with remote host definitions in several standard locations. It also provides helper functionality for synchronizing the JSON data with a remote server as well as adding hosts to the file if they are seen on the network or removing hosts if they become offline.

To start using the library, simply create one of the following files:

• /etc/fluidfs/peers.json
• $HOME/.fluidfs/peers.json
• $PWD/peers.json

Or define a path using the $PEERS_PATH environment variable. When calling peers.Load(), it will look in each of these locations to find and parse the peers.json file, returning a Peers object. Alternatively, a new Peers object can be created and a path specified to its Load() method to load a specific file not above. The peers.json file can also be saved from the Peers object using the Dump() method.

The Peers object can also be synchronized from a remote service using the Sync() method. Synchronization fetches peers.json from a URL that can be specified by the environment, and can also submit an API key along with the request.

Other important helpers include the ability to identify the localhost or peer from the hostname of the system, or to identify all local peer processes. In short, the Peers object is a useful way to manage the configuration of a connected network of communicating devices.

Documentation

Overview

Package peers provides helpers for defining and synchronizing remote peers on a network. The package essentially surrounds JSON files with remote host definitions in several standard locations. It also provides helper functionality for synchronizing the JSON data with a remote server as well as adding hosts to the file if they are seen on the network or removing hosts if they become offline.

To start using the library, simply create one of the following files:

- /etc/fluidfs/peers.json - $HOME/.fluidfs/peers.json - $PWD/peers.json

Or define a path using the $PEERS_PATH environment variable. When calling peers.Load(), it will look in each of these locations to find and parse the peers.json file, returning a Peers object. Alternatively, a new Peers object can be created and a path specified to its Load() method to load a specific file not above. The peers.json file can also be saved from the Peers object using the Dump() method.

The Peers object can also be synchronized from a remote service using the Sync() method. Synchronization fetches peers.json from a URL that can be specified by the environment, and can also submit an API key along with the request.

Other important helpers include the ability to identify the localhost or peer from the hostname of the system, or to identify all local peer processes. In short, the Peers object is a useful way to manage the configuration of a connected network of communicating devices.

Index

• func Path() string
• type Peer
  • func (p *Peer) Endpoint(dns bool) string
  • func (p *Peer) IsLocal() bool
  • func (p *Peer) ZMQEndpoint(server bool) string
• type Peers
  • func Load() *Peers
  • func LoadFrom(path string) (*Peers, error)
  • func Sync() (*Peers, error)
  • func SyncFrom(url, apikey string) (*Peers, error)
  • func (p *Peers) Dump(path string) error
  • func (p *Peers) Get(hostname string) (*Peer, error)
  • func (p *Peers) Load(path string) error
  • func (p *Peers) Local(hostname string) []*Peer
  • func (p *Peers) Localhost(hostname string, pid uint32) (*Peer, error)

Functions

func Path

func Path() string

Path returns the recommended location to store a peers.json file for external services to use. It returns the environment peers path if it exists, otherwise the user peers path. If there is no user directory, then it falls back on the system peers path.

Types

type Peer

type Peer struct {
	PID         uint32 `json:"pid"`                   // the precedence id of the peer
	Name        string `json:"name"`                  // unique name of the peer
	Description string `json:"description,omitempty"` // a text description of the peer
	Hostname    string `json:"hostname,omitempty"`    // the hostname of the peer
	IPAddr      string `json:"ip_address"`            // the ip address of the peer
	Domain      string `json:"domain,omitempty"`      // the domain name of hte host
	Port        uint16 `json:"port"`                  // the port the replica is listening on

	// Extra information that may be associated with the host
	AWSInstance map[string]string `json:"aws_instance,omitempty"`
}

Peer represents a single instance of another replica process or host on the network that can be communicated with.

func (*Peer) Endpoint

func (p *Peer) Endpoint(dns bool) string

Endpoint returns an string with the ip address and the port (or the domain) to connect to the peer using TCP.

func (*Peer) IsLocal

func (p *Peer) IsLocal() bool

IsLocal returns True if the Peer has the same hostname as the localhost. Because the host can be specified as a FQDN, this method splits the name on "." and inspects the first element of the name.

func (*Peer) ZMQEndpoint

func (p *Peer) ZMQEndpoint(server bool) string

ZMQEndpoint returns an endpoint to bind or connect on specifically for the ZMQ protocol, that is a TCP protocol socket on the specified port.

If server is true, then a bind address of tcp://*:port is returned so that messages received on any IP address at that port are handled. If server is false then one of two things happen. If the peer IsLocal() then tcp://localhost:port is returned. Otherwise tcp://IPAddr:port is returned.

type Peers

type Peers struct {
	Info  map[string]interface{} `json:"info"`     // metadata associated with the collection
	Peers []*Peer                `json:"replicas"` // the network peers (also called replicas)
	// contains filtered or unexported fields
}

Peers is a collection of network hosts or processes that can be communicated with, along with associated metadata. The Peers object is the primary interaction with files on disk and exposes methods that select relevent hosts and addresses.

func Load

func Load() *Peers

Load is the primary entry point for the peers package. It uses a list of paths, ordered by priority to find the peers.json file and instantiate the peers object from it. If it does not find a peers.json file it simply returns an empty collection rather than an error.

The lookup paths for the peers.json file are as follows:

- $PEERS_PATH - $PWD/peers.json - $HOME/.fluidfs/peers.json - /etc/fluidfs/peers.json

At the moment, the first path that is available short circuits the load process and all remaining paths are ignored.

func LoadFrom

func LoadFrom(path string) (*Peers, error)

LoadFrom is a secondary entry point for the peers package. It requires a specific path and if there are any errors loading, the error is returned.

func Sync

func Sync() (*Peers, error)

Sync is a helper function that performs a SyncFrom() but looks up the url and api key from the environment, expecting the following:

- $PEERS_SYNC_URL: url endpoint for sync GET request - $PEERS_SYNC_APIKEY: key to add to headers as X-Api-Key

See the SyncFrom function for more details.

func SyncFrom

func SyncFrom(url, apikey string) (*Peers, error)

SyncFrom is a remote entry point for the peers package. It uses an HTTP request to synchronize the peers from a remote host and instantiate the peers collection. It expects a url and an api key to perform the GET request, adding the api key to the headers as "X-Api-Key".

func (*Peers) Dump

func (p *Peers) Dump(path string) error

Dump the peers collection as a JSON file to disk. If an empty string is passed in as an argument, then it will dump to the location on disk it was loaded from.

func (*Peers) Get

func (p *Peers) Get(hostname string) (*Peer, error)

Get a specific peer by name (which should be unique). If the named peer is not found, then an error is returned.

func (*Peers) Load

func (p *Peers) Load(path string) error

Load the peers collection from a JSON file on disk. If the peers are successfully loaded, the path it was loaded from is stored and no error is returned.

func (*Peers) Local

func (p *Peers) Local(hostname string) []*Peer

Local returns the peers that are local to the specified host by comparing the Peer's Host parameter with the hostname. If the hostname is an empty string, then the hostname of the system is used. No errors are returned from this function, instead returning an empty list of not found. Because the Peer's hostname can be a FQDN, the Host is split on "." and the first element is used. If no local replicas are found, it returns an empty list.

func (*Peers) Localhost

func (p *Peers) Localhost(hostname string, pid uint32) (*Peer, error)

Localhost returns the peer that is defined by the current localhost. Note that multiple peers can reside on a single machine, but this method will only return one Peer. Filtering multiple local replicas can be done with a precedence ID. If no ID is specified (e.g. 0) then the first local peer is returned. If no matching peer is found then an error is returned.