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