API Gateway:Go を使用してゲートウェイプラグインを開発する

Go

Windows

macOS

Linux

プロジェクトディレクトリの初期化

1. プロジェクトディレクトリ (例: wasm-demo-go) を作成します。

2. ディレクトリで、次のコマンドを実行して Go プロジェクトを初期化します。

   go mod init wasm-demo-go

3. 中国本土にいる場合は、依存関係をダウンロードするためにプロキシを設定する必要がある場合があります。

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

4. プラグインをビルドするための依存関係をダウンロードします。

   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

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(
    // プラグイン名
    "my-plugin",
    // プラグイン設定を解析するためのユーザー定義関数を設定します
     wrapper.ParseConfigBy(parseConfig),
    // リクエストヘッダーを処理するためのユーザー定義関数を設定します
    wrapper.ProcessRequestHeadersBy(onHttpRequestHeaders),
  )
}

// カスタムプラグイン設定
type MyConfig struct {
  mockEnable bool
}

// コンソールからの YAML 設定は自動的に JSON に変換されます。json パラメーターから直接設定を解析できます。
func parseConfig(json gjson.Result, config *MyConfig, log logs.Log) error {
  // 設定を解析し、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
}

WASM ファイルのコンパイルと生成

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

前提条件

Docker をインストールする必要があります。

Docker Compose を使用した起動と検証

1. プラグインを作成したときに作成したディレクトリ (例: `wasm-demo` ディレクトリ) に移動します。このディレクトリに `main.wasm` ファイルがコンパイルされて生成されていることを確認します。

2. ディレクトリに、`docker-compose.yaml` という名前のファイルを次の内容で作成します：

   version: '3.7'
   services:
     envoy:
       image: higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/gateway:v2.1.5
       entrypoint: /usr/local/bin/envoy
       # ここでは wasm のデバッグレベルのロギングが有効になっていることに注意してください。本番環境のデプロイメントでは、デフォルトのレベルは 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. 同じディレクトリに、`envoy.yaml` という名前のファイルを次の内容で作成します：

   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
       # 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. 次のコマンドを実行して Docker Compose を起動します。

   docker compose up

機能の検証

設定のないプラグイン

プラグインに設定が不要な場合は、空の構造体を定義するだけです。

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
}

プラグインから外部サービスをリクエストする

現在、HTTP 呼び出しのみがサポートされています。Nacos サービス、Kubernetes サービス、およびゲートウェイコンソールで設定されている固定 IP アドレスまたは DNS ソースからのサービスにアクセスできます。なお、net/http ライブラリの HTTP クライアントは直接使用できません。次の例に示すカプセル化された HTTP クライアントを使用する必要があります。

次の例では、設定解析フェーズでサービスタイプが解析され、対応する HTTP クライアントが生成されます。リクエストヘッダー処理フェーズでは、設定されたリクエストパスに基づいて対応するサービスが呼び出されます。その後、レスポンスヘッダーが解析され、元のリクエストヘッダーに設定されます。

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 {
  // HTTP 呼び出しを開始するために使用されるクライアント
  client      wrapper.HttpClient
  // リクエスト URL
  requestPath string
  // このキーを使用して、呼び出されたサービスのレスポンスヘッダーから対応するフィールドを取得し、元のリクエストヘッダーに設定します。キーはこの設定項目です。
  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 (例: my-svc.dns、my-svc.static、service-provider.DEFAULT-GROUP.public.nacos、または httpbin.my-ns.svc.cluster.local)
  serviceName := json.Get("serviceName").String()
  servicePort := json.Get("servicePort").Int()
  if servicePort == 0 {
    if strings.HasSuffix(serviceName, ".static") {
      // 静的 IP サービスの論理ポートは 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 {
  // クライアントの Get メソッドを使用して HTTP GET 呼び出しを開始します。ここではタイムアウトパラメーターは省略されており、デフォルトのタイムアウトは 500 ms です。
  err := config.client.Get(config.requestPath, nil,
           // コールバック関数。レスポンスが非同期で返されたときに実行されます
           func(statusCode int, responseHeaders http.Header, responseBody []byte) {
             // リクエストが 200 ステータスコードを返しませんでした。これを処理します。
             if statusCode != http.StatusOK {
               log.Errorf("http call failed, status: %d", statusCode)
               proxywasm.SendHttpResponse(http.StatusInternalServerError, nil,
                 []byte("http call failed"), -1)
               return
             }
             // HTTP ステータスコードとレスポンスボディを出力します
             log.Infof("get status: %d, response body: %s", statusCode, responseBody)
             // レスポンスヘッダーからトークンフィールドを解析し、元のリクエストヘッダーに設定します
             token := responseHeaders.Get(config.tokenHeader)
             if token != "" {
               proxywasm.AddHttpRequestHeader(config.tokenHeader, token)
             }
             // 元のリクエストフローを再開して処理を続行し、バックエンドサービスに転送できるようにします
             proxywasm.ResumeHttpRequest()
    })

  if err != nil {
    // 外部サービスへの呼び出しが失敗したため、リクエストを続行し、イベントをログに記録します。
    log.Errorf("Error occured while calling http, it seems cannot find the service cluster.")
    return types.ActionContinue
  } else {
    // 非同期コールバックが完了するのを待ちます。HeaderStopAllIterationAndWatermark ステータスを返します。これは ResumeHttpRequest で再開できます。
    return types.HeaderStopAllIterationAndWatermark
  }
}

プラグインから Redis を呼び出す

次のサンプルコードを使用して、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 (例: my-redis.dns または redis.my-ns.svc.cluster.local)
  serviceName := json.Get("serviceName").String()
  servicePort := json.Get("servicePort").Int()
  if servicePort == 0 {
    if strings.HasSuffix(serviceName, ".static") {
      // 静的 IP サービスの論理ポートは 80 です
      servicePort = 80
    } else {
      servicePort = 6379
    }
  }
  username := json.Get("username").String()
  password := json.Get("password").String()
  // 単位: 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)
  // Redis API が err != nil を返す場合、通常はゲートウェイが Redis バックエンドサービスを見つけられないことが原因です。Redis バックエンドサービスが誤って削除されていないか確認してください。
  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 {
    // Redis への呼び出しが失敗したため、リクエストを続行し、イベントをログに記録します。
    log.Errorf("Error occured while calling redis, it seems cannot find the redis cluster.")
    return types.HeaderContinue
  } else {
    // リクエストを保留し、Redis の呼び出しが完了するのを待ちます。
    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
}