Developing a WASM plugin with Golang
Implement a WASM plugin with Golang
1. Prepare Development Tools
First, install Golang and Tinygo.
1. Golang
Min Version: 1.18
Official download link: https://go.dev/doc/install
Windows
- Download the installer: https://go.dev/dl/go1.19.windows-amd64.msi
- Run the downloaded installer to start the installation. It will be installed to
Program Files
orProgram Files (x86)
folder by default. - After completed the installation, open “Run” dialog with hotkey “Win+R”. Type “cmd” in the dialog and click “OK” to open Command Line Prompt. Type:
go version
. If version info is displayed, the package has been successfully installed.
MacOS
- Download the installer: https://go.dev/dl/go1.19.darwin-amd64.pkg
- Run the downloaded installer to start the installation. It will be installed to
/usr/local/go
folder by default. - Open Terminal and type:
go version
. If version info is displayed, the package has been successfully installed.
Linux
- Download the installer: https://go.dev/dl/go1.19.linux-amd64.tar.gz
- Execute following commands to start the installation:
rm -rf /usr/local/go && tar -C /usr/local -xzf go1.19.linux-amd64.tar.gzexport PATH=$PATH:/usr/local/go/bin
- Execute
go version
. If version info is displayed, the package has been successfully installed.
2. TinyGo
Min Version: 0.28.1
Official download link: https://tinygo.org/getting-started/install/
Windows
- Download the package: https://github.com/tinygo-org/tinygo/releases/download/v0.28.1/tinygo0.28.1.windows-amd64.zip
- Unpack the package to the target folder
- If the package is unpacked to folder
C:\tinygo
, you need to addC:\tinygo\bin
into the environment variablePATH
, using set command in Command Line Prompt for example.
set PATH=%PATH%;"C:\tinygo\bin";
- Execute
tinygo version
command in Command Line Prompt. If version info is displayed, the package has been successfully installed.
MacOS
- Download and unpack the package
wget https://github.com/tinygo-org/tinygo/releases/download/v0.28.1/tinygo0.28.1.darwin-amd64.tar.gztar -zxf tinygo0.28.1.darwin-amd64.tar.gz
- If the package is unpacked to folder
/tmp
, you need to add/tmp/tinygo/bin
to the environment variablePATH
:
export PATH=/tmp/tinygo/bin:$PATH
- Execute command
tinygo version
in Terminal. If version info is displayed, the package has been successfully installed.
Linux
Following steps are based on Ubuntu AMD64. For other OSes, please refer to the official document.
- Download and install the DEB package.
wget https://github.com/tinygo-org/tinygo/releases/download/v0.28.1/tinygo_0.28.1_amd64.debsudo dpkg -i tinygo_0.28.1_amd64.debexport PATH=$PATH:/usr/local/bin
- Execute command
tinygo version
in Terminal. If version info is displayed, the package has been successfully installed.
2. Write a plugin
1. Initialize the project
You can create your wasm-go plugin directory in the repo higress’s plugins/wasm-go that you can use the scaffolding tools provided in this directory(see 1.1); or create a new directory for your Go project yourself(see 1.2). If you are developing wasm-go plugins for the first time, it is recommended to take the former.
1.1 create wasm-go plugin in plugins/wasm-go
git clone https://github.com/alibaba/higress.git
, to clone project to local;cd plugins/wasm-go; mkdir wasm-demo-go
, to go to the project’s plugins/wasm-go directory and create the wasm-demo-go directory.
1.2 create a new project yourself
- Create a new folder for the project. For example:
wasm-demo-go
. - Execute following commands in the new folder to initialize the Go project:
go mod init wasm-demo-go
- If you are in the Chinese mainland, you may need to set a proxy for downloading dependencies.
go env -w GOPROXY=https://proxy.golang.com.cn,direct
- Download dependencies for plugin building.
go get github.com/tetratelabs/proxy-wasm-go-sdkgo get github.com/alibaba/higress/plugins/wasm-go@maingo get github.com/tidwall/gjson
2. Write main.go
You can find a simple sample below, which provides following functions:
- If
mockEnable
is set totrue
, sendhello world
directly as the response. - If
mockEnable
is not set or set tofalse
, add an extra HTTP headerhello: world
to the original request. More samples can be found in section 4 below.
Note: Plugin configurations use YAML format in the gateway console. But plugins receive them in JSON format. So in the sample below, actual config data are extracted from JSON by the
parseConfig
function.
package main
import ( "github.com/alibaba/higress/plugins/wasm-go/pkg/wrapper" "github.com/tetratelabs/proxy-wasm-go-sdk/proxywasm" "github.com/tetratelabs/proxy-wasm-go-sdk/proxywasm/types" "github.com/tidwall/gjson")
func main() { wrapper.SetCtx( // Plugin name "my-plugin", // A custom function for parsing plugin configurations wrapper.ParseConfigBy(parseConfig), // A custom function for processing request headers wrapper.ProcessRequestHeadersBy(onHttpRequestHeaders), )}
// Custom plugin configurationtype MyConfig struct { mockEnable bool}
// Plugin configurations set in the console with YAML format will be converted to JSON. So we just need to parse config data from JSON.func parseConfig(json gjson.Result, config *MyConfig, log wrapper.Log) error { // Get the configuration property and set to the config object. config.mockEnable = json.Get("mockEnable").Bool() return nil}
func onHttpRequestHeaders(ctx wrapper.HttpContext, config MyConfig, log wrapper.Log) types.Action { proxywasm.AddHttpRequestHeader("hello", "world") if config.mockEnable { proxywasm.SendHttpResponse(200, nil, []byte("hello world"), -1) } return types.ActionContinue}
HTTP Processing Pointcuts
In the sample above, wrapper.ProcessRequestHeadersBy
applies custom function onHttpRequestHeaders
when processing requests inHTTP request header processing stage
. Besides that, you can use following methods to set custom processing functions for various stages.
HTTP Processing Stage | Trigger Time | Pointcut Mounting Method |
---|---|---|
HTTP request header processing stage | When gateway receives request headers from client | wrapper.ProcessRequestHeadersBy |
HTTP request body processing stage | When gateway receives request body from client | wrapper.ProcessRequestBodyBy |
HTTP response header processing stage | When gateway receives response headers from upstream | wrapper.ProcessResponseHeadersBy |
HTTP response body processing stage | When gateway receives response body from upstream | wrapper.ProcessResponseBodyBy |
Utility Functions
In the sample above, proxywasm.AddHttpRequestHeader
and proxywasm.SendHttpResponse
are two utility methods provided by the plugin SDK. You can find major utility functions in the table below:
Category | Name | Usage | Available HTTP Processing Stage(s) |
---|---|---|---|
Request Header Processing | GetHttpRequestHeaders | Get all the request headers sent by the client | HTTP request header processing stage |
ReplaceHttpRequestHeaders | Replace all headers in the request. | HTTP request header processing stage | |
GetHttpRequestHeader | Get the specified header in the request. | HTTP request header processing stage | |
RemoveHttpRequestHeader | Remove the specified header from the request. | HTTP request header processing stage | |
ReplaceHttpRequestHeader | Replace the specified header in the response. | HTTP request header processing stage | |
AddHttpRequestHeader | Add a new header to the request. | HTTP request header processing stage | |
Request Body Processing | GetHttpRequestBody | Get the request body received from client. | HTTP request body processing stage |
AppendHttpRequestBody | Append the specified binary data to the request body. | HTTP request body processing stage | |
PrependHttpRequestBody | Prepend the specified binary data to the request body. | HTTP request body processing stage | |
ReplaceHttpRequestBody | Replace the entire request body received from client. | HTTP request body processing stage | |
Response Header Processing | GetHttpResponseHeaders | Get all the response headers received from upstream. | HTTP response header processing stage |
ReplaceHttpResponseHeaders | Replace all headers in the response. | HTTP response header processing stage | |
GetHttpResponseHeader | Get the specified header in the response. | HTTP response header processing stage | |
RemoveHttpResponseHeader | Remove the specified header from the response. | HTTP response header processing stage | |
ReplaceHttpResponseHeader | Replace the specified header in the response. | HTTP response header processing stage | |
AddHttpResponseHeader | Add a new header to the response. | HTTP response header processing stage | |
Response Body Processing | GetHttpResponseBody | Get the response body received from upstream. | HTTP response body processing stage |
AppendHttpResponseBody | Append the specified binary data to the response body. | HTTP response body processing stage | |
PrependHttpResponseBody | Prepend the specified binary data to the response body. | HTTP response body processing stage | |
ReplaceHttpResponseBody | Replace the entire response body with specific data. | HTTP response body processing stage | |
HTTP Call | DispatchHttpCall | Send an HTTP request. | - |
GetHttpCallResponseHeaders | Get the response headers associated with a DispatchHttpCall call. | - | |
GetHttpCallResponseBody | Get the response body associated with a DispatchHttpCall call. | - | |
GetHttpCallResponseTrailers | Get the response trailer associated with a DispatchHttpCall call. | - | |
Respond Directly | SendHttpResponse | Return a specific HTTP response immediately. | - |
Process Resuming | ResumeHttpRequest | Resume the request processing workflow paused before. | - |
ResumeHttpResponse | Resume the response processing workflow paused before. | - |
3. Build WASM file
- If your project directory is in the plugins/wasm-go directory, see 3.1.
- If you are using a self-initialized directory, see 3.2.
3.1 Building wasm-go plugin image with scaffolding
The wasm-go plugin can be built quickly with the following command:
$ PLUGIN_NAME=wasm-demo-go make build... ...image: wasm-demo-go:20230223-173305-3b1a471output wasm file: extensions/wasm-demo-go/plugin.wasm
This command eventually builds a wasm file and a Docker image.
This local wasm file is exported to the specified plugin’s directory and can be used directly for local debugging.
You can also use make build-push
to build and push the image together.
See plugins/wasm-go for more.
3.2 Compile wasm files locally
Execute the following command:
tinygo build -o main.wasm -scheduler=none -target=wasi -gc=custom -tags='custommalloc nottinygc_finalizer' ./main.go
A new file named main.wasm will be created after a successful compilation, which will be used in the local debugging sample below as well.
When using custom plugin function in the cloud native gateway market, you just need to upload this file.
3. Local Debugging
TBD
More Samples
Plugin with No Configuration
If the plugin needs no configuration, just define an empty config struct.
package main
import ( "github.com/alibaba/higress/plugins/wasm-go/pkg/wrapper" "github.com/tetratelabs/proxy-wasm-go-sdk/proxywasm" "github.com/tetratelabs/proxy-wasm-go-sdk/proxywasm/types")
func main() { wrapper.SetCtx( "hello-world", wrapper.ProcessRequestHeadersBy(onHttpRequestHeaders), )}
type MyConfig struct {}
func onHttpRequestHeaders(ctx wrapper.HttpContext, config MyConfig, log wrapper.Log) types.Action { proxywasm.SendHttpResponse(200, nil, []byte("hello world"), -1) return types.ActionContinue}
Send Requests to External Services in the Plugin
Only HTTP requests are supported for now. You can send requests to Nacos and K8s services with service sources configured in the gateway console, and services with a static IP or DNS source. Please be noted, HTTP client in the net/http
package cannot be used here. You only use the wrapped HTTP client as shown in the sample below.
In the following sample works as below:
- Parse service type in the config parsing stage, and generate the corresponding HTTP client.
- In the HTTP request header processing stage, send a service request to the configured URL.
- Parse response headers and get token value using the specified key.
- Set the token value to the headers of the original request.
package main
import ( "errors" "net/http" "strings" "github.com/alibaba/higress/plugins/wasm-go/pkg/wrapper" "github.com/tetratelabs/proxy-wasm-go-sdk/proxywasm" "github.com/tetratelabs/proxy-wasm-go-sdk/proxywasm/types" "github.com/tidwall/gjson")
func main() { wrapper.SetCtx( "http-call", wrapper.ParseConfigBy(parseConfig), wrapper.ProcessRequestHeadersBy(onHttpRequestHeaders), )}
type MyConfig struct { // The client used to initiate an HTTP request client wrapper.HttpClient // Request URL requestPath string // Use this key when extracting token header from the service response and setting a header to the request. The value is configurable. tokenHeader string}
func parseConfig(json gjson.Result, config *MyConfig, log wrapper.Log) error { config.tokenHeader = json.Get("tokenHeader").String() if config.tokenHeader == "" { return errors.New("missing tokenHeader in config") } config.requestPath = json.Get("requestPath").String() if config.requestPath == "" { return errors.New("missing requestPath in config") } serviceSource := json.Get("serviceSource").String() // If serviceSource is set to "ip" or "dns", serviceName shall be specified when creating the service. // If serviceSource is set to "nacos" or "k8s", serviceName shall be set to the original name specified when registering the service. serviceName := json.Get("serviceName").String() servicePort := json.Get("servicePort").Int() if serviceName == "" || servicePort == 0 { return errors.New("invalid service config") } switch serviceSource { case "k8s": namespace := json.Get("namespace").String() config.client = wrapper.NewClusterClient(wrapper.K8sCluster{ ServiceName: serviceName, Namespace: namespace, Port: servicePort, }) return nil case "nacos": namespace := json.Get("namespace").String() config.client = wrapper.NewClusterClient(wrapper.NacosCluster{ ServiceName: serviceName, NamespaceID: namespace, Port: servicePort, }) return nil case "ip": config.client = wrapper.NewClusterClient(wrapper.StaticIpCluster{ ServiceName: serviceName, Port: servicePort, }) return nil case "dns": domain := json.Get("domain").String() config.client = wrapper.NewClusterClient(wrapper.DnsCluster{ ServiceName: serviceName, Port: servicePort, Domain: domain, }) return nil default: return errors.New("unknown service source: " + serviceSource) }}
func onHttpRequestHeaders(ctx wrapper.HttpContext, config MyConfig, log wrapper.Log) types.Action { // Use the Get function of the client to initiate an HTTP Get request. // The timeout parameter is omitted here, whose default value is 500ms. config.client.Get(config.requestPath, nil, // A callback function which will be called asynchronously when receiving the response. func(statusCode int, responseHeaders http.Header, responseBody []byte) { // Process the response with a status code other than 200. if statusCode != http.StatusOK { log.Errorf("http call failed, status: %d", statusCode) proxywasm.SendHttpResponse(http.StatusInternalServerError, nil, []byte("http call failed"), -1) return } // Print out the status code and response body log.Infof("get status: %d, response body: %s", statusCode, responseBody) // Extract token value from the response header and set the header of the original request token := responseHeaders.Get(config.tokenHeader) if token != "" { proxywasm.AddHttpRequestHeader(config.tokenHeader, token) } // Resume the original request processing workflow. Continue the process, so the request can be forwarded to the upstream. proxywasm.ResumeHttpRequest() }) // We need to wait for the callback to finish its process. // Return Pause action here to pause the request processing workflow, which can be resumed by a ResumeHttpRequest call. return types.ActionPause}