API Gateway:Develop gateway plugins using Go

Golang

Windows

macOS

Linux

Initialize the project directory

1. Create a project directory. For example: wasm-demo-go.

2. In the directory, run the following command to initialize the Go project.

   go mod init wasm-demo-go

3. If you are in mainland China, you may need to set a proxy for downloading dependencies.

   go env -w GOPROXY=https://proxy.golang.com.cn,direct

4. Download the dependencies for building the plugin.

   go get github.com/higress-group/proxy-wasm-go-sdk@go-1.24
   go get github.com/higress-group/wasm-go@main
   go get github.com/tidwall/gjson

Develop the main.go file

package main

import (
  "github.com/higress-group/wasm-go/pkg/wrapper"
  logs "github.com/higress-group/wasm-go/pkg/log"
  "github.com/higress-group/proxy-wasm-go-sdk/proxywasm"
  "github.com/higress-group/proxy-wasm-go-sdk/proxywasm/types"
  "github.com/tidwall/gjson"
)

func main() {}

func init() {
  wrapper.SetCtx(
    // Plugin name
    "my-plugin",
    // A custom function to parse the plugin configuration
     wrapper.ParseConfigBy(parseConfig),
    // A custom function to process request headers
    wrapper.ProcessRequestHeadersBy(onHttpRequestHeaders),
  )
}

// Custom plugin configuration
type MyConfig struct {
  mockEnable bool
}

// The YAML configuration file from the console is automatically converted to JSON. You can parse the configuration directly from the json parameter.
func parseConfig(json gjson.Result, config *MyConfig, log logs.Log) error {
  // Parse the configuration and update it in the config struct.
  config.mockEnable = json.Get("mockEnable").Bool()
  return nil
}

func onHttpRequestHeaders(ctx wrapper.HttpContext, config MyConfig, log logs.Log) types.Action {
  proxywasm.AddHttpRequestHeader("hello", "world")
  if config.mockEnable {
    proxywasm.SendHttpResponse(200, nil, []byte("hello world"), -1)
  }
  return types.HeaderContinue
}

Compile the WASM file

go mod tidy
GOOS=wasip1 GOARCH=wasm go build -buildmode=c-shared -o main.wasm ./

Prerequisites

Install Docker Engine.

Use Docker Compose to launch and verify

1. Go to the project directory (take wasm-demo directory as an example). Make sure that the main.wasm file is generated in this directory.

2. In the directory, create a file named docker-compose.yaml with the following content:

   version: '3.7'
   services:
     envoy:
       image: higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/gateway:v2.1.5
       entrypoint: /usr/local/bin/envoy
       # Note: The log level for wasm is set to debug here. For production deployments, the default is info.
       command: -c /etc/envoy/envoy.yaml --component-log-level wasm:debug
       depends_on:
       - httpbin
       networks:
       - wasmtest
       ports:
       - "10000:10000"
       volumes:
       - ./envoy.yaml:/etc/envoy/envoy.yaml
       - ./main.wasm:/etc/envoy/main.wasm
   
     httpbin:
       image: kennethreitz/httpbin:latest
       networks:
       - wasmtest
       ports:
       - "12345:80"
   
   networks:
     wasmtest: {}

3. In the same directory, create a file named envoy.yaml with the following content:

   admin:
     address:
       socket_address:
         protocol: TCP
         address: 0.0.0.0
         port_value: 9901
   static_resources:
     listeners:
     - name: listener_0
       address:
         socket_address:
           protocol: TCP
           address: 0.0.0.0
           port_value: 10000
       filter_chains:
       - filters:
         - name: envoy.filters.network.http_connection_manager
           typed_config:
             "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
             scheme_header_transformation:
               scheme_to_overwrite: https
             stat_prefix: ingress_http
             route_config:
               name: local_route
               virtual_hosts:
               - name: local_service
                 domains: ["*"]
                 routes:
                 - match:
                     prefix: "/"
                   route:
                     cluster: httpbin
             http_filters:
             - name: wasmdemo
               typed_config:
                 "@type": type.googleapis.com/udpa.type.v1.TypedStruct
                 type_url: type.googleapis.com/envoy.extensions.filters.http.wasm.v3.Wasm
                 value:
                   config:
                     name: wasmdemo
                     vm_config:
                       runtime: envoy.wasm.runtime.v8
                       code:
                         local:
                           filename: /etc/envoy/main.wasm
                     configuration:
                       "@type": "type.googleapis.com/google.protobuf.StringValue"
                       value: |
                         {
                           "mockEnable": false
                         }
             - name: envoy.filters.http.router
               typed_config:
                 "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
     clusters:
     - name: httpbin
       connect_timeout: 30s
       type: LOGICAL_DNS
       # Comment out the following line to test on v6 networks
       dns_lookup_family: V4_ONLY
       lb_policy: ROUND_ROBIN
       load_assignment:
         cluster_name: httpbin
         endpoints:
         - lb_endpoints:
           - endpoint:
               address:
                 socket_address:
                   address: httpbin
                   port_value: 80

4. Run the following command to start Docker Compose.

   docker compose up

Verify the feature

Plugin with no configuration

If a plugin requires no configuration, just define an empty struct.

package main

import (
  "github.com/higress-group/wasm-go/pkg/wrapper"
  logs "github.com/higress-group/wasm-go/pkg/log"
  "github.com/higress-group/proxy-wasm-go-sdk/proxywasm"
  "github.com/higress-group/proxy-wasm-go-sdk/proxywasm/types"
)

func main() {}

func init() {
  wrapper.SetCtx(
    "hello-world",
    wrapper.ProcessRequestHeadersBy(onHttpRequestHeaders),
  )
}

type MyConfig struct {}

func onHttpRequestHeaders(ctx wrapper.HttpContext, config MyConfig, log logs.Log) types.Action {
  proxywasm.SendHttpResponse(200, nil, []byte("hello world"), -1)
  return types.HeaderContinue
}

Request external services in a plugin

Currently, only HTTP calls are supported. You can access services registered in Nacos or Kubernetes (K8s) that have their service source configured in the gateway console, as well as services with a fixed address or DNS source. Please note that you cannot use the HTTP client from the net/http library directly; you must use the HTTP client encapsulated as shown in the example below.

In the example, the service type is determined and the corresponding HTTP client is created during the configuration parsing phase. During the request header processing phase, the configured request path is used to access the corresponding service, the response headers are parsed, and then set back into the original request headers.

package main

import (
  "errors"
  "net/http"
  "strings"
  "github.com/higress-group/wasm-go/pkg/wrapper"
  logs "github.com/higress-group/wasm-go/pkg/log"
  "github.com/higress-group/proxy-wasm-go-sdk/proxywasm"
  "github.com/higress-group/proxy-wasm-go-sdk/proxywasm/types"
  "github.com/tidwall/gjson"
)

func main() {}

func init() {
  wrapper.SetCtx(
    "http-call",
    wrapper.ParseConfigBy(parseConfig),
    wrapper.ProcessRequestHeadersBy(onHttpRequestHeaders),
  )
}

type MyConfig struct {
  // The client used to initiate HTTP calls
  client      wrapper.HttpClient
  // Request URL
  requestPath string
  // The key to retrieve the corresponding field from the called service's response headers. This field is then set in the original request's headers.
  tokenHeader string
}

func parseConfig(json gjson.Result, config *MyConfig, log logs.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")
  }
  // The full FQDN with the service type, for example, my-svc.dns, my-svc.static, service-provider.DEFAULT-GROUP.public.nacos, or httpbin.my-ns.svc.cluster.local
  serviceName := json.Get("serviceName").String()
  servicePort := json.Get("servicePort").Int()
  if servicePort == 0 {
    if strings.HasSuffix(serviceName, ".static") {
      // The logical port for static IP services is 80
      servicePort = 80
    }
  }
  config.client = wrapper.NewClusterClient(wrapper.FQDNCluster{
    FQDN: serviceName,
    Port: servicePort,
        })
}

func onHttpRequestHeaders(ctx wrapper.HttpContext, config MyConfig, log logs.Log) types.Action {
  // Use the client's Get method to initiate an HTTP GET call. The timeout parameter is omitted here, so the default timeout is 500 milliseconds.
  err := config.client.Get(config.requestPath, nil,
           // The callback function, which is executed when the response is returned asynchronously.
           func(statusCode int, responseHeaders http.Header, responseBody []byte) {
             // The request did not return a 200 status code. Handle the error.
             if statusCode != http.StatusOK {
               log.Errorf("http call failed, status: %d", statusCode)
               proxywasm.SendHttpResponse(http.StatusInternalServerError, nil,
                 []byte("http call failed"), -1)
               return
             }
             // Print the HTTP status code and response body.
             log.Infof("get status: %d, response body: %s", statusCode, responseBody)
             // Parse the token field from the response headers and set it in the original request headers.
             token := responseHeaders.Get(config.tokenHeader)
             if token != "" {
               proxywasm.AddHttpRequestHeader(config.tokenHeader, token)
             }
             // Resume the original request flow to continue processing and forward it to the backend service.
             proxywasm.ResumeHttpRequest()
    })

  if err != nil {
    // The external service call failed. Continue the request and log the error.
    log.Errorf("Error occured while calling http, it seems cannot find the service cluster.")
    return types.ActionContinue
  } else {
    // Wait for the asynchronous callback to complete. Return HeaderStopAllIterationAndWatermark, which can be resumed by ResumeHttpRequest.
    return types.HeaderStopAllIterationAndWatermark
  }
}

Call Redis in a plugin

Use the following code example to implement a Redis rate-limiting plugin.

package main

import (
  "strconv"
  "time"

  "github.com/higress-group/proxy-wasm-go-sdk/proxywasm"
  "github.com/higress-group/proxy-wasm-go-sdk/proxywasm/types"
  "github.com/tidwall/gjson"
  "github.com/tidwall/resp"

  "github.com/higress-group/wasm-go/pkg/wrapper"
  logs "github.com/higress-group/wasm-go/pkg/log"
)

func main() {}

func init() {
  wrapper.SetCtx(
    "redis-demo",
    wrapper.ParseConfigBy(parseConfig),
    wrapper.ProcessRequestHeadersBy(onHttpRequestHeaders),
    wrapper.ProcessResponseHeadersBy(onHttpResponseHeaders),
  )
}

type RedisCallConfig struct {
  client wrapper.RedisClient
  qpm    int
}

func parseConfig(json gjson.Result, config *RedisCallConfig, log logs.Log) error {
  // The full FQDN with the service type, for example, my-redis.dns or redis.my-ns.svc.cluster.local
  serviceName := json.Get("serviceName").String()
  servicePort := json.Get("servicePort").Int()
  if servicePort == 0 {
    if strings.HasSuffix(serviceName, ".static") {
      // The logical port for static IP services is 80
      servicePort = 80
    } else {
      servicePort = 6379
    }
  }
  username := json.Get("username").String()
  password := json.Get("password").String()
  // Unit: milliseconds
  timeout := json.Get("timeout").Int()
  if timeout == 0 {
    timeout = 1000
  }
  qpm := json.Get("qpm").Int()
  config.qpm = int(qpm)
  config.client = wrapper.NewRedisClusterClient(wrapper.FQDNCluster{
    FQDN: serviceName,
    Port: servicePort,
  })
  return config.client.Init(username, password, timeout)
}

func onHttpRequestHeaders(ctx wrapper.HttpContext, config RedisCallConfig, log logs.Log) types.Action {
  now := time.Now()
  minuteAligned := now.Truncate(time.Minute)
  timeStamp := strconv.FormatInt(minuteAligned.Unix(), 10)
  // If the Redis API returns err != nil, it is usually because the gateway cannot find the Redis backend service. Check if the Redis backend service was accidentally deleted.
  err := config.client.Incr(timeStamp, func(response resp.Value) {
    if response.Error() != nil {
      log.Errorf("call redis error: %v", response.Error())
      proxywasm.ResumeHttpRequest()
    } else {
      ctx.SetContext("timeStamp", timeStamp)
      ctx.SetContext("callTimeLeft", strconv.Itoa(config.qpm-response.Integer()))
      if response.Integer() == 1 {
        err := config.client.Expire(timeStamp, 60, func(response resp.Value) {
          if response.Error() != nil {
            log.Errorf("call redis error: %v", response.Error())
          }
          proxywasm.ResumeHttpRequest()
        })
        if err != nil {
          log.Errorf("Error occured while calling redis, it seems cannot find the redis cluster.")
          proxywasm.ResumeHttpRequest()
        }
      } else {
        if response.Integer() > config.qpm {
          proxywasm.SendHttpResponse(429, [][2]string{{"timeStamp", timeStamp}, {"callTimeLeft", "0"}}, []byte("Too many requests\n"), -1)
        } else {
          proxywasm.ResumeHttpRequest()
        }
      }
    }
  })
  if err != nil {
    // The Redis call failed. Continue the request and log the error.
    log.Errorf("Error occured while calling redis, it seems cannot find the redis cluster.")
    return types.HeaderContinue
  } else {
    // Hold the request and wait for the Redis call to complete.
    return types.HeaderStopAllIterationAndWatermark
  }
}

func onHttpResponseHeaders(ctx wrapper.HttpContext, config RedisCallConfig, log logs.Log) types.Action {
  if ctx.GetContext("timeStamp") != nil {
    proxywasm.AddHttpResponseHeader("timeStamp", ctx.GetContext("timeStamp").(string))
  }
  if ctx.GetContext("callTimeLeft") != nil {
    proxywasm.AddHttpResponseHeader("callTimeLeft", ctx.GetContext("callTimeLeft").(string))
  }
  return types.HeaderContinue
}