seafoam

package module
v0.0.0-...-26ac522 Latest Latest
Warning

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

 Go to latest Published: May 7, 2019 License: Apache-2.0 Imports: 13 Imported by: 0

README

Seafoam

NOTE: Serious bugs may be present in this repository.

GoDoc Go Report Card

Introduction

Seafoam is a fork of Smudge that extends functionality to include leadership, datacenter, and cluster-validity awareness. Seafoam is meant to be a lightweight clustering tool that enables highly scalable and robust platform creation while still maintaining smudge's lightweight nature.

Seafoam utilizes a simple series of polling-election mechanics to prevent split-brain behaviour in largescale applications when under significant load-stress. A side effect of this is that Seafoam requires more setup than smudge, although it can be set to 'fallback mode' in which functionality is essentially identical to that of smudge.

Complete documentation is available from the associated Godoc.

Features

  • Smudge-backed gossip (i.e., epidemic) protocol for dissemination, the latency of which grows logarithmically with the number of members.
  • Supports both IPv4 and IPv6.
  • Pluggable logging
  • Leader-awareness in large clusters
  • Lighthouse-based validity checking
  • Low network bandwidth requirements

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 seafoam.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
---------------------------------- | --------------- | -------------------------------
SEAFOAM_CLUSTER_NAME               |     seafoam     | Cluster name for for multicast discovery
SEAFOAM_HEARTBEAT_MILLIS           |       250       | Milliseconds between heartbeats
SEAFOAM_INITIAL_HOSTS              |                 | Comma-delimmited list of known members as IP or IP:PORT
SEAFOAM_LISTEN_PORT                |       9999      | UDP port to listen on
SEAFOAM_LISTEN_IP                  |    127.0.0.1    | IP address to listen on
SEAFOAM_MAX_BROADCAST_BYTES        |       256       | Maximum byte length of broadcast payloads
SEAFOAM_MULTICAST_ENABLED          |       true      | Multicast announce on startup; listen for multicast announcements
SEAFOAM_MULTICAST_ANNOUNCE_INTERVAL|        0        | Seconds between multicast announcements, 0 will disable subsequent anouncements
SEAFOAM_MULTICAST_ADDRESS          | See description | The multicast broadcast address. Default: `224.0.0.0` (IPv4) or `[ff02::1]` (IPv6)
SEAFOAM_MULTICAST_PORT             |       9998      | The multicast listen port

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 = "SEAFOAM_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 = "seafoam"

	// EnvVarHeartbeatMillis is the name of the environment variable that
	// sets the heartbeat frequency (in millis).
	EnvVarHeartbeatMillis = "SEAFOAM_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 = "SEAFOAM_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 = "SEAFOAM_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 = "SEAFOAM_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 = "SEAFOAM_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 = "SEAFOAM_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 = "SEAFOAM_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 = "SEAFOAM_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 = "SEAFOAM_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 = "SEAFOAM_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 = "SEAFOAM_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

	// DefaultDatacenter is the default DC for seafoam.
	DefaultDatacenter = 255

	// EnvVarDatacenter is the name of the environment variable that
	// defines the Datacenter in which this instance of seafoam resides.
	EnvVarDatacenter = "SEAFOAM_DATACENTER"

	// EnvVarIsLighthouse is the name of the environment variable that
	// defines the Rank in which this instance of seafoam resides.
	EnvVarIsLighthouse = "SEAFOAM_IS_LIGHTHOUSE"
)

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 

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 GetDatacenter 

func GetDatacenter() uint8

GetDatacenter returns the defined Datacenter number.

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 GetIsLighthouse 

func GetIsLighthouse() bool

GetIsLighthouse returns whether this node is a lighthouse.

func GetListenIP 

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 

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 

func GetMulticastAddress() string

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

func GetMulticastAnnounceIntervalSeconds 

func GetMulticastAnnounceIntervalSeconds() int

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

func GetMulticastEnabled 

func GetMulticastEnabled() bool

GetMulticastEnabled returns whether multicast announcements are enabled.

func GetMulticastPort 

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 

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 

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 SetDatacenter 

func SetDatacenter(dc uint8)

SetDatacenter sets the defined Datacenter number.

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 SetIsLighthouse 

func SetIsLighthouse(light bool)

SetIsLighthouse sets whether this node is a lighthouse

func SetListenIP 

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 

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 

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 

func SetMulticastAddress(val string)

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

func SetMulticastAnnounceIntervalSeconds 

func SetMulticastAnnounceIntervalSeconds(val int)

SetMulticastAnnounceIntervalSeconds sets the number of seconds between multicast announcements

func SetMulticastEnabled 

func SetMulticastEnabled(val bool)

SetMulticastEnabled sets whether multicast announcements are enabled.

func SetMulticastPort 

func SetMulticastPort(val int)

SetMulticastPort sets multicast announcement listening port.

func SetPingHistoryFrontload 

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, rank NodeRank, datacenter uint8)

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 

type DefaultLogger struct{}

DefaultLogger is the default logger that is included with Smudge.

func (DefaultLogger) Log 

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 

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 

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) Datacenter 

func (n *Node) Datacenter() uint8

Datacenter returns the DC of the node

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 

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) Rank 

func (n *Node) Rank() NodeRank

Rank returns the NodeRank of the node

func (*Node) Status 

func (n *Node) Status() NodeStatus

Status returns this node's current status.

func (*Node) StatusSource 

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 NodeRank 

type NodeRank uint8
const (
	// Rank Normal indicates nodes that have no rank besides their default.
	RankNormal NodeRank = iota

	// Rank Leader indicates the node who is in charge of the cluster.
	RankLeader

	// Rank Lighthouse indicates a node who MUST be included in the cluster.
	RankLighthouse
)

func (NodeRank) String 

func (r NodeRank) String() string

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.