host

Documentation

Overview

Package host implements the functionality to provision and talk to runtimes.

Index

• Variables
• type CompositeRuntime
• type Config
  • func (cfg *Config) GetComponent() (*bundle.Component, error)
• type ConfigUpdatedEvent
• type Event
• type FailedToStartEvent
• type Provisioner
• type RichRuntime
  • func NewRichRuntime(rt Runtime) RichRuntime
• type Runtime
• type RuntimeBundle
  • func (bnd *RuntimeBundle) ExplodedPath(comp component.ID, fn string) string
• type RuntimeEventEmitter
• type RuntimeHandler
• type RuntimeLogWrapper
  • func NewRuntimeLogWrapper(logger *logging.Logger, suffixes ...interface{}) *RuntimeLogWrapper
  • func (w *RuntimeLogWrapper) Write(chunk []byte) (int, error)
• type StartedEvent
• type StoppedEvent
• type UpdatedEvent

Variables

var (
	// ErrInvalidArgument is the error returned when any of the passed method arguments is invalid.
	ErrInvalidArgument = fmt.Errorf("runtime: invalid argument")
	// ErrCheckTxFailed is the error returned when a transaction is rejected by the runtime.
	ErrCheckTxFailed = fmt.Errorf("runtime: check tx failed")
	// ErrInternal is the error returned when an unspecified internal error occurs.
	ErrInternal = fmt.Errorf("runtime: internal error")
)

Types

type CompositeRuntime

type CompositeRuntime interface {
	// Component returns the runtime component with the given unique identifier.
	// If the component with the given identifier does not exist, nil is returned.
	Component(id component.ID) (Runtime, bool)
}

CompositeRuntime is a runtime that provides multiple components which are themselves runtimes.

type Config

type Config struct {
	// Bundle is the runtime bundle.
	Bundle *RuntimeBundle

	// Components are optional component ids that should be provisioned in case the runtime has
	// multiple components.
	Components []component.ID

	// Extra is an optional provisioner-specific configuration.
	Extra interface{}

	// MessageHandler is the message handler for the Runtime Host Protocol messages.
	MessageHandler RuntimeHandler

	// LocalConfig is the node-local runtime configuration.
	LocalConfig map[string]interface{}
}

Config contains common configuration for the provisioned runtime.

func (*Config) GetComponent

func (cfg *Config) GetComponent() (*bundle.Component, error)

GetComponent ensures that only a single component is configured for this runtime and returns it.

type ConfigUpdatedEvent

type ConfigUpdatedEvent struct{}

ConfigUpdatedEvent is a runtime configuration updated event.

This event can be used by runtime host implementations to signal that the underlying runtime configuration has changed and some things (e.g. registration) may need a refresh.

type Event

type Event struct {
	Started       *StartedEvent
	FailedToStart *FailedToStartEvent
	Stopped       *StoppedEvent
	Updated       *UpdatedEvent
	ConfigUpdated *ConfigUpdatedEvent
}

Event is a runtime host event.

type FailedToStartEvent

type FailedToStartEvent struct {
	// Error is the error that has occurred.
	Error error
}

FailedToStartEvent is a failed to start runtime event.

type Provisioner

type Provisioner interface {
	// NewRuntime provisions a new runtime.
	//
	// This method may return before the runtime is fully provisioned. The returned runtime will not
	// be started automatically, you must call Start explicitly.
	NewRuntime(cfg Config) (Runtime, error)

	// Name returns the name of the provisioner.
	Name() string
}

Provisioner is the runtime provisioner interface.

type RichRuntime

type RichRuntime interface {
	Runtime

	// CheckTx requests the runtime to check a given transaction.
	CheckTx(
		ctx context.Context,
		rb *block.Block,
		lb *consensus.LightBlock,
		epoch beacon.EpochTime,
		maxMessages uint32,
		batch transaction.RawBatch,
	) ([]protocol.CheckTxResult, error)

	// Query requests the runtime to answer a runtime-specific query.
	Query(
		ctx context.Context,
		rb *block.Block,
		lb *consensus.LightBlock,
		epoch beacon.EpochTime,
		maxMessages uint32,
		method string,
		args []byte,
	) ([]byte, error)

	// LocalRPC requests the runtime to handle a local RPC call.
	LocalRPC(
		ctx context.Context,
		method string,
		args interface{},
		rsp interface{},
	) error

	// ConsensusSync requests the runtime to sync its light client up to the given consensus height.
	ConsensusSync(ctx context.Context, height uint64) error
}

RichRuntime provides higher-level functions for talking with a runtime.

func NewRichRuntime

func NewRichRuntime(rt Runtime) RichRuntime

NewRichRuntime creates a new higher-level wrapper for a given runtime. It provides additional convenience functions for talking with a runtime.

type Runtime

type Runtime interface {
	// ID is the runtime identifier.
	ID() common.Namespace

	// GetActiveVersion retrieves the version of the currently active runtime.
	GetActiveVersion() (*version.Version, error)

	// GetInfo retrieves the runtime information.
	GetInfo(ctx context.Context) (*protocol.RuntimeInfoResponse, error)

	// GetCapabilityTEE retrieves the CapabilityTEE of the runtime.
	//
	// It may be nil in case the CapabilityTEE is not available or if the runtime is not running
	// inside a TEE.
	GetCapabilityTEE() (*node.CapabilityTEE, error)

	// Call sends a request message to the runtime over the Runtime Host Protocol and waits for the
	// response (which may be a failure).
	Call(ctx context.Context, body *protocol.Body) (*protocol.Body, error)

	// UpdateCapabilityTEE asks the runtime to update its CapabilityTEE with latest data.
	UpdateCapabilityTEE()

	// WatchEvents subscribes to runtime status events.
	WatchEvents() (<-chan *Event, pubsub.ClosableSubscription)

	// Start starts the runtime.
	Start()

	// Abort attempts to abort a runtime so that it will be ready to service new requests.
	// In case abort fails or force flag is set, the runtime will be restarted.
	Abort(ctx context.Context, force bool) error

	// Stop signals the provisioned runtime to stop.
	Stop()
}

Runtime is a provisioned runtime interface.

type RuntimeBundle

type RuntimeBundle struct {
	*bundle.Bundle

	// ExplodedDataDir is the path to the data directory under which the bundle has been exploded.
	ExplodedDataDir string

	// ExplodedDetachedDirs are the paths to the data directories of detached components.
	ExplodedDetachedDirs map[component.ID]string
}

RuntimeBundle is a exploded runtime bundle ready for execution.

func (*RuntimeBundle) ExplodedPath

func (bnd *RuntimeBundle) ExplodedPath(comp component.ID, fn string) string

ExplodedPath returns the path where the given asset for the given component can be found.

type RuntimeEventEmitter

type RuntimeEventEmitter interface {
	// EmitEvent allows the caller to emit a runtime event.
	EmitEvent(ev *Event)
}

RuntimeEventEmitter is the interface for emitting events for a provisioned runtime.

type RuntimeHandler

type RuntimeHandler interface {
	protocol.Handler

	// NewSubHandler creates a sub-handler specialized for the given runtime component.
	NewSubHandler(cr CompositeRuntime, component *bundle.Component) (RuntimeHandler, error)

	// AttachRuntime attaches a given hosted runtime instance to this handler.
	AttachRuntime(host Runtime) error
}

RuntimeHandler is the message handler for the host side of the runtime host protocol.

type RuntimeLogWrapper

type RuntimeLogWrapper struct {
	// contains filtered or unexported fields
}

RuntimeLogWrapper is a Writer that interprets data written to it as JSON-formatted runtime logs, and re-logs the messages as oasis-node logs. For example, it translates runtime log levels to oasis-node log levels, because the two have slightly different formats.

It hardcodes some assumptions about the format of the runtime logs.

func NewRuntimeLogWrapper

func NewRuntimeLogWrapper(logger *logging.Logger, suffixes ...interface{}) *RuntimeLogWrapper

NewRuntimeLogWrapper creates a new RuntimeLogWrapper.

func (*RuntimeLogWrapper) Write

func (w *RuntimeLogWrapper) Write(chunk []byte) (int, error)

Write implements io.Writer

type StartedEvent

type StartedEvent struct {
	// Version is the runtime version.
	Version version.Version

	// CapabilityTEE is the newly started runtime's CapabilityTEE. It may be nil in case the runtime
	// is not running inside a TEE.
	CapabilityTEE *node.CapabilityTEE
}

StartedEvent is a runtime started event.

type StoppedEvent

type StoppedEvent struct{}

StoppedEvent is a runtime stopped event.

type UpdatedEvent

type UpdatedEvent struct {
	// Version is the runtime version.
	Version version.Version

	// CapabilityTEE is the updated runtime's CapabilityTEE. It may be nil in case the runtime is
	// not running inside a TEE.
	CapabilityTEE *node.CapabilityTEE
}

UpdatedEvent is a runtime metadata updated event.