smudge

package module
v1.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 6, 2020 License: Apache-2.0 Imports: 13 Imported by: 7

README

Smudge

GoDoc Build Status Go Report Card Maintainability

Introduction

Smudge is a minimalist Go implementation of the SWIM (Scalable Weakly-consistent Infection-style Membership) protocol for cluster node membership, status dissemination, and failure detection developed at Cornell University by Motivala, et al. It isn't a distributed data store in its own right, but rather a framework intended to facilitate the construction of such systems.

Smudge also extends the standard SWIM protocol so that in addition to the standard membership status functionality it also allows the transmission of broadcasts containing a small amount (256 bytes) of arbitrary content to all present healthy members. This maximum is related to the limit imposed on maximum safe UDP packet size by RFC 791 and RFC 2460. We recognize that some systems allow larger packets, however, and although that can risk fragmentation and dropped packets the maximum payload size is configurable.

Smudge was conceived with space-sensitive systems (mobile, IoT, containers) in mind, and therefore was developed with a minimalist philosophy of doing a few things well. As such, its feature set is relatively small and mostly limited to functionality around adding and removing nodes and detecting status changes on the cluster.

Complete documentation is available from the associated Godoc.

Features

  • Uses gossip (i.e., epidemic) protocol for dissemination, the latency of which grows logarithmically with the number of members.
  • Low-bandwidth UDP-based failure detection and status dissemination.
  • Imposes a constant message load per group member, regardless of the number of members.
  • Member status changes are eventually detected by all non-faulty members of the cluster (strong completeness).
  • Supports transmission of short broadcasts that are propagated at most once to all present, healthy members.
  • Supports both IPv4 and IPv6.
  • Pluggable logging

Known issues

  • Broadcasts are limited to 256 bytes, or 512 bytes when using IPv6.
  • No WAN support: only local-network, private IPs are supported.
Deviations from Motivala, et al
  • Dead nodes are not immediately removed, but are instead periodically re-tried (with exponential backoff) for a time before finally being removed.
  • Smudge allows the transmission of short, arbitrary-content broadcasts to all healthy nodes.

How broadcasts work

TL;DR a broadcast can be added to the local node by either calling a function or by receiving it from a remote node. A broadcast is send to other nodes a couple of times, piggybacked on membership messages. Then after a while the broadcast is removed from the node.

Emit counter

The emit counter represents the number of times a broadcast message must be send to other nodes. An emit counter is calculated with the following formula: int(2.5 * log(number of nodes) + 0.5). The larger the network the higher the emit counter will be, but the larger the network the slower the emit counter will grow.

Examples:

  • 2 nodes: int(2.5 * log(2) + 0.5) = 2
  • 10 nodes: int(2.5 * log(10) + 0.5) = 6
  • 20 nodes: int(2.5 * log(20) + 0.5) = 8
Broadcasts

When a broadcast is added to Smudge, either because it is added locally (by calling a function of the library) or is received from a remote node, an emit counter initialized with the formula above. The emit counter and the broadcast are then saved to a local buffer.

The emit counter is used to track how many times a broadcast must be send to other nodes in the network. When the emit counter gets below a certain, large negative, thresh-hold the broadcast is removed from the buffer. Only broadcasts with a positive emit counter will be send when they are selected.

When Smudge is about to send a membership message it looks for the broadcast with the largest emit counter. If multiple broadcasts have the same emit counter value, one is arbitrarily chosen. The selected broadcast can have a negative emit counter. If the emit counter is larger then 0 Smudge adds that broadcast to the membership message that will be send. In any case the emit counter is lowered by 1.

When a broadcast is received from another node and that broadcast is already in the buffer it will be ignored. To achieve this the origin IP of the node that added the broadcast to the network is saved as part of the broadcast.

How to build

Although Smudge is intended to be directly extended, a Dockerfile is provided for testing and proofs-of-function.

The Dockerfile uses a multi-stage build, so Docker 17.05 or higher is required. The build compiles the code in a dedicated Golang container and drops the resulting binary into a scratch image for execution. This makes a Makefile or build.sh largely superfluous and removed the need to configure a local environment.

Running the tests

To run the tests in a containerized environment, which requires only that you have Docker installed (not Go), you can do:

make test

Or, if you'd rather not use a Makefile:

go test -v github.com/clockworksoul/smudge
Building the Docker image

To execute the build, you simply need to do the following:

make image

Or, if you'd rather not use a Makefile:

docker build -t clockworksoul/smudge:latest .
Testing the Docker image

You can test Smudge locally using the Docker image. First create a network to use for your Smudge nodes and then add some nodes to the network.

For IPv4 you can use the following commands:

docker network create smudge
docker run -i -t --network smudge --rm clockworksoul/smudge:latest /smudge
# you can add nodes with the following command
docker run -i -t --network smudge --rm clockworksoul/smudge:latest /smudge -node 172.20.0.2

To try out Smudge with IPv6 you can use the following commands:

docker network create --ipv6 --subnet fd02:6b8:b010:9020:1::/80 smudge6
docker run -i -t --network smudge6 --rm clockworksoul/smudge:latest /smudge
# you can add nodes with the following command
docker run -i -t --network smudge6 --rm clockworksoul/smudge:latest /smudge -node [fd02:6b8:b010:9020:1::2]:9999
Building the binary with the Go compiler
Set up your Golang environment

If you already have a $GOPATH set up, you can skip to the following section.

First, you'll need to decide where your Go code and binaries will live. This will be your Gopath. You simply need to export this as GOPATH:

export GOPATH=~/go/

Change it to whatever works for you. You'll want to add this to your .bashrc or .bash_profile.

Clone the repo into your GOPATH

Clone the code into $GOPATH/src/github.com/clockworksoul/smudge. Using the full-qualified path structure makes it possible to import the code into other libraries, as well as Smudge's own main() function.

git clone git@github.com:clockworksoul/smudge.git $GOPATH/src/github.com/clockworksoul/smudge
Execute your build

Once you have a $GOPATH already configured and the repository correctly cloned into $GOPATH/src/github.com/clockworksoul/smudge, you can execute the following:

make build

When using the Makefile, the compiled binary will be present in the /bin directory in the code directory.

If you'd rather not use a Makefile:

go build -a -installsuffix cgo -o smudge github.com/clockworksoul/smudge/smudge

The binary, compiled for your current environment, will be present in your present working directory.

How to use

To use the code, you simply specify a few configuration options (or use the defaults), create and add a node status change listener, and call the smudge.Begin() function.

Configuring the node with environment variables

Perhaps the simplest way of directing the behavior of the SWIM driver is by setting the appropriate system environment variables, which is useful when making use of Smudge inside of a container.

The following variables and their default values are as follows:

Variable                           | Default         | Description
---------------------------------- | --------------- | -------------------------------
SMUDGE_CLUSTER_NAME                |      smudge     | Cluster name for for multicast discovery
SMUDGE_HEARTBEAT_MILLIS            |       250       | Milliseconds between heartbeats
SMUDGE_INITIAL_HOSTS               |                 | Comma-delimmited list of known members as IP or IP:PORT
SMUDGE_LISTEN_PORT                 |       9999      | UDP port to listen on
SMUDGE_LISTEN_IP                   |    127.0.0.1    | IP address to listen on
SMUDGE_MAX_BROADCAST_BYTES         |       256       | Maximum byte length of broadcast payloads
SMUDGE_MULTICAST_ENABLED           |       true      | Multicast announce on startup; listen for multicast announcements
SMUDGE_MULTICAST_ANNOUNCE_INTERVAL |        0        | Seconds between multicast announcements, 0 will disable subsequent anouncements
SMUDGE_MULTICAST_ADDRESS           | See description | The multicast broadcast address. Default: `224.0.0.0` (IPv4) or `[ff02::1]` (IPv6)
SMUDGE_MULTICAST_PORT              |       9998      | The multicast listen port
Configuring the node with API calls

If you prefer to direct the behavior of the service using the API, the calls are relatively straight-forward. Note that setting the application properties using this method overrides the behavior of environment variables.

smudge.SetListenPort(9999)
smudge.SetHeartbeatMillis(250)
smudge.SetListenIP(net.ParseIP("127.0.0.1"))
smudge.SetMaxBroadcastBytes(256) // set to 512 when using IPv6
Creating and adding a status change listener

Creating a status change listener is very straight-forward:

type MyStatusListener struct {
    smudge.StatusListener
}

func (m MyStatusListener) OnChange(node *smudge.Node, status smudge.NodeStatus) {
    fmt.Printf("Node %s is now status %s\n", node.Address(), status)
}

func main() {
    smudge.AddStatusListener(MyStatusListener{})
}
Creating and adding a broadcast listener

Adding a broadcast listener is very similar to creating a status listener:

type MyBroadcastListener struct {
    smudge.BroadcastListener
}

func (m MyBroadcastListener) OnBroadcast(b *smudge.Broadcast) {
    fmt.Printf("Received broadcast from %v: %s\n",
        b.Origin().Address(),
        string(b.Bytes()))
}

func main() {
    smudge.AddBroadcastListener(MyBroadcastListener{})
}
Adding a new member to the "known nodes" list

Adding a new member to your known nodes list will also make that node aware of the adding server. To join an existing cluster without using multicast (or on a network where multicast is disabled) you must use this method to add at least one of that cluster's healthy member nodes.

node, err := smudge.CreateNodeByAddress("localhost:10000")
if err == nil {
    smudge.AddNode(node)
}
Starting the server

Once everything else is done, starting the server is trivial:

Simply call: smudge.Begin()

Transmitting a broadcast

To transmit a broadcast to all healthy nodes currenty in the cluster you can use one of the BroadcastBytes(bytes []byte) or BroadcastString(str string) functions.

Be aware of the following caveats:

  • Attempting to send a broadcast before the server has been started will cause a panic.
  • The broadcast will not be received by the originating member; BroadcastListeners on the originating member will not be triggered.
  • Nodes that join the cluster after the broadcast has been fully propagated will not receive the broadcast; nodes that join after the initial transmission but before complete proagation may or may not receive the broadcast.
Getting a list of nodes

The AllNodes() can be used to get all known nodes; HealthyNodes() works similarly, but returns only healthy nodes (defined as nodes with a status of "alive").

Everything in one place
package main

import "github.com/clockworksoul/smudge"
import "fmt"
import "net"

type MyStatusListener struct {
    smudge.StatusListener
}

func (m MyStatusListener) OnChange(node *smudge.Node, status smudge.NodeStatus) {
    fmt.Printf("Node %s is now status %s\n", node.Address(), status)
}

type MyBroadcastListener struct {
    smudge.BroadcastListener
}

func (m MyBroadcastListener) OnBroadcast(b *smudge.Broadcast) {
    fmt.Printf("Received broadcast from %s: %s\n",
        b.Origin().Address(),
        string(b.Bytes()))
}

func main() {
    heartbeatMillis := 500
    listenPort := 9999

    // Set configuration options
    smudge.SetListenPort(listenPort)
    smudge.SetHeartbeatMillis(heartbeatMillis)
    smudge.SetListenIP(net.ParseIP("127.0.0.1"))

    // Add the status listener
    smudge.AddStatusListener(MyStatusListener{})

    // Add the broadcast listener
    smudge.AddBroadcastListener(MyBroadcastListener{})

    // Add a new remote node. Currently, to join an existing cluster you must
    // add at least one of its healthy member nodes.
    node, err := smudge.CreateNodeByAddress("localhost:10000")
    if err == nil {
        smudge.AddNode(node)
    }

    // Start the server!
    smudge.Begin()
}
Bringing your own logger

Smudge comes with a DefaultLogger that writes log messages to stderr. You can plug in your own logger by implementing the functions of the Logger interface and setting the logger by calling smudge.SetLogger(MyCoolLogger).

Documentation

Index

Constants

View Source 
const (
	// PingNoData is returned by n.PingMillis() to indicate that a node has
	// not yet been pinged, and therefore no ping data exists.
	PingNoData int = -1

	// PingTimedOut is returned by n.PingMillis() to indicate that a node's
	// last PING timed out. This is the typical value for dead nodes.
	PingTimedOut int = -2
)
View Source 
const (
	// EnvVarClusterName is the name of the environment variable the defines
	// the name of the cluster. Multicast messages from differently-named
	// instances are ignored.
	EnvVarClusterName = "SMUDGE_CLUSTER_NAME"

	// DefaultClusterName is the default name of the cluster for the purposes
	// of multicast announcements: multicast messages from differently-named
	// instances are ignored.
	DefaultClusterName string = "smudge"

	// EnvVarHeartbeatMillis is the name of the environment variable that
	// sets the heartbeat frequency (in millis).
	EnvVarHeartbeatMillis = "SMUDGE_HEARTBEAT_MILLIS"

	// DefaultHeartbeatMillis is the default heartbeat frequency (in millis).
	DefaultHeartbeatMillis int = 500

	// EnvVarInitialHosts is the name of the environment variable that sets
	// the initial known hosts. The value it sets should be a comma-delimitted
	// string of one or more IP:PORT pairs (port is optional if it matched the
	// value of SMUDGE_LISTEN_PORT).
	EnvVarInitialHosts = "SMUDGE_INITIAL_HOSTS"

	// DefaultInitialHosts default lists of initially known hosts.
	DefaultInitialHosts string = ""

	// EnvVarListenPort is the name of the environment variable that sets
	// the UDP listen port.
	EnvVarListenPort = "SMUDGE_LISTEN_PORT"

	// DefaultListenPort is the default UDP listen port.
	DefaultListenPort int = 9999

	// EnvVarListenIP is the name of the environment variable that sets
	// the listen IP.
	EnvVarListenIP = "SMUDGE_LISTEN_IP"

	// DefaultListenIP is the default listen IP.
	DefaultListenIP = "127.0.0.1"

	// EnvVarMaxBroadcastBytes is the name of the environment variable that
	// the maximum byte length for broadcast payloads. Note that increasing
	// this runs the risk of packet fragmentation and dropped messages.
	EnvVarMaxBroadcastBytes = "SMUDGE_MAX_BROADCAST_BYTES"

	// DefaultMaxBroadcastBytes is the default maximum byte length for
	// broadcast payloads. This is guided by the maximum safe UDP packet size
	// of 508 bytes, which must also contain status updates and additional
	// message overhead.
	DefaultMaxBroadcastBytes int = 256

	// EnvVarMulticastAddress is the name of the environment variable that
	// defines the multicast address that will be used.
	EnvVarMulticastAddress = "SMUDGE_MULTICAST_ADDRESS"

	// DefaultMulticastAddress is the default multicast address. Empty string
	// indicates 224.0.0.0 for IPv4 and [ff02::1] for IPv6.
	DefaultMulticastAddress string = ""

	// EnvVarMulticastEnabled is the name of the environment variable that
	// describes whether Smudge will attempt to announce its presence via
	// multicast on startup.
	EnvVarMulticastEnabled = "SMUDGE_MULTICAST_ENABLED"

	// DefaultMulticastEnabled is the default value for whether Smudge will
	// attempt to announce its presence via multicast on startup.
	DefaultMulticastEnabled string = "true"

	// EnvVarMulticastAnnounceIntervalSeconds is the name of the environment
	// variable that describes whether Smudge will attempt to re-announce its
	// presence via multicast every X seconds.
	EnvVarMulticastAnnounceIntervalSeconds = "SMUDGE_MULTICAST_ANNOUNCE_INTERVAL"

	// DefaultMulticastAnnounceIntervalSeconds is the default value for whether
	// Smudge will re-announce its presence via multicast
	DefaultMulticastAnnounceIntervalSeconds = 0

	// EnvVarMulticastPort is the name of the environment variable that
	// defines the multicast announcement listening port.
	EnvVarMulticastPort = "SMUDGE_MULTICAST_PORT"

	// DefaultMulticastPort is the default value for the multicast
	// listening port.
	DefaultMulticastPort int = 9998

	// EnvVarPingHistoryFrontload is the name of the environment variable that
	// defines the value (in milliseconds) used to pre-populate the ping
	// history buffer, which is used to dynamically calculate ping timeouts and
	// is gradually overwritten with real data over time.
	EnvVarPingHistoryFrontload = "SMUDGE_PING_HISTORY_FRONTLOAD"

	// DefaultPingHistoryFrontload is the default value (in milliseconds) used
	// to pre-populate the ping history buffer, which is used to dynamically
	// calculate ping timeouts and is gradually overwritten with real data
	// over time.
	DefaultPingHistoryFrontload = 200

	// EnvVarMinPingTime is the name of the environment variable that
	// defines the lower bound on recorded ping response times (in
	// milliseconds). This prevents the system instability and flapping that
	// can come from consistently small values.
	EnvVarMinPingTime = "SMUDGE_MIN_PING_TIME"

	// DefaultMinPingTime is default lower bound on recorded ping response
	// times (in milliseconds). This prevents the system instability and
	// flapping that can come from consistently small values.
	DefaultMinPingTime = 150
)

Variables

This section is empty.

Functions

func AddBroadcastListener 

func AddBroadcastListener(listener BroadcastListener)

AddBroadcastListener allows the submission of a BroadcastListener implementation whose OnChange() function will be called whenever the node is notified of any change in the status of a cluster member.

func AddStatusListener 

func AddStatusListener(listener StatusListener)

AddStatusListener allows the submission of a StatusListener implementation whose OnChange() function will be called whenever the node is notified of any change in the status of a cluster member.

func Begin 

func Begin()

Begin starts the server by opening a UDP port and beginning the heartbeat. Note that this is a blocking function, so act appropriately.

func BroadcastBytes 

func BroadcastBytes(bytes []byte) error

BroadcastBytes allows a user to emit a short broadcast in the form of a byte slice, which will be transmitted at most once to all other healthy current members. Members that join after the broadcast has already propagated through the cluster will not receive the message. The maximum broadcast length is 256 bytes.

func BroadcastString 

func BroadcastString(str string) error

BroadcastString allows a user to emit a short broadcast in the form of a string, which will be transmitted at most once to all other healthy current members. Members that join after the broadcast has already propagated through the cluster will not receive the message. The maximum broadcast length is 256 bytes.

func GetClusterName added in v1.0.0 

func GetClusterName() string

GetClusterName gets the name of the cluster for the purposes of multicast announcements: multicast messages from differently-named instances are ignored.

func GetHeartbeatMillis 

func GetHeartbeatMillis() int

GetHeartbeatMillis gets this host's heartbeat frequency in milliseconds.

func GetInitialHosts 

func GetInitialHosts() []string

GetInitialHosts returns the list of initially known hosts.

func GetListenIP added in v1.0.0 

func GetListenIP() net.IP

GetListenIP returns the IP that this host will listen on.

func GetListenPort 

func GetListenPort() int

GetListenPort returns the port that this host will listen on.

func GetLocalIP 

func GetLocalIP() (net.IP, error)

GetLocalIP queries the host interface to determine the local IP address of this machine. If a local IP address cannot be found, then nil is returned. Local IPv6 address takes presedence over a local IPv4 address. If the query to the underlying OS fails, an error is returned.

func GetMaxBroadcastBytes 

func GetMaxBroadcastBytes() int

GetMaxBroadcastBytes returns the maximum byte length for broadcast payloads.

func GetMinPingTime added in v1.0.0 

func GetMinPingTime() int

GetMinPingTime returns the minimum ping response time in milliseconds. Ping response times below this value are recorded as this minimum.

func GetMulticastAddress added in v1.0.0 

func GetMulticastAddress() string

GetMulticastAddress returns the address the will be used for multicast announcements.

func GetMulticastAnnounceIntervalSeconds added in v1.0.0 

func GetMulticastAnnounceIntervalSeconds() int

GetMulticastAnnounceIntervalSeconds returns the amount of seconds to wait between multicast announcements.

func GetMulticastEnabled added in v1.0.0 

func GetMulticastEnabled() bool

GetMulticastEnabled returns whether multicast announcements are enabled.

func GetMulticastPort added in v1.0.0 

func GetMulticastPort() int

GetMulticastPort returns the defined multicast announcement listening port.

func GetNowInMillis 

func GetNowInMillis() uint32

GetNowInMillis returns the current local time in milliseconds since the epoch.

func GetPingHistoryFrontload added in v1.0.0 

func GetPingHistoryFrontload() int

GetPingHistoryFrontload returns the value (in milliseconds) used to pre-populate the ping history buffer, which is used to dynamically calculate ping timeouts and is gradually overwritten with real data over time.

func PingNode 

func PingNode(node *Node) error

PingNode can be used to explicitly ping a node. Calls the low-level doPingNode(), and outputs a message (and returns an error) if it fails.

func SetClusterName added in v1.0.0 

func SetClusterName(val string)

SetClusterName sets the name of the cluster for the purposes of multicast announcements: multicast messages from differently-named instances are ignored.

func SetHeartbeatMillis 

func SetHeartbeatMillis(val int)

SetHeartbeatMillis sets this nodes heartbeat frequency. Unlike SetListenPort(), calling this function after Begin() has been called will have an effect.

func SetListenIP added in v1.0.0 

func SetListenIP(val net.IP)

SetListenIP sets the IP to listen on. It has no effect once Begin() has been called.

func SetListenPort 

func SetListenPort(val int)

SetListenPort sets the UDP port to listen on. It has no effect once Begin() has been called.

func SetLogThreshold 

func SetLogThreshold(level LogLevel)

SetLogThreshold allows the output noise level to be adjusted by setting the logging priority threshold.

func SetLogger added in v1.0.0 

func SetLogger(l Logger)

SetLogger plugs in another logger to control the output of the library

func SetMaxBroadcastBytes 

func SetMaxBroadcastBytes(val int)

SetMaxBroadcastBytes sets the maximum byte length for broadcast payloads. Note that increasing this beyond the default of 256 runs the risk of packet fragmentation and dropped messages.

func SetMinPingTime added in v1.0.0 

func SetMinPingTime(val int)

SetMinPingTime sets the minimum ping response time in milliseconds. Ping response times below this value are recorded as this minimum.

func SetMulticastAddress added in v1.0.0 

func SetMulticastAddress(val string)

SetMulticastAddress sets the address that will be used for multicast announcements.

func SetMulticastAnnounceIntervalSeconds added in v1.0.0 

func SetMulticastAnnounceIntervalSeconds(val int)

SetMulticastAnnounceIntervalSeconds sets the number of seconds between multicast announcements

func SetMulticastEnabled added in v1.0.0 

func SetMulticastEnabled(val bool)

SetMulticastEnabled sets whether multicast announcements are enabled.

func SetMulticastPort added in v1.0.0 

func SetMulticastPort(val int)

SetMulticastPort sets multicast announcement listening port.

func SetPingHistoryFrontload added in v1.0.0 

func SetPingHistoryFrontload(val int)

SetPingHistoryFrontload sets the value (in milliseconds) used to pre-populate the ping history buffer, which is used to dynamically calculate ping timeouts and is gradually overwritten with real data over time. Setting this to 0 will restore the default value.

func UpdateNodeStatus 

func UpdateNodeStatus(node *Node, status NodeStatus, statusSource *Node)

UpdateNodeStatus assigns a new status for the specified node and adds it to the list of recently updated nodes. If the status is StatusDead, then the node will be moved from the live nodes list to the dead nodes list.

Types

type Broadcast 

type Broadcast struct {
	// contains filtered or unexported fields
}

Broadcast represents a packet of bytes emitted across the cluster on top of the status update infrastructure. Although useful, its payload is limited to only 256 bytes.

func (*Broadcast) Bytes 

func (b *Broadcast) Bytes() []byte

Bytes returns a copy of this broadcast's bytes. Manipulating the contents of this slice will not be reflected in the contents of the broadcast.

func (*Broadcast) Index 

func (b *Broadcast) Index() uint32

Index returns the origin message index for this broadcast. This value is incremented for each broadcast. The combination of originIP:originPort:Index is unique.

func (*Broadcast) Label 

func (b *Broadcast) Label() string

Label returns a unique label string composed of originIP:originPort:Index.

func (*Broadcast) Origin 

func (b *Broadcast) Origin() *Node

Origin returns the node that this broadcast originated from.

type BroadcastListener 

type BroadcastListener interface {
	// The OnBroadcast() function is called whenever the node is notified of
	// an incoming broadcast message.
	OnBroadcast(broadcast *Broadcast)
}

BroadcastListener is the interface that must be implemented to take advantage of the cluster member status update notification functionality provided by the AddBroadcastListener() function.

type DefaultLogger added in v1.0.0 

type DefaultLogger struct{}

DefaultLogger is the default logger that is included with Smudge.

func (DefaultLogger) Log added in v1.0.0 

func (d DefaultLogger) Log(level LogLevel, a ...interface{}) (n int, err error)

Log writes a log message of a certain level to the logger

func (DefaultLogger) Logf added in v1.0.0 

func (d DefaultLogger) Logf(level LogLevel, format string, a ...interface{}) (n int, err error)

Logf writes a log message with a specific format to the logger

type LogLevel 

type LogLevel byte

LogLevel represents a logging levels to be used as a parameter passed to the SetLogThreshhold() function. 

const (
	// LogAll allows all log output of all levels to be emitted.
	LogAll LogLevel = iota

	// LogTrace restricts log output to trace level and above.
	LogTrace

	// LogDebug restricts log output to debug level and above.
	LogDebug

	// LogInfo restricts log output to info level and above.
	LogInfo

	// LogWarn restricts log output to warn level and above.
	LogWarn

	// LogError restricts log output to error level and above.
	LogError

	// LogFatal restricts log output to fatal level.
	LogFatal

	// LogOff prevents all log output entirely.
	LogOff
)

func (LogLevel) String 

func (s LogLevel) String() string

type Logger added in v1.0.0 

type Logger interface {
	Log(level LogLevel, a ...interface{}) (int, error)
	Logf(level LogLevel, format string, a ...interface{}) (int, error)
}

Logger should be implemented by Logger's that are passed via SetLogger.

type Node 

type Node struct {
	// contains filtered or unexported fields
}

Node represents a single node in the cluster and its status

func AddNode 

func AddNode(node *Node) (*Node, error)

AddNode can be used to explicitly add a node to the list of known live nodes. Updates the node timestamp but DOES NOT implicitly update the node's status; you need to do this explicitly.

func AllNodes 

func AllNodes() []*Node

AllNodes will return a list of all nodes known at the time of the request, including nodes that have been marked as "dead" but haven't yet been removed from the registry.

func CreateNodeByAddress 

func CreateNodeByAddress(address string) (*Node, error)

CreateNodeByAddress will create and return a new node when supplied with a node address ("ip:port" string). This doesn't add the node to the list of live nodes; use AddNode().

func CreateNodeByIP 

func CreateNodeByIP(ip net.IP, port uint16) (*Node, error)

CreateNodeByIP will create and return a new node when supplied with an IP address and port number. This doesn't add the node to the list of live nodes; use AddNode().

func HealthyNodes 

func HealthyNodes() []*Node

HealthyNodes will return a list of all nodes known at the time of the request with a healthy status.

func RemoveNode 

func RemoveNode(node *Node) (*Node, error)

RemoveNode can be used to explicitly remove a node from the list of known live nodes. Updates the node timestamp but DOES NOT implicitly update the node's status; you need to do this explicitly.

func (*Node) Address 

func (n *Node) Address() string

Address rReturns the address for this node in string format, which is simply the node's local IP and listen port. This is used as a unique identifier throughout the code base.

func (*Node) Age 

func (n *Node) Age() uint32

Age returns the time since we last heard from this node, in milliseconds.

func (*Node) EmitCounter 

func (n *Node) EmitCounter() int8

EmitCounter returns the number of times remaining that current status will be emitted by this node to other nodes.

func (*Node) IP 

func (n *Node) IP() net.IP

IP returns the IP associated with this node.

func (*Node) PingMillis added in v1.0.0 

func (n *Node) PingMillis() int

PingMillis returns the milliseconds transpired between the most recent PING to this node and its responded ACK. If this node has not yet been pinged, this vaue will be PingNoData (-1). If this node's last PING timed out, this value will be PingTimedOut (-2).

func (*Node) Port 

func (n *Node) Port() uint16

Port returns the port associated with this node.

func (*Node) Status 

func (n *Node) Status() NodeStatus

Status returns this node's current status.

func (*Node) StatusSource added in v1.0.0 

func (n *Node) StatusSource() *Node

StatusSource returns a pointer to the node that originally stated this node's Status; the source of the gossip.

func (*Node) Timestamp 

func (n *Node) Timestamp() uint32

Timestamp returns the timestamp of this node's last ping or status update, in milliseconds from the epoch

func (*Node) Touch 

func (n *Node) Touch()

Touch updates the timestamp to the local time in milliseconds.

type NodeStatus 

type NodeStatus byte

NodeStatus represents the believed status of a member node. 

const (
	// StatusUnknown is the default node status of newly-created nodes.
	StatusUnknown NodeStatus = iota

	// StatusAlive indicates that a node is alive and healthy.
	StatusAlive

	// StatusSuspected indicatates that a node is suspected of being dead.
	StatusSuspected

	// StatusDead indicatates that a node is dead and no longer healthy.
	StatusDead

	// StatusForwardTo is a pseudo status used by message to indicate
	// the target of a ping request.
	StatusForwardTo
)

func (NodeStatus) String 

func (s NodeStatus) String() string

type StatusListener 

type StatusListener interface {
	// The OnChange() function is called whenever the node is notified of any
	// change in the status of a cluster member.
	OnChange(node *Node, status NodeStatus)
}

StatusListener is the interface that must be implemented to take advantage of the cluster member status update notification functionality provided by the AddStatusListener() function.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.