[go-fan] Go Module Review: tetratelabs/wazero

[github-actions]

🐹 Go Fan Report: tetratelabs/wazero

Module Overview

wazero is a zero-dependency, pure-Go WebAssembly runtime — no CGo, no external C libraries. It supports the WebAssembly Core Specification plus WASI Preview 1, with both JIT (compiler) and interpreter backends. This makes it uniquely suited for embedding WASM execution in Go services like this gateway.

Version in use: v1.11.0

Current Usage in gh-aw-mcpg

The project uses wazero to run WASM-based DIFC security guards in-process. Guards are sandboxed WASM binaries that label MCP resources and responses to enforce information-flow control policies.

• Files: 3 files (internal/guard/wasm.go, wasm_parse.go, wasm_test.go)
• Import Packages: wazero, wazero/api, wazero/imports/wasi_snapshot_preview1, wazero/sys
• Key APIs Used:
  • NewRuntimeConfigCompiler() + WithCloseOnContextDone(true) + WithCompilationCache()
  • NewRuntimeWithConfig() — one runtime per guard instance
  • wasi_snapshot_preview1.Instantiate() — WASI host support
  • NewHostModuleBuilder("env") — custom call_backend and host_log host functions
  • NewModuleConfig() with stdin isolation
  • api.Module.ExportedFunction(), api.Function.Call() — function dispatch
  • api.Memory.Read/Write/Grow/ReadUint32Le — linear memory access
  • sys.ExitError — trap/exit discrimination
  • NewCompilationCache() — shared in-memory JIT cache

Research Findings

Architecture Quality

The implementation is well-structured:

• ✅ Uses compiler (JIT) backend explicitly — good performance
• ✅ Shared CompilationCache across all guard instances — avoids redundant JIT compilation
• ✅ WithCloseOnContextDone(true) — proper context-aware cancellation
• ✅ sys.ExitError used for type-safe WASI exit discrimination
• ✅ Guard-allocator preferred path (alloc/dealloc exports) for safe memory management
• ✅ Trap poisoning — permanently marks failed guards to prevent use of corrupted state
• ✅ context.WithoutCancel for cleanup to avoid dealloc skips on context cancellation

Recent Updates (wazero v1.11)

The current version v1.11.0 is the latest stable. wazero has an active release cadence with improvements in memory management, WASI compatibility, and compilation speed. Disk-based compilation cache has been available since early versions.

Best Practices from Maintainers

• Prefer CompiledModule + multiple instantiations over recreating the runtime for the same binary
• Use wazero.NewCompilationCacheWithDir() for disk persistence across restarts
• Memory limits should be encoded in the WASM binary itself (max pages in the memory section)

Improvement Opportunities

🏃 Quick Wins

1. Disk-based compilation cache — Replace wazero.NewCompilationCache() with wazero.NewCompilationCacheWithDir(cacheDir) to persist JIT artifacts across gateway restarts. This eliminates cold-start compilation latency (can be significant for complex WASM guard binaries). A subdirectory of the existing --log-dir or a dedicated cache path (e.g., MCP_GATEWAY_WASM_CACHE_DIR) would work well.

2. Warn on non-allocator path — tryCallWasmFunction has a fallback that manually places I/O buffers at the end of WASM linear memory. This is fragile: if the guard's heap grows into that region, behavior is undefined. The fallback should emit a logger.LogWarn when used, encouraging guard authors to export alloc/dealloc.

✨ Feature Opportunities

3. Instance pooling for concurrency — Currently each WasmGuard serializes all calls through a mutex because WASM modules are single-threaded. wazero supports instantiating the same CompiledModule multiple times independently. A pool of N instances per guard would allow N concurrent calls without blocking, improving throughput under load. This would require a sync.Pool or a channel-based pool of module instances.

4. Pre-compile to CompiledModule — Split guard creation into two phases: runtime.CompileModule(ctx, wasmBytes) → CompiledModule, then runtime.InstantiateModule(ctx, compiled, config). This separates compilation (done once) from instantiation (done per pool slot), and is also more idiomatic for the pooling opportunity above.

📐 Best Practice Alignment

5. Trap string matching fragility — isWasmTrap() uses strings.Contains(err.Error(), "wasm error:") as a fallback for non-WASI execution faults (e.g., Rust panic → unreachable). This relies on wazero's internal error message format which is not part of the public API and could change across versions. It would be worth opening a discussion with the wazero maintainers about a typed error for execution traps, or adding a version comment to flag this as a known coupling.

6. Module name collision — WithName("guard") is hard-coded for all guard instances. Currently each guard gets its own runtime, so there's no collision. But if the architecture ever changes to share runtimes, this would fail silently. A name derived from the guard's name field (e.g., WithName(name)) would be safer and more debuggable in wazero traces.

🔧 General Improvements

7. Document memory limit responsibility — There is no per-module memory cap enforced from the host. If a guard WASM binary omits a (memory N M) max bound, it could consume unbounded memory. A code comment or guard authorship guide should document that max memory pages must be set in the WASM binary itself, and that the gateway does not enforce an independent cap.

Recommendations (Prioritized)

Priority	Item	Impact	Effort
High	Disk-based compilation cache	Eliminates cold-start penalty	Low
High	Warn on non-allocator fallback path	Prevents subtle memory corruption	Low
Medium	Pre-compile to CompiledModule	Cleaner architecture, enables pooling	Medium
Medium	Instance pooling	Better concurrency under load	High
Low	Trap string matching — document or fix	API stability	Low
Low	Module name from guard name	Defensive future-proofing	Very Low

Next Steps

• Explore wazero.NewCompilationCacheWithDir() — add a MCP_GATEWAY_WASM_CACHE_DIR env var and --wasm-cache-dir flag, defaulting to a subdirectory of --log-dir
• Add a logger.LogWarn in the non-allocator fallback path in tryCallWasmFunction
• Consider refactoring to CompiledModule as groundwork for future instance pooling
• Add a note to guard authorship documentation about WASM memory limits

---

Generated by Go Fan 🐹
Module summary saved to: /tmp/gh-aw/agent/wazero.md (specs/mods/ not writable in CI)
Run: §25364088625

Note

🔒 Integrity filter blocked 12 items

The following items were blocked because they don't meet the GitHub integrity level.

• search_repositories search_repositories: has lower integrity than agent requires. The agent cannot read data with integrity below "unapproved".
• https://github.com/santhosh-tekuri/jsonschema search_repositories: has lower integrity than agent requires. The agent cannot read data with integrity below "unapproved".
• https://github.com/spf13/cobra search_repositories: has lower integrity than agent requires. The agent cannot read data with integrity below "unapproved".
• https://github.com/spf13/cobra/releases/tag/v1.10.2 get_latest_release: has lower integrity than agent requires. The agent cannot read data with integrity below "unapproved".
• https://github.com/santhosh-tekuri/jsonschema/releases/tag/v6.0.2 get_latest_release: has lower integrity than agent requires. The agent cannot read data with integrity below "unapproved".
• https://github.com/wazero/wazero/releases/tag/v1.11.0 get_latest_release: has lower integrity than agent requires. The agent cannot read data with integrity below "unapproved".
• get_file_contents get_file_contents: has lower integrity than agent requires. The agent cannot read data with integrity below "unapproved".
• https://github.com/wazero/wazero/releases/tag/v1.11.0 list_releases: has lower integrity than agent requires. The agent cannot read data with integrity below "unapproved".
• https://github.com/wazero/wazero/releases/tag/v1.10.1 list_releases: has lower integrity than agent requires. The agent cannot read data with integrity below "unapproved".
• https://github.com/wazero/wazero/releases/tag/v1.9.0 list_releases: has lower integrity than agent requires. The agent cannot read data with integrity below "unapproved".
• https://github.com/wazero/wazero/releases/tag/v1.8.2 list_releases: has lower integrity than agent requires. The agent cannot read data with integrity below "unapproved".
• https://github.com/wazero/wazero/releases/tag/v1.8.1 list_releases: has lower integrity than agent requires. The agent cannot read data with integrity below "unapproved".

To allow these resources, lower min-integrity in your GitHub frontmatter:

tools:
  github:
    min-integrity: approved  # merged | approved | unapproved | none

Generated by Go Fan · ● 1.3M · ◷

• expires on May 12, 2026, 7:49 AM UTC