cluster

Documentation

Overview

Package cluster provides utilities for multi-server clustering. It allows nodes to coordinate a shared membership state, which can in turn be used to build higher level features, such as Distributed Nonce Pools and RPC routing.

In general, an application will create a Cluster, using CreateMembership() to register the current process in the cluster. The data of each Member is arbitrary, and can be used by the higher level application to coordinate state.

Multiple clusters can be created in a given server process. However, multiple Cluster instances for the same real cluster should be avoided.

Index

• Variables
• type Cluster
• type Member
• type Membership
• type Reader

Variables

var ErrClosed = errors.New("reader is closed")

ErrClosed indicates the cluster reader was closed.

Types

type Cluster

type Cluster interface {
	Reader

	// CreateMembership creates a unique, unregistered member of the cluster.
	//
	// The membership will only be visible byu the rest of the cluster when
	// Register() is called.
	CreateMembership() (Membership, error)
}

Cluster provides access to a cluster of members.

type Member

type Member struct {
	// ID is the canonical string representation of a UUID.
	//
	// It will remain stable through multiple Register/Deregister()
	// cycles.
	ID string `json:"id"`

	// Data is an arbitrary piece of data.
	// It may contain non human-readable data.
	//
	// The string type is used to ensure immutability.
	Data string `json:"data"`
}

Member represents a member in the cluster.

The ID is generated by the underlying implementation, and the Data is arbitrarily set by the caller. Usually, the Data will contain some stateful information related to the cluster's use.

type Membership

type Membership interface {
	// ID returns the ID of the membership.
	ID() string

	// Data returns the current data of the membership
	Data() string

	// SetData sets the data of the current membership.
	//
	// There is no guarantee for when this data will
	// propagate to the rest of the members.
	SetData(data string) error

	// Register registers the membership with the cluster.
	//
	// Register will block until the local process observes the
	// registration, but there is no guarantee for when other members
	// will observe the change.
	Register(ctx context.Context) error

	// Deregister de-registers the membership with the cluster.
	//
	// Deregister will block until the local process observes the
	// de-registration, but there is no guarantee for when other members
	// will observer the change.
	Deregister(ctx context.Context) error
}

Membership represents a mutable Member in the cluster. It is the mechanism in which processes can register/deregister themselves in a cluster.

type Reader

type Reader interface {
	// GetMembers returns the current set of members in the cluster.
	GetMembers(ctx context.Context) ([]Member, error)

	// WatchMembers returns a channel that emits snapshots of the
	// set of members in a cluster. It is closed when the provided
	// context is cancelled, or the reader is closed.
	//
	// Events are sent in a non-blocking fashion to the channel.
	// Therefore, receivers should aim to update their state as
	// quickly as possible.
	WatchMembers(ctx context.Context) <-chan []Member

	// Close closes the reader, closing all channels returned by
	// WatchMembers, and any underlying goroutines.
	Close()
}

Reader reads the state of the cluster.