README.md

Intro

This SDK is used to develop the WASM Plugins for Higress in Go.

Build on local yourself

You can also build wasm locally and copy it to a Docker image. This requires a local build environment:

Go version: >= 1.24

The following is an example of building the plugin request-block.

step1. build wasm

cd examples/request-block
GOOS=wasip1 GOARCH=wasm go build -buildmode=c-shared -o main.wasm main.go

step2. build and push docker image

A simple Dockerfile:

FROM scratch
COPY main.wasm plugin.wasm

docker build -t <your_registry_hub>/request-block:1.0.0 -f <your_dockerfile> .
docker push <your_registry_hub>/request-block:1.0.0

Apply WasmPlugin API

Read this document to learn more about wasmplugin.

Create a WasmPlugin API resource:

apiVersion: extensions.higress.io/v1alpha1
kind: WasmPlugin
metadata:
  name: request-block
  namespace: higress-system
spec:
  defaultConfig:
    block_urls:
    - "swagger.html"
  url: oci://<your_registry_hub>/request-block:1.0.0

When the resource is applied on the Kubernetes cluster with kubectl apply -f <your-wasm-plugin-yaml>, the request will be blocked if the string swagger.html in the url.

curl <your_gateway_address>/api/user/swagger.html

HTTP/1.1 403 Forbidden
date: Wed, 09 Nov 2022 12:12:32 GMT
server: istio-envoy
content-length: 0

route-level & domain-level takes effect

apiVersion: extensions.higress.io/v1alpha1
kind: WasmPlugin
metadata:
  name: request-block
  namespace: higress-system
spec:
  defaultConfig:
   # this config will take effect globally (all incoming requests not matched by rules below)
   block_urls:
   - "swagger.html"
  matchRules:
  # ingress-level takes effect
  - ingress:
    - default/foo
    # the ingress foo in namespace default will use this config
    config:
      block_bodies:
      - "foo"
  - ingress:
    - default/bar
    # the ingress bar in namespace default will use this config
    config:
      block_bodies:
      - "bar"
  # domain-level takes effect
  - domain:
    - "*.example.com"
    # if the request's domain matched, this config will be used
    config:
      block_bodies:
       - "foo"
       - "bar"
  url: oci://<your_registry_hub>/request-block:1.0.0

The rules will be matched in the order of configuration. If one match is found, it will stop, and the matching configuration will take effect.

Unit Testing

For comprehensive unit testing support, see our Test Framework Documentation.