tsconsensus

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

• type Command
• type CommandResult
• type Config
  • func DefaultConfig() Config
• type Consensus
  • func Start(ctx context.Context, ts *tsnet.Server, fsm raft.FSM, clusterTag string, ...) (*Consensus, error)
  • func (c *Consensus) ExecuteCommand(cmd Command) (CommandResult, error)
  • func (c *Consensus) Stop(ctx context.Context) error
• type StreamLayer
  • func (sl StreamLayer) Accept() (net.Conn, error)
  • func (sl StreamLayer) Dial(address raft.ServerAddress, timeout time.Duration) (net.Conn, error)

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.

func (*Consensus) Stop

func (c *Consensus) Stop(ctx context.Context) error

Stop attempts to gracefully shutdown various components.

type StreamLayer

type StreamLayer struct {
	net.Listener
	// contains filtered or unexported fields
}

StreamLayer implements an interface asked for by raft.NetworkTransport. It does the raft interprocess communication via tailscale.

func (StreamLayer) Accept

func (sl StreamLayer) Accept() (net.Conn, error)

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.