{"owner":"higress-group","repo":"higress","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# AGENTS.md\n\nGuidance for AI agents working in this repository.\n\nHigress is a cloud-native API gateway built on Istio and Envoy. The control\nplane extends Istio/pilot (Go); the data plane is Envoy extended with WASM\nplugins (Go/Rust/C++/AssemblyScript) and a Go-based `golang-filter`. It supports\nIngress/Gateway API and ships a rich plugin ecosystem (including AI gateway\nplugins).\n\n## Mandatory issue-spec gate for agent-assisted changes\n\nBefore substantive implementation, determine whether an AI or coding agent is\nmaterially participating under the\n[agent-assisted contribution policy](docs/developers/agent-assisted-contributions.md).\nFor every contribution to which that policy applies:\n\n- do not begin implementation until a Higress maintainer has approved both the\n  Proposal Issue and Design Issue; an issue-spec status or agent assertion is\n  not maintainer approval;\n- implement only through TASKs authorized by the approved Design and preserve\n  traceability to the applicable SPECs;\n- ensure the Design contains a concrete Verification Plan before verification\n  begins; and\n- create and complete the corresponding verification TASKs with exact commands,\n  results, evidence links, and hashes before claiming success or asking\n  maintainers to accept verification or review.\n\nDeclare agent participation in the PR template. The policy excludes human-only\nwork. Small documentation-only corrections limited to spelling, punctuation,\nwhitespace, or formatting (such as typo adjustments) may skip the issue-spec\nworkflow when they involve no substantive choice or behavioral effect.\nAgent-assisted bug fixes and material feature work must still follow this gate.\nAn authenticated `gh` user with canonical-repository `role_name` of `maintain`\nor `admin` may use the verified maintainer/administrator exception documented\nin the canonical policy. Before bypassing the gate, run the documented `gh`\nidentity and collaborator-permission checks, record the login, returned\n`role_name`, actual PR author, and rationale in the PR, and still disclose agent\nparticipation. The PR author must match the verified login and the PR must attest\nthat `GH_TOKEN` and `GITHUB_TOKEN` were unset for every verification command;\nany failed or mismatched check disqualifies the exception. Select the matching\nverified-exception status in the PR template. The accepting or merging maintainer\nmust independently validate current live evidence with token overrides unset.\nThis exception never waives bug-fix runtime verification.\n\nFor work subject to this gate, the maintainer-approved issue-spec Design Issue\nis the authoritative design carrier. Do not create or require a plugin-local\n`design/` document for the gate. An optional durable capability spec serves a\nseparate long-lived purpose and, only when maintainers request one, belongs at\n`issue-spec/specs/<plugin-qualified-capability>/spec.md`, using a unique\nlowercase, hyphen-separated capability slug that identifies the plugin. It\nmust not replace or duplicate the approved Design Issue. Higress leaves\n`durable_specs` unset; do not invent a path field or enable repository\nprojection without explicit maintainer direction.\n\n## Repository layout\n\nTop-level directories (all paths relative to repo root):\n\n- `cmd/higress/` — main entrypoint (`main.go`) for the Higress controller binary.\n- `pkg/` — core Go control-plane packages: `bootstrap/`, `cert/`, `cmd/`,\n  `common/`, `config/`, `ingress/` (Ingress/Gateway config translation),\n  `kube/`.\n- `api/` — protobuf/CRD API definitions; Higress CRDs live in\n  `api/extensions/v1alpha1` (e.g. the `WasmPlugin` type). Generated with\n  `make gen-api` / `make gen-client` (see `api/gen.sh`, `buf.*`).\n- `client/` — generated Go clientset for Higress CRDs.\n- `istio/` — git submodules of higress-group forks of Istio (`api`, `istio`,\n  `client-go`, `pkg`, `proxy`); see `.gitmodules`. Pulled via `make submodule`\n  (part of `prebuild`).\n- `envoy/` — Envoy + `go-control-plane` submodules (higress-group forks).\n- `external/` — vendored/external mirror dirs used during build (istio, envoy,\n  proxy, etc.).\n- `plugins/` — all data-plane plugins (see \"Plugins\" below).\n- `registry/` — service-discovery registry integrations (nacos, consul, eureka,\n  zookeeper, direct, mcp, ...).\n- `hgctl/` — the `hgctl` CLI (separate Go module) for managing Higress.\n- `helm/` — Helm charts: `helm/core` (the dev/install chart) and `helm/higress`.\n- `test/` — `test/e2e/` (conformance/e2e, see \"Build & test\") and\n  `test/gateway/`.\n- `tools/` — build/CI scripting: `tools/hack/` (build scripts), `tools/bin/`,\n  `tools/linter/`, `*.mk`.\n- `samples/` — example manifests (gateway-api, hello-world, wasmplugin, ...).\n- `docker/`, `docs/`, `release-notes/` — packaging, docs, and release notes.\n- `Makefile` — istio common-files wrapper (supports `BUILD_WITH_CONTAINER`);\n  real targets live in `Makefile.core.mk` (+ `Makefile.overrides.mk`).\n\n## Plugins\n\nAll plugins live under `plugins/`. See `plugins/README.md` for the contributor\noverview. Prebuilt plugin images are published to\n`higress-registry.cn-hangzhou.cr.aliyuncs.com/plugins`.\n\n### plugins/wasm-go/ (primary WASM plugin framework, Go)\n\n- `extensions/<name>/` — one directory per plugin (~59 plugins, many `ai-*`).\n  Each plugin is its own Go module: `main.go`, `go.mod`/`go.sum`, `VERSION`,\n  `README.md`(+`README_EN.md`), often `config/`, `util/`, `main_test.go`.\n  Optional `.buildrc` sets `EXTRA_TAGS`; optional `prepare.sh`/`prepare.sh`.\n  `plugin.wasm` is a build artifact and is **not** committed.\n- Shared SDK: plugins depend on external modules\n  `github.com/higress-group/wasm-go` and\n  `github.com/higress-group/proxy-wasm-go-sdk` (NOT an in-repo SDK dir).\n  In-repo, `plugins/wasm-go/pkg/mcp/` provides MCP helpers and\n  `plugins/wasm-go/mcp-servers/` holds MCP server plugins.\n- `examples/` — reference plugins, including the Go counterparts of C++\n  plugins. These are excluded from official plugin release discovery.\n- Build: `plugins/wasm-go/Makefile`. `PLUGIN_NAME=<name> make build` builds an\n  official plugin; add `PLUGIN_ROOT=examples` for a reference plugin. The wasm\n  file is written below the selected root, and the image is built via\n  `Dockerfile`/`DockerfileBuilder` (uses a `wasm-go-builder` image, Go 1.24,\n  TinyGo optional). `make build-push` pushes the image; `make local-build`\n  builds locally with `GOOS=wasip1 GOARCH=wasm go build -buildmode=c-shared`.\n- Conventions: `VERSION` is the image tag; the CI/e2e batch builder\n  (`tools/hack/build-wasm-plugins.sh`) only compiles a wasm-go plugin whose\n  `VERSION` ends in `-alpha` (see the section at the bottom of this file).\n\n### plugins/wasm-rust/ (Rust WASM plugins)\n\n- Workspace-style: root `Cargo.toml`/`Cargo.lock`, shared `src/`, the official\n  `extensions/ai-data-masking/` plugin, and reference implementations under\n  `example/`.\n- Build via `plugins/wasm-rust/Makefile` (`PLUGIN_NAME=<name> make build`, plus\n  `lint`/`test`); add `PLUGIN_ROOT=example` for a reference plugin. The batch\n  builder runs only official `extensions/` plugins when `PLUGIN_TYPE=RUST`.\n\n### plugins/wasm-cpp/ (C++ WASM plugins, Bazel)\n\n- Bazel project: `WORKSPACE`, `BUILD`, `bazel/`, `common/`, `scripts/`,\n  `extensions/<name>/` (e.g. `basic_auth`, `jwt_auth`, `key_rate_limit`,\n  `model_router`, ...). Build via `plugins/wasm-cpp/Makefile`\n  (`PLUGIN_NAME=<name> make build`), invoked with `PLUGIN_TYPE=CPP`.\n\n### plugins/wasm-assemblyscript/ (AssemblyScript WASM plugins)\n\n- Node/AssemblyScript project: `asconfig.json`, `package.json`, `assembly/`,\n  `extensions/`.\n\n### plugins/golang-filter/ (Envoy Go HTTP filter, NOT WASM)\n\n- A native Envoy Golang HTTP filter (`main.go`, `mcp-server/`, `mcp-session/`);\n  compiled as a shared object (`.so`) independent of Envoy — no Envoy rebuild\n  needed. Requires Higress >= 2.1.0. Plugins register in `main.go`'s `init()`\n  via `RegisterHttpFilterFactoryAndConfigParser`. See\n  `plugins/golang-filter/README.md`.\n- Build: `plugins/golang-filter/Makefile` (docker build, outputs\n  `golang-filter_<arch>.so`). Wired into the gateway image build via\n  `Makefile.core.mk` targets `build-golang-filter[-amd64|-arm64]`.\n\n### How plugins are loaded\n\n`WasmPlugin` CRDs (`extensions.higress.io/v1alpha1`) reference a plugin by\n`url:` — either `oci://.../plugins/<name>:<version>` (image) or\n`file:///opt/plugins/.../plugin.wasm` (local mount used in e2e). The dev install\n`make install-dev-wasmplugin` sets Helm `global.volumeWasmPlugins=true` to mount\nlocally built wasm files into the gateway.\n\n## Build & test\n\nRun targets from the repo root; `Makefile` delegates to `Makefile.core.mk`.\nCommon ones:\n\n- `make build` / `make build-linux` — build the Higress controller binary\n  (`prebuild` first fetches submodules).\n- `make build-hgctl` — build the `hgctl` CLI.\n- `make build-gateway` / `make build-istio` / `make build-envoy` — data-plane\n  and control-plane images (gateway pulls in the golang-filter).\n- `make build-wasmplugins` — runs `tools/hack/build-wasm-plugins.sh` to batch\n  build WASM plugins (respects `PLUGIN_TYPE` / `PLUGIN_NAME`; Go plugins require\n  a `-alpha` VERSION).\n- `make gen-api` / `make gen-client` — regenerate API/client code.\n\n### Conformance / e2e tests (`test/e2e/`)\n\n- Entrypoint `test/e2e/e2e_test.go`, run with build tag `conformance` and\n  `--test-area` / `--execute-tests` flags.\n- Cases live in `test/e2e/conformance/tests/` as **paired `<name>.go` +\n  `<name>.yaml`** files (~68 cases; WASM cases are prefixed by language, e.g.\n  `go-wasm-*`, `cpp-wasm-*`). Support code: `conformance/base/`,\n  `conformance/utils/`, `conformance/embed.go`.\n- Key Make targets (each spins up a kind cluster):\n  - `make higress-conformance-test` — Ingress/Gateway conformance.\n  - `make higress-wasmplugin-test` — WASM plugin e2e (uses\n    `install-dev-wasmplugin`, which builds plugins and mounts them).\n  - `*-prepare` / `*-skip-docker-build` / `*-clean` variants exist for\n    iterating; `run-higress-e2e-test[-wasmplugin]` runs `go test` against an\n    already-prepared cluster (filter with `TEST_SHORTNAME`).\n- For the specifics of authoring a wasm-go e2e test, see the section below.\n\n## Writing e2e conformance tests with wasm-go plugins\n\nWhen adding an e2e conformance test that ships its own wasm-go plugin under\n`plugins/wasm-go/extensions/<name>/`:\n\n- The plugin's `VERSION` file **must end in `-alpha`** (e.g. `1.0.0-alpha`).\n  CI's `tools/hack/build-wasm-plugins.sh` only compiles a wasm-go plugin when\n  its version ends in `-alpha`; otherwise it silently skips it.\n- `plugin.wasm` is a build artifact and is **not** committed. If the plugin\n  isn't built, the `file:///opt/plugins/.../plugin.wasm` URL in the test's\n  `WasmPlugin` manifest resolves to a missing file, envoy rejects the wasm\n  config and fails closed, and every request on that route returns HTTP 500.\n  Locally this can be masked because a previously built `plugin.wasm` still\n  exists on disk — so a test can pass locally yet 500 in CI.\n"},"files":{"AGENTS.md":"# AGENTS.md\n\nGuidance for AI agents working in this repository.\n\nHigress is a cloud-native API gateway built on Istio and Envoy. The control\nplane extends Istio/pilot (Go); the data plane is Envoy extended with WASM\nplugins (Go/Rust/C++/AssemblyScript) and a Go-based `golang-filter`. It supports\nIngress/Gateway API and ships a rich plugin ecosystem (including AI gateway\nplugins).\n\n## Mandatory issue-spec gate for agent-assisted changes\n\nBefore substantive implementation, determine whether an AI or coding agent is\nmaterially participating under the\n[agent-assisted contribution policy](docs/developers/agent-assisted-contributions.md).\nFor every contribution to which that policy applies:\n\n- do not begin implementation until a Higress maintainer has approved both the\n  Proposal Issue and Design Issue; an issue-spec status or agent assertion is\n  not maintainer approval;\n- implement only through TASKs authorized by the approved Design and preserve\n  traceability to the applicable SPECs;\n- ensure the Design contains a concrete Verification Plan before verification\n  begins; and\n- create and complete the corresponding verification TASKs with exact commands,\n  results, evidence links, and hashes before claiming success or asking\n  maintainers to accept verification or review.\n\nDeclare agent participation in the PR template. The policy excludes human-only\nwork. Small documentation-only corrections limited to spelling, punctuation,\nwhitespace, or formatting (such as typo adjustments) may skip the issue-spec\nworkflow when they involve no substantive choice or behavioral effect.\nAgent-assisted bug fixes and material feature work must still follow this gate.\nAn authenticated `gh` user with canonical-repository `role_name` of `maintain`\nor `admin` may use the verified maintainer/administrator exception documented\nin the canonical policy. Before bypassing the gate, run the documented `gh`\nidentity and collaborator-permission checks, record the login, returned\n`role_name`, actual PR author, and rationale in the PR, and still disclose agent\nparticipation. The PR author must match the verified login and the PR must attest\nthat `GH_TOKEN` and `GITHUB_TOKEN` were unset for every verification command;\nany failed or mismatched check disqualifies the exception. Select the matching\nverified-exception status in the PR template. The accepting or merging maintainer\nmust independently validate current live evidence with token overrides unset.\nThis exception never waives bug-fix runtime verification.\n\nFor work subject to this gate, the maintainer-approved issue-spec Design Issue\nis the authoritative design carrier. Do not create or require a plugin-local\n`design/` document for the gate. An optional durable capability spec serves a\nseparate long-lived purpose and, only when maintainers request one, belongs at\n`issue-spec/specs/<plugin-qualified-capability>/spec.md`, using a unique\nlowercase, hyphen-separated capability slug that identifies the plugin. It\nmust not replace or duplicate the approved Design Issue. Higress leaves\n`durable_specs` unset; do not invent a path field or enable repository\nprojection without explicit maintainer direction.\n\n## Repository layout\n\nTop-level directories (all paths relative to repo root):\n\n- `cmd/higress/` — main entrypoint (`main.go`) for the Higress controller binary.\n- `pkg/` — core Go control-plane packages: `bootstrap/`, `cert/`, `cmd/`,\n  `common/`, `config/`, `ingress/` (Ingress/Gateway config translation),\n  `kube/`.\n- `api/` — protobuf/CRD API definitions; Higress CRDs live in\n  `api/extensions/v1alpha1` (e.g. the `WasmPlugin` type). Generated with\n  `make gen-api` / `make gen-client` (see `api/gen.sh`, `buf.*`).\n- `client/` — generated Go clientset for Higress CRDs.\n- `istio/` — git submodules of higress-group forks of Istio (`api`, `istio`,\n  `client-go`, `pkg`, `proxy`); see `.gitmodules`. Pulled via `make submodule`\n  (part of `prebuild`).\n- `envoy/` — Envoy + `go-control-plane` submodules (higress-group forks).\n- `external/` — vendored/external mirror dirs used during build (istio, envoy,\n  proxy, etc.).\n- `plugins/` — all data-plane plugins (see \"Plugins\" below).\n- `registry/` — service-discovery registry integrations (nacos, consul, eureka,\n  zookeeper, direct, mcp, ...).\n- `hgctl/` — the `hgctl` CLI (separate Go module) for managing Higress.\n- `helm/` — Helm charts: `helm/core` (the dev/install chart) and `helm/higress`.\n- `test/` — `test/e2e/` (conformance/e2e, see \"Build & test\") and\n  `test/gateway/`.\n- `tools/` — build/CI scripting: `tools/hack/` (build scripts), `tools/bin/`,\n  `tools/linter/`, `*.mk`.\n- `samples/` — example manifests (gateway-api, hello-world, wasmplugin, ...).\n- `docker/`, `docs/`, `release-notes/` — packaging, docs, and release notes.\n- `Makefile` — istio common-files wrapper (supports `BUILD_WITH_CONTAINER`);\n  real targets live in `Makefile.core.mk` (+ `Makefile.overrides.mk`).\n\n## Plugins\n\nAll plugins live under `plugins/`. See `plugins/README.md` for the contributor\noverview. Prebuilt plugin images are published to\n`higress-registry.cn-hangzhou.cr.aliyuncs.com/plugins`.\n\n### plugins/wasm-go/ (primary WASM plugin framework, Go)\n\n- `extensions/<name>/` — one directory per plugin (~59 plugins, many `ai-*`).\n  Each plugin is its own Go module: `main.go`, `go.mod`/`go.sum`, `VERSION`,\n  `README.md`(+`README_EN.md`), often `config/`, `util/`, `main_test.go`.\n  Optional `.buildrc` sets `EXTRA_TAGS`; optional `prepare.sh`/`prepare.sh`.\n  `plugin.wasm` is a build artifact and is **not** committed.\n- Shared SDK: plugins depend on external modules\n  `github.com/higress-group/wasm-go` and\n  `github.com/higress-group/proxy-wasm-go-sdk` (NOT an in-repo SDK dir).\n  In-repo, `plugins/wasm-go/pkg/mcp/` provides MCP helpers and\n  `plugins/wasm-go/mcp-servers/` holds MCP server plugins.\n- `examples/` — reference plugins, including the Go counterparts of C++\n  plugins. These are excluded from official plugin release discovery.\n- Build: `plugins/wasm-go/Makefile`. `PLUGIN_NAME=<name> make build` builds an\n  official plugin; add `PLUGIN_ROOT=examples` for a reference plugin. The wasm\n  file is written below the selected root, and the image is built via\n  `Dockerfile`/`DockerfileBuilder` (uses a `wasm-go-builder` image, Go 1.24,\n  TinyGo optional). `make build-push` pushes the image; `make local-build`\n  builds locally with `GOOS=wasip1 GOARCH=wasm go build -buildmode=c-shared`.\n- Conventions: `VERSION` is the image tag; the CI/e2e batch builder\n  (`tools/hack/build-wasm-plugins.sh`) only compiles a wasm-go plugin whose\n  `VERSION` ends in `-alpha` (see the section at the bottom of this file).\n\n### plugins/wasm-rust/ (Rust WASM plugins)\n\n- Workspace-style: root `Cargo.toml`/`Cargo.lock`, shared `src/`, the official\n  `extensions/ai-data-masking/` plugin, and reference implementations under\n  `example/`.\n- Build via `plugins/wasm-rust/Makefile` (`PLUGIN_NAME=<name> make build`, plus\n  `lint`/`test`); add `PLUGIN_ROOT=example` for a reference plugin. The batch\n  builder runs only official `extensions/` plugins when `PLUGIN_TYPE=RUST`.\n\n### plugins/wasm-cpp/ (C++ WASM plugins, Bazel)\n\n- Bazel project: `WORKSPACE`, `BUILD`, `bazel/`, `common/`, `scripts/`,\n  `extensions/<name>/` (e.g. `basic_auth`, `jwt_auth`, `key_rate_limit`,\n  `model_router`, ...). Build via `plugins/wasm-cpp/Makefile`\n  (`PLUGIN_NAME=<name> make build`), invoked with `PLUGIN_TYPE=CPP`.\n\n### plugins/wasm-assemblyscript/ (AssemblyScript WASM plugins)\n\n- Node/AssemblyScript project: `asconfig.json`, `package.json`, `assembly/`,\n  `extensions/`.\n\n### plugins/golang-filter/ (Envoy Go HTTP filter, NOT WASM)\n\n- A native Envoy Golang HTTP filter (`main.go`, `mcp-server/`, `mcp-session/`);\n  compiled as a shared object (`.so`) independent of Envoy — no Envoy rebuild\n  needed. Requires Higress >= 2.1.0. Plugins register in `main.go`'s `init()`\n  via `RegisterHttpFilterFactoryAndConfigParser`. See\n  `plugins/golang-filter/README.md`.\n- Build: `plugins/golang-filter/Makefile` (docker build, outputs\n  `golang-filter_<arch>.so`). Wired into the gateway image build via\n  `Makefile.core.mk` targets `build-golang-filter[-amd64|-arm64]`.\n\n### How plugins are loaded\n\n`WasmPlugin` CRDs (`extensions.higress.io/v1alpha1`) reference a plugin by\n`url:` — either `oci://.../plugins/<name>:<version>` (image) or\n`file:///opt/plugins/.../plugin.wasm` (local mount used in e2e). The dev install\n`make install-dev-wasmplugin` sets Helm `global.volumeWasmPlugins=true` to mount\nlocally built wasm files into the gateway.\n\n## Build & test\n\nRun targets from the repo root; `Makefile` delegates to `Makefile.core.mk`.\nCommon ones:\n\n- `make build` / `make build-linux` — build the Higress controller binary\n  (`prebuild` first fetches submodules).\n- `make build-hgctl` — build the `hgctl` CLI.\n- `make build-gateway` / `make build-istio` / `make build-envoy` — data-plane\n  and control-plane images (gateway pulls in the golang-filter).\n- `make build-wasmplugins` — runs `tools/hack/build-wasm-plugins.sh` to batch\n  build WASM plugins (respects `PLUGIN_TYPE` / `PLUGIN_NAME`; Go plugins require\n  a `-alpha` VERSION).\n- `make gen-api` / `make gen-client` — regenerate API/client code.\n\n### Conformance / e2e tests (`test/e2e/`)\n\n- Entrypoint `test/e2e/e2e_test.go`, run with build tag `conformance` and\n  `--test-area` / `--execute-tests` flags.\n- Cases live in `test/e2e/conformance/tests/` as **paired `<name>.go` +\n  `<name>.yaml`** files (~68 cases; WASM cases are prefixed by language, e.g.\n  `go-wasm-*`, `cpp-wasm-*`). Support code: `conformance/base/`,\n  `conformance/utils/`, `conformance/embed.go`.\n- Key Make targets (each spins up a kind cluster):\n  - `make higress-conformance-test` — Ingress/Gateway conformance.\n  - `make higress-wasmplugin-test` — WASM plugin e2e (uses\n    `install-dev-wasmplugin`, which builds plugins and mounts them).\n  - `*-prepare` / `*-skip-docker-build` / `*-clean` variants exist for\n    iterating; `run-higress-e2e-test[-wasmplugin]` runs `go test` against an\n    already-prepared cluster (filter with `TEST_SHORTNAME`).\n- For the specifics of authoring a wasm-go e2e test, see the section below.\n\n## Writing e2e conformance tests with wasm-go plugins\n\nWhen adding an e2e conformance test that ships its own wasm-go plugin under\n`plugins/wasm-go/extensions/<name>/`:\n\n- The plugin's `VERSION` file **must end in `-alpha`** (e.g. `1.0.0-alpha`).\n  CI's `tools/hack/build-wasm-plugins.sh` only compiles a wasm-go plugin when\n  its version ends in `-alpha`; otherwise it silently skips it.\n- `plugin.wasm` is a build artifact and is **not** committed. If the plugin\n  isn't built, the `file:///opt/plugins/.../plugin.wasm` URL in the test's\n  `WasmPlugin` manifest resolves to a missing file, envoy rejects the wasm\n  config and fails closed, and every request on that route returns HTTP 500.\n  Locally this can be masked because a previously built `plugin.wasm` still\n  exists on disk — so a test can pass locally yet 500 in CI.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# AGENTS.md\n\nGuidance for AI agents working in this repository.\n\nHigress is a cloud-native API gateway built on Istio and Envoy. The control\nplane extends Istio/pilot (Go); the data plane is Envoy extended with WASM\nplugins (Go/Rust/C++/AssemblyScript) and a Go-based `golang-filter`. It supports\nIngress/Gateway API and ships a rich plugin ecosystem (including AI gateway\nplugins).\n\n## Mandatory issue-spec gate for agent-assisted changes\n\nBefore substantive implementation, determine whether an AI or coding agent is\nmaterially participating under the\n[agent-assisted contribution policy](docs/developers/agent-assisted-contributions.md).\nFor every contribution to which that policy applies:\n\n- do not begin implementation until a Higress maintainer has approved both the\n  Proposal Issue and Design Issue; an issue-spec status or agent assertion is\n  not maintainer approval;\n- implement only through TASKs authorized by the approved Design and preserve\n  traceability to the applicable SPECs;\n- ensure the Design contains a concrete Verification Plan before verification\n  begins; and\n- create and complete the corresponding verification TASKs with exact commands,\n  results, evidence links, and hashes before claiming success or asking\n  maintainers to accept verification or review.\n\nDeclare agent participation in the PR template. The policy excludes human-only\nwork. Small documentation-only corrections limited to spelling, punctuation,\nwhitespace, or formatting (such as typo adjustments) may skip the issue-spec\nworkflow when they involve no substantive choice or behavioral effect.\nAgent-assisted bug fixes and material feature work must still follow this gate.\nAn authenticated `gh` user with canonical-repository `role_name` of `maintain`\nor `admin` may use the verified maintainer/administrator exception documented\nin the canonical policy. Before bypassing the gate, run the documented `gh`\nidentity and collaborator-permission checks, record the login, returned\n`role_name`, actual PR author, and rationale in the PR, and still disclose agent\nparticipation. The PR author must match the verified login and the PR must attest\nthat `GH_TOKEN` and `GITHUB_TOKEN` were unset for every verification command;\nany failed or mismatched check disqualifies the exception. Select the matching\nverified-exception status in the PR template. The accepting or merging maintainer\nmust independently validate current live evidence with token overrides unset.\nThis exception never waives bug-fix runtime verification.\n\nFor work subject to this gate, the maintainer-approved issue-spec Design Issue\nis the authoritative design carrier. Do not create or require a plugin-local\n`design/` document for the gate. An optional durable capability spec serves a\nseparate long-lived purpose and, only when maintainers request one, belongs at\n`issue-spec/specs/<plugin-qualified-capability>/spec.md`, using a unique\nlowercase, hyphen-separated capability slug that identifies the plugin. It\nmust not replace or duplicate the approved Design Issue. Higress leaves\n`durable_specs` unset; do not invent a path field or enable repository\nprojection without explicit maintainer direction.\n\n## Repository layout\n\nTop-level directories (all paths relative to repo root):\n\n- `cmd/higress/` — main entrypoint (`main.go`) for the Higress controller binary.\n- `pkg/` — core Go control-plane packages: `bootstrap/`, `cert/`, `cmd/`,\n  `common/`, `config/`, `ingress/` (Ingress/Gateway config translation),\n  `kube/`.\n- `api/` — protobuf/CRD API definitions; Higress CRDs live in\n  `api/extensions/v1alpha1` (e.g. the `WasmPlugin` type). Generated with\n  `make gen-api` / `make gen-client` (see `api/gen.sh`, `buf.*`).\n- `client/` — generated Go clientset for Higress CRDs.\n- `istio/` — git submodules of higress-group forks of Istio (`api`, `istio`,\n  `client-go`, `pkg`, `proxy`); see `.gitmodules`. Pulled via `make submodule`\n  (part of `prebuild`).\n- `envoy/` — Envoy + `go-control-plane` submodules (higress-group forks).\n- `external/` — vendored/external mirror dirs used during build (istio, envoy,\n  proxy, etc.).\n- `plugins/` — all data-plane plugins (see \"Plugins\" below).\n- `registry/` — service-discovery registry integrations (nacos, consul, eureka,\n  zookeeper, direct, mcp, ...).\n- `hgctl/` — the `hgctl` CLI (separate Go module) for managing Higress.\n- `helm/` — Helm charts: `helm/core` (the dev/install chart) and `helm/higress`.\n- `test/` — `test/e2e/` (conformance/e2e, see \"Build & test\") and\n  `test/gateway/`.\n- `tools/` — build/CI scripting: `tools/hack/` (build scripts), `tools/bin/`,\n  `tools/linter/`, `*.mk`.\n- `samples/` — example manifests (gateway-api, hello-world, wasmplugin, ...).\n- `docker/`, `docs/`, `release-notes/` — packaging, docs, and release notes.\n- `Makefile` — istio common-files wrapper (supports `BUILD_WITH_CONTAINER`);\n  real targets live in `Makefile.core.mk` (+ `Makefile.overrides.mk`).\n\n## Plugins\n\nAll plugins live under `plugins/`. See `plugins/README.md` for the contributor\noverview. Prebuilt plugin images are published to\n`higress-registry.cn-hangzhou.cr.aliyuncs.com/plugins`.\n\n### plugins/wasm-go/ (primary WASM plugin framework, Go)\n\n- `extensions/<name>/` — one directory per plugin (~59 plugins, many `ai-*`).\n  Each plugin is its own Go module: `main.go`, `go.mod`/`go.sum`, `VERSION`,\n  `README.md`(+`README_EN.md`), often `config/`, `util/`, `main_test.go`.\n  Optional `.buildrc` sets `EXTRA_TAGS`; optional `prepare.sh`/`prepare.sh`.\n  `plugin.wasm` is a build artifact and is **not** committed.\n- Shared SDK: plugins depend on external modules\n  `github.com/higress-group/wasm-go` and\n  `github.com/higress-group/proxy-wasm-go-sdk` (NOT an in-repo SDK dir).\n  In-repo, `plugins/wasm-go/pkg/mcp/` provides MCP helpers and\n  `plugins/wasm-go/mcp-servers/` holds MCP server plugins.\n- `examples/` — reference plugins, including the Go counterparts of C++\n  plugins. These are excluded from official plugin release discovery.\n- Build: `plugins/wasm-go/Makefile`. `PLUGIN_NAME=<name> make build` builds an\n  official plugin; add `PLUGIN_ROOT=examples` for a reference plugin. The wasm\n  file is written below the selected root, and the image is built via\n  `Dockerfile`/`DockerfileBuilder` (uses a `wasm-go-builder` image, Go 1.24,\n  TinyGo optional). `make build-push` pushes the image; `make local-build`\n  builds locally with `GOOS=wasip1 GOARCH=wasm go build -buildmode=c-shared`.\n- Conventions: `VERSION` is the image tag; the CI/e2e batch builder\n  (`tools/hack/build-wasm-plugins.sh`) only compiles a wasm-go plugin whose\n  `VERSION` ends in `-alpha` (see the section at the bottom of this file).\n\n### plugins/wasm-rust/ (Rust WASM plugins)\n\n- Workspace-style: root `Cargo.toml`/`Cargo.lock`, shared `src/`, the official\n  `extensions/ai-data-masking/` plugin, and reference implementations under\n  `example/`.\n- Build via `plugins/wasm-rust/Makefile` (`PLUGIN_NAME=<name> make build`, plus\n  `lint`/`test`); add `PLUGIN_ROOT=example` for a reference plugin. The batch\n  builder runs only official `extensions/` plugins when `PLUGIN_TYPE=RUST`.\n\n### plugins/wasm-cpp/ (C++ WASM plugins, Bazel)\n\n- Bazel project: `WORKSPACE`, `BUILD`, `bazel/`, `common/`, `scripts/`,\n  `extensions/<name>/` (e.g. `basic_auth`, `jwt_auth`, `key_rate_limit`,\n  `model_router`, ...). Build via `plugins/wasm-cpp/Makefile`\n  (`PLUGIN_NAME=<name> make build`), invoked with `PLUGIN_TYPE=CPP`.\n\n### plugins/wasm-assemblyscript/ (AssemblyScript WASM plugins)\n\n- Node/AssemblyScript project: `asconfig.json`, `package.json`, `assembly/`,\n  `extensions/`.\n\n### plugins/golang-filter/ (Envoy Go HTTP filter, NOT WASM)\n\n- A native Envoy Golang HTTP filter (`main.go`, `mcp-server/`, `mcp-session/`);\n  compiled as a shared object (`.so`) independent of Envoy — no Envoy rebuild\n  needed. Requires Higress >= 2.1.0. Plugins register in `main.go`'s `init()`\n  via `RegisterHttpFilterFactoryAndConfigParser`. See\n  `plugins/golang-filter/README.md`.\n- Build: `plugins/golang-filter/Makefile` (docker build, outputs\n  `golang-filter_<arch>.so`). Wired into the gateway image build via\n  `Makefile.core.mk` targets `build-golang-filter[-amd64|-arm64]`.\n\n### How plugins are loaded\n\n`WasmPlugin` CRDs (`extensions.higress.io/v1alpha1`) reference a plugin by\n`url:` — either `oci://.../plugins/<name>:<version>` (image) or\n`file:///opt/plugins/.../plugin.wasm` (local mount used in e2e). The dev install\n`make install-dev-wasmplugin` sets Helm `global.volumeWasmPlugins=true` to mount\nlocally built wasm files into the gateway.\n\n## Build & test\n\nRun targets from the repo root; `Makefile` delegates to `Makefile.core.mk`.\nCommon ones:\n\n- `make build` / `make build-linux` — build the Higress controller binary\n  (`prebuild` first fetches submodules).\n- `make build-hgctl` — build the `hgctl` CLI.\n- `make build-gateway` / `make build-istio` / `make build-envoy` — data-plane\n  and control-plane images (gateway pulls in the golang-filter).\n- `make build-wasmplugins` — runs `tools/hack/build-wasm-plugins.sh` to batch\n  build WASM plugins (respects `PLUGIN_TYPE` / `PLUGIN_NAME`; Go plugins require\n  a `-alpha` VERSION).\n- `make gen-api` / `make gen-client` — regenerate API/client code.\n\n### Conformance / e2e tests (`test/e2e/`)\n\n- Entrypoint `test/e2e/e2e_test.go`, run with build tag `conformance` and\n  `--test-area` / `--execute-tests` flags.\n- Cases live in `test/e2e/conformance/tests/` as **paired `<name>.go` +\n  `<name>.yaml`** files (~68 cases; WASM cases are prefixed by language, e.g.\n  `go-wasm-*`, `cpp-wasm-*`). Support code: `conformance/base/`,\n  `conformance/utils/`, `conformance/embed.go`.\n- Key Make targets (each spins up a kind cluster):\n  - `make higress-conformance-test` — Ingress/Gateway conformance.\n  - `make higress-wasmplugin-test` — WASM plugin e2e (uses\n    `install-dev-wasmplugin`, which builds plugins and mounts them).\n  - `*-prepare` / `*-skip-docker-build` / `*-clean` variants exist for\n    iterating; `run-higress-e2e-test[-wasmplugin]` runs `go test` against an\n    already-prepared cluster (filter with `TEST_SHORTNAME`).\n- For the specifics of authoring a wasm-go e2e test, see the section below.\n\n## Writing e2e conformance tests with wasm-go plugins\n\nWhen adding an e2e conformance test that ships its own wasm-go plugin under\n`plugins/wasm-go/extensions/<name>/`:\n\n- The plugin's `VERSION` file **must end in `-alpha`** (e.g. `1.0.0-alpha`).\n  CI's `tools/hack/build-wasm-plugins.sh` only compiles a wasm-go plugin when\n  its version ends in `-alpha`; otherwise it silently skips it.\n- `plugin.wasm` is a build artifact and is **not** committed. If the plugin\n  isn't built, the `file:///opt/plugins/.../plugin.wasm` URL in the test's\n  `WasmPlugin` manifest resolves to a missing file, envoy rejects the wasm\n  config and fails closed, and every request on that route returns HTTP 500.\n  Locally this can be masked because a previously built `plugin.wasm` still\n  exists on disk — so a test can pass locally yet 500 in CI.\n","category":"root","tokens":2747}]}