API Gateway：Mengembangkan plugin gerbang menggunakan Go

Go

Windows

macOS

Linux

Inisialisasi direktori proyek

1. Buat direktori proyek, misalnya wasm-demo-go.

2. Di dalam direktori tersebut, jalankan perintah berikut untuk menginisialisasi proyek Go.

   go mod init wasm-demo-go

3. Jika Anda berada di Tiongkok Daratan, Anda mungkin perlu mengatur proxy untuk mengunduh dependensi.

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

4. Unduh dependensi untuk membangun 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

Menulis file main.go

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(
    // Nama plugin
    "my-plugin",
    // Tetapkan fungsi user-defined untuk mengurai konfigurasi plugin
     wrapper.ParseConfigBy(parseConfig),
    // Tetapkan fungsi user-defined untuk memproses header permintaan
    wrapper.ProcessRequestHeadersBy(onHttpRequestHeaders),
  )
}

// Konfigurasi plugin kustom
type MyConfig struct {
  mockEnable bool
}

// Konfigurasi YAML dari konsol secara otomatis dikonversi ke JSON. Anda dapat mengurai konfigurasi langsung dari parameter json.
func parseConfig(json gjson.Result, config *MyConfig, log logs.Log) error {
  // Uraikan konfigurasi dan perbarui dalam config.
  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
}

Kompilasi dan hasilkan file WASM

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

Prasyarat

Anda harus menginstal Docker.

Mulai dan verifikasi menggunakan Docker Compose

1. Buka direktori yang Anda buat saat menulis plugin, misalnya direktori `wasm-demo`. Pastikan file `main.wasm` telah dikompilasi dan dihasilkan di direktori ini.

2. Di dalam direktori tersebut, buat file bernama `docker-compose.yaml` dengan konten berikut:

   version: '3.7'
   services:
     envoy:
       image: higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/gateway:v2.1.5
       entrypoint: /usr/local/bin/envoy
       # Perhatikan bahwa logging level debug diaktifkan untuk wasm di sini. Untuk deployment produksi, level default adalah 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. Di direktori yang sama, buat file bernama `envoy.yaml` dengan konten berikut:

   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
       # Komentari baris berikut untuk menguji pada jaringan v6
       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. Jalankan perintah berikut untuk memulai Docker Compose.

   docker compose up

Verifikasi fitur

Plugin tanpa konfigurasi

Jika plugin tidak memerlukan konfigurasi, Anda cukup mendefinisikan struct kosong.

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
}

Meminta layanan eksternal dari plugin

Saat ini, hanya panggilan HTTP yang didukung. Anda dapat mengakses layanan Nacos, layanan Kubernetes, dan layanan dari alamat IP tetap atau sumber DNS yang dikonfigurasi di konsol gerbang. Perhatikan bahwa Anda tidak dapat langsung menggunakan klien HTTP dari pustaka net/http. Anda harus menggunakan klien HTTP terenkapsulasi seperti pada contoh berikut.

Dalam contoh berikut, tipe layanan diuraikan selama fase penguraian konfigurasi untuk menghasilkan klien HTTP yang sesuai. Selama fase pemrosesan header permintaan, layanan yang sesuai dipanggil berdasarkan path permintaan yang dikonfigurasi. Header respons kemudian diuraikan dan ditetapkan dalam header permintaan asli.

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 {
  // Klien yang digunakan untuk memulai panggilan HTTP
  client      wrapper.HttpClient
  // URL permintaan
  requestPath string
  // Gunakan kunci ini untuk mengambil bidang yang sesuai dari header respons layanan yang dipanggil, lalu tetapkan dalam header permintaan asli. Kuncinya adalah item konfigurasi ini.
  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")
  }
  // FQDN lengkap dengan tipe layanan, seperti my-svc.dns, my-svc.static, service-provider.DEFAULT-GROUP.public.nacos, atau httpbin.my-ns.svc.cluster.local
  serviceName := json.Get("serviceName").String()
  servicePort := json.Get("servicePort").Int()
  if servicePort == 0 {
    if strings.HasSuffix(serviceName, ".static") {
      // Port logis untuk layanan IP statis adalah 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 {
  // Gunakan metode Get klien untuk memulai panggilan HTTP GET. Parameter timeout dihilangkan di sini, dan timeout default adalah 500 ms.
  err := config.client.Get(config.requestPath, nil,
           // Fungsi callback, yang dieksekusi ketika respons dikembalikan secara asinkron
           func(statusCode int, responseHeaders http.Header, responseBody []byte) {
             // Permintaan tidak mengembalikan kode status 200. Proses hal ini.
             if statusCode != http.StatusOK {
               log.Errorf("http call failed, status: %d", statusCode)
               proxywasm.SendHttpResponse(http.StatusInternalServerError, nil,
                 []byte("http call failed"), -1)
               return
             }
             // Cetak kode status HTTP dan badan respons
             log.Infof("get status: %d, response body: %s", statusCode, responseBody)
             // Uraikan bidang token dari header respons dan tetapkan dalam header permintaan asli
             token := responseHeaders.Get(config.tokenHeader)
             if token != "" {
               proxywasm.AddHttpRequestHeader(config.tokenHeader, token)
             }
             // Lanjutkan aliran permintaan asli untuk melanjutkan pemrosesan agar dapat diteruskan ke layanan backend
             proxywasm.ResumeHttpRequest()
    })

  if err != nil {
    // Karena panggilan ke layanan eksternal gagal, izinkan permintaan untuk dilanjutkan dan catat kejadian tersebut.
    log.Errorf("Error occured while calling http, it seems cannot find the service cluster.")
    return types.ActionContinue
  } else {
    // Tunggu callback asinkron selesai. Kembalikan status HeaderStopAllIterationAndWatermark, yang dapat dilanjutkan oleh ResumeHttpRequest.
    return types.HeaderStopAllIterationAndWatermark
  }
}

Memanggil Redis dari plugin

Gunakan contoh kode berikut untuk mengimplementasikan plugin rate-limiting Redis.

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 {
  // FQDN lengkap dengan tipe layanan, seperti my-redis.dns atau redis.my-ns.svc.cluster.local
  serviceName := json.Get("serviceName").String()
  servicePort := json.Get("servicePort").Int()
  if servicePort == 0 {
    if strings.HasSuffix(serviceName, ".static") {
      // Port logis untuk layanan IP statis adalah 80
      servicePort = 80
    } else {
      servicePort = 6379
    }
  }
  username := json.Get("username").String()
  password := json.Get("password").String()
  // Satuan: ms
  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)
  // Jika API Redis mengembalikan err != nil, biasanya karena gerbang tidak dapat menemukan layanan backend Redis. Periksa apakah layanan backend Redis tidak sengaja dihapus.
  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 {
    // Karena panggilan ke Redis gagal, izinkan permintaan untuk dilanjutkan dan catat kejadian tersebut.
    log.Errorf("Error occured while calling redis, it seems cannot find the redis cluster.")
    return types.HeaderContinue
  } else {
    // Tahan permintaan dan tunggu panggilan Redis selesai.
    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
}