This directory contains the operator, developer, and design documentation for vmod-wasm. The project targets Varnish 9.x with Wasmtime 44.0.0, so the docs assume that release contract unless a section says otherwise.
- Read Production Deployment when deciding how to install, constrain, monitor, reload, and roll back vmod-wasm in front of real traffic.
- Read Development Guide when writing or adapting a Proxy-Wasm module for Varnish.
- Read Proxy-Wasm Compatibility before porting an existing filter from another Proxy-Wasm host.
- Read Configuration Reference when you need exact VCL function names, return values, defaults, and valid scopes.
| Document | Use it for |
|---|---|
| Production Deployment | Release bundles, runtime limits, monitoring, VCL reloads, canaries, rollback, capacity planning |
| Development Guide | Building Rust/Wasm modules, SDK callback shape, HTTP callouts, tests, debugging |
| Configuration Reference | Complete wasm.* VCL API reference with parameters, return values, and examples |
| Proxy-Wasm Compatibility | ABI support matrix, properties, pseudo-headers, limitations |
| Architecture | Engine lifetime, store pooling, HTTP callout flow, VDP response-body integration, file map |
| Security Model | Sandbox boundaries, SSRF controls, module supply-chain guidance, incident response |
The examples/ workspace contains small, focused modules that
exercise the VMOD from VTC tests:
proxy-wasm-filteris the best starting point for a normal Rustproxy-wasmSDK module.passthroughis a no-op lifecycle baseline.transformshows a minimal response-header mutation.rustdemonstrates raw vmod-wasm host functions.edge-security-filteris a realistic reference fixture covering config, metrics, shared data, callouts, body callbacks, and local responses.
For production edge-security deployments, use the standalone vmod-wasm Edge Security Filter repository. The in-tree filter remains a fixture so vmod-wasm can test a realistic workload without depending on another repository during CI.
Before promoting a release, the documentation and source distribution should survive the same checks as the code:
docker build -t vmod-wasm-ci .
docker run --rm vmod-wasm-ci make check
docker run --rm vmod-wasm-ci make distcheck DISTCHECK_CONFIGURE_FLAGS="--with-wasmtime=/opt/wasmtime"Use make perf-test for a short local throughput comparison and
make soak-test for longer VCL reload, pooling, and sustained-traffic checks.