gossip

Documentation

Overview

Package gossip implements a protocol for sharing information between Cockroach nodes using an ad-hoc, peer-to-peer network. The self-assembled network aims to minimize time for new information to reach each node, and minimize network traffic required.

Gossiped information is identified by key. Gossip information is captured by info objects. Info objects may be stored individually (e.g. the number of nodes in the system), or may be organized into groups (e.g. multiple values of the same type from different originators).

Groups organize multiple instance of info for the same key prefix. Groups come in two types: MinGroup groups keep only the minimum values seen; MaxGroup groups keep only the maximum values seen. An example is load or disk capacity values for nodes. In a cluster with thousands of nodes, groups force the gossip network to limit itself to only a portion of total data volume (e.g. the 100 least loaded nodes or the 100 disks with most unused capacity).

Single-valued info values can have any type. Values to be used with groups must either be of type int64, float64, string or implement the util.Ordered interface.

A map of info objects and a map of Group objects are kept by a Gossip instance. Single-valued info objects can be added via Gossip.AddInfo(). Groups must be registered via Gossip.RegisterGroup(). Info objects are added to groups if their key matches. Info can be queried for single-valued keys via Gossip.GetInfo. Sorted values for groups are queried via Gossip.GetGroupInfos().

Index

• Constants
• Variables
• func MakeCapacityKey(nodeID proto.NodeID, storeID proto.StoreID) string
• func MakeKey(components ...string) string
• func MakeNodeIDKey(nodeID proto.NodeID) string
• func MakePrefixPattern(prefix string) string
• type Callback
• type Gossip
  • func New(rpcContext *rpc.Context, gossipInterval time.Duration, ...) *Gossip
  • func (g *Gossip) AddInfo(key string, val interface{}, ttl time.Duration) error
  • func (g *Gossip) GetGroupInfos(prefix string) ([]interface{}, error)
  • func (g *Gossip) GetInfo(key string) (interface{}, error)
  • func (g *Gossip) GetInfosAsJSON() ([]byte, error)
  • func (g *Gossip) GetNodeDescriptor(nodeID proto.NodeID) (proto.NodeDescriptor, error)
  • func (g *Gossip) GetNodeID() proto.NodeID
  • func (g *Gossip) GetNodeIDAddress(nodeID proto.NodeID) (net.Addr, error)
  • func (s Gossip) Gossip(args *proto.GossipRequest, reply *proto.GossipResponse) error
  • func (g *Gossip) Incoming() []proto.NodeID
  • func (g *Gossip) MaxHops() uint32
  • func (g *Gossip) Outgoing() []proto.NodeID
  • func (g *Gossip) RegisterCallback(pattern string, method Callback)
  • func (g *Gossip) RegisterGroup(prefix string, limit int, typeOf GroupType) error
  • func (g *Gossip) SetNodeDescriptor(desc *proto.NodeDescriptor) error
  • func (g *Gossip) SetResolvers(resolvers []resolver.Resolver)
  • func (g *Gossip) Start(rpcServer *rpc.Server, stopper *util.Stopper)
• type GroupType

Constants

const (
	// MaxPeers is the maximum number of connected gossip peers.
	MaxPeers = 10

	// TestInterval is the default gossip interval used for running tests.
	TestInterval = 10 * time.Millisecond
)

const (
	// KeyClusterID is the unique UUID for this Cockroach cluster.
	// The value is a string UUID for the cluster.  The cluster ID is
	// gossiped by all nodes that contain a replica of the first range,
	// and it serves as a check for basic gossip connectivity. The
	// Gossip.Connected channel is closed when we see this key.
	KeyClusterID = "cluster-id"

	// KeyConfigAccounting is the accounting configuration map.
	KeyConfigAccounting = "accounting"

	// KeyConfigPermission is the permission configuration map.
	KeyConfigPermission = "permissions"

	// KeyConfigZone is the zone configuration map.
	KeyConfigZone = "zones"

	// KeyCapacityPrefix is the key prefix for gossiping available
	// store capacity. The suffix is composed of: <node ID>-<store ID>.
	// The value is a storage.StoreDescriptor struct.
	KeyCapacityPrefix = "capacity"

	// KeyNodeCount is the count of gossip nodes in the
	// network. The value is an int64 containing the count of nodes in
	// the cluster.
	// TODO(spencer): should remove this and instead just count the
	//   number of node ids being gossiped.
	KeyNodeCount = "node-count"

	// KeyNodeIDPrefix is the key prefix for gossiping node id
	// addresses. The actual key is suffixed with the decimal
	// representation of the node id and the value is the host:port
	// string address of the node. E.g. node:1 => 127.0.0.1:24001
	KeyNodeIDPrefix = "node"

	// KeySentinel is a key for gossip which must not expire or
	// else the node considers itself partitioned and will retry with
	// bootstrap hosts.  The sentinel is gossiped by the node that holds
	// the leader lease for the first range.
	KeySentinel = "sentinel"

	// KeyFirstRangeDescriptor is the descriptor for the "first"
	// range. The "first" range contains the meta1 key range, the first
	// level of the bi-level key addressing scheme. The value is a slice
	// of storage.Replica structs.
	KeyFirstRangeDescriptor = "first-range"
)

Constants for gossip keys.

Variables

var (
	// TestBootstrap is the default gossip bootstrap used for running tests.
	TestBootstrap = []resolver.Resolver{}
)

Functions

func MakeCapacityKey

func MakeCapacityKey(nodeID proto.NodeID, storeID proto.StoreID) string

MakeCapacityKey returns the gossip key for the given store's capacity.

func MakeKey

func MakeKey(components ...string) string

MakeKey creates a canonical key under which to gossip a piece of information. The first argument will typically be one of the key constants defined in this package.

func MakeNodeIDKey

func MakeNodeIDKey(nodeID proto.NodeID) string

MakeNodeIDKey returns the gossip key for node ID info.

func MakePrefixPattern

func MakePrefixPattern(prefix string) string

MakePrefixPattern returns a regular expression pattern that matches precisely the Gossip keys created by invocations of MakeKey with multiple arguments for which the first argument is equal to the given prefix.

Types

type Callback

type Callback func(key string, contentsChanged bool)

Callback is a callback method to be invoked on gossip update of info denoted by key. The contentsChanged bool indicates whether the info contents were updated. False indicates the info timestamp was refreshed, but its contents remained unchanged.

type Gossip

type Gossip struct {
	Connected chan struct{} // Closed upon initial connection

	RPCContext *rpc.Context // The context required for RPC
	// contains filtered or unexported fields
}

Gossip is an instance of a gossip node. It embeds a gossip server. During bootstrapping, the bootstrap list contains candidates for entry to the gossip network.

func New

func New(rpcContext *rpc.Context, gossipInterval time.Duration, resolvers []resolver.Resolver) *Gossip

New creates an instance of a gossip node.

func (*Gossip) AddInfo

func (g *Gossip) AddInfo(key string, val interface{}, ttl time.Duration) error

AddInfo adds or updates an info object. Returns an error if info couldn't be added.

func (*Gossip) GetGroupInfos

func (g *Gossip) GetGroupInfos(prefix string) ([]interface{}, error)

GetGroupInfos returns a slice of info values from specified group, or an error if group is not registered.

func (*Gossip) GetInfo

func (g *Gossip) GetInfo(key string) (interface{}, error)

GetInfo returns an info value by key or an error if specified key does not exist or has expired.

func (*Gossip) GetInfosAsJSON

func (g *Gossip) GetInfosAsJSON() ([]byte, error)

GetInfosAsJSON returns the contents of the infostore, marshalled to JSON.

func (*Gossip) GetNodeDescriptor

func (g *Gossip) GetNodeDescriptor(nodeID proto.NodeID) (proto.NodeDescriptor, error)

GetNodeDescriptor looks up the descriptor of the node by ID.

func (*Gossip) GetNodeID

func (g *Gossip) GetNodeID() proto.NodeID

GetNodeID returns the instance's saved NodeID.

func (*Gossip) GetNodeIDAddress

func (g *Gossip) GetNodeIDAddress(nodeID proto.NodeID) (net.Addr, error)

GetNodeIDAddress looks up the address of the node by ID.

func (Gossip) Gossip

func (s Gossip) Gossip(args *proto.GossipRequest, reply *proto.GossipResponse) error

Gossip receives gossiped information from a peer node. The received delta is combined with the infostore, and this node's own gossip is returned to requesting client.

func (*Gossip) Incoming

func (g *Gossip) Incoming() []proto.NodeID

Incoming returns a slice of incoming gossip client connection node IDs.

func (*Gossip) MaxHops

func (g *Gossip) MaxHops() uint32

MaxHops returns the maximum number of hops to reach the furthest gossiped information currently in the network.

func (*Gossip) Outgoing

func (g *Gossip) Outgoing() []proto.NodeID

Outgoing returns a slice of outgoing gossip client connection node IDs. Note that these outgoing client connections may not actually be legitimately connected. They may be in the process of trying, or may already have failed, but haven't yet been processed by the gossip instance.

func (*Gossip) RegisterCallback

func (g *Gossip) RegisterCallback(pattern string, method Callback)

RegisterCallback registers a callback for a key pattern to be invoked whenever new info for a gossip key matching pattern is received. The callback method is invoked with the info key which matched pattern.

func (*Gossip) RegisterGroup

func (g *Gossip) RegisterGroup(prefix string, limit int, typeOf GroupType) error

RegisterGroup registers a new group with info store. Returns an error if the group was already registered.

func (*Gossip) SetNodeDescriptor

func (g *Gossip) SetNodeDescriptor(desc *proto.NodeDescriptor) error

SetNodeDescriptor adds the node descriptor to the gossip network and sets the infostore's node ID.

func (*Gossip) SetResolvers

func (g *Gossip) SetResolvers(resolvers []resolver.Resolver)

SetResolvers initializes the set of gossip resolvers used to find nodes to bootstrap the gossip network.

func (*Gossip) Start

func (g *Gossip) Start(rpcServer *rpc.Server, stopper *util.Stopper)

Start launches the gossip instance, which commences joining the gossip network using the supplied rpc server and the gossip bootstrap addresses specified via command-line flag: --gossip.

This method starts bootstrap loop, gossip server, and client management in separate goroutines and returns.

type GroupType

type GroupType int

GroupType indicates the bounds of the values encountered within the group.

const (
	// MinGroup maintains minimum values for keys matching group prefix.
	MinGroup GroupType = iota
	// MaxGroup maintains maximum values for keys matching group prefix.
	MaxGroup
)