package tsconsensus

import "tailscale.com/tsconsensus"

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, cfg Config) (*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
}

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.

Source Files ¶

authorization.go http.go monitor.go tsconsensus.go