Documentation ¶
Index ¶
- Constants
- func DecodeF32(input uint64) float32
- func DecodeF64(input uint64) float64
- func DecodeI32(input uint64) int32
- func DecodeU32(input uint64) uint32
- func EncodeF32(input float32) uint64
- func EncodeF64(input float64) uint64
- func EncodeI32(input int32) uint64
- func EncodeI64(input int64) uint64
- func EncodeU32(input uint32) uint64
- func RuntimeVersion() string
- func SetLogLevel(level LogLevel)
- type CurrentPlugin
- func (p *CurrentPlugin) Alloc(n uint64) (uint64, error)
- func (p *CurrentPlugin) AllocWithContext(ctx context.Context, n uint64) (uint64, error)
- func (p *CurrentPlugin) Free(offset uint64) error
- func (p *CurrentPlugin) FreeWithContext(ctx context.Context, offset uint64) error
- func (p *CurrentPlugin) Length(offs uint64) (uint64, error)
- func (p *CurrentPlugin) LengthWithContext(ctx context.Context, offs uint64) (uint64, error)
- func (p *CurrentPlugin) Log(level LogLevel, message string)
- func (p *CurrentPlugin) Logf(level LogLevel, format string, args ...any)
- func (p *CurrentPlugin) Memory() api.Memory
- func (p *CurrentPlugin) ReadBytes(offset uint64) ([]byte, error)
- func (p *CurrentPlugin) ReadString(offset uint64) (string, error)
- func (p *CurrentPlugin) WriteBytes(b []byte) (uint64, error)
- func (p *CurrentPlugin) WriteString(s string) (uint64, error)
- type FunctionDefinition
- type HostFunction
- type HostFunctionStackCallback
- type HttpRequest
- type InputOffsetKey
- type LogLevel
- type Manifest
- type ManifestMemory
- type Module
- type Plugin
- func (plugin *Plugin) Call(name string, data []byte) (uint32, []byte, error)
- func (plugin *Plugin) CallWithContext(ctx context.Context, name string, data []byte) (uint32, []byte, error)
- func (p *Plugin) Close() error
- func (p *Plugin) CloseWithContext(ctx context.Context) error
- func (plugin *Plugin) FunctionExists(name string) bool
- func (plugin *Plugin) GetError() string
- func (plugin *Plugin) GetErrorWithContext(ctx context.Context) string
- func (plugin *Plugin) GetOutput() ([]byte, error)
- func (plugin *Plugin) GetOutputWithContext(ctx context.Context) ([]byte, error)
- func (p *Plugin) Log(level LogLevel, message string)
- func (p *Plugin) Logf(level LogLevel, format string, args ...any)
- func (plugin *Plugin) Memory() api.Memory
- func (plugin *Plugin) SetInput(data []byte) (uint64, error)
- func (plugin *Plugin) SetInputWithContext(ctx context.Context, data []byte) (uint64, error)
- func (p *Plugin) SetLogger(logger func(LogLevel, string))
- type PluginConfig
- type PluginCtxKey
- type Runtime
- type ValueType
- type Wasm
- type WasmData
- type WasmFile
- type WasmUrl
Constants ¶
const ( // ValueTypeI32 is a 32-bit integer. ValueTypeI32 = api.ValueTypeI32 // ValueTypeI64 is a 64-bit integer. ValueTypeI64 = api.ValueTypeI64 // ValueTypeF32 is a 32-bit floating point number. ValueTypeF32 = api.ValueTypeF32 // ValueTypeF64 is a 64-bit floating point number. ValueTypeF64 = api.ValueTypeF64 // ValueTypePTR represents a pointer to an Extism memory block. Alias for ValueTypeI64 ValueTypePTR = ValueTypeI64 )
const ( None runtimeType = iota Haskell Wasi )
Variables ¶
This section is empty.
Functions ¶
func RuntimeVersion ¶ added in v1.3.1
func RuntimeVersion() string
func SetLogLevel ¶ added in v1.4.0
func SetLogLevel(level LogLevel)
SetPluginLogLevel sets the log level for the plugin
Types ¶
type CurrentPlugin ¶
type CurrentPlugin struct {
// contains filtered or unexported fields
}
func (*CurrentPlugin) Alloc ¶
func (p *CurrentPlugin) Alloc(n uint64) (uint64, error)
Alloc a new memory block of the given length, returning its offset
func (*CurrentPlugin) AllocWithContext ¶ added in v1.2.0
Alloc a new memory block of the given length, returning its offset
func (*CurrentPlugin) Free ¶
func (p *CurrentPlugin) Free(offset uint64) error
Free the memory block specified by the given offset
func (*CurrentPlugin) FreeWithContext ¶ added in v1.2.0
func (p *CurrentPlugin) FreeWithContext(ctx context.Context, offset uint64) error
Free the memory block specified by the given offset
func (*CurrentPlugin) Length ¶
func (p *CurrentPlugin) Length(offs uint64) (uint64, error)
Length returns the number of bytes allocated at the specified offset
func (*CurrentPlugin) LengthWithContext ¶ added in v1.2.0
Length returns the number of bytes allocated at the specified offset
func (*CurrentPlugin) Log ¶
func (p *CurrentPlugin) Log(level LogLevel, message string)
func (*CurrentPlugin) Logf ¶
func (p *CurrentPlugin) Logf(level LogLevel, format string, args ...any)
func (*CurrentPlugin) Memory ¶
func (p *CurrentPlugin) Memory() api.Memory
Memory returns the plugin's WebAssembly memory interface.
func (*CurrentPlugin) ReadBytes ¶
func (p *CurrentPlugin) ReadBytes(offset uint64) ([]byte, error)
ReadBytes reads a byte array from memory
func (*CurrentPlugin) ReadString ¶
func (p *CurrentPlugin) ReadString(offset uint64) (string, error)
ReadString reads a string from wasm memory
func (*CurrentPlugin) WriteBytes ¶
func (p *CurrentPlugin) WriteBytes(b []byte) (uint64, error)
WriteBytes writes a string to wasm memory and return the offset
func (*CurrentPlugin) WriteString ¶
func (p *CurrentPlugin) WriteString(s string) (uint64, error)
Write a string to wasm memory and return the offset
type FunctionDefinition ¶ added in v1.5.0
type FunctionDefinition struct {
// contains filtered or unexported fields
}
FunctionDefinition represents a function defined in a module. It provides a wrapper around the underlying wazero function definition.
func (*FunctionDefinition) Name ¶ added in v1.5.0
func (f *FunctionDefinition) Name() string
type HostFunction ¶
type HostFunction struct { Name string Namespace string Params []api.ValueType Returns []api.ValueType // contains filtered or unexported fields }
HostFunction represents a custom function defined by the host.
func NewHostFunctionWithStack ¶
func NewHostFunctionWithStack( name string, callback HostFunctionStackCallback, params []ValueType, returnTypes []ValueType) HostFunction
NewHostFunctionWithStack creates a new instance of a HostFunction, which is designed to provide custom functionality in a given host environment. Here's an example multiplication function that loads operands from memory:
mult := NewHostFunctionWithStack( "mult", func(ctx context.Context, plugin *CurrentPlugin, stack []uint64) { a := DecodeI32(stack[0]) b := DecodeI32(stack[1]) stack[0] = EncodeI32(a * b) }, []ValueType{ValueTypeI64, ValueTypeI64}, ValueTypeI64 )
func (*HostFunction) SetNamespace ¶
func (f *HostFunction) SetNamespace(namespace string)
type HostFunctionStackCallback ¶
type HostFunctionStackCallback func(ctx context.Context, p *CurrentPlugin, stack []uint64)
HostFunctionStackCallback is a Function implemented in Go instead of a wasm binary. The plugin parameter is the calling plugin, used to access memory or exported functions and logging.
The stack is includes any parameters encoded according to their ValueType. Its length is the max of parameter or result length. When there are results, write them in order beginning at index zero. Do not use the stack after the function returns.
Here's a typical way to read three parameters and write back one.
// read parameters in index order argv, argvBuf := DecodeU32(inputs[0]), DecodeU32(inputs[1]) // write results back to the stack in index order stack[0] = EncodeU32(ErrnoSuccess)
This function can be non-deterministic or cause side effects. It also has special properties not defined in the WebAssembly Core specification. Notably, this uses the caller's memory (via Module.Memory). See https://www.w3.org/TR/wasm-core-1/#host-functions%E2%91%A0
To safely decode/encode values from/to the uint64 inputs/ouputs, users are encouraged to use Extism's EncodeXXX or DecodeXXX functions.
type HttpRequest ¶
HttpRequest represents an HTTP request to be made by the plugin.
type InputOffsetKey ¶ added in v1.4.0
type InputOffsetKey string
type LogLevel ¶
type LogLevel int32
LogLevel defines different log levels.
func (LogLevel) ExtismCompat ¶ added in v1.4.0
type Manifest ¶
type Manifest struct { Wasm []Wasm `json:"wasm"` Memory *ManifestMemory `json:"memory,omitempty"` Config map[string]string `json:"config,omitempty"` AllowedHosts []string `json:"allowed_hosts,omitempty"` AllowedPaths map[string]string `json:"allowed_paths,omitempty"` Timeout uint64 `json:"timeout_ms,omitempty"` }
Manifest represents the plugin's manifest, including Wasm modules and configuration. See https://extism.org/docs/concepts/manifest for schema.
func (*Manifest) UnmarshalJSON ¶
type ManifestMemory ¶ added in v1.2.0
type Module ¶ added in v1.5.0
type Module struct {
// contains filtered or unexported fields
}
Module is a wrapper around a wazero module. It allows us to provide our own API and stability guarantees despite any changes that wazero may choose to make.
func (*Module) ExportedFunctions ¶ added in v1.5.0
func (m *Module) ExportedFunctions() map[string]FunctionDefinition
ExportedFunctions returns a map of functions exported from the module keyed by the function name.
type Plugin ¶
type Plugin struct { Runtime *Runtime Modules map[string]Module Main Module Timeout time.Duration Config map[string]string // NOTE: maybe we can have some nice methods for getting/setting vars Var map[string][]byte AllowedHosts []string AllowedPaths map[string]string LastStatusCode int LastResponseHeaders map[string]string MaxHttpResponseBytes int64 MaxVarBytes int64 Adapter *observe.AdapterBase TraceCtx *observe.TraceCtx // contains filtered or unexported fields }
Plugin is used to call WASM functions
func NewPlugin ¶
func NewPlugin( ctx context.Context, manifest Manifest, config PluginConfig, functions []HostFunction) (*Plugin, error)
NewPlugin creates a new Extism plugin with the given manifest, configuration, and host functions. The returned plugin can be used to call WebAssembly functions and interact with the plugin.
func (*Plugin) CallWithContext ¶ added in v1.2.0
func (plugin *Plugin) CallWithContext(ctx context.Context, name string, data []byte) (uint32, []byte, error)
Call a function by name with the given input and context, returning the output
func (*Plugin) CloseWithContext ¶ added in v1.2.0
CloseWithContext closes the plugin by freeing the underlying resources.
func (*Plugin) FunctionExists ¶
FunctionExists returns true when the named function is present in the plugin's main Module
func (*Plugin) GetError ¶
GetError retrieves the error message from the last WebAssembly function call, if any.
func (*Plugin) GetErrorWithContext ¶ added in v1.2.0
GetErrorWithContext retrieves the error message from the last WebAssembly function call.
func (*Plugin) GetOutput ¶
GetOutput retrieves the output data from the last WebAssembly function call.
func (*Plugin) GetOutputWithContext ¶ added in v1.2.0
GetOutputWithContext retrieves the output data from the last WebAssembly function call.
func (*Plugin) SetInput ¶
SetInput sets the input data for the plugin to be used in the next WebAssembly function call.
func (*Plugin) SetInputWithContext ¶ added in v1.2.0
SetInputWithContext sets the input data for the plugin to be used in the next WebAssembly function call.
type PluginConfig ¶
type PluginConfig struct { ModuleConfig wazero.ModuleConfig RuntimeConfig wazero.RuntimeConfig EnableWasi bool ObserveAdapter *observe.AdapterBase ObserveOptions *observe.Options EnableHttpResponseHeaders bool }
PluginConfig contains configuration options for the Extism plugin.
type PluginCtxKey ¶ added in v1.4.0
type PluginCtxKey string
type Runtime ¶
type Runtime struct { Wazero wazero.Runtime Extism api.Module Env api.Module // contains filtered or unexported fields }
Runtime represents the Extism plugin's runtime environment, including the underlying Wazero runtime and modules.
type WasmData ¶
type WasmData struct { Data []byte `json:"data"` Hash string `json:"hash,omitempty"` Name string `json:"name,omitempty"` }
WasmData represents in-memory WebAssembly data, including its content, hash, and name.
type WasmFile ¶
type WasmFile struct { Path string `json:"path"` Hash string `json:"hash,omitempty"` Name string `json:"name,omitempty"` }
WasmFile represents WebAssembly data that needs to be loaded from a file.
type WasmUrl ¶
type WasmUrl struct { Url string `json:"url"` Hash string `json:"hash,omitempty"` Headers map[string]string `json:"headers,omitempty"` Name string `json:"name,omitempty"` Method string `json:"method,omitempty"` }
WasmUrl represents WebAssembly data that needs to be fetched from a URL.