Module host 

proxy-wasm host implementation (DW-055).

This module implements the host side of the proxy-wasm ABI: the import functions that a WebAssembly plugin calls to interact with the proxy. The plugin exports phase callbacks (e.g. proxy_on_request_headers) that the host calls at the appropriate point in the request pipeline; the plugin calls back into the host via the imports defined here to read/write request data, log, send responses, etc.

Architecture

• WasmEngine — process-wide wasmtime engine + linker, compiled once at startup. Holds the compiled modules keyed by config name. Cheap to clone (Arc internals).
• PluginModule — a compiled wasmtime module for one plugin config entry. Created once at config publish time.
• PluginInstance — a per-request plugin instance (store + instance + context). Created for each request that passes through a route with plugins.
• PluginContext — the per-instance state the host imports read from and write to: request/response headers, body, the action returned by the plugin, etc. Stored in the wasmtime store’s user data.

Fuel and epoch preemption

Each instance is created with a fuel budget (PluginLimits::fuel). wasmtime consumes fuel on every operation; when the budget is exhausted, the plugin traps with an out-of-fuel error, which the host catches and converts to a 500 (the plugin is misbehaving, not the request). Epoch-based interruption is used for time caps: a background thread increments the epoch, and the plugin is interrupted if it runs past PluginLimits::timeout_ms.

Memory caps

PluginLimits::memory_mb caps the linear memory the plugin can allocate. wasmtime’s ResourceLimiter trait enforces this at the allocation boundary.

Import names and WASI

Modules built with the Rust proxy-wasm SDK (what dwara-cli plugin new scaffolds) import the spec ABI names, so the host registers BOTH the spec names (proxy_send_local_response, proxy_get_current_time_nanoseconds) and dwara’s original spellings (proxy_send_http_response, proxy_get_current_time) with identical behavior. The wasm32-wasip1 target additionally emits a small wasi_snapshot_preview1 import set (environment, fd_write, proc_exit, random_get, clock_time_get, sched_yield); the host provides minimal stubs for exactly that set — a module importing other WASI functions fails to instantiate (fail-closed).

Structs

LocalResponse

A local response set by the plugin via proxy_send_http_response.

PendingCallout

One proxy_http_call dispatch, parsed and validated at the hostcall boundary (DW-167). The instance queues it; the dispatch driver (the async plugin_dispatch boundary) performs the exchange and delivers the response back through PluginInstance::deliver_callout_response.

PluginContext

The per-instance context the host imports read from and write to.

PluginInstance

A per-request plugin instance: a wasmtime store + instance.

PluginLimits

Per-plugin resource limits (DW-055 decision 4; §9.3).

PluginMetric

A plugin-registered metric.

PluginModule

A compiled plugin module (one per config entry).

WasmEngine

Process-wide wasmtime engine + linker for proxy-wasm plugins.

Enums

PhaseResult

The result of a phase callback.

PluginMetricType

Metric types (proxy-wasm §2.4).

Constants

SHARED_DATA_CAP_BYTES

Per-module cap on the VM-scoped shared-data store: total bytes (key + value lengths summed over the entries). The store outlives every request (module lifetime), so an unbounded map is a slow OOM the wasm ResourceLimiter cannot see. A set that would exceed the cap FAILS (the plugin gets an error status it can branch on) — entries are never evicted: a silently evicted rate-limit counter or cache entry is a correctness bug, a refused set is a signal.

SHARED_DATA_CAP_ENTRIES

Per-module cap on the VM-scoped shared-data store: entry count (same posture as SHARED_DATA_CAP_BYTES; bounds key overhead a byte cap alone would miss).

Type Aliases

SharedData

The VM-scoped shared-data store (DW-167): one map per compiled plugin module, shared by every per-request instance through the Mutex. Keys are strings; values are bytes with a CAS version for optimistic concurrency.