Package org.mockserver.wasm

Class WasmRuntime

java.lang.Object
org.mockserver.wasm.WasmRuntime
public class WasmRuntime extends Object
Thin wrapper around a compiled chicory WASM instance.

Thread-safety: chicory Instance is NOT thread-safe, so a fresh Instance is created for each invocation. The parsed WasmModule, by contrast, is immutable and freely reusable across threads, so it is cached (see MODULE_CACHE) keyed by a content hash of the module bytes — parsing/validating the binary is chicory's most expensive step and is pure given the bytes, so it is done at most once per distinct module.

ABI. Two export shapes are supported, both returning non-zero for a match:

  • Legacy body-only — match(i32 ptr, i32 len) -> i32. The request body is written into linear memory at offset 0 and the function is called with (0, bodyLength).
  • Richer request envelope — match_request(i32 ptr, i32 len) -> i32. A JSON envelope {"version","method","path","queryStringParameters","headers","cookies","body"} is written into linear memory at offset 0 and the function is called with (0, jsonLength). This lets a module read the method, path, query parameters, headers and cookies in addition to the body. See ENVELOPE_VERSION for how the envelope stays backward compatible.
If the module exports match_request it is preferred; otherwise the runtime falls back to match with the body only, so existing body-only modules keep working unchanged.

This class fails closed: any error returns false.

  • Constructor Details

    • WasmRuntime

      public WasmRuntime(byte[] wasmBytes)
      Create a runtime with the default memory page limit from ConfigurationProperties.wasmMaxMemoryPages().

    • WasmRuntime

      public WasmRuntime(byte[] wasmBytes, int maxMemoryPages)
      Create a runtime with an explicit memory page limit.
      Parameters:
      wasmBytes - the compiled WASM binary
      maxMemoryPages - maximum number of WASM linear memory pages (each page is 64 KiB)

  • Method Details

    • callMatch

      public boolean callMatch(String requestBody)
      Call the WASM module with just the request body (legacy body-only ABI).

      Retained for back-compat; equivalent to callMatch(WasmRequest.ofBody(requestBody)).

      Parameters:
      requestBody - the HTTP request body (may be null)
      Returns:
      true if the module reports a match

    • callMatch

      public boolean callMatch(WasmRequest request)
      Call the WASM module with the full request envelope (method, path, headers, body).

      If the module exports MATCH_REQUEST the JSON envelope is passed and that function is invoked; otherwise the runtime falls back to the legacy MATCH export with only the body, preserving back-compat for body-only modules.

      Parameters:
      request - the request parts to expose to the module (must not be null)
      Returns:
      true if the module reports a match

    • callShape

      public WasmResponse callShape(WasmRequest request, WasmResponse response)
      Call the module's optional SHAPE_RESPONSE export to (possibly) rewrite the response the matched expectation would return. This is the ABI v3 response-shaping hook.

      The runtime writes the shape envelope into linear memory at offset 0 and calls shape_response(0, len) -> i64. The module writes its response JSON somewhere in its own linear memory and returns a packed (ptr << 32) | len; the runtime reads len bytes at ptr and parses them into a WasmResponse. A return of 0 means "no change".

      Parameters:
      request - the matched request parts (serialised under the envelope's request field)
      response - the response the expectation would return (serialised under response)
      Returns:
      the parsed shaped response, or null when the module does not export SHAPE_RESPONSE or explicitly opts out (returns 0)
      Throws:
      WasmShapeException - if the module traps, returns an out-of-bounds or oversized region, or returns bytes that are not a valid response JSON object — the caller falls back to the unshaped response and logs once (see WasmResponseShaper)

    • invalidate

      public static void invalidate(byte[] wasmBytes)
      Drop the cached parsed module for the given bytes, if present. Called when a module is unloaded so its parsed form is released promptly. A no-op when the bytes were never cached. Correctness never depends on this (the cache is content-keyed); it only bounds memory.

    • invalidateAll

      public static void invalidateAll()
      Clear all cached parsed modules. Called on a full WASM store reset.