raftio

Documentation

Overview

Package raftio contains structs, interfaces and function definitions required to build custom persistent Raft log storage and transport modules.

Structs, interfaces and functions defined in the raftio package are only required when building your custom persistent Raft log storage or transport modules. Skip this package if you plan to use the default built-in LogDB and transport modules provided by Dragonboat.

Structs, interfaces and functions defined in the raftio package are not considered as a part of Dragonboat's public APIs. Breaking changes might happen in the coming minor releases.

Index

• Constants
• Variables
• type ChunkHandler
• type ConnectionInfo
• type EntryInfo
• type IConnection
• type ILogDB
• type IRaftEventListener
• type ISnapshotConnection
• type ISystemEventListener
• type ITransport
• type LeaderInfo
• type MessageHandler
• type Metrics
• type NodeInfo
  • func GetNodeInfo(cid uint64, nid uint64) NodeInfo
• type RaftState
• type SnapshotInfo

Constants

const (
	// LogDBBinVersion is the current logdb binary compatibility version
	// implemented in Dragonboat.
	// For v1.4  BinVersion = 100
	//     v2.0  BinVersion = 210
	LogDBBinVersion uint32 = 210
	// PlainLogDBBinVersion is the logdb binary compatibility version value when
	// plain entries are used in ILogDB.
	PlainLogDBBinVersion uint32 = 100
	// TransportBinVersion is the transport binary compatibility version implemented in
	// Dragonboat.
	// For v1.4  TransportBinLog = 100
	//     v2.0  TransportBinLog = 210
	TransportBinVersion uint32 = 210
)

const (
	// NoLeader is a special leader ID value to indicate that there is currently
	// no leader or leader ID is unknown.
	NoLeader uint64 = 0
)

Variables

var (
	// ErrNoSavedLog indicates no saved log.
	ErrNoSavedLog = errors.New("no saved log")
	// ErrNoBootstrapInfo indicates that there is no saved bootstrap info.
	ErrNoBootstrapInfo = errors.New("no bootstrap info")
)

Types

type ChunkHandler

type ChunkHandler func(pb.Chunk) bool

ChunkHandler is the handler function type for handling received snapshot chunks. It adds the new snapshot chunk to the snapshot chunk sink. Chunks from the same snapshot are combined into the snapshot image and then be passed to dragonboat.

ChunkHandler returns a boolean value indicating whether the snapshot connection is still valid for accepting future snapshot chunks.

type ConnectionInfo

type ConnectionInfo struct {
	Address            string
	SnapshotConnection bool
}

ConnectionInfo contains info of the connection.

type EntryInfo

type EntryInfo struct {
	ClusterID uint64
	NodeID    uint64
	Index     uint64
}

EntryInfo contains info on log entries.

type IConnection

type IConnection interface {
	// Close closes the IConnection instance.
	Close()
	// SendMessageBatch sends the specified message batch to the target. It is
	// recommended to deliver the message batch to the target in order to enjoy
	// best possible performance, but out of order delivery is allowed at the
	// cost of reduced performance.
	SendMessageBatch(batch pb.MessageBatch) error
}

IConnection is the interface used by the transport module for sending Raft messages. Each IConnection works for a specified target NodeHost instance, it is possible for a target to have multiple concurrent IConnection instances in use.

type ILogDB

type ILogDB interface {
	// Name returns the type name of the ILogDB instance.
	Name() string
	// Close closes the ILogDB instance.
	Close() error
	// BinaryFormat returns an constant uint32 value representing the binary
	// format version compatible with the ILogDB instance.
	BinaryFormat() uint32
	// ListNodeInfo lists all available NodeInfo found in the log DB.
	ListNodeInfo() ([]NodeInfo, error)
	// SaveBootstrapInfo saves the specified bootstrap info to the log DB.
	SaveBootstrapInfo(clusterID uint64,
		nodeID uint64, bootstrap pb.Bootstrap) error
	// GetBootstrapInfo returns saved bootstrap info from log DB. It returns
	// ErrNoBootstrapInfo when there is no previously saved bootstrap info for
	// the specified node.
	GetBootstrapInfo(clusterID uint64, nodeID uint64) (pb.Bootstrap, error)
	// SaveRaftState atomically saves the Raft states, log entries and snapshots
	// metadata found in the pb.Update list to the log DB. shardID is a 1-based
	// ID of the worker invoking the SaveRaftState method, as each worker
	// accesses the log DB from its own thread, SaveRaftState will never be
	// concurrently called with the same shardID.
	SaveRaftState(updates []pb.Update, shardID uint64) error
	// IterateEntries returns the continuous Raft log entries of the specified
	// Raft node between the index value range of [low, high) up to a max size
	// limit of maxSize bytes. It returns the located log entries, their total
	// size in bytes and the occurred error.
	IterateEntries(ents []pb.Entry,
		size uint64, clusterID uint64, nodeID uint64, low uint64,
		high uint64, maxSize uint64) ([]pb.Entry, uint64, error)
	// ReadRaftState returns the persistented raft state found in Log DB.
	ReadRaftState(clusterID uint64,
		nodeID uint64, lastIndex uint64) (RaftState, error)
	// RemoveEntriesTo removes entries with indexes between (0, index].
	RemoveEntriesTo(clusterID uint64, nodeID uint64, index uint64) error
	// CompactEntriesTo reclaims underlying storage space used for storing
	// entries up to the specified index.
	CompactEntriesTo(clusterID uint64,
		nodeID uint64, index uint64) (<-chan struct{}, error)
	// SaveSnapshots saves all snapshot metadata found in the pb.Update list.
	SaveSnapshots([]pb.Update) error
	// GetSnapshot returns the most recent snapshot associated with the specified
	// cluster.
	GetSnapshot(clusterID uint64, nodeID uint64) (pb.Snapshot, error)
	// RemoveNodeData removes all data associated with the specified node.
	RemoveNodeData(clusterID uint64, nodeID uint64) error
	// ImportSnapshot imports the specified snapshot by creating all required
	// metadata in the logdb.
	ImportSnapshot(snapshot pb.Snapshot, nodeID uint64) error
}

ILogDB is the interface implemented by the log DB for persistently store Raft states, log entries and other Raft metadata.

type IRaftEventListener

type IRaftEventListener interface {
	LeaderUpdated(info LeaderInfo)
}

IRaftEventListener is the interface to allow users to get notified for certain Raft events.

type ISnapshotConnection

type ISnapshotConnection interface {
	// Close closes the ISnapshotConnection instance.
	Close()
	// SendChunk sends the snapshot chunk to the target. It is
	// recommended to have the snapshot chunk delivered in order for the best
	// performance, but out of order delivery is allowed at the cost of reduced
	// performance.
	SendChunk(chunk pb.Chunk) error
}

ISnapshotConnection is the interface used by the transport module for sending snapshot chunks. Each ISnapshotConnection works for a specified target NodeHost instance.

type ISystemEventListener

type ISystemEventListener interface {
	NodeHostShuttingDown()
	NodeUnloaded(info NodeInfo)
	NodeReady(info NodeInfo)
	MembershipChanged(info NodeInfo)
	ConnectionEstablished(info ConnectionInfo)
	ConnectionFailed(info ConnectionInfo)
	SendSnapshotStarted(info SnapshotInfo)
	SendSnapshotCompleted(info SnapshotInfo)
	SendSnapshotAborted(info SnapshotInfo)
	SnapshotReceived(info SnapshotInfo)
	SnapshotRecovered(info SnapshotInfo)
	SnapshotCreated(info SnapshotInfo)
	SnapshotCompacted(info SnapshotInfo)
	LogCompacted(info EntryInfo)
	LogDBCompacted(info EntryInfo)
}

ISystemEventListener is the system event listener used by the NodeHost.

type ITransport

type ITransport interface {
	// Name returns the type name of the ITransport instance.
	Name() string
	// Start launches the transport module and make it ready to start sending and
	// receiving Raft messages. If necessary, ITransport may take this opportunity
	// to start listening for incoming data.
	Start() error
	// Close closes the transport module.
	Close() error
	// GetConnection returns an IConnection instance used for sending messages
	// to the specified target NodeHost instance.
	GetConnection(ctx context.Context, target string) (IConnection, error)
	// GetSnapshotConnection returns an ISnapshotConnection instance used for
	// sending snapshot chunks to the specified target NodeHost instance.
	GetSnapshotConnection(ctx context.Context,
		target string) (ISnapshotConnection, error)
}

ITransport is the interface to be implemented by a customized transport module. A transport module is responsible for exchanging Raft messages, snapshots and other metadata between NodeHost instances.

type LeaderInfo

type LeaderInfo struct {
	ClusterID uint64
	NodeID    uint64
	Term      uint64
	LeaderID  uint64
}

LeaderInfo contains info on Raft leader.

type MessageHandler

type MessageHandler func(pb.MessageBatch)

MessageHandler is the handler function type for handling received message batches. Received message batches should be passed to the message handler to be processed.

type Metrics

type Metrics struct {
	// Busy indicates whether the LogDB is busy and not suitable for saving new
	// data into the store.
	Busy bool
}

Metrics is the metrics of the LogDB.

type NodeInfo

type NodeInfo struct {
	ClusterID uint64
	NodeID    uint64
}

NodeInfo is used to identify a Raft node.

func GetNodeInfo

func GetNodeInfo(cid uint64, nid uint64) NodeInfo

GetNodeInfo returns a NodeInfo instance with the specified cluster ID and node ID.

type RaftState

type RaftState struct {
	// State is the Raft state persistent to the disk
	State pb.State
	// FirstIndex is the index of the first entry to iterate
	FirstIndex uint64
	// EntryCount is the number of entries to iterate
	EntryCount uint64
}

RaftState is the persistent Raft state found in the Log DB.

type SnapshotInfo

type SnapshotInfo struct {
	ClusterID uint64
	NodeID    uint64
	From      uint64
	Index     uint64
}

SnapshotInfo contains info of the snapshot.