Features / WASM plugins

WASM plugins

A WASM plugin lets you answer requests on a route with your own code, compiled to WebAssembly, without loading native code into the server. This page covers what a plugin can and cannot do, how to configure one, the limits that apply, and the two interfaces a plugin can implement.

What a plugin is

WebAssembly (WASM) is a portable binary format that runs inside a virtual machine instead of directly on the processor. MiraServe runs plugins in Wasmtime, an embedded WebAssembly runtime, with a fresh, isolated instance for every request.

A plugin is a route handler: when a request matches its route, MiraServe hands the request to the plugin and returns whatever response the plugin produces. It is not a filter that runs in front of other handlers.

What a plugin can do:

  • Read the request and build a response: status code, headers and body.
  • Use CPU and memory up to the limits you set.

What a plugin cannot do:

  • Open files. No directories are made available to it.
  • Read environment variables or command-line arguments.
  • Open network connections or make outbound HTTP requests. Outbound requests are refused.
  • Run past its CPU budget, memory ceiling or time limit.
  • Set framing or connection headers, or weaken the site's security headers (see responses).

Smallest working setup

server {
    listen ":443" protocols="h3,h2,h1"
    tls {
        cert "/etc/miraserve/certs/example.com.crt"
        key "/etc/miraserve/certs/example.com.key"
    }
}

site "example.com" {
    root "/var/www/example"

    route "/hello" {
        wasm-plugin "/etc/miraserve/plugins/hello.wasm" max-memory="16MB" max-fuel=5000000 timeout="100ms"
    }

    route "/*" {
        try-files "{path}" "{path}/index.html" "=404"
    }
}

Validate it, including a check that the module file exists and is readable:

$ miraserve check --fs /etc/miraserve/conf/miraserve.kdl

The module is compiled when the configuration is loaded or reloaded. If it is not a valid module, or does not implement one of the interfaces below, the server refuses to start, or a reload is rejected and the running configuration stays in place.

Directive reference

wasm-plugin goes inside a route block and replaces any other handler on that route. It takes the module path as its only argument.

PropertyDefaultAllowed rangeMeaning
(argument)requireda regular file up to 32 MiBPath to a .wasm binary or .wat text module.
max-memory16 MiB64 KiB to 256 MiBCeiling on the plugin's linear memory for one request.
max-fuel50000001 to 50,000,000CPU budget per request, in Wasmtime fuel units (roughly one per executed instruction). Copies between the host and the plugin are also charged.
timeout100ms1ms to 30sWall-clock limit per request, enforced even inside a tight loop.

A child directive allow-hosts is parsed but currently rejected by check with error E501, because outbound HTTP from plugins is not enabled. Values outside the ranges above also produce E501.

What happens when a limit is hit

CauseResponse to clientMetric outcome
Fuel exhausted504fuel_exhausted
Timeout504timeout
Memory ceiling503memory_limit
Trap or other plugin error500trap
Request body larger than max-body-bytes (10 MiB by default)413not counted

The client receives a generic error page; Wasmtime's internal error text is only written to the server log. Outcomes are counted in miraserve_wasm_invocations_total and miraserve_wasm_fuel_consumed_total (see telemetry). The first three causes also count as wasm_sandbox in miraserve_security_blocks_total.

Other fixed limits: the response body may be at most 4 MiB, and the request body is read fully before the plugin starts, up to the server's max-body-bytes.

Response headers

MiraServe removes these headers from every plugin response: Content-Length, Transfer-Encoding, Connection, Keep-Alive, Upgrade, TE, Trailer, Proxy-Authenticate, Proxy-Authorization, Proxy-Connection, HTTP2-Settings, Host and Alt-Svc, plus any header named in a Connection header. A plugin may not return a 1xx status. The site's security headers are then applied and always overwrite any values the plugin set.

Plugin interfaces

MiraServe looks at the module and accepts one of two shapes.

A wasi:http component

WASI (the WebAssembly System Interface) is a set of standard interfaces between WebAssembly code and its host. wasi:http is the WASI 0.2 interface for HTTP handlers. A component that exports the wasi:http/proxy world receives the full request (method, path and query, headers, body) and writes a full response. This is the shape to use for anything beyond a fixed reply.

MiraServe links the WASI 0.2 interfaces with an empty context: no preopened directories, no environment variables, no arguments. Outgoing wasi:http requests are refused. A component that does not export wasi:http/proxy is rejected at load time.

The repository does not include a guide or toolchain instructions for building wasi:http components. Any toolchain that produces a WASI 0.2 component exporting wasi:http/proxy is the expected input. MiraServe embeds Wasmtime 48.

A core module with the MiraServe interface

A plain WebAssembly module (not a component) can use a small MiraServe-specific interface instead. It only sees the request method and path, not the query string, headers or body, so it suits fixed or path-based replies.

The module must export:

  • memory: its linear memory.
  • miraserve_handle(method_ptr: i32, method_len: i32, path_ptr: i32, path_len: i32) -> i32: called once per request. The return value is the HTTP status. A value that is not a valid status, or is in the 1xx range, becomes 500.
  • Optionally miraserve_alloc(len: i32) -> i32: if present, MiraServe calls it to get a buffer for the method and path. Otherwise it grows memory by a fresh page and writes them there.

It may import these functions from the miraserve module. Each returns a negative number on error:

ImportMeaning
read_request_method(ptr, cap) -> i32Copy up to cap bytes of the method to ptr; returns the number copied.
read_request_path(ptr, cap) -> i32Same, for the path.
set_response_body(ptr, len) -> i32Set the response body (at most 4 MiB).
set_response_header(name_ptr, name_len, value_ptr, value_len) -> i32Add a header. At most 64 headers, names up to 256 bytes, values up to 4096 bytes.

This complete plugin, saved as hello.wat, can be used directly as the module path:

(module
  (import "miraserve" "set_response_body" (func $set_body (param i32 i32) (result i32)))
  (import "miraserve" "set_response_header" (func $set_header (param i32 i32 i32 i32) (result i32)))
  (memory (export "memory") 1)
  (data (i32.const 1024) "Hello from a sandboxed plugin\n")
  (data (i32.const 1100) "content-type")
  (data (i32.const 1120) "text/plain; charset=utf-8")
  (func (export "miraserve_handle")
        (param $method_ptr i32) (param $method_len i32)
        (param $path_ptr i32) (param $path_len i32)
        (result i32)
    (drop (call $set_header (i32.const 1100) (i32.const 12) (i32.const 1120) (i32.const 25)))
    (drop (call $set_body (i32.const 1024) (i32.const 30)))
    (i32.const 200))
)
$ curl https://example.com/hello
Hello from a sandboxed plugin

Running plugins under systemd

Wasmtime compiles plugins to machine code when the configuration loads, which needs memory that is writable and then executable. The generated systemd unit therefore sets MemoryDenyWriteExecute=no. If you do not use plugins, generate the unit with --no-wasm to turn that protection on. See running as a service.

Limits and current state

  • Outbound network access from plugins is not available; allow-hosts is rejected.
  • Core modules see only the method and path.
  • Request bodies are buffered in full before the plugin runs, and responses are buffered up to 4 MiB; plugins cannot stream.
  • Each request gets a new instance, so a plugin keeps no state between requests.