api

package
v0.0.0-...-364fed7 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 11, 2021 License: Apache-2.0 Imports: 11 Imported by: 0

Documentation

Overview

Package api implements a higher-level abstraction over the cluster compared to nodepb.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DefaultSearchFunc 

func DefaultSearchFunc(i, j Descriptor) bool

DefaultSearchFunc returns true when i >= j.

func DumpState 

func DumpState(w io.Writer, s *State)

DumpState dumps State as text to w.

func Prefix 

func Prefix(a, b id.Digits) int

Prefix returns the first index where a and b differ. Returns len(a) if they are equal. Returns -1 if a and b have different lengths.

func WraparoundSearchFunc 

func WraparoundSearchFunc(wraparound id.ID) func(i, j Descriptor) bool

WraparoundSearchFunc sorts IDs in two tiers: IDs that are larger than wraparound and IDs that are smaller than wraparound. This allows for wraparound semantics in the ring.

Example: Given a set (0, 100, 200, 300) and wrapping around 150, numbers will be sorted as (200, 300, 0, 100).

Types

type Descriptor 

type Descriptor struct {
	// ID for routing.
	ID id.ID
	// Addr for connecting.
	Addr string
}

Descriptor describes a node in a cluster.

func NextHop 

func NextHop(s *State, key id.ID) (next Descriptor, ok bool)

NextHop looks up the next hop for a key for the given State s. May return s.Node if it is the closest node. Returning ok==false indicates a routing failure, likely due to a bug.

func ReverseDescriptors 

func ReverseDescriptors(ds []Descriptor) []Descriptor

ReverseDescriptors reverses ds.

type DescriptorSet 

type DescriptorSet struct {
	// Descriptors is the inner set of descriptors.
	Descriptors []Descriptor

	// Size is the maximum size of the set. Operations against the DescriptorSet
	// will keep it bound to this.
	Size int

	// KeepBiggest will keep the biggest elements when doing an Insert.
	// If the set is IDs (0, 1, 2), size=3, then an insert of 5
	// with KeepBiggest=true will change the set to (1, 2, 5), while
	// KeepBiggest=false will keep at (0, 1, 2).
	//
	// KeepBiggest being true corresponds to the set of predecessors.
	KeepBiggest bool

	// SearchFunc should return true when i is >= j.
	SearchFunc func(i, j Descriptor) bool
}

DescriptorSet is an ordered set of descriptors.

func (*DescriptorSet) Clone 

func (dset *DescriptorSet) Clone() *DescriptorSet

Clone returns a copy of DescriptorSet.

func (*DescriptorSet) Contains 

func (dset *DescriptorSet) Contains(d Descriptor) bool

Contains returns true if d is in dset.

func (*DescriptorSet) Insert 

func (dset *DescriptorSet) Insert(d Descriptor) bool

Insert inserts d into dset, removing other elements if dset is full. If d already exists in dset, Insert is a no-op.

func (*DescriptorSet) IsFull 

func (dset *DescriptorSet) IsFull() bool

IsFull returns true if dset is at capacity.

func (*DescriptorSet) Push 

func (dset *DescriptorSet) Push(d Descriptor) bool

Push pushes d into dset. If d already exists in dset or dset is full, Push is a no-op. Returns true if dset was modified.

func (*DescriptorSet) Remove 

func (dset *DescriptorSet) Remove(d Descriptor) bool

Remove removes d from dset. Returns true if the element was removed.

type ErrStateChanged 

type ErrStateChanged struct {
	NewState *State
}

ErrStateChanged is the error of a Hello if a node's state has changed since StateAck.

func (ErrStateChanged) Error 

func (e ErrStateChanged) Error() string

Error returns the error string.

type Health 

type Health uint

Health state for a node. 

const (
	// Healthy is the default state.
	Healthy Health = iota
	// Unhealthy represnts a suspicion that a node is misbehaving.
	Unhealthy
	// Dead represents a dead node that should be removed from the state.
	Dead
)

func (Health) String 

func (h Health) String() string

String returns the health as a string.

type Hello 

type Hello struct {
	// Initiator is the node that initiated the Hello.
	Initiator Descriptor

	// The next node (if any) that will also send a Hello.
	Next *Descriptor

	// State of the initiator.
	State *State

	// StateAck is used to verify the state for the initiator of a previous Hello
	// hasn't changed. Set to the value of State.LastUpdated from a previous Hello.
	StateAck time.Time
}

Hello is a state sharing message.

type Node 

type Node interface {
	// Join informs a node that joiner wishes to join the cluster. Joins will
	// be propagated and routed through the cluster based on the joiner ID.
	// Each peer along the routing path will send a NodeHello to the joiner.
	Join(ctx context.Context, joiner Descriptor) error

	// NodeHello is used for nodes to share state. If h.StateAck is
	// set and the state has changed, NodeHello should reply with an
	// ErrStateChanged.
	NodeHello(ctx context.Context, h Hello) error

	// NodeGoodbye informs a node that the leaver is leaving the cluster.
	NodeGoodbye(ctx context.Context, leaver Descriptor) error

	// GetState gets the current state of a node.
	GetState(ctx context.Context) (*State, error)
}

Node is a node in the cluster.

type RoutingTable 

type RoutingTable [][]*Descriptor

func NewRoutingTable 

func NewRoutingTable(width, height int) RoutingTable

NewRoutingTable creates a new RoutingTable with the given size.

type State 

type State struct {

	// The node this State is for.
	Node Descriptor

	// The nodes immediately before and after this node in the
	// hash ring.
	Predecessors, Successors *DescriptorSet

	// Size is the bit length of IDs to store for rounding, and
	// Base is the power-of-two base to represent them as.
	Size, Base int

	// Routing is the table used for routing.
	//
	// There is one row per digit in the ID, and Base number of columns.
	Routing [][]*Descriptor

	// Neighbors are geographically close peers in the cluster.
	Neighbors *DescriptorSet

	// Statuses maps a Descriptor's ID to its health state.
	Statuses map[Descriptor]Health

	// LastUpdated is the last time this State was updated. Used to ID it
	// between previous iterations of the State.
	LastUpdated time.Time
	// contains filtered or unexported fields
}

State is the state of a node used for routing messages. Methods against State are goroutine state.

func NewState 

func NewState(
	node Descriptor,
	numLeaves, numNeighbors int,
	size, base int,
) *State

NewState creates a new State for a node.

func (*State) Calculate 

func (s *State) Calculate(hellos []Hello)

Calculate initializes the state based on a set of hellos. hellos is expected to be ordered from seed to peer.

func (*State) Clone 

func (s *State) Clone() *State

Clone returns a copy of s.

func (*State) IsLeaf 

func (s *State) IsLeaf(d Descriptor) bool

IsLeaf returns true if d is a leaf node.

func (*State) IsNewer 

func (s *State) IsNewer(t time.Time) bool

IsNewer returns true if State has been modified since t.

func (*State) Leaves 

func (s *State) Leaves(all bool) []Descriptor

Leaves returns the full set of unique leaves. If all is true, known unhealthy leaves will also be returned.

func (*State) MixinLeaves 

func (s *State) MixinLeaves(peer *State) (updated bool)

MixinLeaves will take leaves from a peer and incorporate them into s. The peer itself will also be considered a leaf.

Ignores nodes that s or peer do not find healthy.

Returns true when updated.

func (*State) MixinState 

func (s *State) MixinState(peer *State) (updatedRoutes, updatedNeighbors, updatedLeaves bool)

MixinState takes the routes, neighbors, and leaves from the peer and mixes them all into s.

func (*State) Peers 

func (s *State) Peers(all bool) []Descriptor

Peers returns the unique set of peers in s. Return order not guaranteed. If all is true, known unhealthy peers will also be returned.

func (*State) ReplaceNeighbor 

func (s *State) ReplaceNeighbor(d Descriptor, peer *State) (changed, ok bool)

ReplaceNeighbor will replace d with a healthy neighbor from peer. d must exist as a neighbor and be unhealthy.

func (*State) ReplacePredecessor 

func (s *State) ReplacePredecessor(d Descriptor, peer *State) (changed bool)

ReplacePredecessor will replace d with a healthy leaf from peer. d must exist as a Predecessor and be unhealthy.

func (*State) ReplaceRoute 

func (s *State) ReplaceRoute(d Descriptor, peer *State) (replaced, ok bool)

ReplaceRoute will replace d in the routing table with an entry from peer. d must exist as a route and be unhealthy, otherwise returns ok==false.

func (*State) ReplaceSuccessor 

func (s *State) ReplaceSuccessor(d Descriptor, peer *State) (changed bool)

ReplaceSuccessor will replace d with a healthy leaf from peer. d must exist as a Successors and be unhealthy.

func (*State) RouteIndex 

func (s *State) RouteIndex(d Descriptor) (row, col int)

RouteIndex returns the index in the routing table for d. d must not be s.Node, otherwise erturns -1, -1.

func (*State) SetHealth 

func (s *State) SetHealth(p Descriptor, h Health) (changed bool)

SetHealth updates the health of p. Note that updating the health only affects routing; callers must manually remove unhealthy peers.

func (*State) Untrack 

func (s *State) Untrack(p Descriptor) (changed bool)

Untrack removes p from s' health tracking. If p is a peer, Untrack will do nothing. This prevents untracking an unhealthy peer that is still being used for routing.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.