higress/AGENTS.md

# AGENTS.md

Guidance for AI agents working in this repository.

Higress is a cloud-native API gateway built on Istio and Envoy. The control
plane extends Istio/pilot (Go); the data plane is Envoy extended with WASM
plugins (Go/Rust/C++/AssemblyScript) and a Go-based `golang-filter`. It supports
Ingress/Gateway API and ships a rich plugin ecosystem (including AI gateway
plugins).

## Repository layout

Top-level directories (all paths relative to repo root):

- `cmd/higress/` — main entrypoint (`main.go`) for the Higress controller binary.
- `pkg/` — core Go control-plane packages: `bootstrap/`, `cert/`, `cmd/`,
  `common/`, `config/`, `ingress/` (Ingress/Gateway config translation),
  `kube/`.
- `api/` — protobuf/CRD API definitions; Higress CRDs live in
  `api/extensions/v1alpha1` (e.g. the `WasmPlugin` type). Generated with
  `make gen-api` / `make gen-client` (see `api/gen.sh`, `buf.*`).
- `client/` — generated Go clientset for Higress CRDs.
- `istio/` — git submodules of higress-group forks of Istio (`api`, `istio`,
  `client-go`, `pkg`, `proxy`); see `.gitmodules`. Pulled via `make submodule`
  (part of `prebuild`).
- `envoy/` — Envoy + `go-control-plane` submodules (higress-group forks).
- `external/` — vendored/external mirror dirs used during build (istio, envoy,
  proxy, etc.).
- `plugins/` — all data-plane plugins (see "Plugins" below).
- `registry/` — service-discovery registry integrations (nacos, consul, eureka,
  zookeeper, direct, mcp, ...).
- `hgctl/` — the `hgctl` CLI (separate Go module) for managing Higress.
- `helm/` — Helm charts: `helm/core` (the dev/install chart) and `helm/higress`.
- `test/` — `test/e2e/` (conformance/e2e, see "Build & test") and
  `test/gateway/`.
- `tools/` — build/CI scripting: `tools/hack/` (build scripts), `tools/bin/`,
  `tools/linter/`, `*.mk`.
- `samples/` — example manifests (gateway-api, hello-world, wasmplugin, ...).
- `docker/`, `docs/`, `release-notes/` — packaging, docs, and release notes.
- `Makefile` — istio common-files wrapper (supports `BUILD_WITH_CONTAINER`);
  real targets live in `Makefile.core.mk` (+ `Makefile.overrides.mk`).

## Plugins

All plugins live under `plugins/`. See `plugins/README.md` for the contributor
overview. Prebuilt plugin images are published to
`higress-registry.cn-hangzhou.cr.aliyuncs.com/plugins`.

### plugins/wasm-go/ (primary WASM plugin framework, Go)

- `extensions/<name>/` — one directory per plugin (~59 plugins, many `ai-*`).
  Each plugin is its own Go module: `main.go`, `go.mod`/`go.sum`, `VERSION`,
  `README.md`(+`README_EN.md`), often `config/`, `util/`, `main_test.go`.
  Optional `.buildrc` sets `EXTRA_TAGS`; optional `prepare.sh`/`prepare.sh`.
  `plugin.wasm` is a build artifact and is **not** committed.
- Shared SDK: plugins depend on external modules
  `github.com/higress-group/wasm-go` and
  `github.com/higress-group/proxy-wasm-go-sdk` (NOT an in-repo SDK dir).
  In-repo, `plugins/wasm-go/pkg/mcp/` provides MCP helpers and
  `plugins/wasm-go/mcp-servers/` holds MCP server plugins.
- `examples/` — minimal reference plugins (custom-log, custom-span-attribute,
  test-foreign-function).
- Build: `plugins/wasm-go/Makefile`. `PLUGIN_NAME=<name> make build` builds a
  wasm file (output to `extensions/<name>/plugin.wasm`) + image via
  `Dockerfile`/`DockerfileBuilder` (uses a `wasm-go-builder` image, Go 1.24,
  TinyGo optional). `make build-push` pushes the image; `make local-build`
  builds locally with `GOOS=wasip1 GOARCH=wasm go build -buildmode=c-shared`.
- Conventions: `VERSION` is the image tag; the CI/e2e batch builder
  (`tools/hack/build-wasm-plugins.sh`) only compiles a wasm-go plugin whose
  `VERSION` ends in `-alpha` (see the section at the bottom of this file).

### plugins/wasm-rust/ (Rust WASM plugins)

- Workspace-style: root `Cargo.toml`/`Cargo.lock`, shared `src/`,
  `extensions/<name>/` per plugin (e.g. `ai-data-masking`, `ai-intent`,
  `request-block`, `say-hello`, `demo-wasm`), `example/`.
- Build via `plugins/wasm-rust/Makefile` (`PLUGIN_NAME=<name> make build`, plus
  `lint`/`test`); the batch builder runs it when `PLUGIN_TYPE=RUST`.

### plugins/wasm-cpp/ (C++ WASM plugins, Bazel)

- Bazel project: `WORKSPACE`, `BUILD`, `bazel/`, `common/`, `scripts/`,
  `extensions/<name>/` (e.g. `basic_auth`, `jwt_auth`, `key_rate_limit`,
  `model_router`, ...). Build via `plugins/wasm-cpp/Makefile`
  (`PLUGIN_NAME=<name> make build`), invoked with `PLUGIN_TYPE=CPP`.

### plugins/wasm-assemblyscript/ (AssemblyScript WASM plugins)

- Node/AssemblyScript project: `asconfig.json`, `package.json`, `assembly/`,
  `extensions/`.

### plugins/golang-filter/ (Envoy Go HTTP filter, NOT WASM)

- A native Envoy Golang HTTP filter (`main.go`, `mcp-server/`, `mcp-session/`);
  compiled as a shared object (`.so`) independent of Envoy — no Envoy rebuild
  needed. Requires Higress >= 2.1.0. Plugins register in `main.go`'s `init()`
  via `RegisterHttpFilterFactoryAndConfigParser`. See
  `plugins/golang-filter/README.md`.
- Build: `plugins/golang-filter/Makefile` (docker build, outputs
  `golang-filter_<arch>.so`). Wired into the gateway image build via
  `Makefile.core.mk` targets `build-golang-filter[-amd64|-arm64]`.

### How plugins are loaded

`WasmPlugin` CRDs (`extensions.higress.io/v1alpha1`) reference a plugin by
`url:` — either `oci://.../plugins/<name>:<version>` (image) or
`file:///opt/plugins/.../plugin.wasm` (local mount used in e2e). The dev install
`make install-dev-wasmplugin` sets Helm `global.volumeWasmPlugins=true` to mount
locally built wasm files into the gateway.

## Build & test

Run targets from the repo root; `Makefile` delegates to `Makefile.core.mk`.
Common ones:

- `make build` / `make build-linux` — build the Higress controller binary
  (`prebuild` first fetches submodules).
- `make build-hgctl` — build the `hgctl` CLI.
- `make build-gateway` / `make build-istio` / `make build-envoy` — data-plane
  and control-plane images (gateway pulls in the golang-filter).
- `make build-wasmplugins` — runs `tools/hack/build-wasm-plugins.sh` to batch
  build WASM plugins (respects `PLUGIN_TYPE` / `PLUGIN_NAME`; Go plugins require
  a `-alpha` VERSION).
- `make gen-api` / `make gen-client` — regenerate API/client code.

### Conformance / e2e tests (`test/e2e/`)

- Entrypoint `test/e2e/e2e_test.go`, run with build tag `conformance` and
  `--test-area` / `--execute-tests` flags.
- Cases live in `test/e2e/conformance/tests/` as **paired `<name>.go` +
  `<name>.yaml`** files (~68 cases; WASM cases are prefixed by language, e.g.
  `go-wasm-*`, `cpp-wasm-*`). Support code: `conformance/base/`,
  `conformance/utils/`, `conformance/embed.go`.
- Key Make targets (each spins up a kind cluster):
  - `make higress-conformance-test` — Ingress/Gateway conformance.
  - `make higress-wasmplugin-test` — WASM plugin e2e (uses
    `install-dev-wasmplugin`, which builds plugins and mounts them).
  - `*-prepare` / `*-skip-docker-build` / `*-clean` variants exist for
    iterating; `run-higress-e2e-test[-wasmplugin]` runs `go test` against an
    already-prepared cluster (filter with `TEST_SHORTNAME`).
- For the specifics of authoring a wasm-go e2e test, see the section below.

## Writing e2e conformance tests with wasm-go plugins

When adding an e2e conformance test that ships its own wasm-go plugin under
`plugins/wasm-go/extensions/<name>/`:

- The plugin's `VERSION` file **must end in `-alpha`** (e.g. `1.0.0-alpha`).
  CI's `tools/hack/build-wasm-plugins.sh` only compiles a wasm-go plugin when
  its version ends in `-alpha`; otherwise it silently skips it.
- `plugin.wasm` is a build artifact and is **not** committed. If the plugin
  isn't built, the `file:///opt/plugins/.../plugin.wasm` URL in the test's
  `WasmPlugin` manifest resolves to a missing file, envoy rejects the wasm
  config and fails closed, and every request on that route returns HTTP 500.
  Locally this can be masked because a previously built `plugin.wasm` still
  exists on disk — so a test can pass locally yet 500 in CI.