rafttest

Documentation

Overview

Package rafttest provides functional tests for etcd's raft implementation.

Copyright 2023 The etcd Authors

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Index

• type InteractionEnv
  • func NewInteractionEnv(opts *InteractionOpts) *InteractionEnv
  • func (env *InteractionEnv) AddNodes(n int, cfg raft.Config, snap pb.Snapshot) error
  • func (env *InteractionEnv) Campaign(idx int) error
  • func (env *InteractionEnv) Compact(idx int, newFirstIndex uint64) error
  • func (env *InteractionEnv) DeliverMsgs(rs ...Recipient) int
  • func (env *InteractionEnv) ForgetLeader(idx int)
  • func (env *InteractionEnv) Handle(t *testing.T, d datadriven.TestData) string
  • func (env *InteractionEnv) LogLevel(name string) error
  • func (env *InteractionEnv) ProcessAppendThread(idx int) error
  • func (env *InteractionEnv) ProcessApplyThread(idx int) error
  • func (env *InteractionEnv) ProcessReady(idx int) error
  • func (env *InteractionEnv) Propose(idx int, data []byte) error
  • func (env *InteractionEnv) ProposeConfChange(idx int, c raftpb.ConfChangeI) error
  • func (env *InteractionEnv) RaftLog(idx int) error
  • func (env *InteractionEnv) Stabilize(idxs ...int) error
  • func (env *InteractionEnv) Status(idx int) error
  • func (env *InteractionEnv) Tick(idx int, num int) error
• type InteractionOpts
• type Node
• type Recipient
• type RedirectLogger
  • func (l *RedirectLogger) Debug(v ...interface{})
  • func (l *RedirectLogger) Debugf(format string, v ...interface{})
  • func (l *RedirectLogger) Error(v ...interface{})
  • func (l *RedirectLogger) Errorf(format string, v ...interface{})
  • func (l *RedirectLogger) Fatal(v ...interface{})
  • func (l *RedirectLogger) Fatalf(format string, v ...interface{})
  • func (l *RedirectLogger) Info(v ...interface{})
  • func (l *RedirectLogger) Infof(format string, v ...interface{})
  • func (l *RedirectLogger) Panic(v ...interface{})
  • func (l *RedirectLogger) Panicf(format string, v ...interface{})
  • func (l *RedirectLogger) Quiet() bool
  • func (l *RedirectLogger) Warning(v ...interface{})
  • func (l *RedirectLogger) Warningf(format string, v ...interface{})
  • func (l *RedirectLogger) Write(p []byte) (int, error)
  • func (l *RedirectLogger) WriteByte(c byte) error
  • func (l *RedirectLogger) WriteRune(r rune) (int, error)
  • func (l *RedirectLogger) WriteString(s string) (int, error)
• type Storage

Types

type InteractionEnv

type InteractionEnv struct {
	Options  *InteractionOpts
	Nodes    []Node
	Messages []pb.Message // in-flight messages

	Output *RedirectLogger
}

InteractionEnv facilitates testing of complex interactions between the members of a raft group.

func NewInteractionEnv

func NewInteractionEnv(opts *InteractionOpts) *InteractionEnv

NewInteractionEnv initializes an InteractionEnv. opts may be nil.

func (*InteractionEnv) AddNodes

func (env *InteractionEnv) AddNodes(n int, cfg raft.Config, snap pb.Snapshot) error

AddNodes adds n new nodes initialized from the given snapshot (which may be empty), and using the cfg as template. They will be assigned consecutive IDs.

func (*InteractionEnv) Campaign

func (env *InteractionEnv) Campaign(idx int) error

Campaign the node at the given index.

func (*InteractionEnv) Compact

func (env *InteractionEnv) Compact(idx int, newFirstIndex uint64) error

Compact truncates the log on the node at index idx so that the supplied new first index results.

func (*InteractionEnv) DeliverMsgs

func (env *InteractionEnv) DeliverMsgs(rs ...Recipient) int

DeliverMsgs goes through env.Messages and, depending on the Drop flag, delivers or drops messages to the specified Recipients. Returns the number of messages handled (i.e. delivered or dropped). A handled message is removed from env.Messages.

func (*InteractionEnv) ForgetLeader

func (env *InteractionEnv) ForgetLeader(idx int)

ForgetLeader makes the follower at the given index forget its leader.

func (*InteractionEnv) Handle

func (env *InteractionEnv) Handle(t *testing.T, d datadriven.TestData) string

Handle is the entrypoint for data-driven interaction testing. Commands and parameters are parsed from the supplied TestData. Errors during data parsing are reported via the supplied *testing.T; errors from the raft nodes and the storage engine are reported to the output buffer.

func (*InteractionEnv) LogLevel

func (env *InteractionEnv) LogLevel(name string) error

func (*InteractionEnv) ProcessAppendThread

func (env *InteractionEnv) ProcessAppendThread(idx int) error

ProcessAppendThread runs processes a single message on the "append" thread of the node with the given index.

func (*InteractionEnv) ProcessApplyThread

func (env *InteractionEnv) ProcessApplyThread(idx int) error

ProcessApplyThread runs processes a single message on the "apply" thread of the node with the given index.

func (*InteractionEnv) ProcessReady

func (env *InteractionEnv) ProcessReady(idx int) error

ProcessReady runs Ready handling on the node with the given index.

func (*InteractionEnv) Propose

func (env *InteractionEnv) Propose(idx int, data []byte) error

Propose a regular entry.

func (*InteractionEnv) ProposeConfChange

func (env *InteractionEnv) ProposeConfChange(idx int, c raftpb.ConfChangeI) error

ProposeConfChange proposes a configuration change on the node with the given index.

func (*InteractionEnv) RaftLog

func (env *InteractionEnv) RaftLog(idx int) error

RaftLog pretty prints the raft log to the output buffer.

func (*InteractionEnv) Stabilize

func (env *InteractionEnv) Stabilize(idxs ...int) error

Stabilize repeatedly runs Ready handling on and message delivery to the set of nodes specified via the idxs slice until reaching a fixed point.

func (*InteractionEnv) Status

func (env *InteractionEnv) Status(idx int) error

Status pretty-prints the raft status for the node at the given index to the output buffer.

func (*InteractionEnv) Tick

func (env *InteractionEnv) Tick(idx int, num int) error

Tick the node at the given index the given number of times.

type InteractionOpts

type InteractionOpts struct {
	OnConfig func(*raft.Config)

	// SetRandomizedElectionTimeout is used to plumb this function down from the
	// raft test package.
	SetRandomizedElectionTimeout func(node *raft.RawNode, timeout int)
}

InteractionOpts groups the options for an InteractionEnv.

type Node

type Node struct {
	*raft.RawNode
	Storage

	Config     *raft.Config
	AppendWork []pb.Message // []MsgStorageAppend
	ApplyWork  []pb.Message // []MsgStorageApply
	History    []pb.Snapshot
}

Node is a member of a raft group tested via an InteractionEnv.

type Recipient

type Recipient struct {
	ID   uint64
	Drop bool
}

type RedirectLogger

type RedirectLogger struct {
	*strings.Builder
	Lvl int // 0 = DEBUG, 1 = INFO, 2 = WARNING, 3 = ERROR, 4 = FATAL, 5 = NONE
}

func (*RedirectLogger) Debug

func (l *RedirectLogger) Debug(v ...interface{})

func (*RedirectLogger) Debugf

func (l *RedirectLogger) Debugf(format string, v ...interface{})

func (*RedirectLogger) Error

func (l *RedirectLogger) Error(v ...interface{})

func (*RedirectLogger) Errorf

func (l *RedirectLogger) Errorf(format string, v ...interface{})

func (*RedirectLogger) Fatal

func (l *RedirectLogger) Fatal(v ...interface{})

func (*RedirectLogger) Fatalf

func (l *RedirectLogger) Fatalf(format string, v ...interface{})

func (*RedirectLogger) Info

func (l *RedirectLogger) Info(v ...interface{})

func (*RedirectLogger) Infof

func (l *RedirectLogger) Infof(format string, v ...interface{})

func (*RedirectLogger) Panic

func (l *RedirectLogger) Panic(v ...interface{})

func (*RedirectLogger) Panicf

func (l *RedirectLogger) Panicf(format string, v ...interface{})

func (*RedirectLogger) Quiet

func (l *RedirectLogger) Quiet() bool

func (*RedirectLogger) Warning

func (l *RedirectLogger) Warning(v ...interface{})

func (*RedirectLogger) Warningf

func (l *RedirectLogger) Warningf(format string, v ...interface{})

func (*RedirectLogger) Write

func (l *RedirectLogger) Write(p []byte) (int, error)

func (*RedirectLogger) WriteByte

func (l *RedirectLogger) WriteByte(c byte) error

func (*RedirectLogger) WriteRune

func (l *RedirectLogger) WriteRune(r rune) (int, error)

func (*RedirectLogger) WriteString

func (l *RedirectLogger) WriteString(s string) (int, error)

type Storage

type Storage interface {
	raft.Storage
	SetHardState(state pb.HardState) error
	ApplySnapshot(pb.Snapshot) error
	Compact(newFirstIndex uint64) error
	Append([]pb.Entry) error
}

Storage is the interface used by InteractionEnv. It is comprised of raft's Storage interface plus access to operations that maintain the log and drive the Ready handling loop.