spacedb_query/runtime.rs
1//! The deterministic, sandboxed WASM runtime that runs a function next to the data.
2//!
3//! Two rules make a result corroboratable:
4//!
5//! 1. **No ambient nondeterminism.** The module gets **no WASI** — no clock,
6//! randomness, network, or filesystem. Its only input is the bytes we hand it;
7//! its only output is the bytes it returns. So `f(input)` is pure: same module
8//! + input ⇒ same output, fuel, and peak memory on any host.
9//! 2. **Bounded by fuel + memory, never by the wall clock.** Fuel is a
10//! deterministic instruction count, so every honest host either completes
11//! within the same budget or traps at the same point. A wall-clock timeout
12//! would make *completion itself* device-dependent and break corroboration.
13//!
14//! ## The function ABI (host ⇄ guest)
15//!
16//! A function module exports:
17//! - `memory` — its linear memory,
18//! - `alloc(len: i32) -> i32` — a guest allocator returning a writable offset,
19//! - `run(in_ptr: i32, in_len: i32) -> i64` — the entry point; the `i64` packs the
20//! output slice as `(out_ptr as u32) << 32 | (out_len as u32)`.
21//!
22//! No host imports are required — which is exactly what keeps a function
23//! deterministic and safe to run on a volunteer device.
24
25use std::collections::HashMap;
26use std::sync::Mutex;
27
28use wasmtime::{
29 Config, Engine, Instance, Linker, Module, Store, StoreLimits, StoreLimitsBuilder, TypedFunc,
30};
31
32use crate::corroborate::FunctionRun;
33use crate::error::{QueryError, QueryResult};
34use crate::functions::CtxHostState;
35
36/// Per-invocation bounds. Both are **deterministic** — fuel is an instruction
37/// count; the memory cap is in whole MB — so they bound execution identically on
38/// every host.
39#[derive(Clone, Copy, Debug, PartialEq, Eq)]
40pub struct RunLimits {
41 pub max_fuel: u64,
42 pub max_mem_mb: u32,
43}
44
45impl Default for RunLimits {
46 fn default() -> Self {
47 Self {
48 max_fuel: 100_000_000,
49 max_mem_mb: 64,
50 }
51 }
52}
53
54/// One execution: the answer the function produced, and the attestation proving it.
55#[derive(Clone, Debug)]
56pub struct Execution {
57 /// The output bytes — the answer that travels back.
58 pub output: Vec<u8>,
59 /// The deterministic, content-addressed attestation.
60 pub run: FunctionRun,
61}
62
63/// Store data — holds the memory limiter the engine consults on every
64/// `memory.grow`.
65struct HostState {
66 limits: StoreLimits,
67}
68
69/// How many compiled modules a runtime keeps. A query touches two (map and
70/// reduce) and a node serves a handful of deployed functions; past this the
71/// cache is simply cleared, so it can never grow without bound.
72const MODULE_CACHE_CAP: usize = 64;
73
74/// A reusable compute-to-data engine. Construct once per host; [`run`](Self::run)
75/// is stateless apart from a compile cache keyed by the workload hash.
76pub struct FunctionRuntime {
77 engine: Engine,
78 /// Compiled modules by BLAKE3 of their bytes — the workload identity every
79 /// run already computes. A map-reduce runs the same two modules once per
80 /// shard and once per reduce step; compiling them each time was the whole
81 /// cost of the query (cranelift dwarfs the guest's work). `Module` is a
82 /// cheap `Arc` handle, and compilation is a pure function of the bytes and
83 /// the engine config, so a cached module is indistinguishable from a fresh one.
84 modules: Mutex<HashMap<[u8; 32], Module>>,
85 /// The Database-Function linker (`spacedb::host_call`), built once: it
86 /// depends only on the engine, and a run instantiates from it.
87 ctx_linker: Linker<CtxHostState>,
88}
89
90impl FunctionRuntime {
91 /// The shared wasmtime engine (fuel-metered, backtrace-free) — reused by the
92 /// Database-Function path in [`crate::functions`].
93 pub(crate) fn engine(&self) -> &Engine {
94 &self.engine
95 }
96
97 /// Construct the runtime. Fails as [`QueryError::Engine`] if wasmtime rejects
98 /// the configuration on this host — a consumer gets an error to handle, not a
99 /// panic.
100 pub fn new() -> QueryResult<Self> {
101 let mut config = Config::new();
102 config.consume_fuel(true);
103 // We only need traps as recoverable errors, not stack traces. Capturing a
104 // wasm backtrace on trap walks native frames, which aborts on Windows with
105 // this slim feature set — and a determinism-bound runtime has no use for it.
106 config.wasm_backtrace(false);
107 let engine = Engine::new(&config).map_err(|e| QueryError::Engine(e.to_string()))?;
108 let ctx_linker = crate::functions::ctx_linker(&engine)?;
109 Ok(Self {
110 engine,
111 modules: Mutex::new(HashMap::new()),
112 ctx_linker,
113 })
114 }
115
116 /// The linker every Database Function instantiates from.
117 pub(crate) fn ctx_linker(&self) -> &Linker<CtxHostState> {
118 &self.ctx_linker
119 }
120
121 /// The compiled module for `module_wasm`, whose hash is `workload_hash`.
122 pub(crate) fn module(
123 &self,
124 workload_hash: &[u8; 32],
125 module_wasm: &[u8],
126 ) -> QueryResult<Module> {
127 let mut modules = self.modules.lock().unwrap_or_else(|p| p.into_inner());
128 if let Some(module) = modules.get(workload_hash) {
129 return Ok(module.clone());
130 }
131 let module = Module::new(&self.engine, module_wasm)
132 .map_err(|e| QueryError::Compile(e.to_string()))?;
133 if modules.len() >= MODULE_CACHE_CAP {
134 modules.clear();
135 }
136 modules.insert(*workload_hash, module.clone());
137 Ok(module)
138 }
139
140 /// Run `module_wasm`'s `run` entry over `input` under `limits`, returning the
141 /// output and its verifiable [`FunctionRun`]. `module_wasm` is the deployed
142 /// `.wasm` (hashed as the workload identity).
143 pub fn run(
144 &self,
145 module_wasm: &[u8],
146 input: &[u8],
147 limits: &RunLimits,
148 ) -> QueryResult<Execution> {
149 self.run_prehashed(&hash(module_wasm), module_wasm, input, None, limits)
150 }
151
152 /// [`run`](Self::run) with the module's hash already known (a planner hashes
153 /// each module once per query, not once per shard) and, when the caller has
154 /// it, the input's digest too (a pinned snapshot carries its own). The
155 /// attestation is identical: these are the same values `run` computes.
156 pub fn run_prehashed(
157 &self,
158 workload_hash: &[u8; 32],
159 module_wasm: &[u8],
160 input: &[u8],
161 input_digest: Option<[u8; 32]>,
162 limits: &RunLimits,
163 ) -> QueryResult<Execution> {
164 let workload_hash = *workload_hash;
165 let input_digest = input_digest.unwrap_or_else(|| hash(input));
166
167 let module = self.module(&workload_hash, module_wasm)?;
168
169 let max_bytes = limits.max_mem_mb as usize * 1024 * 1024;
170 let mut store = Store::new(
171 &self.engine,
172 HostState {
173 limits: StoreLimitsBuilder::new().memory_size(max_bytes).build(),
174 },
175 );
176 store.limiter(|h| &mut h.limits);
177 store
178 .set_fuel(limits.max_fuel)
179 .map_err(|e| QueryError::Fuel(e.to_string()))?;
180
181 let instance = Instance::new(&mut store, &module, &[])
182 .map_err(|e| QueryError::Instantiate(e.to_string()))?;
183
184 let memory = instance
185 .get_memory(&mut store, "memory")
186 .ok_or(QueryError::MissingExport("memory"))?;
187 let alloc: TypedFunc<i32, i32> = instance
188 .get_typed_func(&mut store, "alloc")
189 .map_err(|_| QueryError::MissingExport("alloc"))?;
190 let run: TypedFunc<(i32, i32), i64> = instance
191 .get_typed_func(&mut store, "run")
192 .map_err(|_| QueryError::MissingExport("run"))?;
193
194 // alloc + write the input
195 let in_len =
196 i32::try_from(input.len()).map_err(|_| QueryError::Abi("input too large".into()))?;
197 let in_ptr = alloc
198 .call(&mut store, in_len)
199 .map_err(|e| QueryError::Trap(e.to_string()))?;
200 memory
201 .write(&mut store, in_ptr as usize, input)
202 .map_err(|e| QueryError::Abi(format!("input write: {e}")))?;
203
204 // run, then read the returned (out_ptr, out_len) slice
205 let packed = run
206 .call(&mut store, (in_ptr, in_len))
207 .map_err(|e| QueryError::Trap(e.to_string()))?;
208 let packed = packed as u64;
209 let out_ptr = (packed >> 32) as usize;
210 let out_len = (packed & 0xFFFF_FFFF) as usize;
211 let output = crate::functions::read_output(memory.data(&store), out_ptr, out_len)?;
212 let output_digest = hash(&output);
213
214 // fuel consumed = budget − remaining; peak ≈ final size (functions don't
215 // shrink memory within a single run)
216 let remaining = store.get_fuel().map_err(|e| QueryError::Fuel(e.to_string()))?;
217 let fuel_used = limits.max_fuel.saturating_sub(remaining);
218 let mem_peak_mb = (memory.data_size(&store) / (1024 * 1024)) as u32;
219
220 Ok(Execution {
221 output,
222 run: FunctionRun {
223 workload_hash,
224 input_digest,
225 output_digest,
226 fuel_used,
227 mem_peak_mb,
228 },
229 })
230 }
231}
232
233fn hash(bytes: &[u8]) -> [u8; 32] {
234 *blake3::hash(bytes).as_bytes()
235}