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 DebugController
  • func NewDebugControllerClient(c *grpc.ClientConn) DebugController
• type DebugStatus
• type IdentityStatus
• type NodeController
  • func NewNodeControllerClient(c *grpc.ClientConn) NodeController
• type RegistrationStatus
• type RuntimeStatus
• type SeedStatus
• type Status

Constants

const DebugModuleName = "control/debug"

DebugModuleName is the module name for the debug controller service.

const ModuleName = "control"

ModuleName is the module name for the 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.

var ErrNotImplemented = errors.New(ModuleName, 1, "control: not implemented")

ErrNotImplemented is the error raised when the node does not support the required functionality.

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 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"`

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

	// TLS is the public key 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 {
	// LastAttemptSuccessful is true if the last registration attempt has been
	// successful.
	LastAttemptSuccessful bool `json:"last_attempt_successful"`

	// LastAttemptErrorMessage contains the error message if the last
	// registration attempt has not been successful.
	LastAttemptErrorMessage string `json:"last_attempt_error_message,omitempty"`

	// LastAttempt is the time of the last registration attempt.
	// In case the node did not successfully register yet, it will be the zero timestamp.
	LastAttempt time.Time `json:"last_attempt"`

	// 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.
	Committee *commonWorker.Status `json:"committee"`
	// Executor contains the executor worker status in case this node is an executor node.
	Executor *executorWorker.Status `json:"executor,omitempty"`
	// Storage contains the storage worker status in case this node is a storage node.
	Storage *storageWorker.Status `json:"storage,omitempty"`

	// Provisioner is the name of the runtime provisioner.
	Provisioner string `json:"provisioner,omitempty"`
}

RuntimeStatus is the per-runtime status overview.

type SeedStatus

type SeedStatus struct {
	// ChainContext is the chain domain separation context.
	ChainContext string `json:"chain_context"`

	// Addresses is a list of seed node's addresses.
	Addresses []string `json:"addresses"`

	// NodePeers is a list of peers that are connected to the node.
	NodePeers []string `json:"node_peers"`
}

SeedStatus is the status of the seed node.

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,omitempty"`

	// LightClient is the status overview of the light client service.
	LightClient *consensus.LightClientStatus `json:"light_client,omitempty"`

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

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

	// Keymanager is the node's key manager worker status if the node is a key manager node.
	Keymanager *keymanagerWorker.Status `json:"keymanager,omitempty"`

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

	// P2P is the P2P status of the node.
	P2P *p2p.Status `json:"p2p,omitempty"`

	// Seed is the seed node status if the node is a seed node.
	Seed *SeedStatus `json:"seed,omitempty"`
}

Status is the current status overview.