Help us shape the future of Go! Take the 2026 Go Developer Survey

wasm

package
v1.0.0 Latest Latest
Warning

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

Go to latest
Published: Sep 26, 2026 License: AGPL-3.0 Imports: 13 Imported by: 0

Documentation

Overview

Package wasm 在进程内运行插件的 WebAssembly 后端(wazero,纯 Go、无 CGO)。

一个插件就是一个 wasip1 reactor 模块。宿主与插件之间只有一条调用约定(ABI), 往返的消息一律是 JSON:

插件导出 lumo_alloc(size) -> ptr          宿主往插件内存里写请求前先让插件分配
插件导出 lumo_call(ptr, len) -> ptr<<32|len  处理一次请求,返回结果所在的位置
宿主导出 lumo.host_call(ptr, len) -> len   插件发起宿主调用,宿主暂存结果、只回长度
宿主导出 lumo.host_result(ptr)             插件分配好缓冲区后把暂存的结果取走

宿主调用拆成两步,是为了不在宿主函数里反过来调插件的导出函数:Go 编出来的 wasm 不保证能重入,两步交接则全程只有一个方向的调用。

插件拿不到文件系统、网络、环境变量与命令行参数;时钟与随机数照常提供(Go 运行时离不开)。 标准输出与标准错误接到宿主日志上。每次调用都有时限,超时即中断并丢弃该实例。

Index

Constants

View Source
const (
	// MemoryLimitPages 是每个实例的线性内存上限(64 KiB 一页,共 32 MiB)。
	MemoryLimitPages = 512
	// MaxInstances 是每个插件同时存在的实例数上限。实例是单线程的,并发请求靠多实例分担。
	MaxInstances = 4

	// DescribeTimeout 是 describe 调用的时限。
	DescribeTimeout = 2 * time.Second
)
View Source
const ABIVersion = 1

ABIVersion 是调用约定的版本。插件在 describe 里报出自己编译时的版本,对不上就不加载。

View Source
const HostModule = "lumo"

HostModule 是宿主函数所在的导入模块名。

Variables

View Source
var ErrBusy = errors.New("插件正忙,这次没排上")

ErrBusy 表示时限内等不到空闲实例:插件没坏,只是忙不过来。

View Source
var ErrClosed = errors.New("插件已停止运行")

ErrClosed 表示插件已卸下。

View Source
var ErrTimeout = errors.New("插件调用超时")

ErrTimeout 表示调用超时被中断。

Functions

func IsCrash

func IsCrash(err error) bool

IsCrash 判断一次失败是不是插件「坏了」:超时、陷入(panic、越界)或违反调用约定。

处理函数正常返回的错误不算——网络不通、参数不对这类是插件自己该处理的, 拿它们去累计「连续失败」会把一个只是暂时连不上外部服务的插件停掉。

Types

type Description

type Description struct {
	ABI int    `json:"abi"`
	SDK string `json:"sdk"`
	// Handlers 按类别列出插件登记了哪些处理函数,宿主据此核对清单里的声明。
	Handlers map[string][]string `json:"handlers"`
}

Description 是插件在 describe 里报出的自我描述。

type Engine

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

Engine 持有一个 wazero 运行时,所有插件共用。

func NewEngine

func NewEngine(ctx context.Context, opts Options) (*Engine, error)

NewEngine 构造运行时并装好 WASI 与宿主函数模块。

func (*Engine) Close

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

Close 关闭运行时及其上的全部插件实例。

func (*Engine) Load

func (e *Engine) Load(ctx context.Context, name string, binary []byte) (*Plugin, error)

Load 编译插件并做一次 describe,返回可调用的插件。

type GuestError

type GuestError struct{ Message string }

GuestError 是插件的处理函数自己返回的错误。插件没有崩,只是这次没做成。

func (*GuestError) Error

func (e *GuestError) Error() string

type HostFunc

type HostFunc func(ctx context.Context, plugin, op string, args json.RawMessage) (any, error)

HostFunc 处理插件发起的一次宿主调用。plugin 是调用方插件的标识。

type Options

type Options struct {
	// CacheDir 是编译缓存目录;留空则不落盘,每次启动都重新编译。
	CacheDir string
	// Host 处理插件发起的宿主调用。
	Host   HostFunc
	Logger *slog.Logger
}

Options 是 Engine 的构造参数。

type Plugin

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

Plugin 是一个编译好的插件,持有它的实例池。

func (*Plugin) Call

func (p *Plugin) Call(ctx context.Context, req Request, timeout time.Duration) (json.RawMessage, error)

Call 向插件发一次请求,返回它的结果。

func (*Plugin) Close

func (p *Plugin) Close(ctx context.Context) error

Close 停止插件:销毁空闲实例、释放编译结果。正在进行的调用结束后各自销毁实例。

func (*Plugin) Description

func (p *Plugin) Description() Description

Description 返回插件的自我描述。

func (*Plugin) Name

func (p *Plugin) Name() string

Name 返回插件标识。

type Request

type Request struct {
	// Type 是请求类别:describe、action、filter、route、cron、shortcode、widget、slot。
	Type string `json:"type"`
	// Name 是处理函数的名字,如动作名、过滤器名、路由名。
	Name string `json:"name,omitempty"`
	// Payload 是请求数据,结构随类别而定。
	Payload any `json:"payload,omitempty"`
}

Request 是宿主发给插件的一次请求。

Directories

Path Synopsis
Package wasmtest 给测试编译插件:用 Go SDK 现场编一个 wasip1 模块。
Package wasmtest 给测试编译插件:用 Go SDK 现场编一个 wasip1 模块。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL