mesh

package module
v0.0.0-...-3b404ea Latest Latest
Warning

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

 Go to latest Published: Mar 24, 2023 License: Apache-2.0 Imports: 19 Imported by: 0

README

mesh GoDoc Circle CI

Mesh is a tool for building distributed applications.

Mesh implements a gossip protocol that provide membership, unicast, and broadcast functionality with eventually-consistent semantics. In CAP terms, it is AP: highly-available and partition-tolerant.

Mesh works in a wide variety of network setups, including thru NAT and firewalls, and across clouds and datacenters. It works in situations where there is only partial connectivity, i.e. data is transparently routed across multiple hops when there is no direct connection between peers. It copes with partitions and partial network failure. It can be easily bootstrapped, typically only requiring knowledge of a single existing peer in the mesh to join. It has built-in shared-secret authentication and encryption. It scales to on the order of 100 peers, and has no dependencies.

Using

Mesh is currently distributed as a Go package. See the API documentation.

We plan to offer Mesh as a standalone service + an easy-to-use API. We will support multiple deployment scenarios, including as a standalone binary, as a container, as an ambassador or sidecar component to an existing container, and as an infrastructure service in popular platforms.

Developing

Mesh builds with the standard Go tooling. You will need to put the repository in Go's expected directory structure; i.e., $GOPATH/src/github.com/csghh/mesh.

Building

If necessary, you may fetch the latest version of all of the dependencies into your GOPATH via

go get -d -u -t ./...

Build the code with the usual

go install ./...

Testing

Assuming you've fetched dependencies as above,

go test ./...

Dependencies

Mesh is a library, designed to be imported into a binary package. Vendoring is currently the best way for binary package authors to ensure reliable, reproducible builds. Therefore, we strongly recommend our users use vendoring for all of their dependencies, including Mesh. To avoid compatibility and availability issues, Mesh doesn't vendor its own dependencies, and doesn't recommend use of third-party import proxies.

There are several tools to make vendoring easier, including gb, gvt, glide, and govendor.

Workflow

Mesh follows a typical PR workflow. All contributions should be made as pull requests that satisfy the guidelines, below.

Guidelines
  • All code must abide Go Code Review Comments
  • Names should abide What's in a name
  • Code must build on both Linux and Darwin, via plain go build
  • Code should have appropriate test coverage, invoked via plain go test

In addition, several mechanical checks are enforced. See the lint script for details.

Getting Help

If you have any questions about, feedback for or problems with mesh:

Your feedback is always welcome!

Documentation

Index

Constants

View Source 
const (
	// PeerNameFlavour is the type of peer names we use.
	PeerNameFlavour = "mac"

	// NameSize is the number of bytes in a peer name.
	NameSize = 6

	// UnknownPeerName is used as a sentinel value.
	UnknownPeerName = PeerName(0)
)
View Source 
const (
	// Protocol identifies a sort of major version of the protocol.
	Protocol = "weave"

	// ProtocolMinVersion establishes the lowest protocol version among peers
	// that we're willing to try to communicate with.
	ProtocolMinVersion = 1

	// ProtocolMaxVersion establishes the highest protocol version among peers
	// that we're willing to try to communicate with.
	ProtocolMaxVersion = 2
)
View Source 
const (
	// ProtocolHeartbeat identifies a heartbeat msg.
	ProtocolHeartbeat = iota
	// ProtocolReserved1 is a legacy overly control message.
	ProtocolReserved1
	// ProtocolReserved2 is a legacy overly control message.
	ProtocolReserved2
	// ProtocolReserved3 is a legacy overly control message.
	ProtocolReserved3
	// ProtocolGossip identifies a pure gossip msg.
	ProtocolGossip
	// ProtocolGossipUnicast identifies a gossip (unicast) msg.
	ProtocolGossipUnicast
	// ProtocolGossipBroadcast identifies a gossip (broadcast) msg.
	ProtocolGossipBroadcast
	// ProtocolOverlayControlMsg identifies a control msg.
	ProtocolOverlayControlMsg
)

Variables

View Source 
var (
	// Port is the port used for all mesh communication.
	Port = 6783

	// ChannelSize is the buffer size used by so-called actor goroutines
	// throughout mesh.
	ChannelSize = 16
)

Functions

This section is empty.

Types

type Config 

type Config struct {
	Host               string
	Port               int
	Password           []byte
	ConnLimit          int
	ProtocolMinVersion byte
	PeerDiscovery      bool
	TrustedSubnets     []*net.IPNet
	GossipInterval     *time.Duration
	// SingleHopTopolgy is used to indicate a topology of nodes participating
	// in the mesh where each node is fully connected to other nodes
	SingleHopTopolgy bool
}

Config defines dimensions of configuration for the router. TODO(pb): provide usable defaults in NewRouter

type Connection 

type Connection interface {
	Remote() *Peer
	// contains filtered or unexported methods
}

Connection describes a link between peers. It may be in any state, not necessarily established.

type Gossip 

type Gossip interface {
	// GossipUnicast emits a single message to a peer in the mesh.
	//
	// TODO(pb): rename to Unicast?
	//
	// Unicast takes []byte instead of GossipData because "to date there has
	// been no compelling reason [in practice] to do merging on unicast."
	// But there may be some motivation to have unicast Mergeable; see
	// https://github.com/weaveworks/weave/issues/1764
	//
	// TODO(pb): for uniformity of interface, rather take GossipData?
	GossipUnicast(dst PeerName, msg []byte) error

	// GossipBroadcast emits a message to all peers in the mesh.
	//
	// TODO(pb): rename to Broadcast?
	GossipBroadcast(update GossipData)

	// GossipNeighbourSubset emits a message to subset of neighbour peers in the mesh.
	GossipNeighbourSubset(update GossipData)
}

Gossip is the sending interface.

TODO(pb): rename to e.g. Sender

type GossipData 

type GossipData interface {
	// Encode encodes the data into multiple byte-slices.
	Encode() [][]byte

	// Merge combines another GossipData into this one and returns the result.
	//
	// TODO(pb): does it need to be leave the original unmodified?
	Merge(GossipData) GossipData
}

GossipData is a merge-able dataset. Think: log-structured data.

type Gossiper 

type Gossiper interface {
	// OnGossipUnicast merges received data into state.
	//
	// TODO(pb): rename to e.g. OnUnicast
	OnGossipUnicast(src PeerName, msg []byte) error

	// OnGossipBroadcast merges received data into state and returns a
	// representation of the received data (typically a delta) for further
	// propagation.
	//
	// TODO(pb): rename to e.g. OnBroadcast
	OnGossipBroadcast(src PeerName, update []byte) (received GossipData, err error)

	// Gossip returns the state of everything we know; gets called periodically.
	Gossip() (complete GossipData)

	// OnGossip merges received data into state and returns "everything new
	// I've just learnt", or nil if nothing in the received data was new.
	OnGossip(msg []byte) (delta GossipData, err error)
}

Gossiper is the receiving interface.

TODO(pb): rename to e.g. Receiver

type GossiperMaker 

type GossiperMaker interface {
	MakeGossiper(channelName string, router *Router) Gossiper
}

GossiperMaker is an interface to create a Gossiper instance

type LocalConnection 

type LocalConnection struct {
	OverlayConn OverlayConnection
	// contains filtered or unexported fields
}

LocalConnection is the local (our) side of a connection. It implements ProtocolSender, and manages per-channel GossipSenders.

func (*LocalConnection) Remote 

func (conn *LocalConnection) Remote() *Peer

func (*LocalConnection) SendProtocolMsg 

func (conn *LocalConnection) SendProtocolMsg(m protocolMsg) error

SendProtocolMsg implements ProtocolSender.

type LocalConnectionStatus 

type LocalConnectionStatus struct {
	Address  string
	Outbound bool
	State    string
	Info     string
	Attrs    map[string]interface{}
}

LocalConnectionStatus is the current state of a physical connection to a peer.

type Logger 

type Logger interface {
	Printf(format string, args ...interface{})
}

Logger is a simple interface used by mesh to do logging.

type NullOverlay 

type NullOverlay struct{}

NullOverlay implements Overlay and OverlayConnection with no-ops.

func (NullOverlay) AddFeaturesTo 

func (NullOverlay) AddFeaturesTo(map[string]string)

AddFeaturesTo implements Overlay.

func (NullOverlay) Attrs 

func (NullOverlay) Attrs() map[string]interface{}

Attrs implements OverlayConnection.

func (NullOverlay) Confirm 

func (NullOverlay) Confirm()

Confirm implements OverlayConnection.

func (NullOverlay) ControlMessage 

func (NullOverlay) ControlMessage(byte, []byte)

ControlMessage implements OverlayConnection.

func (NullOverlay) Diagnostics 

func (NullOverlay) Diagnostics() interface{}

Diagnostics implements Overlay.

func (NullOverlay) ErrorChannel 

func (NullOverlay) ErrorChannel() <-chan error

ErrorChannel implements OverlayConnection.

func (NullOverlay) EstablishedChannel 

func (NullOverlay) EstablishedChannel() <-chan struct{}

EstablishedChannel implements OverlayConnection.

func (NullOverlay) PrepareConnection 

func (NullOverlay) PrepareConnection(OverlayConnectionParams) (OverlayConnection, error)

PrepareConnection implements Overlay.

func (NullOverlay) Stop 

func (NullOverlay) Stop()

Stop implements OverlayConnection.

type Overlay 

type Overlay interface {
	// Enhance a features map with overlay-related features.
	AddFeaturesTo(map[string]string)

	// Prepare on overlay connection. The connection should remain
	// passive until it has been Confirm()ed.
	PrepareConnection(OverlayConnectionParams) (OverlayConnection, error)

	// Obtain diagnostic information specific to the overlay.
	Diagnostics() interface{}

	// Stop the overlay.
	Stop()
}

Overlay yields OverlayConnections.

type OverlayConnection 

type OverlayConnection interface {
	// Confirm that the connection is really wanted, and so the
	// Overlay should begin heartbeats etc. to verify the operation of
	// the overlay connection.
	Confirm()

	// EstablishedChannel returns a channel that will be closed when the
	// overlay connection is established, i.e. its operation has been
	// confirmed.
	EstablishedChannel() <-chan struct{}

	// ErrorChannel returns a channel that forwards errors from the overlay
	// connection. The overlay connection is not expected to be operational
	// after the first error, so the channel only needs to buffer a single
	// error.
	ErrorChannel() <-chan error

	// Stop terminates the connection.
	Stop()

	// ControlMessage handles a message from the remote peer. 'tag' exists for
	// compatibility, and should always be ProtocolOverlayControlMessage for
	// non-sleeve overlays.
	ControlMessage(tag byte, msg []byte)

	// Attrs returns the user-facing overlay name plus any other
	// data that users may wish to check or monitor
	Attrs() map[string]interface{}
}

OverlayConnection describes all of the machinery to manage overlay connectivity to a particular peer.

type OverlayConnectionParams 

type OverlayConnectionParams struct {
	RemotePeer *Peer

	// The local address of the corresponding TCP connection. Used to
	// derive the local IP address for sending. May differ for
	// different overlay connections.
	LocalAddr *net.TCPAddr

	// The remote address of the corresponding TCP connection. Used to
	// determine the address to send to, but only if the TCP
	// connection is outbound. Otherwise the Overlay needs to discover
	// it (e.g. from incoming datagrams).
	RemoteAddr *net.TCPAddr

	// Is the corresponding TCP connection outbound?
	Outbound bool

	// Unique identifier for this connection
	ConnUID uint64

	// Session key, if connection is encrypted; nil otherwise.
	//
	// NB: overlay connections must take care not to use nonces which
	// may collide with those of the main connection. These nonces are
	// 192 bits, with the top most bit unspecified, the next bit set
	// to 1, followed by 126 zero bits, and a message sequence number
	// in the lowest 64 bits.
	SessionKey *[32]byte

	// Function to send a control message to the counterpart
	// overlay connection.
	SendControlMessage func(tag byte, msg []byte) error

	// Features passed at connection initiation
	Features map[string]string
}

OverlayConnectionParams are used to set up overlay connections.

type Peer 

type Peer struct {
	Name PeerName
	// contains filtered or unexported fields
}

Peer is a local representation of a peer, including connections to other peers. By itself, it is a remote peer.

func (*Peer) String 

func (peer *Peer) String() string

String returns the peer name and nickname.

type PeerDescription 

type PeerDescription struct {
	Name           PeerName
	NickName       string
	UID            PeerUID
	Self           bool
	NumConnections int
}

PeerDescription collects information about peers that is useful to clients.

type PeerName 

type PeerName uint64

PeerName is used as a map key. Since net.HardwareAddr isn't suitable for that - it's a slice, and slices can't be map keys - we convert that to/from uint64.

func PeerNameFromBin 

func PeerNameFromBin(nameByte []byte) PeerName

PeerNameFromBin parses PeerName from a byte slice.

func PeerNameFromString 

func PeerNameFromString(nameStr string) (PeerName, error)

PeerNameFromString parses PeerName from a generic string.

func PeerNameFromUserInput 

func PeerNameFromUserInput(userInput string) (PeerName, error)

PeerNameFromUserInput parses PeerName from a user-provided string.

func (PeerName) String 

func (name PeerName) String() string

String encodes PeerName as a string.

type PeerShortID 

type PeerShortID uint16

PeerShortID exists for the sake of fast datapath. They are 12 bits, randomly assigned, but we detect and recover from collisions. This does limit us to 4096 peers, but that should be sufficient for a while.

type PeerStatus 

type PeerStatus struct {
	Name        string
	NickName    string
	UID         PeerUID
	ShortID     PeerShortID
	Version     uint64
	Connections []connectionStatus
}

PeerStatus is the current state of a peer in the mesh.

type PeerUID 

type PeerUID uint64

PeerUID uniquely identifies a peer in a mesh.

type Peers 

type Peers struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

Peers collects all of the known peers in the mesh, including ourself.

func (*Peers) Descriptions 

func (peers *Peers) Descriptions() []PeerDescription

Descriptions returns descriptions for all known peers.

func (*Peers) Fetch 

func (peers *Peers) Fetch(name PeerName) *Peer

Fetch returns a peer matching the passed name, without incrementing its refcount. If no matching peer is found, Fetch returns nil.

func (*Peers) FetchByShortID 

func (peers *Peers) FetchByShortID(shortID PeerShortID) *Peer

FetchByShortID returns a peer matching the passed short ID. If no matching peer is found, FetchByShortID returns nil.

func (*Peers) GarbageCollect 

func (peers *Peers) GarbageCollect()

GarbageCollect takes a lock, triggers a GC, and invokes the accumulated GC callbacks.

func (*Peers) OnGC 

func (peers *Peers) OnGC(callback func(*Peer))

OnGC adds a new function to be set of functions that will be executed on all subsequent GC runs, receiving the GC'd peer.

func (*Peers) OnInvalidateShortIDs 

func (peers *Peers) OnInvalidateShortIDs(callback func())

OnInvalidateShortIDs adds a new function to a set of functions that will be executed on all subsequent GC runs, when the mapping from short IDs to peers has changed.

type Router 

type Router struct {
	Config
	Overlay         Overlay
	Ourself         *localPeer
	Peers           *Peers
	Routes          *routes
	ConnectionMaker *connectionMaker
	GossiperMaker   GossiperMaker
	// contains filtered or unexported fields
}

Router manages communication between this peer and the rest of the mesh. Router implements Gossiper.

func NewRouter 

func NewRouter(config Config, name PeerName, nickName string, overlay Overlay, logger Logger) (*Router, error)

NewRouter returns a new router. It must be started.

func (*Router) GetGossip 

func (router *Router) GetGossip(channelName string) Gossip

GetGossip returns a GossipChannel from the router, or nil if the channel has not been seen/created

func (*Router) Gossip 

func (router *Router) Gossip() GossipData

Gossip yields the current topology as GossipData.

func (*Router) NewGossip 

func (router *Router) NewGossip(channelName string, g Gossiper) (Gossip, error)

NewGossip returns a usable GossipChannel from the router.

TODO(pb): rename?

func (*Router) OnGossip 

func (router *Router) OnGossip(update []byte) (GossipData, error)

OnGossip receives broadcasts of TopologyGossipData. It returns an "improved" version of the received update. See peers.ApplyUpdate.

func (*Router) OnGossipBroadcast 

func (router *Router) OnGossipBroadcast(_ PeerName, update []byte) (GossipData, error)

OnGossipBroadcast receives broadcasts of TopologyGossipData. It returns the received update unchanged.

func (*Router) OnGossipUnicast 

func (router *Router) OnGossipUnicast(sender PeerName, msg []byte) error

OnGossipUnicast implements Gossiper, but always returns an error, as a router should only receive gossip broadcasts of TopologyGossipData.

func (*Router) Start 

func (router *Router) Start()

Start listening for TCP connections. This is separate from NewRouter so that gossipers can register before we start forming connections.

func (*Router) Stop 

func (router *Router) Stop() error

Stop shuts down the router.

type Status 

type Status struct {
	Protocol           string
	ProtocolMinVersion int
	ProtocolMaxVersion int
	Encryption         bool
	PeerDiscovery      bool
	Name               string
	NickName           string
	Port               int
	Peers              []PeerStatus
	UnicastRoutes      []unicastRouteStatus
	BroadcastRoutes    []broadcastRouteStatus
	Connections        []LocalConnectionStatus
	TerminationCount   int
	Targets            []string
	OverlayDiagnostics interface{}
	TrustedSubnets     []string
}

Status is our current state as a peer, as taken from a router. This is designed to be used as diagnostic information.

func NewStatus 

func NewStatus(router *Router) *Status

NewStatus returns a Status object, taken as a snapshot from the router.

Source Files

View all Source files

Directories

Path Synopsis
metcdsrv
examples
increment-only-counter

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.