dwara_core/wasm/
mod.rs

1//! proxy-wasm host (DW-055).
2//!
3//! This module implements a proxy-wasm ABI host on top of wasmtime,
4//! allowing dwara to run community Kong/Envoy proxy-wasm filters
5//! unmodified. The host compiles unconditionally in the OSS build
6//! (there are no cargo features for it): `dataplane::plugin_dispatch`
7//! (DW-157) drives it on the live request path for routes that
8//! reference plugins.
9//!
10//! ## Architecture
11//!
12//! - [`abi`] — proxy-wasm ABI constants and header map serialization.
13//! - [`host`] — the wasmtime host: engine, linker (ABI imports), plugin
14//!   module, and per-request instance.
15//!
16//! ## Phase contract (§9.3)
17//!
18//! dwara's request pipeline calls plugin phase callbacks at defined
19//! points. Each plugin declares which phase(s) it hooks. The phases
20//! relevant to HTTP filters are:
21//!
22//! 1. `request_headers` — after route resolution, before authn.
23//! 2. `request_body` — after authn/authz/rate-limit, before upstream.
24//! 3. `response_headers` — after the upstream responds, before masking.
25//! 4. `response_body` — after masking, before compression.
26//!
27//! A plugin can short-circuit the request by calling
28//! `proxy_send_http_response` (returns a local response instead of
29//! forwarding to the upstream). The host catches this and returns the
30//! stored response immediately.
31//!
32//! ## Fuel and epoch preemption (decision 4; §9.3)
33//!
34//! Each plugin instance gets a fuel budget ([`PluginLimits::fuel`]).
35//! wasmtime consumes fuel on every operation; exhaustion traps the
36//! plugin, which the host converts to a 500. Memory is capped via
37//! wasmtime's `ResourceLimiter`. Time caps use epoch interruption.
38//!
39//! ## Done-when
40//!
41//! A community Kong/Envoy proxy-wasm filter runs unmodified. The test
42//! suite includes a minimal proxy-wasm filter compiled from Rust source
43//! that exercises the core ABI surface (header inspection, response
44//! short-circuit, body modification).
45
46pub mod abi;
47pub mod host;
48pub mod lifecycle;
49pub mod runner;
50// DW-119: the WASM-to-unified-chain adapter. Bridges the proxy-wasm
51// host's per-request instances into the unified plugin chain (plugins
52// domain) so native filters and WASM plugins share the same phase
53// slot; compiles unconditionally alongside the rest of the host.
54pub mod adapter;
55// DW-165: registry plugin source resolution (cache-first fetch,
56// SHA-256 digest + Ed25519 signature verification, atomic digest-
57// named cache) — the step before `lifecycle` loads the bytes.
58pub mod source;
59// DW-167: the plugin HTTP callout transport (proxy_http_call). The
60// pause/resume driver lives at the async plugin_dispatch boundary in
61// the dataplane; this module is the synchronous exchange itself.
62pub mod callout;
63
64pub use abi::{deserialize_header_map, serialize_header_map, ACTION_CONTINUE, ACTION_END_STREAM};
65pub use callout::{
66    perform_callout, CalloutError, CalloutRequest, CalloutResponse, CALLOUT_BODY_CAP_BYTES,
67    CALLOUT_TIMEOUT_MAX_MS, CALLOUT_TIMEOUT_MIN_MS, MAX_CALLOUT_ROUNDS,
68};
69pub use host::{
70    LocalResponse, PendingCallout, PhaseResult, PluginContext, PluginInstance, PluginLimits,
71    PluginMetric, PluginMetricType, PluginModule, WasmEngine,
72};
73pub use lifecycle::{LoadError, LoadedPlugin, PluginHealth, PluginLifecycle, ValidationError};
74pub use runner::{PhaseOutcome, PluginInstances, PluginRunner};
75pub use source::{resolve_sources, SourceError, SourceResolutions, DEFAULT_CACHE_DIR};
dwara_core/wasm/mod.rs

dwara_core/wasm/
mod.rs
