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 ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
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 ¶
Endpoint returns an string with the ip address and the port (or the domain) to connect to the peer using TCP.
func (*Peer) IsLocal ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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.
Source Files