runtime

package
v1.3.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 22, 2026 License: Apache-2.0 Imports: 23 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DefaultRuntime 

func DefaultRuntime(ctx context.Context) (wazero.Runtime, error)

DefaultRuntime implements NewRuntime by returning a wazero runtime with WASI and AssemblyScript host functions instantiated.

Types

type CallFn 

type CallFn func(ctx context.Context, payload []byte) ([]byte, error)

CallFn is a host callback used by method-ID based Hookr plugins.

type DefaultHasher 

type DefaultHasher struct{}

DefaultHasher is an explicit no-op hasher for trusted local development flows. It should not be used when loading untrusted plugins.

func (DefaultHasher) Hash 

func (h DefaultHasher) Hash(raw []byte) (string, error)

func (DefaultHasher) IsValid 

func (h DefaultHasher) IsValid(hash string, raw []byte) bool

type File 

type File struct {
	Path          string
	Hash          string
	Name          string
	AllowUnsigned bool
	// contains filtered or unexported fields
}

File is a struct that represents a WebAssembly module that is stored in a file. We can possibly add more types of Wasm modules in the future, which have different sources.

func NewFile 

func NewFile(path string, opts ...FileOption) (*File, error)

NewFile creates a new File instance and verifies it. If the file or name is invalid, an error is returned. Otherwise the *File is returned.

func (*File) GetData 

func (f *File) GetData() ([]byte, error)

GetData returns the WasmData for WasmData if the data has already been loaded into memory somewhere else

func (*File) Verify 

func (f *File) Verify() (*File, error)

Verify checks if the File has been configured correctly and returns it if it is. Otherwise will return a specific error

type FileOption 

type FileOption func(*File)

func WithAllowUnsigned added in v1.3.0 

func WithAllowUnsigned() FileOption

WithAllowUnsigned explicitly allows loading a plugin without a configured hash.

func WithHash 

func WithHash(hash string) FileOption

WithHash sets the expected Hash field of a File

func WithHasher 

func WithHasher(hasher Hasher) FileOption

WithHasher sets the Hasher to use for validating the hash of the File

type Hasher 

type Hasher interface {
	// Hash returns a hash for the provided data
	Hash(data []byte) (string, error)

	// IsValid checks if a hash and data match
	IsValid(hash string, data []byte) bool
}

Hasher hashes and validates byte arrays. It provides functionality for computing cryptographic hashes of data and validating data against a previously computed hash.

There are two built-in implementations:

  • Sha256Hasher: Uses the SHA-256 algorithm for secure hashing
  • DefaultHasher: A no-op implementation that performs no actual hashing

Example: 

// Using Sha256Hasher
hasher := Sha256Hasher{}

// Compute hash of a file
data, _ := os.ReadFile("plugin.wasm")
hash, _ := hasher.Hash(data)
fmt.Println("SHA-256 hash:", hash)

// Verify file integrity
isValid := hasher.IsValid(hash, data)
fmt.Println("Is valid:", isValid)

type HostMethod added in v1.3.0 

type HostMethod interface {
	FnMethod() (id uint32, fn CallFn)
}

type HostMethodFunc added in v1.3.0 

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

HostMethodFunc is a wrapper for method-ID based host callbacks.

func HostFnMethod added in v1.3.0 

func HostFnMethod(id uint32, fn CallFn) HostMethodFunc

HostFnMethod creates a method-ID based host callback registration.

func (HostMethodFunc) FnMethod added in v1.3.0 

func (f HostMethodFunc) FnMethod() (id uint32, fn CallFn)

FnMethod returns the method ID and callback.

type Invoker added in v1.3.0 

type Invoker interface {
	InvokeMethod(context.Context, uint32, []byte) ([]byte, error)
	InvokeMethodWithResponse(context.Context, uint32, []byte, func([]byte) error) error
	HasPluginMethodID(uint32) bool
	PluginHandshake() (runtimecontract.Handshake, bool)
	Close(context.Context) error
}

Invoker is the minimal runtime surface used by generated host SDKs and reload hooks.

type LiveRuntime added in v1.3.0 

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

LiveRuntime wraps Runtime with file watching and atomic reload behavior.

func NewLive added in v1.3.0 

func NewLive(ctx context.Context, cfg ReloadConfig, opts ...Option) (*LiveRuntime, error)

NewLive creates a plugin runtime that watches the plugin file and reloads it when the artifact changes on disk.

func (*LiveRuntime) Close added in v1.3.0 

func (l *LiveRuntime) Close(ctx context.Context) error

func (*LiveRuntime) HasPluginMethodID added in v1.3.0 

func (l *LiveRuntime) HasPluginMethodID(methodID uint32) bool

func (*LiveRuntime) InvokeMethod added in v1.3.0 

func (l *LiveRuntime) InvokeMethod(
	ctx context.Context,
	methodID uint32,
	payload []byte,
) ([]byte, error)

func (*LiveRuntime) InvokeMethodWithResponse added in v1.3.0 

func (l *LiveRuntime) InvokeMethodWithResponse(
	ctx context.Context,
	methodID uint32,
	payload []byte,
	fn func([]byte) error,
) error

func (*LiveRuntime) PluginHandshake added in v1.3.0 

func (l *LiveRuntime) PluginHandshake() (runtimecontract.Handshake, bool)

type NewRuntime 

type NewRuntime func(context.Context) (wazero.Runtime, error)

NewRuntime returns a new wazero runtime which is called when the New method on hookr.Runtime is called. The result is closed upon wapc.Module Close.

type Option 

type Option func(*Runtime) error

func WithContractSchema added in v1.3.0 

func WithContractSchema(schema runtimecontract.Schema) Option

WithContractSchema validates and configures expected schema + handshake requirements.

func WithFile 

func WithFile(file string, opts ...FileOption) Option

WithFile sets the file for the engine.

func WithHostMethodFns added in v1.3.0 

func WithHostMethodFns(fns ...HostMethod) Option

WithHostMethodFns sets method-ID based host callbacks callable from method-ID plugins.

func WithLogger 

func WithLogger(logFn logger.Logger) Option

WithLogger sets the logger for the engine.

func WithRandSource 

func WithRandSource(rand io.Reader) Option

WithRandSource sets the random source for the runtime.

func WithStderr 

func WithStderr(stderr io.Writer) Option

WithStderr sets the stderr writer for the engine.

func WithStdout 

func WithStdout(stdout io.Writer) Option

WithStdout sets the stdout writer for the engine.

type PluginFunc 

type PluginFunc[In, Out any] interface {
	// Call takes an input of type In and returns an output of type Out
	// It returns an error if the call fails
	Call(ctx context.Context, input In) (Out, error)
}

type ReloadConfig added in v1.3.0 

type ReloadConfig struct {
	Debounce      time.Duration
	OnReload      func(context.Context, Invoker, ReloadEvent) error
	OnReloadError func(context.Context, error)
}

ReloadConfig configures automatic live reload for a plugin runtime.

type ReloadEvent added in v1.3.0 

type ReloadEvent struct {
	PluginPath string
	Time       time.Time
	Previous   RuntimeInfo
	Current    RuntimeInfo
}

ReloadEvent describes a successful live reload attempt.

type Runtime 

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

func New 

func New(ctx context.Context, opts ...Option) (_ *Runtime, err error)

func (*Runtime) Close 

func (e *Runtime) Close(ctx context.Context) error

func (*Runtime) Compile 

func (e *Runtime) Compile() error

Compile compiles the plugin module. It must be called after the runtime is initialized and before the module is instantiated.

func (*Runtime) ContractHasMethodID added in v1.3.0 

func (e *Runtime) ContractHasMethodID(methodID uint32) bool

ContractHasMethodID reports whether the configured schema contains methodID.

func (*Runtime) ContractSchema added in v1.3.0 

func (e *Runtime) ContractSchema() (runtimecontract.Schema, bool)

ContractSchema returns the configured expected schema metadata, when provided.

func (*Runtime) ExpectedHandshake added in v1.3.0 

func (e *Runtime) ExpectedHandshake() (runtimecontract.Handshake, bool)

ExpectedHandshake returns the configured host-side handshake requirements.

func (*Runtime) HasPluginCapabilities added in v1.3.0 

func (e *Runtime) HasPluginCapabilities(mask uint64) bool

HasPluginCapabilities reports whether plugin capabilities include all bits in mask.

func (*Runtime) HasPluginMethodID added in v1.3.0 

func (e *Runtime) HasPluginMethodID(methodID uint32) bool

HasPluginMethodID reports whether the plugin declared support for methodID.

func (*Runtime) Init 

func (e *Runtime) Init() error

Init initializes the engine by setting up the runtime, config, and hookr. It is called when the engine is created.

func (*Runtime) InitConfig 

func (e *Runtime) InitConfig()

InitConfig initializes the wazero module config with the default settings.

func (*Runtime) InitHookr 

func (e *Runtime) InitHookr() error

InitHookr initializes the hookr host module and sets it to the wazero runtime.

func (*Runtime) InitRuntime 

func (e *Runtime) InitRuntime() error

Will initialize the wazero runtime

func (*Runtime) Instantiate 

func (e *Runtime) Instantiate() error

Instantiate instantiates the compiled module. It must be called after the module is compiled. It will also call the WASI and hookr start functions if

func (*Runtime) InvokeMethod added in v1.3.0 

func (e *Runtime) InvokeMethod(
	ctx context.Context,
	methodID uint32,
	payload []byte,
) ([]byte, error)

InvokeMethod calls a plugin method-ID endpoint with the given payload.

func (*Runtime) InvokeMethodWithResponse added in v1.3.0 

func (e *Runtime) InvokeMethodWithResponse(
	ctx context.Context,
	methodID uint32,
	payload []byte,
	fn func([]byte) error,
) error

InvokeMethodWithResponse calls a plugin method-ID endpoint and invokes fn with the response bytes before returning to the caller.

func (*Runtime) MemorySize 

func (e *Runtime) MemorySize() uint32

MemorySize returns the size of the memory for this instance. This is the size in bytes, not the number of pages.

func (*Runtime) PluginCapabilities added in v1.3.0 

func (e *Runtime) PluginCapabilities() uint64

PluginCapabilities returns plugin-reported capability bits (zero when unavailable).

func (*Runtime) PluginHandshake added in v1.3.0 

func (e *Runtime) PluginHandshake() (runtimecontract.Handshake, bool)

PluginHandshake returns the plugin-reported handshake if available.

func (*Runtime) PluginMethodIDs added in v1.3.0 

func (e *Runtime) PluginMethodIDs() []uint32

PluginMethodIDs returns the method IDs the plugin reported during startup introspection.

func (*Runtime) RegisterMethod added in v1.3.0 

func (e *Runtime) RegisterMethod(methodID uint32, fn CallFn)

RegisterMethod registers a method-ID based host callback.

func (*Runtime) SupportsMethodABI added in v1.3.0 

func (e *Runtime) SupportsMethodABI() bool

SupportsMethodABI reports whether the loaded plugin exports __plugin_call.

type RuntimeInfo added in v1.3.0 

type RuntimeInfo struct {
	SchemaHash   [runtimecontract.SchemaHashLen]byte
	ABIMajor     uint16
	ABIMinor     uint16
	Capabilities uint64
	MethodIDs    []uint32
}

RuntimeInfo captures the relevant runtime metadata for reload hooks.

type Sha256Hasher 

type Sha256Hasher struct{}

Sha256Hasher is an implementation of the Hasher interface. It uses SHA-256 hashing algorithm to hash and validate data. This provides a secure way to verify the integrity of WebAssembly modules.

Example: 

hasher := Sha256Hasher{}
hash, _ := hasher.Hash(wasmBytes)
fmt.Println("Use this hash for verification:", hash)

func (Sha256Hasher) Hash 

func (h Sha256Hasher) Hash(data []byte) (string, error)

func (Sha256Hasher) IsValid 

func (h Sha256Hasher) IsValid(hash string, data []byte) bool

Source Files

View all Source files

Directories

Path Synopsis
Package contract defines Hookr host-side primitives for schema-driven plugin contracts.
 Package contract defines Hookr host-side primitives for schema-driven plugin contracts.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.