开发 Wasm 协议插件指南

商宗海 InfoQ

本文主要详细介绍如何基于 wasm go sdk 实现协议扩展以及相关细节，更好的帮助开发者支持更多协议场景。

创建插件工程

前置准备

安装 go链接：

https://golang.org/doc/install

安装 tinygo链接：

https://tinygo.org/getting-started/linux/

提示：如果已有 go 不需要重复安装，tinygo 用于编译成 wasm 插件。tinygo 也可以从 github 直接下载解压，把解压后的 bin 目录加入到 PATH 目录。

创建项目工程

在 $GOPATH/src 目录中创建工程, 假设项目工程名为 plugin-repo，用来包含多个插件：

1. 查看 GOPATH 路径go env | grep GOPATH2. 在 GOPATH/src 目录中创建mkdir plugin-repocd plugin-repo3. 执行项目初始化go mod init4. 创建协议插件目录名称，假设叫做

boltmkdir -p bolt/main执行完成后，目录结构如下：

plugin-repo // 插件仓库根目录├── go.mod // 项目依赖管理└── bolt // 插件名称，开发者扩展代码放到这里 └── main // 注册插件逻辑，开发者编写注册插件逻辑 └── build // 插件编译后，自动生成

因为在开始编写插件时，需要依赖 wasm sdk，需要在插件根目录，执行以下命令，拉取依赖：

go get github.com/zonghaishang/proxy-wasm-sdk-gogo mod vendor

提示：完整实例程序已经包含在 github 仓库, 请参考 plugin-repo

（https://github.com/zonghaishang/plugin-repo）。

编写插件扩展

在开始编写插件前，我们先展示编写完成后的目录结构：

plugin-repo // 插件仓库根目录├── go.mod // 项目依赖管理├── Makefile // 编译插件成 wasm 文件└── bolt ├── protocol.go ├── command.go ├── codec.go ├── api.go ├── main │ ├── main.go │ └── main_test.go ├── build // 插件编译后，自动生成 └── bolt-go.wasm

在协议扩展场景，我们主要提供编解码（codec）、编解码对象（command）、协议层支持心跳 / 响应（protocol）和注册协议（main）。

编解码实现

在处理请求和响应流程中，开发者需要实现 Codec 接口, 方法处理逻辑如下：

Decode：需要开发者将 data 中的字节数据解码成请求或者响应

Encode：需要开发者将请求或者响应编码成字节 buffer

type Codec interface { Decode(ctx context.Context, data Buffer) (Command, error) Encode(ctx context.Context, cmd Command) (Buffer, error)}

注意：在 Decode 流程中，完成解码需要调用 data.Drain(frameLen), frameLen 代表完整请求或者报文总长度。

开发者在编写编解码时，建议采用协议名 +Codec 命名，比如 bolt 编解码，命名为 boltCodec。

目前提供了示例编解码实现，请参考 boltCodec

（https://github.com/zonghaishang/plugin-repo/blob/master/bolt/codec.go）。

编解码对象

编解码主要在二进制字节流和请求 / 响应对象互转，开发者在定义请求 / 响应对象，应该遵守 command 接口。目前 command 主要分 2 类，请求和响应。

请求对象：主要包括请求（request-response）、请求（oneway）、心跳类型
响应对象：主要包括响应请求结果对象

请求对象除了表达 request-response 模型、oneway 和心跳，也会承载超时等属性，与之对应响应会承载响应状态码。

目前请求和响应的接口契约如下：

type Request interface { Command // IsOneWay Check that the request does not care about the response IsOneWay() bool GetTimeout() uint32 // request timeout}type Response interface { Command GetStatus() uint32 // response status}

不管请求还是响应，除了识别 command 类型，还承担请求头部和请求体 2 部分，头部是普通的 key-value 结构，data 部分应该是协议的 content 部分，而不是完整报文内容。

目前 command 的接口定义如下：

// Command base request or response commandtype Command interface { // Header get the data exchange header, maybe return nil. GetHeader() Header // GetData return the full message buffer, the protocol header is not included GetData() Buffer // SetData update the full message buffer, the protocol header is not included SetData(data Buffer) // IsHeartbeat check if the request is a heartbeat request IsHeartbeat() bool // CommandId get command id CommandId() uint64 // SetCommandId update command id // In upstream, because of connection multiplexing, // the id of downstream needs to be replaced with id of upstream // blog: https:mosn.io/blog/posts/multi-protocol-deep-dive/#%E5%8D%8F%E8%AE%AE%E6%89%A9%E5%B1%95%E6%A1%86%E6%9E%B6 SetCommandId(id uint64)}

目前提供了示例编解码对象实现，请参考 command

（https://github.com/zonghaishang/plugin-repo/blob/master/bolt/command.go）。

协议层

因为心跳需要协议层理解，如果开发者扩展的协议支持心跳能力，应当提供扩展

KeepAlive 实现：KeepAlive: 根据请求 id 生成一个心跳请求 commandReply
KeepAlive: 根据收到的请求，返回一个心跳响应 command

type KeepAlive interface { KeepAlive(requestId uint64) Request ReplyKeepAlive(request Request) Response}

注意：如果扩展协议不支持心跳或者不需要心跳，协议层 KeepAlive 方法返回 nil 即可

在 service mesh 场景中，因为增加了一跳，mesh 在转发过程中可能被控制面拦截，比如限流熔断，需要协议层构造并返回响应，因此开发者需要提供 Hijacker 接口实现：

Hijack: 根据请求和拦截状态码，返回一个响应 command

type Hijacker interface { // Hijack allows sidecar to hijack requests Hijack(request Request, code uint32) Response}

目前协议层接口采用组合方式，主要讲编解码独立拆分出去， protocol 接口定义：

type Protocol interface { Name() string Codec() Codec KeepAlive Hijacker Options}type Hijacker interface { // Hijack allows sidecar to hijack requests Hijack(request Request, code uint32) Response}

接口中方法描述：

Name：返回协议名称
Codec：返回协议编解码对象
KeepAlive：协议心跳实现
Hijacker：处理控制面拦截逻辑
Options：协议层配置选项开发，一般协议组合默认配置 proxy.DefaultOptions

目前提供了示例协议实现，请参考 protocol

（https://github.com/zonghaishang/plugin-repo/blob/master/bolt/protocol.go）。

注册协议

在完成协议扩展后，需要将我们编写的插件进行注册，在 wasm 扩展中，我们一切是以 Context 为核心来转的，比如 host 侧触发解码，在沙箱内会调用开发者 protocol context 的回调来解码。

因此注册协议我们需要提供一个 ProtocolContext 接口实现，和 protocol 接口极其类似:

// L7 layer extensiontype ProtocolContext interface { Name() string // protocol name Codec() Codec // frame encode & decode KeepAlive() KeepAlive // protocol keep alive Hijacker() Hijacker // protocol hijacker Options() Options // protocol options}

以 bolt 协议插件为例，我们提供 boltProtocolContext 实现:

// 1. 提供 bolt 插件 protocolContext 实现type boltProtocolContext struct { proxy.DefaultRootContext // notify on plugin start. proxy.DefaultProtocolContext // 继承默认协议实现，比如使用默认 Options() bolt proxy.Protocol // 插件真实协议实现 contextID uint32}// 2. 创建 bolt 单实例协议实例var boltProtocol = bolt.NewBoltProtocol()func boltContext(rootContextID, contextID uint32) proxy.ProtocolContext { return &boltProtocolContext{ bolt: boltProtocol, contextID: contextID, }}// 3. 注册 boltContext 协议钩子func main() { proxy.SetNewProtocolContext(boltContext)}// 4. 如果协议不支持心跳，这里允许返回 nilfunc (proto *boltProtocolContext) KeepAlive() proxy.KeepAlive { return proto.bolt}// 5. 如果需要获取插件参数，可以 override 对应方法func (proto *boltProtocolContext) OnPluginStart(conf proxy.ConfigMap) bool { proxy.Log.Infof("proxy_on_plugin_start from Go!") return true}

目前提供了示例协议注册实现，请参考 main。

调试 & 打包

开发者在编写完插件后，允许在本地 idea 直接开始调试测试，并且不依赖 MOSN 启动。目前推荐在协议开发完后，提供 main_test.go 实现，在里面写集成测试。目前 wasm sdk 提供了模拟器实现（Emulator），可以模拟完整的 MOSN 处理流程，并且可以回调开发者插件对应生命周期方法。基本用法：

// 1. 注册对应 context 和配置，boltContext 在同一个 main 包下已经实现opt := proxy.NewEmulatorOption().    WithNewProtocolContext(boltContext).    WithNewRootContext(rootContext).    WithVMConfiguration(vmConfig)
// 2. 创建一个 sidecar 模拟器host := proxy.NewHostEmulator(opt)// release lock and reset emulator statedefer host.Done()
// 3. 调用 host 对应实现，比如启动沙箱host.StartVM()
// 4. 调用启动插件host.StartPlugin()
// 5. 模拟新请求到来，创建插件上下文ctxId := host.NewProtocolContext()
// 6. 模拟 host 接收客户端请求，并解码cmd, err := host.Decode(...)
// 7. 模拟 host 转发请求，并编码upstreamBuf, err := host.Encode(...)
// 8. 模拟 host 处理完请求host.CompleteProtocolContext(ctxId)

如果要在 GoLand 中直接调试集成测试，需要执行以下操作：

GoLand->Preferences...->Go->Build Tags & Vendoring->Custom tags 填写 proxytest
调试窗口 Edit Configurations...-> 勾选 Use all custom build tags

目前提供了示例集成测试，请参考 main test

（https://github.com/zonghaishang/plugin-repo/blob/master/bolt/main/main_test.go）。

目前打包插件，可以本地开发环境编译打包，也支持镜像方式编译插件，目前通用 makefile

（https://github.com/zonghaishang/plugin-repo/blob/master/Makefile）已经提供，可以 copy 到插件项目根目录中使用。

基于 makefile，2 种打包命令分别如下（编译成功会在插件中创建 build 文件夹，并且输出 bolt-go.wasm）：

1. 本地编译，bolt 替换成开发者插件名make name=bolt2. 基于镜像编译make build-image name=bolt

目前提供了示例打包文件，请参考 bolt-go

（https://github.com/zonghaishang/plugin-repo/tree/master/bolt/build）。

启动 MOSN

目前提供了一份用于 wasm 启动的配置文件 mosn_rpc_config_wasm.json

（https://github.com/mosn/mosn/blob/master/configs/mosn_rpc_config_wasm.json），可以使用以下命令启动 MOSN:

./mosnd start -c /path/to/mosn_rpc_config_wasm.json

提示：

目前提供的配置，会开启 2045 和 2046 端口，2045 接收客户端请求，通过 2046 转发给服务端
mosn_rpc_config_wasm 中已经配置了 bolt-go.wasm，在项目根目录 etc/wasm/ 目录中
如果是自定义协议插件，配置 mosn_rpc_config_wasm.json 中有几点需要修改

vm_config.path 指向的 wasm 路径
wasm_global_plugins.plugin_name 和 codecs.config.from_wasm_plugin 要相同
codecs.config.from_wasm_plugin 和 extend_config.sub_protocol 要相同（一般协议有 2 个 listener 都要改）

其中， mosnd 可执行文件可以通过编译 MOSN 获取，执行以下命令:

下载 mosn 代码到本地 GOPATH, 可以通过本地 shell 执行：go env | grep GOPATH 查看step 1:mkdir -p $GOPATH/src/mosn.iocd $GOPATH/src/mosn.iostep 2:clone mosn 源码git clone https://github.com/mosn/mosn.gitstep 3:本地编译sudo make build-local tags=wasmer编译成功后，会在项目根目录下build/bundles/v0.21.0/binary/mosnd

如果是研发同学，可以根据 step 2 拉取代码，直接通过 GoLand 右键项目根目录 Debug（这样就不用手动去编译以及不需要命令行启动 MOSN 了），在 Edit Configurations... 调试配置页签中修改包路径和程序入口参数：

Package path: mosn.io/mosn/cmd/mosn/mainProgram arguments: start -c /path/to/mosn_rpc_config_wasm.json

提示：

/path/to 需要替换成 MOSN 根目录中到 mosn_rpc_config_wasm.json 文件的完整路径
如果要在 GoLand 中直接调试 MOSN（默认 wasm 模块没有编译），需要执行以下操作：

GoLand->Preferences...->Go->Build Tags & Vendoring->Custom tags 追加 wasmer
调试窗口 Edit Configurations...-> 勾选 Use all custom build tags

启动应用服务

开发完成后，可以先启动 MOSN，然后启动应用的服务端和客户端，以 SOFABoot 应用为例展示。目前 SOFABoot 应用测试程序已经托管到 github 上，可以通过以下命令获取:

git clone https://github.com/sofastack-guides/sofastack-mesh-demo.gitcheckout 到 wasm_benchmark 分支git checkout wasm_benchmarkcd sofastack-mesh-demo/sofa-samples-springboot2本地打包 sofaboot 应用程序mvn clean package打包成功后，会在 sofa-echo-server 和 sofa-echo-client 下生成 target 目录，其中分别包含服务端和客户端可执行程序，文件名分别为：sofa-echo-server-web-1.0-SNAPSHOT-executable.jarsofa-echo-client-web-1.0-SNAPSHOT-executable.jar

启动 SOFABoot 服务端程序：

java -DMOSN_ENABLE=true -Drpc_tr_port=12199 -Dspring.profiles.active=dev -Drpc_register_registry_ignore=true -jar sofa-echo-server-web-1.0-SNAPSHOT-executable.jar

然后启动 SOFABoot 客户端程序：

java -DMOSN_ENABLE=true -Drpc_tr_port=12198 -Dspring.profiles.active=dev -Drpc_register_registry_ignore=true -jar sofa-echo-client-web-1.0-SNAPSHOT-executable.jar

当客户端启动成功后，会在终端输出以下信息（每隔 1 秒发起一次 wasm 请求）：

[57,21,7ms]2021-03-16 20:57:05 echo result: Hello world![57,22,5ms]2021-03-16 20:57:06 echo result: Hello world![57,23,7ms]2021-03-16 20:57:07 echo result: Hello world![57,24,7ms]2021-03-16 20:57:08 echo result: Hello world![57,25,8ms]2021-03-16 20:57:09 echo result: Hello world![57,26,7ms]2021-03-16 20:57:10 echo result: Hello world![57,27,5ms]2021-03-16 20:57:11 echo result: Hello world![57,28,7ms]2021-03-16 20:57:12 echo result: Hello world!

当前扩展特性已经合并进开源社区，感兴趣同学可以查看实现原理：

wasm protocol #1579

（https://github.com/mosn/mosn/pull/1597）

mosn api #31

（https://github.com/mosn/api/pull/31）

wasm sdk-go

（https://github.com/zonghaishang/proxy-wasm-sdk-go）

实现原理文章，参考：

Protocol Extension Base On Wasm

活动推荐：

架构的下一个十年是什么样的？云的下一站是什么？移动开发还有没有未来？7 月 9-10 日，走进 ArchSummit 深圳 2021，收获 2 天技术干货，与近百位大咖面对面交流，你不仅能从他们那得到一些答案，还能 get 他们的成长经验。

点击底部【阅读原文】，随时掌握架构师峰会深圳站最新动态。

点个在看少个 bug👇

继续滑动看下一个