feat: side-channel body passing via host functions (#49)

* fix: use binary bodies (Vec<u8>) in plugin SDK instead of String

Change Request/Response body from Option<String> to Option<Vec<u8>>
with base64 JSON encoding, fixing data loss for binary payloads like
multipart/form-data file uploads. Updates all plugins and the WASM
runtime to use the new binary-safe body type.

* fix: update remaining plugins and macro to use binary body type

Fix #[barbacane_dispatcher] macro error responses and update http-log,
oidc-auth, oauth2-auth, opa-authz HttpRequest structs to use
Option<Vec<u8>> with base64 encoding, matching the host-side expectation.
Also fix http-upstream test assertions to use from_slice.

* test: add comprehensive binary body coverage across SDK, WASM, and integration

SDK unit tests (20 new):
- Response base64 roundtrip (text, binary, none)
- Empty body vs None distinction
- Helper methods: body_string, set_body_text, Response::text
- Null bytes and all-256-byte-values roundtrip
- Middleware short-circuit with binary body
- Request body → Response body dispatcher roundtrip

WASM chain tests (2 new):
- parse_middleware_output with base64-encoded binary body (Continue)
- parse_middleware_output with binary body (ShortCircuit)

WASM cache tests (3 new):
- Binary body cache storage/retrieval
- CacheEntry JSON roundtrip with binary body
- CacheEntry JSON roundtrip with None body

Integration tests (3 new):
- Binary body through auth middleware to upstream (wiremock)
- Binary body direct dispatch without middleware (wiremock)
- Binary response body from upstream to client (wiremock)

* docs: update body type references from Option<String> to Option<Vec<u8>>

- docs/contributing/plugins.md: update SDK type signatures and add
  helper method docs, base64 encoding note
- adr/0023-wasm-plugin-streaming.md: fix Response type reference
- tests/fixture-plugins/streaming-echo: update HttpRequest body field
  to use base64_body serde encoding

* Fix write_to_memory OOM: write at __data_end instead of top of memory

The old approach wrote host data at mem_size - data.len() (top of linear
memory), which is exactly where dlmalloc's heap lives. This caused OOM
crashes in plugins that use host_http_call (e.g. oidc-auth) because the
heap allocation would overwrite the input data.

Now reads the __data_end WASM global at instantiation and writes host
data there — between static data and the stack. This is safe because
write_to_memory is only called before the WASM function executes (stack
is empty at that point).

* Add __heap_base bounds check to write_to_memory

Read both __data_end and __heap_base WASM globals at instantiation.
Input data is now bounded to the [__data_end..__heap_base] region,
preventing oversized payloads from silently corrupting the heap.

* fix: resolve WASM OOM by allocating input buffers via plugin's dlmalloc

The previous write_to_memory approaches (writing at top of memory, then
at __data_end, then via Memory::grow) all placed data in regions that
dlmalloc considered its heap, causing corruption during deserialization.

The fix exports alloc/dealloc from each WASM plugin (via the proc
macros) so the host allocates input buffers through the plugin's own
allocator. This ensures dlmalloc tracks the region and won't reuse it.

Additional optimizations to reduce peak memory:
- Free input buffer after deserialization (dealloc in on_request/
  on_response/dispatch before output serialization)
- Replace serde_json::json!() intermediate Value tree with direct
  ActionOutput struct serialization
- Scale WASM fuel with payload size for large body processing

Also adds 3 integration tests covering 500KB and 2MB body payloads
through middleware + dispatcher chains, and fixes a pre-existing
apikey-auth config format bug in the streaming test.

* feat: add body_access capability to strip request body from middleware that doesn't need it

Middleware plugins that only inspect headers (auth, rate-limit, etc.) no longer
receive the base64-encoded request body, avoiding unnecessary copies of large
payloads into each WASM instance.

- Add `body_access` bool to plugin manifest capabilities
- Compiler reads `body_access` from plugin.toml, carries it through artifact format
- Engine/pool propagate the flag per compiled module
- Data plane strips body (sets to null) before calling middleware without body_access,
  re-attaches it after; middleware with body_access can read and modify the body
- Mark request-transformer, cel, request-size-limit as body_access = true
- Add SPEC-008 design document

* docs: update changelog for binary body support and body_access capability

* perf(http-upstream): reduce peak WASM memory via move-not-clone and manual serialization

Destructure Request to avoid cloning the body, pre-encode to base64
before building JSON output, and use manual SerializeMap to control
allocation. Peak memory drops from ~body×3.7 to ~body×2.7, allowing
3MB uploads to fit within the 16MB WASM instance budget.

Add integration test for 3MB body through middleware + dispatch.

* refactor: extract BodyAccessControl with split-once pattern and 19 unit tests

Replace per-middleware JSON parse/strip/reattach cycles with a single
upfront body extraction. Non-body middlewares get the pre-built body-less
JSON directly; body-access middlewares get one inject/extract cycle.

- New `BodyAccessControl` struct in barbacane-wasm with split/request_for/
  update_after_middleware/finalize API
- 19 unit tests covering split, inject, update, finalize, full chain
  scenarios (mixed, all-no-access, all-access), and edge cases
- Simplify execute_middleware_on_request to 3 lines per middleware
- Document body_access capability in CLAUDE.md

* fix: add base64_body serde to host HttpRequest/HttpResponse and all plugin HttpResponse structs

The host-side HttpRequest/HttpResponse in http_client.rs was missing
#[serde(with = "base64_body")], causing body encoding mismatch with
WASM plugins after the Vec<u8> body migration. Plugins would receive
a base64 string but try to deserialize it as a byte array (or vice
versa), causing silent corruption or deserialization failures.

Also scale WASM memory to max(16MB, max_body_size * 4) so dispatchers
have headroom for large file uploads.

Affected plugins: http-upstream, lambda, ai-proxy, s3, opa-authz,
oauth2-auth, oidc-auth.

Add 5 unit tests for host↔plugin base64 body serde compatibility.

* fix: strip response body for non-body-access middleware (prevents WASM OOM)

Mirror SPEC-008 body_access stripping for the on_response path. Middleware
without body_access = true now receives responses with body: null, preventing
large upstream responses (e.g. file downloads) from being base64-encoded
into every middleware's WASM linear memory.

Also strips response body in the streaming on_response path (observability-only,
modifications are discarded anyway).

Adds body_access = true to response-transformer plugin manifest since it
modifies response bodies and needs access to them.

* test: add workload integration tests and serde contract tests

Add body-echo fixture plugin (dispatcher that echoes request body/metadata),
14 workload integration tests covering body integrity through middleware
chains, large payloads, and response body passthrough, plus 10 serde
compatibility tests verifying wire format between host and plugin types.

These tests would have caught the base64_body serde mismatch, body
corruption through middleware chains, and response body OOM issues
proactively.

* docs: update test count to 1421

* feat: side-channel body passing via host functions (eliminates WASM OOM)

Bodies now travel as raw bytes via dedicated host functions instead of
base64-encoded inside JSON. This eliminates the ~3.65x memory overhead
per boundary crossing, allowing 10MB+ bodies within the 16MB default
WASM memory limit.

New host functions: host_body_len, host_body_read, host_body_set,
host_body_clear, host_http_response_body_len, host_http_response_body_read,
host_http_request_body_set.

Request/Response.body is now #[serde(skip)] — proc macros handle the
side-channel protocol transparently. base64_body module retained for
host-side HTTP types and cache entries.

All 27 plugins migrated. WASM memory formula: max(16MB, body + 4MB).

* docs: update changelog and plugin guide for side-channel body passing

- Changelog: document side-channel host functions, body_access fix, WASM
  memory formula change, and plugin migration
- Plugin guide: update body docs from base64 to side-channel, update
  HTTP call example, update WASM memory limit table

* docs: update test count to 1388

* docs: update ADR-0023 and SPEC-008 for side-channel body passing

- ADR-0023: remove outdated "base64-encoded in JSON" reference
- SPEC-008: mark as Implemented, update problem statement, pseudocode,
  examples, and performance table to reflect side-channel protocol

Author: ndreno

CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- **wasm**: side-channel body passing via 7 new host functions (`host_body_len`, `host_body_read`, `host_body_set`, `host_body_clear`, `host_http_response_body_len`, `host_http_response_body_read`, `host_http_request_body_set`)
+  - Bodies travel as raw bytes instead of base64-encoded inside JSON
+  - Eliminates ~3.65× memory overhead per boundary crossing
+  - 10MB+ bodies work within the default 16MB WASM memory limit
+- **plugin-sdk**: `barbacane_plugin_sdk::body` module — side-channel body helpers (`read_request_body`, `set_response_body`, `clear_response_body`, `read_http_response_body`, `set_http_request_body`)
+
+### Fixed
+- **wasm**: fix WASM OOM on large request bodies — input buffers now allocated via plugin's own dlmalloc instead of writing to top-of-memory
+- **wasm**: short-circuit response bodies now always collected regardless of `body_access` flag (fixes empty error responses from middleware like opa-authz)
+
+### Changed
+- **plugin-sdk**: `Request.body` and `Response.body` now use `#[serde(skip)]` — bodies travel via side-channel, not JSON. Proc macros handle the protocol transparently.
+- **plugin-sdk**: request/response body is now `Option<Vec<u8>>` (was `Option<String>`), enabling binary payload support across all plugins
+- **wasm**: `body_access` capability — middleware that doesn't declare `body_access = true` receives `null` body, reducing WASM memory usage
+  - `request-transformer`, `response-transformer`, `cel`, `request-size-limit` declare `body_access = true`; all other middleware plugins skip the body
+- **wasm**: WASM memory formula changed from `max(16MB, body × 4)` to `max(16MB, body + 4MB)`
+- **plugins**: all 27 plugins migrated to side-channel body protocol; `http-upstream` removed `base64` dependency
+
 ## [0.3.1] - 2026-03-13
 
 ### Fixed

CLAUDE.md

@@ -105,6 +105,9 @@ context_get = true
 | `verify_signature` | `host_verify_signature` |
 | `rate_limit` | `host_rate_limit_check`, `host_rate_limit_read_result` |
 | `cache` | `host_cache_get`, `host_cache_set`, `host_cache_read_result` |
+| `body_access` | *(none — controls whether `on_request` receives the request body)* |
+
+`body_access` is not a host function capability — it's a manifest-level flag (SPEC-008). When `false` (default for middleware), the host strips the request body before calling `on_request`, reducing WASM memory usage. Dispatchers always receive the body regardless. Set `body_access = true` only for middleware that reads or modifies `request.body`.
 
 ### Building Plugins
 

Cargo.lock

@@ -9,9 +9,9 @@
 <p align="center">
   <a href="https://github.com/barbacane-dev/barbacane/actions/workflows/ci.yml"><img src="https://github.com/barbacane-dev/barbacane/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <a href="https://docs.barbacane.dev"><img src="https://img.shields.io/badge/docs-docs.barbacane.dev-blue" alt="Documentation"></a>
-  <img src="https://img.shields.io/badge/unit%20tests-399%20passing-brightgreen" alt="Unit Tests">
-  <img src="https://img.shields.io/badge/plugin%20tests-649%20passing-brightgreen" alt="Plugin Tests">
-  <img src="https://img.shields.io/badge/integration%20tests-192%20passing-brightgreen" alt="Integration Tests">
+  <img src="https://img.shields.io/badge/unit%20tests-444%20passing-brightgreen" alt="Unit Tests">
+  <img src="https://img.shields.io/badge/plugin%20tests-636%20passing-brightgreen" alt="Plugin Tests">
+  <img src="https://img.shields.io/badge/integration%20tests-237%20passing-brightgreen" alt="Integration Tests">
   <img src="https://img.shields.io/badge/cli%20tests-16%20passing-brightgreen" alt="CLI Tests">
   <img src="https://img.shields.io/badge/ui%20tests-44%20passing-brightgreen" alt="UI Tests">
   <img src="https://img.shields.io/badge/e2e%20tests-11%20passing-brightgreen" alt="E2E Tests">

README.md

@@ -5,7 +5,7 @@
 
 ## Context
 
-The current dispatch contract requires plugins to return a fully buffered `Response` (status + headers + `Option<String>` body). This works for typical API proxying but breaks down for use cases that require streaming responses to clients:
+The current dispatch contract requires plugins to return a fully buffered `Response` (status + headers + `Option<Vec<u8>>` body). Bodies travel via side-channel host functions as raw bytes (see SPEC-008). This works for typical API proxying but breaks down for use cases that require streaming responses to clients:
 
 - **LLM completions** — Chat APIs (OpenAI, Anthropic) stream tokens via SSE, often taking 10–60 seconds. Buffering the entire response before sending it to the client defeats the purpose of streaming and creates unacceptable latency.
 - **Event streams** — Server-Sent Events, webhook relays.

adr/0023-wasm-plugin-streaming.md

@@ -113,6 +113,27 @@ pub struct BundledPlugin {
     pub wasm_path: String,
     /// SHA-256 hash of the WASM file.
     pub sha256: String,
+    /// Plugin capabilities declared in plugin.toml.
+    pub capabilities: PluginCapabilities,
+}
+
+/// Plugin capabilities stored in the artifact manifest.
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+pub struct PluginCapabilities {
+    /// Whether the middleware receives the request body in `on_request`.
+    #[serde(default)]
+    pub body_access: bool,
+}
+
+/// A plugin loaded from a .bca artifact, ready for compilation.
+#[derive(Debug, Clone)]
+pub struct LoadedPlugin {
+    /// Plugin version.
+    pub version: String,
+    /// WASM binary content.
+    pub wasm_bytes: Vec<u8>,
+    /// Whether this plugin needs the request body.
+    pub body_access: bool,
 }
 
 /// Metadata about a source spec included in the artifact.
@@ -222,6 +243,7 @@ pub fn compile_with_manifest(
             version: p.version.unwrap_or_else(|| "0.1.0".to_string()),
             plugin_type: p.plugin_type.unwrap_or_else(|| "plugin".to_string()),
             wasm_bytes: p.wasm_bytes,
+            body_access: p.body_access,
         })
         .collect();
 
@@ -302,10 +324,8 @@ pub fn load_specs(artifact_path: &Path) -> Result<HashMap<String, String>, Compi
 }
 
 /// Load all bundled plugins from a .bca artifact.
-/// Returns a map of plugin name -> (version, WASM bytes).
-pub fn load_plugins(
-    artifact_path: &Path,
-) -> Result<HashMap<String, (String, Vec<u8>)>, CompileError> {
+/// Returns a map of plugin name -> LoadedPlugin.
+pub fn load_plugins(artifact_path: &Path) -> Result<HashMap<String, LoadedPlugin>, CompileError> {
     // First load manifest to get plugin metadata
     let manifest = load_manifest(artifact_path)?;
 
@@ -315,21 +335,28 @@ pub fn load_plugins(
 
     let mut plugins = HashMap::new();
 
-    // Build a map of wasm_path -> (name, version) from manifest
-    let plugin_info: HashMap<String, (String, String)> = manifest
+    // Build a map of wasm_path -> plugin info from manifest
+    let plugin_info: HashMap<String, (&BundledPlugin,)> = manifest
         .plugins
         .iter()
-        .map(|p| (p.wasm_path.clone(), (p.name.clone(), p.version.clone())))
+        .map(|p| (p.wasm_path.clone(), (p,)))
         .collect();
 
     for entry in archive.entries()? {
         let mut entry = entry?;
         let path_str = entry.path()?.to_string_lossy().into_owned();
 
-        if let Some((name, version)) = plugin_info.get(&path_str) {
+        if let Some((bundled,)) = plugin_info.get(&path_str) {
             let mut wasm_bytes = Vec::new();
             entry.read_to_end(&mut wasm_bytes)?;
-            plugins.insert(name.clone(), (version.clone(), wasm_bytes));
+            plugins.insert(
+                bundled.name.clone(),
+                LoadedPlugin {
+                    version: bundled.version.clone(),
+                    wasm_bytes,
+                    body_access: bundled.capabilities.body_access,
+                },
+            );
         }
     }
 
@@ -346,6 +373,8 @@ pub struct PluginBundle {
     pub plugin_type: String,
     /// WASM binary content.
     pub wasm_bytes: Vec<u8>,
+    /// Whether this plugin needs the request body.
+    pub body_access: bool,
 }
 
 /// Parse spec files into (ApiSpec, content, sha256) tuples.
@@ -583,6 +612,9 @@ fn compile_inner(
             plugin_type: plugin.plugin_type.clone(),
             wasm_path,
             sha256,
+            capabilities: PluginCapabilities {
+                body_access: plugin.body_access,
+            },
         });
     }
 
@@ -1280,6 +1312,7 @@ paths:
             version: "1.0.0".to_string(),
             plugin_type: "middleware".to_string(),
             wasm_bytes: fake_wasm.clone(),
+            body_access: false,
         }];
 
         let result = compile(
@@ -1302,9 +1335,9 @@ paths:
         // Load plugins back
         let loaded = load_plugins(&output_path).unwrap();
         assert_eq!(loaded.len(), 1);
-        let (version, wasm_bytes) = loaded.get("test-plugin").unwrap();
-        assert_eq!(version, "1.0.0");
-        assert_eq!(wasm_bytes, &fake_wasm);
+        let plugin = loaded.get("test-plugin").unwrap();
+        assert_eq!(plugin.version, "1.0.0");
+        assert_eq!(plugin.wasm_bytes, fake_wasm);
     }
 
     #[test]

crates/barbacane-compiler/src/artifact.rs

@@ -10,8 +10,9 @@ pub mod spec_parser;
 
 pub use artifact::{
     compile, compile_with_manifest, load_manifest, load_plugins, load_routes, load_specs,
-    BundledPlugin, CompileOptions, CompileResult, CompiledOperation, CompiledRoutes, Manifest,
-    PluginBundle, Provenance, SourceSpec, ARTIFACT_VERSION, COMPILER_VERSION,
+    BundledPlugin, CompileOptions, CompileResult, CompiledOperation, CompiledRoutes, LoadedPlugin,
+    Manifest, PluginBundle, PluginCapabilities, Provenance, SourceSpec, ARTIFACT_VERSION,
+    COMPILER_VERSION,
 };
 pub use error::{CompileError, CompileWarning};
 pub use manifest::{

crates/barbacane-compiler/src/lib.rs

@@ -15,6 +15,8 @@ use crate::error::CompileError;
 #[derive(Debug, Deserialize)]
 struct PluginToml {
     plugin: PluginMeta,
+    #[serde(default)]
+    capabilities: PluginTomlCapabilities,
 }
 
 #[derive(Debug, Deserialize)]
@@ -24,12 +26,29 @@ struct PluginMeta {
     plugin_type: String,
 }
 
+#[derive(Debug, Default, Deserialize)]
+struct PluginTomlCapabilities {
+    #[serde(default)]
+    body_access: bool,
+}
+
+/// Plugin metadata extracted from plugin.toml.
+struct PluginMetadata {
+    version: String,
+    plugin_type: String,
+    body_access: bool,
+}
+
 /// Try to read plugin metadata from plugin.toml in the same directory as the WASM file.
-fn read_plugin_metadata(wasm_path: &Path) -> Option<(String, String)> {
+fn read_plugin_metadata(wasm_path: &Path) -> Option<PluginMetadata> {
     let plugin_toml_path = wasm_path.parent()?.join("plugin.toml");
     let content = std::fs::read_to_string(&plugin_toml_path).ok()?;
     let parsed: PluginToml = toml::from_str(&content).ok()?;
-    Some((parsed.plugin.version, parsed.plugin.plugin_type))
+    Some(PluginMetadata {
+        version: parsed.plugin.version,
+        plugin_type: parsed.plugin.plugin_type,
+        body_access: parsed.capabilities.body_access,
+    })
 }
 
 /// Resolve a WASM path from a plugin source, relative to a base path.
@@ -79,22 +98,21 @@ fn resolve_plugin(
     }
 
     // Try to read plugin metadata from plugin.toml
-    let (version, plugin_type) = match source {
+    let metadata = match source {
         PluginSource::Path(path_source) => {
             let wasm_path = resolve_wasm_path(path_source, base_path);
             read_plugin_metadata(&wasm_path)
-                .map(|(v, t)| (Some(v), Some(t)))
-                .unwrap_or((None, None))
         }
-        PluginSource::Url(_) => (None, None),
+        PluginSource::Url(_) => None,
     };
 
     Ok(ResolvedPlugin {
         name: name.to_string(),
         source: source.description(),
         wasm_bytes,
-        version,
-        plugin_type,
+        version: metadata.as_ref().map(|m| m.version.clone()),
+        plugin_type: metadata.as_ref().map(|m| m.plugin_type.clone()),
+        body_access: metadata.as_ref().is_some_and(|m| m.body_access),
     })
 }
 
@@ -155,6 +173,8 @@ pub struct ResolvedPlugin {
     pub version: Option<String>,
     /// Plugin type: "middleware" or "dispatcher" (from plugin.toml if available).
     pub plugin_type: Option<String>,
+    /// Whether this plugin needs the request body in `on_request`.
+    pub body_access: bool,
 }
 
 impl ProjectManifest {

crates/barbacane-compiler/src/manifest.rs

@@ -262,6 +262,8 @@ async fn resolve_project_plugins(
             version: plugin_with_binary.version.clone(),
             plugin_type: plugin_with_binary.plugin_type.clone(),
             wasm_bytes: plugin_with_binary.wasm_binary,
+            // TODO: read body_access from DB once the plugins table has a capabilities column
+            body_access: false,
         });
     }