host

Documentation

Overview

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

Index

• Variables
• type Config
• type ConfigUpdatedEvent
• type Event
• type FailedToStartEvent
• type Provisioner
• type RichRuntime
  • func NewRichRuntime(rt Runtime) RichRuntime
• type Runtime
• type RuntimeBundle
• type RuntimeEventEmitter
• 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 Config

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

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

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

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

Config contains common configuration for the provisioned runtime.

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)

	// 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

	// 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
	// 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(ctx context.Context) error

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

	// Start attempts to start the runtime.
	Start() error

	// 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

	// Exeuctable is the path to the extracted ELF or TEE executable.
	Path string
}

RuntimeBundle is a exploded runtime bundle ready for execution.

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 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.