api

Documentation

Index

• Variables
• type Action
  • func (i Action) String() string
• type Command
  • func (t Command) Less(other Command) bool
  • func (t Command) String() string
• type Key
• type LoadInfo
• type Meta
  • func (m Meta) Contains(k Key) bool
  • func (m Meta) String() string
• type Node
• type NodeID
  • func (nID NodeID) String() string
• type Parent
• type Placement
• type PlacementState
  • func (i PlacementState) String() string
• type RangeID
  • func (id RangeID) String() string
• type RangeInfo
• type RangeState
  • func (i RangeState) String() string
• type Remote
  • func (r Remote) Addr() string
  • func (r Remote) NodeID() NodeID
• type RemoteState
  • func (i RemoteState) String() string
• type Storage

Variables

var ErrNotFound = errors.New("not found")

Types

type Action

type Action uint8

Action represents each of the state transitions that ranger can ask a node to make. (They're named for the RPC interface, but it's pluggable.) They're exposed here for testing. See also Command.

const (
	NoAction Action = iota
	Prepare
	Activate
	Deactivate
	Drop
)

func (Action) String

func (i Action) String() string

type Command

type Command struct {
	RangeIdent RangeID
	NodeIdent  NodeID
	Action     Action
}

func (Command) Less

func (t Command) Less(other Command) bool

func (Command) String

func (t Command) String() string

type Key

type Key string

Key is a point in the keyspace.

const ZeroKey Key = ""

Special case representing both negative and positive infinity. Don't compare anything against this! Always check for it explicitly.

type LoadInfo

type LoadInfo struct {
	Keys   int
	Splits []Key
}

type Meta

type Meta struct {
	Ident RangeID
	Start Key // inclusive
	End   Key // exclusive
}

Meta is a range minus all the state. Should be immutable after construction. TODO: Rename this to RangeMeta.

func (Meta) Contains

func (m Meta) Contains(k Key) bool

func (Meta) String

func (m Meta) String() string

String returns a string like: 1234 (aaa, bbb]

type Node

type Node interface {

	// GetLoadInfo returns the LoadInfo for the given range.
	// Implementations should return NotFound if (from their point of view) the
	// range doesn't exist. This can happen when GetLoadInfo and Prepare and/or
	// Drop are racing.
	GetLoadInfo(rID RangeID) (LoadInfo, error)

	// Prepare.
	Prepare(m Meta, p []Parent) error

	// Activate
	Activate(rID RangeID) error

	// Deactivate
	Deactivate(rID RangeID) error

	// Drop
	// Range state will be set to NsDropping before calling this. If an error is
	// returned, the range will be forgotten. If no error is returned, the range
	// state will be set to NsDroppingError.
	Drop(rID RangeID) error
}

type NodeID

type NodeID string

NodeID is the unique identity of a node. N.b. we used to just use naked strings for this, so it's possible that some of those hanging around. Use this instead.

const ZeroNodeID NodeID = ""

func (NodeID) String

func (nID NodeID) String() string

type Parent

type Parent struct {
	Meta       Meta
	Parents    []RangeID
	Placements []Placement
}

type Placement

type Placement struct {
	Node  string
	State PlacementState
}

type PlacementState

type PlacementState uint8

const (
	// Should never be in this state. Indicates an deserializing error.
	PsUnknown PlacementState = iota

	PsPending
	PsInactive
	PsActive
	PsMissing
	PsDropped
)

func (PlacementState) String

func (i PlacementState) String() string

type RangeID

type RangeID uint64

RangeID is the unique identity of a range.

const ZeroRange RangeID = 0

ZeroRange is not a valid RangeID.

func (RangeID) String

func (id RangeID) String() string

type RangeInfo

type RangeInfo struct {
	Meta  Meta
	State RemoteState
	Info  LoadInfo
}

RangeInfo represents something we know about a Range on a Node at a moment in time. These are emitted and cached by the Roster to anyone who cares.

type RangeState

type RangeState uint8

const (
	RsUnknown RangeState = iota

	// The range is active, i.e. it should be placed on the appropriate number
	// of nodes and left alone until we decide to supersede it with another
	// range by joining or splitting.
	RsActive

	RsSubsuming

	// The range has finished being split or joined, has been dropped from all
	// nodes, and will never be placed on any node again.
	RsObsolete
)

func (RangeState) String

func (i RangeState) String() string

type Remote

type Remote struct {
	Ident string
	Host  string
	Port  int
}

Remote represents a service listening on some remote host and port. They're returned by discovery. This is most often used to refer to nodes/rangelets, but isn't limited to that -- clients use it to find the controller, and I have vague ideas about rangelets finding distributors in future. That is why Ident is a string and not simply a NodeID.

Ident must be globally unique and stable within a ranger installation, since they are used to refer to *logical* service instances (which may have state) as they are rescheduled between machines. (For example, a k8s pod using local storage may be rescheduled on the same host with a different ip, or even on a different host if using e.g. an EBS volume.)

TODO: Should we remove support for non-node/rangelet use-cases? It would simplify the api. If not, should we store the remote type, too?

func (Remote) Addr

func (r Remote) Addr() string

Addr returns an address which can be dialled to connect to the remote.

func (Remote) NodeID

func (r Remote) NodeID() NodeID

NodeID returns the remote ident as a NodeID, since that's most often how it's used, though it isn't one.

type RemoteState

type RemoteState uint8

const (

	// Should never be in this state. Indicates a bug.
	NsUnknown RemoteState = iota

	// Stable states
	NsInactive
	NsActive

	// During transitions
	NsPreparing    // Pending  -> Inactive
	NsActivating   // Inactive -> Active
	NsDeactivating // Active   -> Inactive
	NsDropping     // Inactive -> NotFound

	// Special case: This is never returned by probes, since those only include
	// the state of ranges which the node has. This is returned by redundant
	// Drop RPCs which instruct nodes to drop a range that they don't have.
	// (Maybe it was already dropped, or maybe the node never had it. Can't
	// know.) This is a success, not an error, because those RPCs may be
	// received multiple times during a normal drop, and should be treated
	// idempotently. But we don't want to return NsUnknown, because we do know.
	NsNotFound
)

func (RemoteState) String

func (i RemoteState) String() string

type Storage

type Storage interface {
	Read() []*RangeInfo
	Write()
}