faucet_transform_wasm/
lib.rs

1#![cfg_attr(docsrs, feature(doc_cfg))]
2//! WebAssembly-as-transform for faucet-stream.
3//!
4//! Loads a user-provided, precompiled `.wasm` module through [`wasmtime`] and
5//! invokes an exported function once per record. Any language that compiles to
6//! core WebAssembly (Rust, TinyGo, AssemblyScript, Zig, C/C++, …) can express
7//! arbitrary per-record logic in a faucet pipeline without forking the project.
8//!
9//! [`WasmTransformConfig`] is the user-facing config; [`WasmTransform`] is the
10//! compiled runtime that owns the wasmtime engine + module and runs it per
11//! page via [`WasmTransform::into_page_stage`].
12//!
13//! # Sandbox
14//!
15//! Modules run in a strict sandbox. Each record call is bounded by
16//! [`fuel`](WasmTransformConfig::fuel_limit) (a deterministic CPU limit) and by
17//! [`memory`](WasmTransformConfig::memory_limit_mb) (linear-memory cap). The
18//! only host imports are `faucet_v1::log` and `faucet_v1::now_ns` — there is no
19//! filesystem, network, clock, or environment access in v1.
20//!
21//! # ABI (v1)
22//!
23//! The module must export:
24//! - `alloc(len: i32) -> i32` — allocate `len` bytes of linear memory, return
25//!   the offset. The host writes the input JSON there before each call.
26//! - `<function>(ptr: i32, len: i32) -> i64` — the transform entry point
27//!   (name from [`WasmTransformConfig::function`], default `"transform"`).
28//!   Input is UTF-8 JSON at `[ptr, ptr+len)`. The packed return value is
29//!   `(out_ptr as u64) << 32 | (out_len as u64)`:
30//!   - `0` → drop the record (filter it out).
31//!   - [`u64::MAX`] → error; the host reads the message from the optional
32//!     `error_ptr()` / `error_len()` exports.
33//!   - otherwise → the output UTF-8 JSON at `[out_ptr, out_ptr+out_len)`.
34//! - `memory` — the exported linear memory (standard name).
35//!
36//! Optional exports: `free(ptr: i32, len: i32)` (host calls it after copying
37//! output out), `error_ptr() -> i32` / `error_len() -> i32` (error message).
38//!
39//! See the crate README and the `docs/book` cookbook page for full details and
40//! reference modules.
41
42mod abi;
43mod config;
44mod engine;
45mod instance;
46pub(crate) mod metrics;
47mod runtime;
48
49pub use config::{WasmOnError, WasmTransformConfig};
50pub use runtime::WasmTransform;
faucet_transform_wasm/lib.rs

faucet_transform_wasm/
lib.rs
