communication

Documentation

Index

• Constants
• Variables
• func LoadCertPool(fileName string) (*x509.CertPool, error)
• type AppendRequest
  • func (a *AppendRequest) String() string
• type AppendResponse
  • func (a *AppendResponse) String() string
• type Communication
  • func StartHTTPCommunication(mux *http.ServeMux) (Communication, error)
  • func StartSecureCommunication(port int, key, cert, cas string) (Communication, error)
  • func StartSeparateCommunication(port int) (Communication, error)
• type JoinRequest
• type ProposalResponse
  • func (a *ProposalResponse) String() string
• type Raft
• type VoteRequest
• type VoteResponse

Constants

const (
	// ContentType is the MIME type that this module will use for all of its
	// HTTP requests and responses.
	ContentType = "application/changeagent+protobuf"
)

Variables

var DefaultAppendResponse = AppendResponse{}

DefaultAppendResponse is a convenient empty response.

var DefaultProposalResponse = ProposalResponse{}

DefaultProposalResponse is a convenient empty response.

Functions

func LoadCertPool

func LoadCertPool(fileName string) (*x509.CertPool, error)

LoadCertPool is a uility that loads a list of CA certificates from a file.

Types

type AppendRequest

type AppendRequest struct {
	Term         uint64
	LeaderID     common.NodeID
	PrevLogIndex uint64
	PrevLogTerm  uint64
	LeaderCommit uint64
	Entries      []common.Entry
}

An AppendRequest is the message that the leader sends when it wants to append a new record to the raft log of another node.

func (*AppendRequest) String

func (a *AppendRequest) String() string

type AppendResponse

type AppendResponse struct {
	Term        uint64
	Success     bool
	CommitIndex uint64
	Error       error
}

An AppendResponse is the repsonse to an AppendRequest.

func (*AppendResponse) String

func (a *AppendResponse) String() string

type Communication

type Communication interface {
	// Close should be called to shut down any communication and close ports.
	Close()

	// Port returns the port number that the communication server is listening
	// on, or zero if it was configured to piggyback on an existing listener.
	Port() int

	// SetRaft must be called to wire up the communications module before anything
	// else may be called.
	SetRaft(raft Raft)

	// Discover may be called by any node to discover the unique ID of another
	// node.
	Discover(address string) (common.NodeID, error)

	// RequestVote is called by a candidate when it wishes to be elected.
	// The response will be delivered asynchronously via a channel.
	RequestVote(address string, req VoteRequest, ch chan<- VoteResponse)

	// Append is called by the leader to add a new entry to the log of another
	// node. It blocks until it gets a response.
	Append(address string, req AppendRequest) (AppendResponse, error)

	// Propose is called by a non-leader node to ask the leader to propose a new
	// change to its followers. It blocks until it gets a response.
	Propose(address string, e *common.Entry) (ProposalResponse, error)

	// Join is called by the leader to add a new node to the cluster. There
	// may be multiple calls here if there are a large number of records
	// to send to the new node to catch it up.
	Join(address string, req JoinRequest) (ProposalResponse, error)
}

Communication is the interface that other modules use in order to communicate with other nodes in the cluster.

func StartHTTPCommunication

func StartHTTPCommunication(mux *http.ServeMux) (Communication, error)

StartHTTPCommunication creates an instance of the Communication interface that runs over HTTP. It uses the default HTTP client over regular (insecure) HTTP and connects to an existing HTTP listener.

func StartSecureCommunication

func StartSecureCommunication(port int, key, cert, cas string) (Communication, error)

StartSecureCommunication uses a separate port and also sets up encryption and authentication using TLS. All three of the key, certificate, and CA file must be specified. Communications are made using the specified key and certificate for both client-side and server-side authentication. Verification is provided against the specified CA file.

In order for this to work, the specified certificate must include the "server_cert" and "usr_cert" options. Verification is always done manually against the specified CA list. However, the "CA" is not checked. This simplifies setup for most clusters on internal networks.

func StartSeparateCommunication

func StartSeparateCommunication(port int) (Communication, error)

StartSeparateCommunication starts listening for communication on a separate port. It will open a new TCP listener on the specified port, and otherwise works the same way.

type JoinRequest

type JoinRequest struct {
	// ClusterID must be consistent on all calls
	ClusterID common.NodeID
	// Last indicates that there will be no more join requests
	Last bool
	// Entries are entries that are just replicated and inserted in storage
	Entries []common.Entry
	// ConfigEntries are entries that must be parsed and applied to local configuration
	ConfigEntries []common.Entry
}

A JoinRequest is sent when we are trying to add a new node to the cluster. We use it to send catch-up messages to the new node so that it will have a copy of the log before we let it formally join the cluster.

type ProposalResponse

type ProposalResponse struct {
	NewIndex uint64
	Error    error
}

A ProposalResponse is the response to the proposal of a new storage entry. It is used when a non-leader node wishes to ask the leader to propose something.

func (*ProposalResponse) String

func (a *ProposalResponse) String() string

type Raft

type Raft interface {
	MyID() common.NodeID
	RequestVote(req VoteRequest) (VoteResponse, error)
	Append(req AppendRequest) (AppendResponse, error)
	Propose(e *common.Entry) (uint64, error)
	Join(req JoinRequest) (uint64, error)
}

Raft is the interface that a Raft implementation must implement so that this module can call it back when it gets various events over the network.

type VoteRequest

type VoteRequest struct {
	Term         uint64
	CandidateID  common.NodeID
	LastLogIndex uint64
	LastLogTerm  uint64
	ClusterID    common.NodeID
}

A VoteRequest is the message that a raft node sends when it wants to be elected the leader.

type VoteResponse

type VoteResponse struct {
	NodeID      common.NodeID
	NodeAddress string
	Term        uint64
	VoteGranted bool
	Error       error
}

A VoteResponse is the response to a VoteRequest.