Skip to main content

graphrt_wasm/
host.rs

1//! Guest execution on the wasmi interpreter.
2//!
3//! A module is validated and compiled once. Every call gets a fresh `Store`
4//! and instance, so guests cannot keep state between runs and one run cannot
5//! observe another.
6
7use std::fmt;
8
9use graphrt_core::node::NodeContext;
10use graphrt_core::value::Value;
11
12use wasmi::{
13    Caller, Config, EnforcedLimits, Engine, Extern, Linker, Module, Store, StoreLimits, StoreLimitsBuilder, TrapCode,
14};
15
16use crate::abi::{ABI_VERSION, HOST_MODULE, unpack};
17use crate::error::WasmError;
18use crate::limits::WasmLimits;
19
20/// One log line written by a guest.
21#[derive(Clone, Debug, PartialEq, Eq)]
22pub struct LogLine {
23    pub level: u8,
24    pub message: String,
25}
26
27/// Per-call host state stored in the wasmi `Store`.
28pub(crate) struct HostState {
29    limits: StoreLimits,
30    ctx: Option<NodeContext>,
31    message_bytes: usize,
32    max_logs: usize,
33    logs: Vec<LogLine>,
34    dropped_logs: usize,
35    max_events: usize,
36    events: usize,
37    max_stream_bytes: usize,
38    stream_bytes: usize,
39}
40
41/// Fixed fuel charged for every host call, on top of one unit per byte copied.
42/// Host work is otherwise invisible to the fuel meter, so without this a guest
43/// could make the host copy unbounded data within its fuel budget.
44pub(crate) const HOST_CALL_FUEL: u64 = 1_000;
45
46/// Raised from host functions to abort the guest with a precise error.
47#[derive(Debug)]
48struct HostTrap(WasmError);
49
50impl fmt::Display for HostTrap {
51    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
52        self.0.fmt(f)
53    }
54}
55
56impl wasmi::errors::HostError for HostTrap {}
57
58/// Which guest entry point to call.
59pub(crate) enum Call<'a> {
60    Describe,
61    Run(&'a [u8]),
62}
63
64/// Output of a guest call.
65pub(crate) struct CallOutput {
66    pub bytes: Vec<u8>,
67    pub logs: Vec<LogLine>,
68    pub dropped_logs: usize,
69}
70
71/// A validated, compiled module plus its import linker.
72pub(crate) struct Compiled {
73    engine: Engine,
74    module: Module,
75    linker: Linker<HostState>,
76    limits: WasmLimits,
77}
78
79impl fmt::Debug for Compiled {
80    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
81        f.debug_struct("Compiled").field("limits", &self.limits).finish_non_exhaustive()
82    }
83}
84
85impl Compiled {
86    /// Validate and compile `bytes`.
87    pub(crate) fn new(bytes: &[u8], limits: WasmLimits) -> Result<Self, WasmError> {
88        if bytes.len() > limits.module_bytes {
89            return Err(WasmError::ModuleTooLarge { size: bytes.len(), limit: limits.module_bytes });
90        }
91        let mut config = Config::default();
92        config
93            .consume_fuel(true)
94            .enforced_limits(EnforcedLimits::strict())
95            .set_max_recursion_depth(limits.max_recursion_depth);
96        let engine = Engine::new(&config);
97        let module = Module::new(&engine, bytes).map_err(|e| WasmError::InvalidModule(e.to_string()))?;
98        for import in module.imports() {
99            if import.module() != HOST_MODULE || !matches!(import.name(), "log" | "chunk" | "progress") {
100                return Err(WasmError::InvalidModule(format!(
101                    "unsupported import `{}::{}` (only `{HOST_MODULE}::log|chunk|progress` are provided)",
102                    import.module(),
103                    import.name()
104                )));
105            }
106        }
107        let linker = build_linker(&engine)?;
108        Ok(Self { engine, module, linker, limits })
109    }
110
111    pub(crate) fn limits(&self) -> &WasmLimits {
112        &self.limits
113    }
114
115    /// Instantiate a fresh copy of the module and call one entry point.
116    pub(crate) fn call(&self, call: Call<'_>, ctx: Option<NodeContext>) -> Result<CallOutput, WasmError> {
117        self.call_logged(call, ctx).map_err(|f| f.error)
118    }
119
120    /// Like [`Compiled::call`], but a failure keeps the log lines the guest wrote
121    /// before it failed: those usually explain the failure.
122    pub(crate) fn call_logged(&self, call: Call<'_>, ctx: Option<NodeContext>) -> Result<CallOutput, CallFailure> {
123        let mut store = self.new_store(ctx).map_err(|error| CallFailure { error, logs: Vec::new() })?;
124        match self.call_in(&mut store, call) {
125            Ok(bytes) => {
126                let state = store.into_data();
127                Ok(CallOutput { bytes, logs: state.logs, dropped_logs: state.dropped_logs })
128            }
129            Err(error) => Err(CallFailure { error, logs: store.into_data().logs }),
130        }
131    }
132
133    fn new_store(&self, ctx: Option<NodeContext>) -> Result<Store<HostState>, WasmError> {
134        let limits = &self.limits;
135        let state = HostState {
136            limits: StoreLimitsBuilder::new()
137                .memory_size(limits.memory_bytes)
138                .memories(1)
139                // Tables live outside linear memory; keep them small so they do not
140                // add tens of MB per instance on top of `memory_bytes`.
141                .tables(4)
142                .table_elements(100_000)
143                .instances(1)
144                .trap_on_grow_failure(true)
145                .build(),
146            ctx,
147            message_bytes: limits.message_bytes,
148            max_logs: limits.max_logs,
149            logs: Vec::new(),
150            dropped_logs: 0,
151            max_events: limits.max_events,
152            events: 0,
153            max_stream_bytes: limits.max_stream_bytes,
154            stream_bytes: 0,
155        };
156        let mut store = Store::new(&self.engine, state);
157        store.limiter(|s| &mut s.limits);
158        store.set_fuel(limits.fuel).map_err(|e| WasmError::Internal(e.to_string()))?;
159        Ok(store)
160    }
161
162    /// Run one entry point in `store`, returning the response bytes.
163    fn call_in(&self, store: &mut Store<HostState>, call: Call<'_>) -> Result<Vec<u8>, WasmError> {
164        let limits = &self.limits;
165        let mut store = store;
166        let instance = self.linker.instantiate_and_start(&mut store, &self.module).map_err(|e| match map_trap(&e) {
167            Some(err) => err,
168            None => WasmError::Instantiate(e.to_string()),
169        })?;
170
171        let version = instance
172            .get_typed_func::<(), i32>(&store, "graphrt_abi_version")
173            .map_err(|_| WasmError::MissingExport("graphrt_abi_version: () -> i32".into()))?
174            .call(&mut store, ())
175            .map_err(|e| call_error(&e))?;
176        if version != ABI_VERSION {
177            return Err(WasmError::AbiVersion { found: version, supported: ABI_VERSION });
178        }
179        let memory = instance.get_memory(&store, "memory").ok_or_else(|| WasmError::MissingExport("memory".into()))?;
180
181        let packed = match call {
182            Call::Describe => instance
183                .get_typed_func::<(), i64>(&store, "graphrt_describe")
184                .map_err(|_| WasmError::MissingExport("graphrt_describe: () -> i64".into()))?
185                .call(&mut store, ())
186                .map_err(|e| call_error(&e))?,
187            Call::Run(input) => {
188                if input.len() > limits.input_bytes {
189                    return Err(WasmError::TooLarge { what: "request", size: input.len(), limit: limits.input_bytes });
190                }
191                let len = i32::try_from(input.len()).map_err(|_| WasmError::TooLarge {
192                    what: "request",
193                    size: input.len(),
194                    limit: limits.input_bytes,
195                })?;
196                let ptr = instance
197                    .get_typed_func::<i32, i32>(&store, "graphrt_alloc")
198                    .map_err(|_| WasmError::MissingExport("graphrt_alloc: (i32) -> i32".into()))?
199                    .call(&mut store, len)
200                    .map_err(|e| call_error(&e))?;
201                let offset = usize::try_from(as_u32(ptr)).map_err(|e| WasmError::Internal(e.to_string()))?;
202                memory
203                    .write(&mut store, offset, input)
204                    .map_err(|_| WasmError::OutOfBounds { ptr: as_u32(ptr), len: as_u32(len) })?;
205                instance
206                    .get_typed_func::<(i32, i32), i64>(&store, "graphrt_run")
207                    .map_err(|_| WasmError::MissingExport("graphrt_run: (i32, i32) -> i64".into()))?
208                    .call(&mut store, (ptr, len))
209                    .map_err(|e| call_error(&e))?
210            }
211        };
212
213        let (ptr, len) = unpack(packed);
214        let len_usize = usize::try_from(len).map_err(|e| WasmError::Internal(e.to_string()))?;
215        if len_usize > limits.output_bytes {
216            return Err(WasmError::TooLarge { what: "response", size: len_usize, limit: limits.output_bytes });
217        }
218        let start = usize::try_from(ptr).map_err(|e| WasmError::Internal(e.to_string()))?;
219        let bytes = start
220            .checked_add(len_usize)
221            .and_then(|end| memory.data(&store).get(start..end))
222            .ok_or(WasmError::OutOfBounds { ptr, len })?
223            .to_vec();
224        Ok(bytes)
225    }
226}
227
228/// A failed guest call with the log lines written before the failure.
229pub(crate) struct CallFailure {
230    pub error: WasmError,
231    pub logs: Vec<LogLine>,
232}
233
234fn as_u32(v: i32) -> u32 {
235    u32::from_ne_bytes(v.to_ne_bytes())
236}
237
238/// Convert a trap raised while calling the guest.
239fn call_error(e: &wasmi::Error) -> WasmError {
240    map_trap(e).unwrap_or_else(|| WasmError::Trap(e.to_string()))
241}
242
243fn map_trap(e: &wasmi::Error) -> Option<WasmError> {
244    if let Some(HostTrap(inner)) = e.downcast_ref::<HostTrap>() {
245        return Some(inner.clone());
246    }
247    match e.as_trap_code()? {
248        TrapCode::OutOfFuel => Some(WasmError::FuelExhausted),
249        TrapCode::GrowthOperationLimited => Some(WasmError::MemoryLimit),
250        other => Some(WasmError::Trap(other.to_string())),
251    }
252}
253
254fn host_trap(err: WasmError) -> wasmi::Error {
255    wasmi::Error::host(HostTrap(err))
256}
257
258/// Copy `len` bytes at `ptr` out of the caller's memory.
259fn read_guest(caller: &Caller<'_, HostState>, ptr: i32, len: i32, what: &'static str) -> Result<Vec<u8>, wasmi::Error> {
260    let (ptr, len) = (as_u32(ptr), as_u32(len));
261    let limit = caller.data().message_bytes;
262    let size = usize::try_from(len).map_err(|e| host_trap(WasmError::Internal(e.to_string())))?;
263    if size > limit {
264        return Err(host_trap(WasmError::TooLarge { what, size, limit }));
265    }
266    let memory = caller
267        .get_export("memory")
268        .and_then(Extern::into_memory)
269        .ok_or_else(|| host_trap(WasmError::MissingExport("memory".into())))?;
270    let start = usize::try_from(ptr).map_err(|e| host_trap(WasmError::Internal(e.to_string())))?;
271    start
272        .checked_add(size)
273        .and_then(|end| memory.data(caller).get(start..end))
274        .map(<[u8]>::to_vec)
275        .ok_or_else(|| host_trap(WasmError::OutOfBounds { ptr, len }))
276}
277
278fn read_text(caller: &Caller<'_, HostState>, ptr: i32, len: i32, what: &'static str) -> Result<String, wasmi::Error> {
279    let bytes = read_guest(caller, ptr, len, what)?;
280    String::from_utf8(bytes).map_err(|_| host_trap(WasmError::InvalidOutput(format!("{what} is not valid UTF-8"))))
281}
282
283/// Charge the guest for host work: a fixed cost plus one unit per byte.
284fn charge(caller: &mut Caller<'_, HostState>, bytes: u64) -> Result<(), wasmi::Error> {
285    let cost = HOST_CALL_FUEL.saturating_add(bytes);
286    let fuel = caller.get_fuel().map_err(|e| host_trap(WasmError::Internal(e.to_string())))?;
287    if fuel < cost {
288        return Err(host_trap(WasmError::FuelExhausted));
289    }
290    caller.set_fuel(fuel - cost).map_err(|e| host_trap(WasmError::Internal(e.to_string())))
291}
292
293/// Reserve one streamed event of `bytes` bytes against the per-call caps.
294fn reserve_event(caller: &mut Caller<'_, HostState>, bytes: u64) -> Result<(), wasmi::Error> {
295    let state = caller.data_mut();
296    if state.events >= state.max_events {
297        return Err(host_trap(WasmError::TooLarge {
298            what: "streamed events",
299            size: state.events.saturating_add(1),
300            limit: state.max_events,
301        }));
302    }
303    let total = state.stream_bytes.saturating_add(usize::try_from(bytes).unwrap_or(usize::MAX));
304    if total > state.max_stream_bytes {
305        return Err(host_trap(WasmError::TooLarge {
306            what: "streamed bytes",
307            size: total,
308            limit: state.max_stream_bytes,
309        }));
310    }
311    state.events += 1;
312    state.stream_bytes = total;
313    Ok(())
314}
315
316fn len_of(len: i32) -> u64 {
317    u64::from(as_u32(len))
318}
319
320fn build_linker(engine: &Engine) -> Result<Linker<HostState>, WasmError> {
321    let link_err = |e: wasmi::errors::LinkerError| WasmError::Internal(e.to_string());
322    let mut linker = Linker::<HostState>::new(engine);
323    linker
324        .func_wrap(HOST_MODULE, "log", |mut caller: Caller<'_, HostState>, level: i32, ptr: i32, len: i32| {
325            // Decide before copying anything, so dropped lines stay cheap.
326            let full = {
327                let state = caller.data();
328                state.logs.len() >= state.max_logs
329            };
330            if full {
331                charge(&mut caller, 0)?;
332                let state = caller.data_mut();
333                state.dropped_logs = state.dropped_logs.saturating_add(1);
334                return Ok(());
335            }
336            charge(&mut caller, len_of(len))?;
337            let message = read_text(&caller, ptr, len, "log line")?;
338            let level = u8::try_from(level.clamp(0, 4)).unwrap_or(2);
339            caller.data_mut().logs.push(LogLine { level, message });
340            Ok(())
341        })
342        .map_err(link_err)?;
343    linker
344        .func_wrap(
345            HOST_MODULE,
346            "chunk",
347            |mut caller: Caller<'_, HostState>, field_ptr: i32, field_len: i32, ptr: i32, len: i32| {
348                let bytes = len_of(field_len).saturating_add(len_of(len));
349                charge(&mut caller, bytes)?;
350                reserve_event(&mut caller, bytes)?;
351                let field = read_text(&caller, field_ptr, field_len, "chunk field")?;
352                let text = read_text(&caller, ptr, len, "chunk")?;
353                if let Some(ctx) = &caller.data().ctx {
354                    ctx.chunk(&field, text);
355                }
356                Ok(())
357            },
358        )
359        .map_err(link_err)?;
360    linker
361        .func_wrap(
362            HOST_MODULE,
363            "progress",
364            |mut caller: Caller<'_, HostState>, name_ptr: i32, name_len: i32, ptr: i32, len: i32| {
365                let bytes = len_of(name_len).saturating_add(len_of(len));
366                charge(&mut caller, bytes)?;
367                reserve_event(&mut caller, bytes)?;
368                let name = read_text(&caller, name_ptr, name_len, "progress name")?;
369                let payload = read_text(&caller, ptr, len, "progress payload")?;
370                let data = match serde_json::from_str::<serde_json::Value>(&payload) {
371                    Ok(json) => Value::from_json(json),
372                    Err(_) => Value::from(payload),
373                };
374                if let Some(ctx) = &caller.data().ctx {
375                    ctx.progress(&name, data);
376                }
377                Ok(())
378            },
379        )
380        .map_err(link_err)?;
381    Ok(linker)
382}