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

  1. Download the installer: https://go.dev/dl/go1.19.windows-amd64.msi
  2. Run the downloaded installer to start the installation. It will be installed to Program Files or Program Files (x86) folder by default.
  3. 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

  1. Download the installer: https://go.dev/dl/go1.19.darwin-amd64.pkg
  2. Run the downloaded installer to start the installation. It will be installed to /usr/local/go folder by default.
  3. Open Terminal and type: go version. If version info is displayed, the package has been successfully installed.

Linux

  1. Download the installer: https://go.dev/dl/go1.19.linux-amd64.tar.gz
  2. Execute following commands to start the installation:
  1. rm -rf /usr/local/go && tar -C /usr/local -xzf go1.19.linux-amd64.tar.gz
    export PATH=$PATH:/usr/local/go/bin
  1. Execute go version. If version info is displayed, the package has been successfully installed.

2. TinyGo

Min Version: 0.25.0
Official download link: https://tinygo.org/getting-started/install/

Windows

  1. Download the package: https://github.com/tinygo-org/tinygo/releases/download/v0.25.0/tinygo0.25.0.windows-amd64.zip
  2. Unpack the package to the target folder
  3. If the package is unpacked to folder C:\tinygo, you need to add C:\tinygo\bin into the environment variable PATH, using set command in Command Line Prompt for example.
  1. set PATH=%PATH%;”C:\tinygo\bin”;
  1. Execute tinygo version command in Command Line Prompt. If version info is displayed, the package has been successfully installed.

MacOS

  1. Download and unpack the package
  1. tar -zxf tinygo0.25.0.darwin-amd64.tar.gz
  1. If the package is unpacked to folder /tmp, you need to add /tmp/tinygo/bin to the environment variable PATH:
  1. export PATH=/tmp/tinygo/bin:$PATH
  1. 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.

  1. Download and install the DEB package.
  1. sudo dpkg -i tinygo_0.25.0_amd64.deb
    export PATH=$PATH:/usr/local/bin
  1. 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

  1. git clone https://github.com/alibaba/higress.git, to clone project to local;
  2. 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

  1. Create a new folder for the project. For example: wasm-demo-go.
  2. Execute following commands in the new folder to initialize the Go project:
  1. go mod init wasm-demo-go
  1. If you are in the Chinese mainland, you may need to set a proxy for downloading dependencies.
  1. Download dependencies for plugin building.
  1. go get github.com/tetratelabs/proxy-wasm-go-sdk
    go get github.com/alibaba/higress/plugins/wasm-go@main
    go get github.com/tidwall/gjson

2. Write main.go

You can find a simple sample below, which provides following functions:

  1. If mockEnable is set to true, send hello world directly as the response.
  2. If mockEnable is not set or set to false, add an extra HTTP header hello: 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.

  1. package main
  2. 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
    )
  3. 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),
    )
    }
  4. // Custom plugin configuration
    type MyConfig struct {
    mockEnable bool
    }
  5. // 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
    }
  6. 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 StageTrigger TimePointcut Mounting Method
HTTP request header processing stageWhen gateway receives request headers from clientwrapper.ProcessRequestHeadersBy
HTTP request body processing stageWhen gateway receives request body from clientwrapper.ProcessRequestBodyBy
HTTP response header processing stageWhen gateway receives response headers from upstreamwrapper.ProcessResponseHeadersBy
HTTP response body processing stageWhen gateway receives response body from upstreamwrapper.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:

CategoryNameUsageAvailable
HTTP Processing Stage(s)
Request Header ProcessingGetHttpRequestHeadersGet all the request headers sent by the clientHTTP request header processing stage
ReplaceHttpRequestHeadersReplace all headers in the request.HTTP request header processing stage
GetHttpRequestHeaderGet the specified header in the request.HTTP request header processing stage
RemoveHttpRequestHeaderRemove the specified header from the request.HTTP request header processing stage
ReplaceHttpRequestHeaderReplace the specified header in the response.HTTP request header processing stage
AddHttpRequestHeaderAdd a new header to the request.HTTP request header processing stage
Request Body ProcessingGetHttpRequestBodyGet the request body received from client.HTTP request body processing stage
AppendHttpRequestBodyAppend the specified binary data to the request body.HTTP request body processing stage
PrependHttpRequestBodyPrepend the specified binary data to the request body.HTTP request body processing stage
ReplaceHttpRequestBodyReplace the entire request body received from client.HTTP request body processing stage
Response Header ProcessingGetHttpResponseHeadersGet all the response headers received from upstream.HTTP response header processing stage
ReplaceHttpResponseHeadersReplace all headers in the response.HTTP response header processing stage
GetHttpResponseHeaderGet the specified header in the response.HTTP response header processing stage
RemoveHttpResponseHeaderRemove the specified header from the response.HTTP response header processing stage
ReplaceHttpResponseHeaderReplace the specified header in the response.HTTP response header processing stage
AddHttpResponseHeaderAdd a new header to the response.HTTP response header processing stage
Response Body ProcessingGetHttpResponseBodyGet the response body received from upstream.HTTP response body processing stage
AppendHttpResponseBodyAppend the specified binary data to the response body.HTTP response body processing stage
PrependHttpResponseBodyPrepend the specified binary data to the response body.HTTP response body processing stage
ReplaceHttpResponseBodyReplace the entire response body with specific data.HTTP response body processing stage
HTTP CallDispatchHttpCallSend an HTTP request.-
GetHttpCallResponseHeadersGet the response headers associated with a DispatchHttpCall call.-
GetHttpCallResponseBodyGet the response body associated with a DispatchHttpCall call.-
GetHttpCallResponseTrailersGet the response trailer associated with a DispatchHttpCall call.-
Respond DirectlySendHttpResponseReturn a specific HTTP response immediately.-
Process ResumingResumeHttpRequestResume the request processing workflow paused before.-
ResumeHttpResponseResume 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:

  1. $ PLUGIN_NAME=wasm-demo-go make build
    image: wasm-demo-go:20230223-173305-3b1a471
    output 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:

  1. tinygo build -o main.wasm -scheduler=none -target=wasi ./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.

  1. package main
  2. 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
    )
  3. func main() {
    wrapper.SetCtx(
    hello-world”,
    wrapper.ProcessRequestHeadersBy(onHttpRequestHeaders),
    )
    }
  4. type MyConfig struct {}
  5. 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:

  1. Parse service type in the config parsing stage, and generate the corresponding HTTP client.
  2. In the HTTP request header processing stage, send a service request to the configured URL.
  3. Parse response headers and get token value using the specified key.
  4. Set the token value to the headers of the original request.
  1. package main
  2. 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
    )
  3. func main() {
    wrapper.SetCtx(
    http-call”,
    wrapper.ParseConfigBy(parseConfig),
    wrapper.ProcessRequestHeadersBy(onHttpRequestHeaders),
    )
    }
  4. 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
    }
  5. 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)
    }
    }
  6. 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
    }