Golang跨语言WebAssembly插件系统开发框架Extism Go SDK的使用

安装

通过go get安装：

go get github.com/extism/go-sdk

快速入门

创建插件

Extism的核心概念是插件(Plug-in)。插件可以看作存储在.wasm文件中的代码模块。

以下是一个加载演示插件的示例：

package main

import (
	"context"
	"fmt"
	"github.com/extism/go-sdk"
	"os"
)

func main() {
	manifest := extism.Manifest{
		Wasm: []extism.Wasm{
			extism.WasmUrl{
				Url: "https://github.com/extism/plugins/releases/latest/download/count_vowels.wasm",
			},
		},
	}

	ctx := context.Background()
	config := extism.PluginConfig{}
	plugin, err := extism.NewPlugin(ctx, manifest, config, []extism.HostFunction{})

	if err != nil {
		fmt.Printf("Failed to initialize plugin: %v\n", err)
		os.Exit(1)
	}
}

调用插件函数

这个插件是用Rust编写的，功能是计算字符串中的元音字母数量。它导出了一个函数count_vowels：

func main() {
    // ...
	data := []byte("Hello, World!")
	exit, out, err := plugin.Call("count_vowels", data)
	if err != nil {
		fmt.Println(err)
		os.Exit(int(exit))
	}

	response := string(out)
	fmt.Println(response)
    // => {"count": 3, "total": 3, "vowels": "aeiouAEIOU"}
}

运行后会输出JSON格式的元音统计结果：

$ go run main.go
# => {"count":3,"total":3,"vowels":"aeiouAEIOU"}

插件状态

插件可以是状态保持的(stateful)或无状态的(stateless)。我们的元音计数插件会记住它曾经统计过的元音总数：

func main () {
    // ...
    exit, out, err := plugin.Call("count_vowels", []byte("Hello, World!"))
    if err != nil {
        fmt.Println(err)
        os.Exit(int(exit))
    }
    fmt.Println(string(out))
    // => {"count": 3, "total": 6, "vowels": "aeiouAEIOU"}

    exit, out, err = plugin.Call("count_vowels", []byte("Hello, World!"))
    if err != nil {
        fmt.Println(err)
        os.Exit(int(exit))
    }
    fmt.Println(string(out))
    // => {"count": 3, "total": 9, "vowels": "aeiouAEIOU"}
}

配置

插件可以接受配置对象。我们的元音计数插件可以配置哪些字符被视为元音：

func main() {
    manifest := extism.Manifest{
        Wasm: []extism.Wasm{
            extism.WasmUrl{
                Url: "https://github.com/extism/plugins/releases/latest/download/count_vowels.wasm",
            },
        },
        Config: map[string]string{
            "vowels": "aeiouyAEIOUY",
        },
    }

    ctx := context.Background()
    config := extism.PluginConfig{}

    plugin, err := extism.NewPlugin(ctx, manifest, config, []extism.HostFunction{})

    if err != nil {
        fmt.Printf("Failed to initialize plugin: %v\n", err)
        os.Exit(1)
    }

    exit, out, err := plugin.Call("count_vowels", []byte("Yellow, World!"))
    if err != nil {
        fmt.Println(err)
        os.Exit(int(exit))
    }

    fmt.Println(string(out))
    // => {"count": 4, "total": 4, "vowels": "aeiouAEIOUY"}
}

主机函数(Host Functions)

我们可以通过主机函数给插件提供新的能力。下面是一个KV存储的示例：

// 模拟KV存储
kvStore := make(map[string][]byte)

// 定义读取KV的函数
kvRead := extism.NewHostFunctionWithStack(
    "kv_read",
    func(ctx context.Context, p *extism.CurrentPlugin, stack []uint64) {
        key, err := p.ReadString(stack[0])
        if err != nil {
            panic(err)
        }

        value, success := kvStore[key]
        if !success {
            value = []byte{0, 0, 0, 0}
        }

        stack[0], err = p.WriteBytes(value)
    },
    []ValueType{ValueTypePTR},
    []ValueType{ValueTypePTR},
)

// 定义写入KV的函数
kvWrite := extism.NewHostFunctionWithStack(
    "kv_write",
    func(ctx context.Context, p *extism.CurrentPlugin, stack []uint64) {
        key, err := p.ReadString(stack[0])
        if err != nil {
            panic(err)
        }

        value, err := p.ReadBytes(stack[1])
        if err != nil {
            panic(err)
        }

        kvStore[key] = value
    },
    []ValueType{ValueTypePTR, ValueTypePTR},
    []ValueType{},
)

// 创建插件时传入主机函数
plugin, err := extism.NewPlugin(ctx, manifest, config, []extism.HostFunction{kvRead, kvWrite});

启用编译缓存

可以启用编译缓存来加速后续的插件初始化：

ctx := context.Background()
cache := wazero.NewCompilationCache()
defer cache.Close(ctx)

config := PluginConfig{
    EnableWasi:    true,
    ModuleConfig:  wazero.NewModuleConfig(),
    RuntimeConfig: wazero.NewRuntimeConfig().WithCompilationCache(cache),
}

_, err := NewPlugin(ctx, manifest, config, []HostFunction{})

预编译插件

如果需要创建多个插件实例，可以先编译插件：

// 第一步：编译插件
compiledPlugin, err := extism.NewCompiledPlugin(ctx, manifest, config, []extism.HostFunction{})
if err != nil {
    panic(err)
}

// 第二步：从编译好的插件创建实例
var wg sync.WaitGroup
for i := 0; i < 3; i++ {
    wg.Add(1)
    go func(id int) {
        defer wg.Done()
        
        plugin, err := compiledPlugin.Instance(ctx, extism.PluginInstanceConfig{})
        if err != nil {
            fmt.Printf("Failed to initialize plugin: %v\n", err)
            return
        }
        defer plugin.Close(ctx)
        
        data := []byte(fmt.Sprintf("Hello, World from goroutine %d!", id))
        _, out, err := plugin.Call("count_vowels", data)
        if err != nil {
            fmt.Println(err)
            return
        }
        
        fmt.Printf("Goroutine %d result: %s\n", id, string(out))
    }(i)
}
wg.Wait()

启用文件系统访问

WASM插件可以读写外部文件。我们需要在extism.Manifest中添加AllowedPaths映射：

package main

import (
	"context"
	"fmt"
	"os"

	extism "github.com/extism/go-sdk"
)

func main() {
	manifest := extism.Manifest{
		AllowedPaths: map[string]string{
			// 将主机目录data映射到WASM运行时内的/mnt目录
			"data": "/mnt",
		},
		Wasm: []extism.Wasm{
			extism.WasmFile{
				Path: "fs_plugin.wasm",
			},
		},
	}

	ctx := context.Background()
	config := extism.PluginConfig{
		EnableWasi: true,
	}
	plugin, err := extism.NewPlugin(ctx, manifest, config, []extism.HostFunction{})

	if err != nil {
		fmt.Printf("Failed to initialize plugin: %v\n", err)
		os.Exit(1)
	}

	data := []byte("Hello world, this is written from within our wasm plugin.")
	exit, _, err := plugin.Call("write_file", data)
	if err != nil {
		fmt.Println(err)
		os.Exit(int(exit))
	}
}

构建示例插件

示例插件也是用Go编写的，我们使用TinyGo来编译它们：

cd plugins/config
tinygo build -target wasi -o ../wasm/config.wasm main.go

以上是Extism Go SDK的基本使用方法，更多高级功能可以参考官方文档。