当前位置:   article > 正文

开发 Wasm 协议插件指南

应用安全防护领域设计wasm插件

点击上方“程序猿技术大咖”,关注并选择“设为星标”

回复“加群”获取入群讨论资格!

本文主要详细介绍如何基于 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. # 1. 查看GOPATH路径
  2. go env | grep GOPATH
  3. # 2. 在GOPATH/src目录中创建
  4. mkdir plugin-repo
  5. cd plugin-repo
  6. # 3. 执行项目初始化
  7. go mod init
  8. # 4. 创建协议插件目录名称,假设叫做
  9. boltmkdir -p bolt/main

执行完成后,目录结构如下:

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

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

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

提示:完整实例程序已经包含在 github 仓库, 请参考 plugin-repo(https://github.com/zonghaishang/plugin-repo)。

三、 编写插件扩展

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

  1. plugin-repo // 插件仓库根目录
  2. ├── go.mod // 项目依赖管理
  3. ├── Makefile // 编译插件成wasm文件
  4. └── bolt
  5. ├── protocol.go
  6. ├── command.go
  7. ├── codec.go
  8. ├── api.go
  9. ├── main
  10. │ ├── main.go
  11. │ └── main_test.go
  12. ├── build // 插件编译后,自动生成
  13. └── bolt-go.wasm

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

1 、编解码实现

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

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

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

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

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

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

目前提供了示例编解码实现,请参考 boltCodec(https://github.com/zonghaishang/plugin-repo/blob/master/bolt/codec.go)。

2、 编解码对象

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

  • 请求对象:主要包括请求(request-response)、请求(oneway)、心跳类型

  • 响应对象:主要包括响应请求结果对象

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

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

  1. type Request interface {
  2. Command
  3. // IsOneWay Check that the request does not care about the response
  4. IsOneWay() bool
  5. GetTimeout() uint32 // request timeout}
  6. type Response interface {
  7. Command
  8. GetStatus() uint32 // response status}

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

目前 command 的接口定义如下:

  1. // Command base request or response command
  2. type Command interface {
  3. // Header get the data exchange header, maybe return nil.
  4. GetHeader() Header
  5. // GetData return the full message buffer, the protocol header is not included
  6. GetData() Buffer
  7. // SetData update the full message buffer, the protocol header is not included
  8. SetData(data Buffer)
  9. // IsHeartbeat check if the request is a heartbeat request
  10. IsHeartbeat() bool
  11. // CommandId get command id
  12. CommandId() uint64
  13. // SetCommandId update command id
  14. // In upstream, because of connection multiplexing,
  15. // the id of downstream needs to be replaced with id of upstream
  16.     // 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    
  17. SetCommandId(id uint64)
  18. }

目前提供了示例编解码对象实现,请参考 command(https://github.com/zonghaishang/plugin-repo/blob/master/bolt/command.go)。

3、 协议层

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

  • KeepAlive: 根据请求 id 生成一个心跳请求 command

  • ReplyKeepAlive: 根据收到的请求,返回一个心跳响应 command

  1. type KeepAlive interface {
  2. KeepAlive(requestId uint64) Request
  3. ReplyKeepAlive(request Request) Response
  4. }

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

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

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

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

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

  1. type Protocol interface {
  2. Name() string Codec() Codec
  3. KeepAlive
  4. Hijacker
  5. Options
  6. }

接口中方法描述:

  • Name:返回协议名称

  • Codec:返回协议编解码对象

  • KeepAlive:协议心跳实现

  • Hijacker:处理控制面拦截逻辑

  • Options:协议层配置选项开发,一般协议组合默认配置 proxy.DefaultOptions

目前提供了示例协议实现,请参考 protocol(https://github.com/zonghaishang/plugin-repo/blob/master/bolt/protocol.go)。

4、 注册协议

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

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

  1. // L7 layer extension
  2. type ProtocolContext interface {
  3. Name() string // protocol name
  4. Codec() Codec // frame encode & decode
  5. KeepAlive() KeepAlive // protocol keep alive
  6. Hijacker() Hijacker // protocol hijacker
  7. Options() Options // protocol options
  8. }

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

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

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

5、 调试&打包

开发者在编写完插件后,允许在本地 idea 直接开始调试测试,并且不依赖 MOSN 启动。目前推荐在协议开发完后,提供 main_test.go 实现,在里面写集成测试。

目前 wasm sdk 提供了模拟器实现(Emulator), 可以模拟完整的 MOSN 处理流程,并且可以回调开发者插件对应生命周期方法。基本用法:

  1. // 1. 注册对应context和配置,boltContext在同一个main包下已经实现
  2. opt := proxy.NewEmulatorOption().
  3. WithNewProtocolContext(boltContext).
  4. WithNewRootContext(rootContext).
  5. WithVMConfiguration(vmConfig)
  6. // 2. 创建一个sidecar模拟器
  7. host := proxy.NewHostEmulator(opt)
  8. // release lock and reset emulator state
  9. defer host.Done()
  10. // 3. 调用host对应实现,比如启动沙箱
  11. host.StartVM()
  12. // 4. 调用启动插件
  13. host.StartPlugin()
  14. // 5. 模拟新请求到来,创建插件上下文
  15. ctxId := host.NewProtocolContext()
  16. // 6. 模拟host接收客户端请求,并解码
  17. cmd, err := host.Decode(...)
  18. // 7. 模拟host转发请求,并编码
  19. upstreamBuf, err := host.Encode(...)
  20. // 8. 模拟host处理完请求
  21. 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. # 1. 本地编译,bolt替换成开发者插件名
  2. make name=bolt
  3. # 2. 基于镜像编译
  4. 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 获取,执行以下命令:

  1. # 下载mosn代码到本地GOPATH, 可以通过本地shell执行:go env | grep GOPATH 查看
  2. # step 1:
  3. mkdir -p $GOPATH/src/mosn.io
  4. cd $GOPATH/src/mosn.io
  5. # step 2:
  6. # clone mosn源码
  7. git clone https://github.com/mosn/mosn.git
  8. # step 3:
  9. # 本地编译
  10. sudo make build-local tags=wasmer
  11. # 编译成功后,会在项目根目录下
  12. build/bundles/v0.21.0/binary/mosnd

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

  1. Package path: mosn.io/mosn/cmd/mosn/main
  2. Program 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 上,可以通过以下命令获取:

  1. git clone https://github.com/sofastack-guides/sofastack-mesh-demo.git
  2. # checkout到wasm_benchmark分支
  3. git checkout wasm_benchmark
  4. cd sofastack-mesh-demo/sofa-samples-springboot2
  5. # 本地打包sofaboot应用程序
  6. mvn clean package
  7. # 打包成功后,会在sofa-echo-server和sofa-echo-client下生成target目录,
  8. # 其中分别包含服务端和客户端可执行程序,文件名分别为:
  9. # sofa-echo-server-web-1.0-SNAPSHOT-executable.jar
  10. # sofa-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 请求):

  1. >>>>>>>> [57,21,7ms]2021-03-16 20:57:05 echo result: Hello world!
  2. >>>>>>>> [57,22,5ms]2021-03-16 20:57:06 echo result: Hello world!
  3. >>>>>>>> [57,23,7ms]2021-03-16 20:57:07 echo result: Hello world!
  4. >>>>>>>> [57,24,7ms]2021-03-16 20:57:08 echo result: Hello world!
  5. >>>>>>>> [57,25,8ms]2021-03-16 20:57:09 echo result: Hello world!
  6. >>>>>>>> [57,26,7ms]2021-03-16 20:57:10 echo result: Hello world!
  7. >>>>>>>> [57,27,5ms]2021-03-16 20:57:11 echo result: Hello world!
  8. >>>>>>>> [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)


感谢您的阅读,也欢迎您发表关于这篇文章的任何建议,关注我,技术不迷茫!

喜欢就点个"在看"呗,留言、转发朋友圈

声明:本文内容由网友自发贡献,不代表【wpsshop博客】立场,版权归原作者所有,本站不承担相应法律责任。如您发现有侵权的内容,请联系我们。转载请注明出处:https://www.wpsshop.cn/w/小舞很执着/article/detail/784702
推荐阅读
相关标签
  

闽ICP备14008679号