Documentation
¶
Overview ¶
Package tsconsensus implements a consensus algorithm for a group of tsnet.Servers
The Raft consensus algorithm relies on you implementing a state machine that will give the same result to a given command as long as the same logs have been applied in the same order.
tsconsensus uses the hashicorp/raft library to implement leader elections and log application.
tsconsensus provides:
- cluster peer discovery based on tailscale tags
- executing a command on the leader
- communication between cluster peers over tailscale using tsnet
Users implement a state machine that satisfies the raft.FSM interface, with the business logic they desire. When changes to state are needed any node may
- create a Command instance with serialized Args.
- call ExecuteCommand with the Command instance this will propagate the command to the leader, and then from the reader to every node via raft.
- the state machine then can implement raft.Apply, and dispatch commands via the Command.Name returning a CommandResult with an Err or a serialized Result.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Command ¶
type Command struct {
// The Name can be used to dispatch the command when received.
Name string
// The Args are serialized for transport.
Args json.RawMessage
}
A Command is a representation of a state machine action.
type CommandResult ¶
type CommandResult struct {
// Err is any error that occurred on the node that tried to execute the command,
// including any error from the underlying operation and deserialization problems etc.
Err error
// Result is serialized for transport.
Result json.RawMessage
}
A CommandResult is a representation of the result of a state machine action.
type Config ¶
type Config struct {
CommandPort uint16
RaftPort uint16
MonitorPort uint16
Raft *raft.Config
MaxConnPool int
ConnTimeout time.Duration
ServeDebugMonitor bool
StateDirPath string
}
A Config holds configurable values such as ports and timeouts. Use DefaultConfig to get a useful Config.
func DefaultConfig ¶
func DefaultConfig() Config
DefaultConfig returns a Config populated with default values ready for use.
type Consensus ¶
type Consensus struct {
// contains filtered or unexported fields
}
A Consensus is the consensus algorithm for a tsnet.Server It wraps a raft.Raft instance and performs the peer discovery and command execution on the leader.
func Start ¶
func Start(ctx context.Context, ts *tsnet.Server, fsm raft.FSM, clusterTag string, cfg Config) (*Consensus, error)
Start returns a pointer to a running Consensus instance. Calling it with a *tsnet.Server will cause that server to join or start a consensus cluster with other nodes on the tailnet tagged with the clusterTag. The *tsnet.Server will run the state machine defined by the raft.FSM also provided, and keep it in sync with the other cluster members' state machines using Raft.
func (*Consensus) ExecuteCommand ¶
func (c *Consensus) ExecuteCommand(cmd Command) (CommandResult, error)
ExecuteCommand propagates a Command to be executed on the leader. Which uses raft to Apply it to the followers.
type StreamLayer ¶
StreamLayer implements an interface asked for by raft.NetworkTransport. It does the raft interprocess communication via tailscale.
func (StreamLayer) Dial ¶
func (sl StreamLayer) Dial(address raft.ServerAddress, timeout time.Duration) (net.Conn, error)
Dial implements the raft.StreamLayer interface with the tsnet.Server's Dial.
Source Files