[ISSUE #7563] Document wasm host abi and test a gateway reference plugin. - #7567

Review: document wasm host ABI and test a gateway reference plugin

This is primarily documentation + test-infrastructure, with one small and safe production change. Well done.

Production change (the only non-test code)

• WasmLoader.java: the _initialize call previously wrapped instance.export("_initialize") in a try/catch for Chicory's InvalidException. It now uses the shared findWasmExtern("_initialize").ifPresent(...), and getWasmExtern delegates to the same private helper. The helper checks export names first, so an absent optional hook stays optional while a present-but-invalid export type still surfaces as an error — exactly the documented policy in ABI-v1.md ("An export with a matching name but the wrong kind ... is invalid, not an absent optional hook"). Removed the now-unused ExportSection import. Correct and more robust.

Test infrastructure

• ReferenceWasmPlugin / ReferenceWasmPluginDataHandler: coherent concrete adapters extending the existing AbstractShenyuWasmPlugin / AbstractWasmPluginDataHandler base classes, implementing the binary request profile documented in ABI-v1.md (10-field frame, version 1, decision 0/1, -1/-2 codes, ≤32 KiB body via DataBufferUtils.join(..., 32768)). synchronized guards the shared loader instance as the doc mandates.
• WasmGatewayTest: a real Spring Boot WebFlux gateway bootstrap on a random port that sends actual HTTP requests. It covers the happy allow/deny path, config update/delete (plugin/selector/rule subscribe & unsubscribe), unmatched-request bypass, 60 concurrent requests with argument isolation, missing-execute-export 5xx, optional missing hooks, guest trap / invalid memory / incompatible-result failure + recovery, and asserts pendingArguments() == 0 after every test (no leaked Java arguments). High-quality integration coverage.
• WasmLifecycleContractTest: lifecycle contract fixtures for the data handler variants.
• .wasm binaries are checked in (rebuilt from .wat via the Makefile using WABT 1.0.42) so Java builds need no Wasm compiler; the pom.xml rat exclude for *.wasm is correct (binaries can't carry license headers; their .wat sources do).

CI

• .github/workflows/wasm-fixtures.yml: least-privilege permissions: contents: read, concurrency with cancel-in-progress, pins WABT 1.0.42 with a sha256 checksum verification, and installs Rust 1.90.0. Triggers only on the relevant wasm paths (plus pom.xml).
• .github/scripts/verify-wasm-fixtures.py: verify_wat rebuilds WAT fixtures into a temp dir and byte-compares against the committed binaries (never modifies them); verify_rust rebuilds the five Rust guests, runs the WASM Java suites, and restores the original committed bytes in a finally block even on failure. Idempotent and safe. Supports --wat-only/--rust-only.
• Full module CI green, including rebuild-and-test, Analyze (java), check-license-header, and rat_check.

Non-blocking note

• verify_wat globs wasm-bridge and wasm-gateway families; only wasm-gateway exists in this PR, and the code handles a missing directory gracefully. Fine as-is.

Approving. This meaningfully improves the WASM subsystem's testability and documents a previously-undocumented contract.

Reviewed 60c7d618b.

Verification (JDK 21):

• shenyu-plugin-wasm-base suite 43/43 green, including the new WasmGatewayTest (9 tests: boots the gateway starter on a random port with a registered WASM plugin and drives real HTTP requests) and WasmLifecycleContractTest (4); shenyu-plugin-wasm-api builds in the same reactor; checkstyle 0 violations and apache-rat:check 0 unapproved on both modules.
• Not reproduced on my side: the WAT byte-identity check and the rebuilt Rust guest runs. This machine has no wat2wasm / WABT 1.0.42 and no Rust 1.90.0 toolchain, so everything the new workflow adds there is reviewed by reading only.
• The WasmLoader change is behaviour-preserving for the found case and tidier for the absent one: _initialize now goes through the same findWasmExtern used by getWasmExtern, so an absent export returns Optional.empty() instead of relying on a caught InvalidException.
• The module is already registered in shenyu-plugin/pom.xml; the RAT exclusion is scoped to this module and the .wat sources carry license headers, so RAT stays clean.

Findings:

• Coordination with #7569 (still open, same author): the earlier review asked for a single lookup policy, landed here as a shared helper. This helper matches on export name and then calls instance.export(name), so a non-function export still throws InvalidException, while #7569 returns Optional.empty() for that case. Only one of the two can be the contract - please state which, and rebase the other. Concrete edge this creates today: a guest exporting a global or memory named _initialize used to be caught and ignored (debug log) and would now propagate out of the loader constructor.
• The new CI job rebuilds WAT fixtures and Rust guests for any PR touching pom.xml, shenyu-plugin-wasm-api/** or shenyu-plugin-wasm-base/**, with a 30 minute timeout and no cargo / WABT caching. cargo build --offline works only because all five rust-* fixtures have zero [dependencies]; the first future dependency turns that step red on a fresh runner. Either drop --offline or cache .cargo/registry.
• verify-wasm-fixtures.py walks the families ["wasm-bridge", "wasm-gateway"] under shenyu-plugin-wasm-base/src/test, but only wasm-gateway exists - wasm-bridge is skipped silently by if not directory.exists(): continue. Either drop the name or assert that an expected family was found.
• verify_rust() rewrites tracked fixtures in the working tree and restores them in finally, which is fine for CI but leaves src/test/resources/*.wasm modified if a local run is aborted. A line in the README saying to run it from a clean checkout would cover that.
• Pinning WABT 1.0.42 by sha256 and Rust 1.90.0 is good practice; actions/checkout@v3 matches most workflows in this repo.

Nit: findWasmExtern has no javadoc while getWasmExtern does, and the name-first-then-export ordering is the entire point of the helper - one line of javadoc would keep the next reader from simplifying it back to a bare instance.export(name).