Skip to main content

fv_compute_wasm/
lib.rs

1//! # fv-compute-wasm — the WASM Component Model backend
2//!
3//! Implements [`fv_compute::TransformBackend`] for `impl = "wasm"`: it compiles a component once
4//! (`load`), then runs whole Arrow `RecordBatch`es across the WIT boundary per call. A **pool of
5//! pre-instantiated wasmtime `Store`s** makes it partition-parallel — each worker
6//! checks out its own instance, so a single box saturates its cores with no per-batch
7//! instantiation cost.
8//!
9//! Register it on a [`fv_compute::Backends`] set for `impl = "wasm"` manifests.
10
11/// Every Rust code block in the README is compiled and run as a doctest.
12#[cfg(doctest)]
13#[doc = include_str!("../README.md")]
14pub struct ReadmeDoctests;
15
16use arrow::array::RecordBatch;
17use fv_compute::{Compute, ComputeError, ImplKind, TransformBackend, TransformManifest};
18use std::path::Path;
19use std::sync::Mutex;
20use wasmtime::component::{Component, Linker};
21use wasmtime::{Config, Engine, Store};
22use wasmtime_wasi::{ResourceTable, WasiCtx, WasiCtxBuilder, WasiCtxView, WasiView};
23
24mod bindings {
25    wasmtime::component::bindgen!({
26        world: "transform-component",
27        path: "wit",
28    });
29}
30pub(crate) use bindings::exports::fv::compute::transform as wit;
31use bindings::TransformComponent;
32
33mod convert;
34
35struct HostState {
36    table: ResourceTable,
37    wasi: WasiCtx,
38}
39impl WasiView for HostState {
40    fn ctx(&mut self) -> WasiCtxView<'_> {
41        WasiCtxView {
42            ctx: &mut self.wasi,
43            table: &mut self.table,
44        }
45    }
46}
47
48/// The WASM backend. One per process (or per engine config); cheap to clone-share via the
49/// registry. Holds the shared wasmtime [`Engine`] (its module cache/allocator).
50pub struct WasmBackend {
51    engine: Engine,
52}
53
54impl WasmBackend {
55    pub fn new() -> Result<Self, ComputeError> {
56        let mut config = Config::new();
57        config.wasm_component_model(true);
58        let engine = Engine::new(&config).map_err(|e| ComputeError::Load {
59            id: "<engine>".into(),
60            msg: e.to_string(),
61        })?;
62        Ok(Self { engine })
63    }
64}
65
66impl TransformBackend for WasmBackend {
67    fn kind(&self) -> ImplKind {
68        ImplKind::Wasm
69    }
70
71    fn load(&self, manifest: &TransformManifest, root: &Path) -> Result<Box<dyn Compute>, ComputeError> {
72        let id = manifest.id.clone();
73        let entry = manifest.entry.as_deref().ok_or_else(|| ComputeError::Load {
74            id: id.clone(),
75            msg: "wasm impl has no `entry`".into(),
76        })?;
77        let path = root.join(entry);
78        let component = Component::from_file(&self.engine, &path).map_err(|e| ComputeError::Load {
79            id: id.clone(),
80            msg: format!("load {}: {e:#}", path.display()),
81        })?;
82        let mut linker = Linker::new(&self.engine);
83        wasmtime_wasi::p2::add_to_linker_sync(&mut linker).map_err(|e| ComputeError::Load {
84            id: id.clone(),
85            msg: format!("wasi linker: {e:#}"),
86        })?;
87
88        Ok(Box::new(WasmCompute {
89            manifest: manifest.clone(),
90            engine: self.engine.clone(),
91            component,
92            linker,
93            pool: Mutex::new(Vec::new()),
94        }))
95    }
96}
97
98struct Instance {
99    store: Store<HostState>,
100    bindings: TransformComponent,
101}
102
103/// A loaded wasm transform. `run` is the hot per-batch path; instances are pooled and reused
104/// (checked out without holding the lock during the guest call, so partitions run in parallel).
105pub struct WasmCompute {
106    manifest: TransformManifest,
107    engine: Engine,
108    component: Component,
109    linker: Linker<HostState>,
110    pool: Mutex<Vec<Instance>>,
111}
112
113impl WasmCompute {
114    fn instantiate(&self) -> Result<Instance, ComputeError> {
115        let wasi = WasiCtxBuilder::new().build();
116        let mut store = Store::new(
117            &self.engine,
118            HostState {
119                table: ResourceTable::new(),
120                wasi,
121            },
122        );
123        let bindings = TransformComponent::instantiate(&mut store, &self.component, &self.linker).map_err(|e| {
124            ComputeError::Load {
125                id: self.manifest.id.clone(),
126                msg: e.to_string(),
127            }
128        })?;
129        Ok(Instance { store, bindings })
130    }
131
132    fn checkout(&self) -> Result<Instance, ComputeError> {
133        if let Some(inst) = self.pool.lock().unwrap().pop() {
134            return Ok(inst);
135        }
136        self.instantiate()
137    }
138
139    fn checkin(&self, inst: Instance) {
140        self.pool.lock().unwrap().push(inst);
141    }
142
143    /// The declared output schema must be produced exactly (names + base types) — fail closed.
144    fn check_output(&self, out: &RecordBatch) -> Result<(), ComputeError> {
145        let expected = self.manifest.output.to_arrow_schema();
146        let got = out.schema();
147        let mismatch = expected.fields().len() != got.fields().len()
148            || expected
149                .fields()
150                .iter()
151                .zip(got.fields().iter())
152                .any(|(e, g)| e.name() != g.name() || e.data_type() != g.data_type());
153        if mismatch {
154            return Err(ComputeError::Schema {
155                id: self.manifest.id.clone(),
156                msg: format!("output schema {:?} != declared {:?}", got, expected),
157            });
158        }
159        Ok(())
160    }
161}
162
163impl Compute for WasmCompute {
164    fn manifest(&self) -> &TransformManifest {
165        &self.manifest
166    }
167
168    fn run(&self, inputs: &[RecordBatch]) -> Result<RecordBatch, ComputeError> {
169        let id = &self.manifest.id;
170        // Enforce the declared input arity (when the manifest declares inputs).
171        if !self.manifest.inputs.is_empty() && inputs.len() != self.manifest.inputs.len() {
172            return Err(ComputeError::Schema {
173                id: id.clone(),
174                msg: format!("expected {} input(s), got {}", self.manifest.inputs.len(), inputs.len()),
175            });
176        }
177        let wit_inputs: Vec<wit::Batch> = inputs
178            .iter()
179            .map(|rb| convert::record_batch_to_wit(id, rb))
180            .collect::<Result<_, _>>()?;
181
182        let mut inst = self.checkout()?;
183        let call = inst
184            .bindings
185            .fv_compute_transform()
186            .call_run(&mut inst.store, &wit_inputs);
187        // Return the instance to the pool before handling the result (even on guest error the
188        // instance is reusable; a trap is rare and we simply don't re-pool it).
189        let result = match call {
190            Ok(inner) => {
191                self.checkin(inst);
192                inner
193            }
194            Err(trap) => {
195                return Err(ComputeError::Run {
196                    id: id.clone(),
197                    msg: format!("wasm trap: {trap:#}"),
198                });
199            }
200        };
201        let out_batch = result.map_err(|e| ComputeError::Run { id: id.clone(), msg: e })?;
202        let out = convert::wit_to_record_batch(id, &out_batch)?;
203        self.check_output(&out)?;
204        Ok(out)
205    }
206}