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:
- 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.
- 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
- If the package is unpacked to folder
/tmp
, you need to add/tmp/tinygo/bin
to the environment variablePATH
:
- 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.
- 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:
- If you are in the Chinese mainland, you may need to set a proxy for downloading dependencies.
- Download dependencies for plugin building.
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.
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:
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:
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.
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.