WASM Payloads

Payloads are WebAssembly modules that process requests and responses at the proxy layer, sandboxed by wasmtime. They can block requests, rewrite paths and headers, and modify response headers — without touching your application code.

Requires building mothership with --features wasm (+8.4 MB).

[[modules]]
name = "auth"
wasm = "./modules/auth.wasm"
routes = ["/admin/.*"]
phase = "request"

[[modules]]
name = "cache"
wasm = "./modules/cache.wasm"
routes = ["/api/.*"]
phase = "response"
config = { ttl = "3600" }

Module configuration

Field	Type	Default	Description
name	string	required	Unique identifier
wasm	string	required	Path to the .wasm file
routes	string[]	[]	Regex patterns the module applies to
phase	string	"request"	request or response
config	table	{}	String key-value config passed to the module
tags	string[]	[]	Tags for filtering

What payloads can do

• Block requests — return a custom status, body, and headers without hitting the backend
• Modify requests — rewrite the path or headers before forwarding
• Modify responses — adjust response headers on the way out

Fail-closed security

• If a configured module fails to load, mothership refuses to start.
• If a module errors during request/response processing, mothership returns 503 rather than letting traffic through unprocessed.

Bundled modules

Mothership ships reference modules you can use directly or as starting points:

Module	Purpose
rate_limiter.wasm	Request rate limiting
cors.wasm	CORS header handling
jwt_validator.wasm	JWT validation
ip_allowlist.wasm	IP allowlisting

Host functions

Guest modules interact with mothership through these host functions:

Function	Description
get_request()	Get request JSON length
read_request(ptr, len)	Read request JSON into a buffer
set_action(action)	Set action: 0 = Continue, 1 = Block
set_block(status, body_ptr, body_len)	Block with status and body
set_block_with_headers(status, body_ptr, body_len, headers_ptr, headers_len)	Block with status, body, and headers (JSON)
log(level, ptr, len)	Log a message (0 = debug, 1 = warn, 2 = info)