Polish vmod-wasm documentation

Author: RamazanKara

CODE_OF_CONDUCT.md

@@ -1,4 +1,4 @@
-# Code Of Conduct
+# Code of Conduct
 
 ## Our Pledge
 

CONTRIBUTING.md

@@ -122,12 +122,12 @@ test: add VTC for bot detection edge case
 Stable release tags include the supported Varnish ABI line:
 
 ```shell
-git tag varnish9-v4.3.3
-git push origin varnish9-v4.3.3
+git tag varnish9-vX.Y.Z
+git push origin varnish9-vX.Y.Z
 ```
 
-The package version remains semantic (`4.3.3`); the tag prefix makes the Varnish
-support line explicit for release assets.
+The package version remains semantic (`X.Y.Z`); the tag prefix makes the
+Varnish support line explicit for release assets.
 
 ## Reporting Issues
 

docs/ARCHITECTURE.md

@@ -2,7 +2,8 @@
 
 ## Overview
 
-vmod-wasm embeds the [Wasmtime](https://wasmtime.dev/) WebAssembly runtime into Varnish Cache as a VMOD (Varnish Module). It supports two execution models:
+vmod-wasm embeds the [Wasmtime](https://wasmtime.dev/) WebAssembly runtime into
+Varnish Cache as a VMOD (Varnish Module). It supports two execution models:
 
 1. **Raw host-function modules** — Wasm modules that import/export C-ABI functions directly
 2. **Proxy-Wasm ABI modules** — Standard filters using the [Proxy-Wasm ABI v0.2.1](https://github.com/proxy-wasm/spec)
@@ -127,7 +128,9 @@ mutating the module set used by older traffic.
 
 ### Store Pooling
 
-Instead of creating a new Wasmtime instance per request, vmod-wasm pre-creates a pool of instances at VCL init time. This eliminates compilation latency from the request path.
+Instead of creating a new Wasmtime instance per request, vmod-wasm pre-creates
+a pool of instances at VCL init time. This eliminates compilation latency from
+the request path.
 
 - Default pool size: 8 stores per module
 - Configurable with `wasm.set_store_pool_size(module, size)` after `wasm.load()`
@@ -142,7 +145,10 @@ and instance. The pool is an optimization, not a correctness dependency.
 
 ### Epoch-Based Time Limits
 
-Unlike fuel-based metering (which adds per-instruction overhead), epoch interruption uses a background thread that increments a global epoch counter. When a Wasm execution exceeds its deadline, the next epoch check traps the execution.
+Unlike fuel-based metering, which adds per-instruction overhead, epoch
+interruption uses a background thread that increments a global epoch counter.
+When a Wasm execution exceeds its deadline, the next epoch check traps the
+execution.
 
 - Zero overhead during normal execution
 - Background ticker thread (1ms resolution)

docs/COMPATIBILITY.md

@@ -4,6 +4,9 @@
 
 This document tracks the implementation status of the
 [Proxy-Wasm ABI v0.2.1](https://github.com/proxy-wasm/spec) specification.
+Use it to check whether an existing HTTP Proxy-Wasm filter can run on Varnish
+without redesign. Unsupported gRPC, L4, and foreign-function surfaces are
+registered for SDK link compatibility only.
 
 ## Runtime Support
 

docs/CONFIGURATION.md

@@ -2,6 +2,16 @@
 
 Complete reference for all vmod-wasm VCL functions and their parameters.
 
+Most production VCL only needs four groups:
+
+- load modules with `wasm.load()`
+- set resource limits with `wasm.set_epoch_deadline()` and
+  `wasm.set_memory_limit()`
+- restrict HTTP callouts with `wasm.set_allowed_upstreams()` and
+  `wasm.set_http_call_limit()`
+- expose observability with `wasm.get_metrics_json()` and
+  `wasm.get_stats_json()`
+
 ## Support And Scope
 
 The stable release line targets Varnish 9.x with Wasmtime C API 44.0.0.
@@ -255,14 +265,15 @@ Behavior when Wasm execution encounters an error.
 
 Return all Proxy-Wasm metrics as a JSON string.
 
-**Returns**: STRING (JSON object with metric names as keys and values as numbers)
+**Returns**: STRING (JSON object with metric names as keys and metric records
+as values)
 
 **Example output**:
 ```json
 {
-  "edge_requests_total": 15234,
-  "edge_blocked_total": 42,
-  "edge_rate_limited_total": 7
+  "edge_requests_total": {"type": "counter", "value": 15234},
+  "edge_blocked_total": {"type": "counter", "value": 42},
+  "edge_rate_limited_total": {"type": "counter", "value": 7}
 }
 ```
 

docs/PRODUCTION.md

@@ -3,8 +3,9 @@
 ## Overview
 
 vmod-wasm embeds a WebAssembly runtime (Wasmtime) into Varnish Cache,
-enabling request/response processing via compiled Wasm modules. This
-document covers production deployment considerations.
+enabling request/response processing via compiled Wasm modules. This guide is
+for operators deciding how to install, constrain, monitor, reload, and roll back
+Wasm filters in production.
 
 The stable release support target is Varnish 9.x on Linux `amd64` and `arm64`.
 GitHub binary bundles include the Wasmtime 44.0.0 runtime library used at build
@@ -35,6 +36,36 @@ Then verify linkage before traffic:
 ldd /usr/lib/varnish/vmods/libvmod_wasm.so | grep libwasmtime
 ```
 
+## Minimal Production Shape
+
+A production VCL should load modules only in `vcl_init`, set explicit runtime
+limits, fail closed for security decisions, and expose metrics on an internal
+path:
+
+```vcl
+import wasm;
+
+sub vcl_init {
+    wasm.load("edge", "/etc/varnish/wasm/edge_security_filter.wasm");
+    wasm.set_epoch_deadline(100);
+    wasm.set_memory_limit(8388608);
+    wasm.set_allowed_upstreams("auth.internal:8080");
+    wasm.set_http_call_limit(3);
+    wasm.set_fail_mode("closed");
+}
+
+sub vcl_recv {
+    if (req.url == "/__wasm_metrics" && req.http.X-Internal == "true") {
+        return (synth(200, "Metrics"));
+    }
+
+    set req.http.X-Wasm-Action = wasm.proxy_wasm_on_request("edge");
+    if (req.http.X-Wasm-Action != "0") {
+        return (synth(403, "Blocked"));
+    }
+}
+```
+
 ## Resource Limits
 
 ### Epoch Deadline (Execution Time Limit)
@@ -194,6 +225,7 @@ sub vcl_deliver {
   `proxy_on_response_body` as they arrive — no buffering
 - Each chunk is forwarded to the client immediately after inspection
 - `end_of_stream=1` is set on the final chunk
+- Memory usage is O(chunk_size), not O(body_size)
 
 ## Module Lifecycle Management
 
@@ -351,7 +383,6 @@ so budget for at least two loaded VCL generations during deployment.
 | Security filter (bot + rate limit) | 100ms | 8 MiB | 0 |
 | Auth validation (with callout) | 200ms | 8 MiB | 3 |
 | Complex transform (body inspection) | 500ms | 16 MiB | 5 |
-- Memory usage is O(chunk_size), not O(body_size)
 
 ## Upgrading Modules
 

docs/SECURITY.md

@@ -2,8 +2,9 @@
 
 ## Overview
 
-vmod-wasm isolates untrusted Wasm code within a sandboxed runtime.
-This document describes the security boundaries and controls.
+vmod-wasm isolates untrusted Wasm code within a sandboxed runtime. This
+document describes the security boundaries, defaults, and production controls
+that matter before you allow modules to process real traffic.
 
 ## Isolation Guarantees
 
@@ -15,7 +16,8 @@ This document describes the security boundaries and controls.
 ### Execution Isolation
 - Epoch-based time limits prevent infinite loops and CPU exhaustion
 - Each request gets a fresh instance — no state leakage between requests
-- Wasm modules cannot access the filesystem, network, or system calls
+- Wasm modules cannot directly access the filesystem, network, or host system
+  calls
 - All host interaction goes through explicitly defined host functions
 
 ### Network Isolation