api

Documentation

Overview

Package api implements the node control API.

Index

• Constants
• Variables
• func RegisterDebugService(server *grpc.Server, service DebugController)
• func RegisterService(server *grpc.Server, service NodeController)
• type ControlledNode
• type DebugController
  • func NewDebugControllerClient(c *grpc.ClientConn) DebugController
• type DebugStatus
• type IdentityStatus
• type NodeController
  • func NewNodeControllerClient(c *grpc.ClientConn) NodeController
• type RegistrationStatus
• type RuntimeStatus
• type Status

Constants

const DebugModuleName = "control/debug"

DebugModuleName is the module name for the debug controller service.

Variables

var ErrIncompatibleBackend = errors.New(DebugModuleName, 1, "debug: incompatible backend")

ErrIncompatibleBackend is the error raised when the current beacon backend does not support manually setting the current epoch.

Functions

func RegisterDebugService

func RegisterDebugService(server *grpc.Server, service DebugController)

RegisterDebugService registers a new debug controller service with the given gRPC server.

func RegisterService

func RegisterService(server *grpc.Server, service NodeController)

RegisterService registers a new node controller service with the given gRPC server.

Types

type ControlledNode

type ControlledNode interface {
	// RequestShutdown is the method called by the control server to trigger node shutdown.
	RequestShutdown() (<-chan struct{}, error)

	// Ready returns a channel that is closed once node is ready.
	Ready() <-chan struct{}

	// GetIdentity returns the node's identity.
	GetIdentity() *identity.Identity

	// GetRegistrationStatus returns the node's current registration status.
	GetRegistrationStatus(ctx context.Context) (*RegistrationStatus, error)

	// GetRuntimeStatus returns the node's current per-runtime status.
	GetRuntimeStatus(ctx context.Context) (map[common.Namespace]RuntimeStatus, error)

	// GetPendingUpgrade returns the node's pending upgrades.
	GetPendingUpgrades(ctx context.Context) ([]*upgrade.PendingUpgrade, error)
}

ControlledNode is an internal interface that the controlled oasis-node must provide.

type DebugController

type DebugController interface {
	// SetEpoch manually sets the current epoch to the given epoch.
	//
	// NOTE: This only works with a mock beacon backend and will otherwise
	//       return an error.
	SetEpoch(ctx context.Context, epoch beacon.EpochTime) error

	// WaitNodesRegistered waits for the given number of nodes to register.
	WaitNodesRegistered(ctx context.Context, count int) error
}

DebugController is a debug-only controller useful during tests.

func NewDebugControllerClient

func NewDebugControllerClient(c *grpc.ClientConn) DebugController

NewDebugControllerClient creates a new gRPC debug controller client service.

type DebugStatus

type DebugStatus struct {
	// Enabled is true iff the node is running with DebugDontBlameOasis
	// set.
	Enabled bool `json:"enabled"`

	// AllowRoot is true iff the node is running with DebugAllowRoot
	// set.
	AllowRoot bool `json:"allow_root"`
}

DebugStatus is the current node debug status, listing the various node debug options if enabled.

type IdentityStatus

type IdentityStatus struct {
	// Node is the node identity public key.
	Node signature.PublicKey `json:"node"`

	// P2P is the public key used for p2p communication.
	P2P signature.PublicKey `json:"p2p"`

	// Consensus is the consensus public key.
	Consensus signature.PublicKey `json:"consensus"`

	// TLS are the public keys used for TLS connections.
	TLS []signature.PublicKey `json:"tls"`
}

IdentityStatus is the current node identity status, listing all the public keys that identify this node in different contexts.

type NodeController

type NodeController interface {
	// RequestShutdown requests the node to shut down gracefully.
	//
	// If the wait argument is true then the method will also wait for the
	// shutdown to complete.
	RequestShutdown(ctx context.Context, wait bool) error

	// WaitSync waits for the node to finish syncing.
	WaitSync(ctx context.Context) error

	// IsSynced checks whether the node has finished syncing.
	IsSynced(ctx context.Context) (bool, error)

	// WaitReady waits for the node to accept runtime work.
	WaitReady(ctx context.Context) error

	// IsReady checks whether the node is ready to accept runtime work.
	IsReady(ctx context.Context) (bool, error)

	// UpgradeBinary submits an upgrade descriptor to a running node.
	// The node will wait for the appropriate epoch, then update its binaries
	// and shut down.
	UpgradeBinary(ctx context.Context, descriptor *upgrade.Descriptor) error

	// CancelUpgrade cancels the specific pending upgrade, unless it is already in progress.
	CancelUpgrade(ctx context.Context, descriptor *upgrade.Descriptor) error

	// GetStatus returns the current status overview of the node.
	GetStatus(ctx context.Context) (*Status, error)
}

NodeController is a node controller interface.

func NewNodeControllerClient

func NewNodeControllerClient(c *grpc.ClientConn) NodeController

NewNodeControllerClient creates a new gRPC node controller client service.

type RegistrationStatus

type RegistrationStatus struct {
	// LastRegistration is the time of the last successful registration with the consensus registry
	// service. In case the node did not successfully register yet, it will be the zero timestamp.
	LastRegistration time.Time `json:"last_registration"`

	// Descriptor is the node descriptor that the node successfully registered with. In case the
	// node did not successfully register yet, it will be nil.
	Descriptor *node.Node `json:"descriptor,omitempty"`

	// NodeStatus is the registry live status of the node.
	NodeStatus *registry.NodeStatus `json:"node_status,omitempty"`
}

RegistrationStatus is the node registration status.

type RuntimeStatus

type RuntimeStatus struct {
	// Descriptor is the runtime registration descriptor.
	Descriptor *registry.Runtime `json:"descriptor"`

	// LatestRound is the round of the latest runtime block.
	LatestRound uint64 `json:"latest_round"`
	// LatestHash is the hash of the latest runtime block.
	LatestHash hash.Hash `json:"latest_hash"`
	// LatestTime is the timestamp of the latest runtime block.
	LatestTime block.Timestamp `json:"latest_time"`
	// LatestStateRoot is the Merkle root of the runtime state tree.
	LatestStateRoot storage.Root `json:"latest_state_root"`

	// GenesisRound is the round of the genesis runtime block.
	GenesisRound uint64 `json:"genesis_round"`
	// GenesisHash is the hash of the genesis runtime block.
	GenesisHash hash.Hash `json:"genesis_hash"`

	// LastRetainedRound is the round of the oldest retained block.
	LastRetainedRound uint64 `json:"last_retained_round"`
	// LastRetainedHash is the hash of the oldest retained block.
	LastRetainedHash hash.Hash `json:"last_retained_hash"`

	// Committee contains the runtime worker status in case this node is a (candidate) member of a
	// runtime committee (e.g., compute or storage).
	Committee *commonWorker.Status `json:"committee"`
	// Storage contains the storage worker status in case this node is a storage node.
	Storage *storageWorker.Status `json:"storage"`
}

RuntimeStatus is the per-runtime status overview.

type Status

type Status struct {
	// SoftwareVersion is the oasis-node software version.
	SoftwareVersion string `json:"software_version"`

	// Debug is the oasis-node debug status.
	Debug *DebugStatus `json:"debug,omitempty"`

	// Identity is the identity of the node.
	Identity IdentityStatus `json:"identity"`

	// Consensus is the status overview of the consensus layer.
	Consensus consensus.Status `json:"consensus"`

	// Runtimes is the status overview for each runtime supported by the node.
	Runtimes map[common.Namespace]RuntimeStatus `json:"runtimes"`

	// Registration is the node's registration status.
	Registration RegistrationStatus `json:"registration"`

	// PendingUpgrades are the node's pending upgrades.
	PendingUpgrades []*upgrade.PendingUpgrade `json:"pending_upgrades"`
}

Status is the current status overview.