WASM Custom Rules

WASM Custom Body Matchers

MockServer supports WebAssembly (WASM) modules as custom body matchers. This lets you write complex matching logic in any language that compiles to WASM (Rust, C, Go, AssemblyScript, etc.) and upload the compiled module to MockServer at runtime.

The WASM module runs inside a pure-Java interpreter (chicory, on its stable 1.x release line), so no native libraries or JNI are required. The module is sandboxed and cannot access the host filesystem, network, or JVM.

Enabling WASM support

WASM body matching is disabled by default. Enable it with:

# environment variable
MOCKSERVER_WASM_ENABLED=true

# Java system property
-Dmockserver.wasmEnabled=true

# configuration property file
mockserver.wasmEnabled=true

Writing a WASM matcher module

Your WASM module must export a function called match with the following signature:

Full runnable examples: the WASM custom-rule examples in the repository implement the same body matcher in both Rust and Go — including a prebuilt .wasm, the MockServer WASM ABI contract, and build instructions.

;; WAT (WebAssembly Text Format)
(module
  (memory (export "memory") 1)
  (func $match (export "match") (param $ptr i32) (param $len i32) (result i32)
    ;; Read $len bytes from linear memory starting at $ptr
    ;; Return 1 for match, 0 for no match
    i32.const 1  ;; always matches (example)
  )
)

Before calling match, MockServer writes the HTTP request body (UTF-8 encoded) into the module's linear memory at offset 0. The $ptr parameter is 0 and $len is the byte length of the body.

Rust example

#[no_mangle]
#[export_name = "match"]
pub extern "C" fn match_fn(ptr: *const u8, len: usize) -> i32 {
    let body = unsafe { std::slice::from_raw_parts(ptr, len) };
    let body_str = std::str::from_utf8(body).unwrap_or("");
    if body_str.contains("expected_value") { 1 } else { 0 }
}

Note: When compiling Rust to WASM, export the function as match (you may need #[export_name = "match"] since match is a Rust keyword).

Matching on method, path and headers (richer ABI)

The body-only match export above sees only the request body. If you also need the request method, path or headers, export a function called match_request instead. MockServer prefers match_request when present and falls back to match otherwise, so existing body-only modules keep working unchanged.

Instead of just the body, MockServer writes a UTF-8 JSON envelope into linear memory at offset 0 and calls match_request(0, len):

{
  "method": "POST",
  "path": "/orders",
  "headers": { "X-Tenant": ["acme"], "Accept": ["application/json"] },
  "body": "..."
}

Each header name maps to an array of values (so multi-valued headers are preserved); body is the request body, or null when absent.

Authoring SDK

To save you hand-parsing that envelope, the repository ships a tiny, dependency-free Rust authoring crate mockserver-wasm-sdk with typed accessors (req.method(), req.path(), req.header("X-Tenant"), req.body()) and an export_match_request! macro that wires up the ABI:

#![no_std]
use mockserver_wasm_sdk::{export_match_request, Request};

fn rule(req: &Request) -> bool {
    req.method() == "POST"
        && req.path() == "/orders"
        && req.header("X-Tenant") == Some("acme")
}

export_match_request!(rule);

See the SDK crate and a sample module (method + path + header) in the repository, including a prebuilt .wasm.

Uploading a WASM module

Upload a compiled WASM module using the REST API:

# Upload a WASM module named "myMatcher"
curl -X PUT "http://localhost:1080/mockserver/wasm/modules?name=myMatcher" \
  --data-binary @my_matcher.wasm

Using a WASM body matcher in an expectation

{
  "httpRequest": {
    "method": "POST",
    "path": "/api/data",
    "body": {
      "type": "WASM",
      "moduleName": "myMatcher"
    }
  },
  "httpResponse": {
    "statusCode": 200,
    "body": "matched by WASM rule"
  }
}

Managing WASM modules

List loaded modules

curl http://localhost:1080/mockserver/wasm/modules
# Returns: ["myMatcher", "anotherModule"]

Remove a module

curl -X DELETE "http://localhost:1080/mockserver/wasm/modules?name=myMatcher"

All WASM modules are also cleared when calling PUT /mockserver/reset.

Test a module against a sample request

To check what a module does before wiring it into an expectation, POST the module plus a sample request to /mockserver/wasm/test. This is handy for IDE integrations and quick local iteration — it runs the module against your sample and tells you whether it matched, without storing the module or creating an expectation.

curl -X POST "http://localhost:1080/mockserver/wasm/test" \
  -H "Content-Type: application/json" \
  -d '{
        "module": "<base64-encoded .wasm>",
        "request": {
          "method": "POST",
          "path": "/orders",
          "headers": { "X-Tenant": ["acme"] },
          "body": "{}"
        }
      }'
# Returns: {"matched":true}

Supply either module (base64-encoded WASM bytes) or moduleName (a module already uploaded). The request object is optional and defaults to an empty body-only request. Like live matching, this is fail-closed: an invalid module returns {"matched":false} rather than an error.

Configuration properties

Error handling

WASM matching uses a fail-closed design. If any error occurs during matching (module not found, invalid WASM binary, runtime trap, missing match export), the matcher returns no match rather than throwing an exception. This prevents a broken WASM module from disrupting other expectations.

Security

• WASM modules run inside the chicory interpreter sandbox -- they cannot access the host filesystem, network, or JVM internals
• Linear memory is capped at wasmMaxMemoryPages pages (default 256 = 16 MiB) to prevent resource exhaustion. The limit is enforced at instance creation via chicory's MemoryLimits.
• The feature is opt-in (disabled by default). When wasmEnabled is false, all WASM control-plane endpoints (upload, list, delete) return 403 Forbidden, and WASM body matchers always return no match.
• All WASM control-plane endpoints respect MockServer's authentication settings (mTLS/JWT)