Oregami
Repositories/oxedyne/fe2o3

oxedyne/fe2o3/fe2o3_austenite/src/eval/plugin.rs

15.1 KiB, 1 run

created by r1870400018:73459, which is this file's identity for as long as the history lasts, whatever it is later renamed to

download · who wrote it · its history

1//! WebAssembly plugins, as Typst 0.15.1 runs them (`typst-library` `foundations/plugin.rs`), through the same
2//! interpreter at the same pin: wasmi 1.0.9, relaxed SIMD off, so a plugin's answer is the one Typst gets.
3//!
4//! The protocol is `wasm_minimal_protocol`: a module imports at most the two `typst_env` host functions,
5//! exports its `memory`, and every exported function becomes a member of the module `plugin()` returns.
6//! Each argument is bytes, its length is what the function receives, and it fetches the bytes with
7//! `wasm_minimal_protocol_write_args_to_buffer`. It hands its result back with
8//! `wasm_minimal_protocol_send_result_to_host` and returns 0 for success or 1 for an error whose message is
9//! the result. The messages below are Typst's, word for word.
10//!
11//! Typst sets no limit on a plugin. Austenite runs untrusted modules in a browser tab and a compile server,
12//! so it adds three, each counted rather than timed so a document's outcome never depends on the machine:
13//! fuel (`FUEL` by default, for a load and again for each call; `Engine::plugin_fuel` may set another), a ceiling on
14//! linear memory (`MEMORY`), and wasmi's own recursion limit. Both limits hold while the module loads as well
15//! as on a call, because loading runs the module's `start` function and allocates its declared memory.
16
17use crate::eval::scope::Scope;
18use crate::eval::value::{
19 Module,
20 Value,
21};
22use crate::eval::func::Func;
23
24use oxedyne_fe2o3_core::prelude::*;
25use oxedyne_fe2o3_hash::fingerprint::Fingerprint;
26use oxedyne_fe2o3_hash::fingerprint::Fingerprinter;
27
28use std::fmt;
29use std::sync::{
30 Arc,
31 Mutex,
32};
33
34use wasmi_core::LimiterError;
35
36// Limits
37// The default fuel for a load or a call, `Engine::plugin_fuel`. Typst sets none, so a document Typst compiles
38// must never meet it: the most the corpus spends is 84,908,412,112, by jogs 0.2.4's `call_function`
39// (classy-german-invoice, german-fx-invoice; ctxjs 0.5.0's `new_context` in starchy-junia spends
40// 4,204,020,394), most of it charged for bulk memory copies, so that call takes about a second. This allows
41// 11.8 times that. A plain loop spends it in 1,577 s natively (release, 2026-10-12), about 26 minutes, so
42// the bound that stops a hostile module sooner is the host's.
43pub const FUEL: u64 = 1_000_000_000_000;
44#[cfg(not(target_arch = "wasm32"))]
45pub const MEMORY: usize = 1 << 30; // bytes of linear memory an instance may hold
46#[cfg(target_arch = "wasm32")]
47pub const MEMORY: usize = 256 << 20; // inside the tab's own linear memory, so lower
48const TABLE_ELEMS: usize = 1 << 20;
49const MAX_TABLES: usize = 8;
50
51const ENV: &str = "typst_env";
52const WRITE_ARGS: &str = "wasm_minimal_protocol_write_args_to_buffer";
53const SEND_RESULT: &str = "wasm_minimal_protocol_send_result_to_host";
54
55/// A loaded module, or one made from another by `plugin.transition`. Instances are pooled: a call takes one,
56/// and gives it back only when the call succeeded, since a failed call may have left it in any state.
57pub struct Plugin {
58 base: Arc<Base>,
59 pool: Mutex<Vec<Instance>>,
60 snapshot: Option<Arc<Snapshot>>, // memory after the transition that made this plugin
61 print: Fingerprint, // the transitions that made it, zero for a module as loaded
62}
63
64struct Base {
65 id: Fingerprint, // of the module's bytes
66 size: usize, // and their length
67 module: wasmi::Module,
68 linker: wasmi::Linker<CallData>,
69}
70
71struct Instance {
72 instance: wasmi::Instance,
73 store: wasmi::Store<CallData>,
74}
75
76struct Snapshot {
77 pages: u64,
78 data: Vec<u8>,
79}
80
81#[derive(Default)]
82struct CallData {
83 args: Vec<Arc<Vec<u8>>>,
84 output: Vec<u8>,
85 fault: Option<Fault>, // a host function's out-of-bounds access, reported after the call
86 cap: Cap,
87}
88
89struct Fault {
90 offset: u32,
91 length: u32,
92 write: bool,
93}
94
95/// The memory and table ceiling. A refused growth traps, so a plugin that asks for more than `MEMORY` stops
96/// with a diagnostic that names the limit rather than limping on with an allocator that failed. wasmi
97/// keeps `LimiterError` out of its public paths, so it is named from `wasmi_core`, at the same pin.
98#[derive(Default)]
99struct Cap {
100 hit: bool,
101}
102
103impl wasmi::ResourceLimiter for Cap {
104 fn memory_growing(&mut self, _current: usize, desired: usize, maximum: Option<usize>)
105 -> std::result::Result<bool, LimiterError>
106 {
107 if desired > MEMORY {
108 self.hit = true;
109 return Err(LimiterError::ResourceLimiterDeniedAllocation);
110 }
111 Ok(maximum.map_or(true, |m| desired <= m))
112 }
113
114 fn table_growing(&mut self, _current: usize, desired: usize, maximum: Option<usize>)
115 -> std::result::Result<bool, LimiterError>
116 {
117 if desired > TABLE_ELEMS {
118 self.hit = true;
119 return Err(LimiterError::ResourceLimiterDeniedAllocation);
120 }
121 Ok(maximum.map_or(true, |m| desired <= m))
122 }
123
124 fn instances(&self) -> usize { 1 }
125 fn tables(&self) -> usize { MAX_TABLES }
126 fn memories(&self) -> usize { 1 }
127}
128
129/// One exported function of a plugin, the value `p.name` is.
130#[derive(Clone)]
131pub struct PluginFunc {
132 plugin: Arc<Plugin>,
133 name: String,
134}
135
136impl PluginFunc {
137 pub fn name(&self) -> &str { &self.name }
138
139 /// What the function is: its module's bytes, the transitions its plugin came through, and its name.
140 pub fn fingerprint(&self) -> Fingerprint {
141 let mut f = Fingerprinter::new();
142 f.write_fingerprint(self.plugin.base.id);
143 f.write_fingerprint(self.plugin.print);
144 f.write_str(&self.name);
145 f.finish()
146 }
147
148 /// Runs the function on `args`, answering its result bytes or Typst's message for the failure.
149 pub fn call(&self, args: Vec<Arc<Vec<u8>>>, fuel: u64) -> Outcome<Vec<u8>> {
150 self.plugin.call(&self.name, args, fuel)
151 }
152
153 /// `plugin.transition(f, ..args)`: a new plugin whose instances start from the memory this call leaves.
154 pub fn transition(&self, args: Vec<Arc<Vec<u8>>>, fuel: u64) -> Outcome<Plugin> {
155 self.plugin.transition(&self.name, args, fuel)
156 }
157}
158
159impl PartialEq for PluginFunc {
160 fn eq(&self, other: &Self) -> bool { self.fingerprint() == other.fingerprint() }
161}
162
163impl fmt::Debug for PluginFunc {
164 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { write!(f, "PluginFunc({})", self.name) }
165}
166
167impl fmt::Debug for Plugin {
168 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { f.pad("Plugin(..)") }
169}
170
171impl Plugin {
172 /// Loads a module from its bytes, as `plugin(source)` does: it must validate and export its memory, and
173 /// one instance is made at once, so a module that cannot start fails here rather than at its first call.
174 pub fn load(bytes: &[u8], fuel: u64) -> Outcome<Self> {
175 let mut config = wasmi::Config::default();
176 config.wasm_relaxed_simd(false); // as Typst: relaxed SIMD may differ between hosts
177 config.consume_fuel(true);
178 let engine = wasmi::Engine::new(&config);
179 let module = match wasmi::Module::new(&engine, bytes) {
180 Ok(m) => m,
181 Err(e) => return Err(err!("failed to load WebAssembly module ({})", e; Input, Invalid)),
182 };
183 if !matches!(module.get_export("memory"), Some(wasmi::ExternType::Memory(_))) {
184 return Err(err!("plugin does not export its memory"; Input, Invalid));
185 }
186 let mut linker = wasmi::Linker::<CallData>::new(&engine);
187 if let Err(e) = linker.func_wrap(ENV, SEND_RESULT, send_result) {
188 return Err(err!("cannot link {}: {}", SEND_RESULT, e; Init));
189 }
190 if let Err(e) = linker.func_wrap(ENV, WRITE_ARGS, write_args) {
191 return Err(err!("cannot link {}: {}", WRITE_ARGS, e; Init));
192 }
193 let base = Arc::new(Base { id: Fingerprint::of(bytes), size: bytes.len(), module, linker });
194 let first = res!(Instance::new(&base, None, fuel));
195 Ok(Self {
196 base,
197 pool: Mutex::new(vec![first]),
198 snapshot: None,
199 print: Fingerprint::from_u128(0),
200 })
201 }
202
203 /// The bytes a memo holding this plugin should count: the module, the snapshot it starts from, and the
204 /// memory of the instances pooled now.
205 pub fn size(&self) -> usize {
206 let held = match self.pool.lock() {
207 Ok(pool) => pool.iter().map(|i| i.memory().map(|m| m.data(&i.store).len()).unwrap_or(0)).sum(),
208 Err(_) => 0,
209 };
210 self.base.size + self.snapshot.as_ref().map_or(0, |s| s.data.len()) + held
211 }
212
213 /// The module `plugin()` returns: every exported function, by name.
214 pub fn into_module(this: Arc<Self>) -> Module {
215 let mut scope = Scope::new();
216 for export in this.base.module.exports() {
217 if matches!(export.ty(), wasmi::ExternType::Func(_)) {
218 let func = PluginFunc { plugin: this.clone(), name: export.name().to_string() };
219 scope.define(export.name(), Value::Func(Func::Plugin(Arc::new(func))));
220 }
221 }
222 Module::new("", scope)
223 }
224
225 fn call(&self, name: &str, args: Vec<Arc<Vec<u8>>>, fuel: u64) -> Outcome<Vec<u8>> {
226 let mut inst = res!(self.acquire(fuel));
227 // A failed instance is dropped, never pooled again.
228 let out = res!(inst.call(name, args, fuel));
229 let mut pool = lock_mutex!(self.pool);
230 pool.push(inst);
231 Ok(out)
232 }
233
234 fn transition(&self, name: &str, args: Vec<Arc<Vec<u8>>>, fuel: u64) -> Outcome<Self> {
235 let mut f = Fingerprinter::new();
236 f.write_fingerprint(self.print);
237 f.write_str(name);
238 f.write_usize(args.len());
239 for a in &args {
240 f.write_usize(a.len());
241 f.write_fingerprint(Fingerprint::of(a));
242 }
243 let print = f.finish();
244 let mut inst = res!(self.acquire(fuel));
245 res!(inst.call(name, args, fuel));
246 let snapshot = Arc::new(res!(inst.snapshot()));
247 // The instance that made the change moves into the new plugin, so the old one never sees it.
248 Ok(Self {
249 base: self.base.clone(),
250 pool: Mutex::new(vec![inst]),
251 snapshot: Some(snapshot),
252 print,
253 })
254 }
255
256 fn acquire(&self, fuel: u64) -> Outcome<Instance> {
257 let held = {
258 let mut pool = lock_mutex!(self.pool);
259 pool.pop()
260 };
261 match held {
262 Some(i) => Ok(i),
263 None => Instance::new(&self.base, self.snapshot.as_deref(), fuel),
264 }
265 }
266}
267
268impl Instance {
269 fn new(base: &Base, snapshot: Option<&Snapshot>, fuel: u64) -> Outcome<Self> {
270 let mut store = wasmi::Store::new(base.linker.engine(), CallData::default());
271 store.limiter(|d: &mut CallData| &mut d.cap as &mut dyn wasmi::ResourceLimiter);
272 // The fuel is set before the start function runs, so a module that loops in `start` stops too.
273 if let Err(e) = store.set_fuel(fuel) {
274 return Err(err!("cannot fuel the plugin's store: {}", e; Init));
275 }
276 let instance = match base.linker.instantiate_and_start(&mut store, &base.module) {
277 Ok(i) => i,
278 Err(e) => return Err(limit_or(&store, &e, fmt!("{}", e), fuel)),
279 };
280 let mut out = Self { instance, store };
281 if let Some(s) = snapshot {
282 res!(out.restore(s));
283 }
284 Ok(out)
285 }
286
287 fn memory(&self) -> Outcome<wasmi::Memory> {
288 match self.instance.get_memory(&self.store, "memory") {
289 Some(m) => Ok(m),
290 None => Err(err!("plugin does not export its memory"; Input, Invalid)),
291 }
292 }
293
294 fn call(&mut self, name: &str, args: Vec<Arc<Vec<u8>>>, fuel: u64) -> Outcome<Vec<u8>> {
295 let handle = match self.instance.get_func(&self.store, name) {
296 Some(f) => f,
297 None => return Err(err!("plugin has no function `{}`", name; Input, Invalid)),
298 };
299 let ty = handle.ty(&self.store);
300 // The signature is checked at the call, not at the load, since a module may export functions such
301 // as `_initialize` that do not follow the protocol.
302 if ty.params().iter().any(|v| *v != wasmi::ValType::I32) {
303 return Err(err!("plugin function `{}` has a parameter that is not a 32-bit integer", name;
304 Input, Invalid));
305 }
306 if ty.results() != [wasmi::ValType::I32] {
307 return Err(err!("plugin function `{}` does not return exactly one 32-bit integer", name;
308 Input, Invalid));
309 }
310 let expected = ty.params().len();
311 let given = args.len();
312 if expected != given {
313 return Err(err!("plugin function takes {} argument{}, but {} {} given",
314 expected, if expected == 1 { "" } else { "s" },
315 given, if given == 1 { "was" } else { "were" }; Input, Invalid));
316 }
317 let lengths: Vec<wasmi::Val> = args.iter().map(|a| wasmi::Val::I32(a.len() as i32)).collect();
318 {
319 let data = self.store.data_mut();
320 data.args = args;
321 data.output = Vec::new();
322 data.fault = None;
323 }
324 if let Err(e) = self.store.set_fuel(fuel) {
325 return Err(err!("cannot fuel the plugin's store: {}", e; Init));
326 }
327 let mut code = [wasmi::Val::I32(-1)];
328 if let Err(e) = handle.call(&mut self.store, &lengths, &mut code) {
329 return Err(limit_or(&self.store, &e, fmt!("plugin panicked: {}", e), fuel));
330 }
331 let data = self.store.data_mut();
332 if let Some(Fault { offset, length, write }) = data.fault.take() {
333 let kind = if write { "write" } else { "read" };
334 return Err(err!("plugin tried to {} out of bounds: pointer {:#x} is out of bounds for {} of length {}",
335 kind, offset, kind, length; Input, Invalid));
336 }
337 let output = std::mem::take(&mut data.output);
338 match code[0] {
339 wasmi::Val::I32(0) => Ok(output),
340 wasmi::Val::I32(1) => match std::str::from_utf8(&output) {
341 Ok(m) => Err(err!("plugin errored with: {}", m; Input, Invalid)),
342 Err(_) => Err(err!("plugin errored, but did not return a valid error message"; Input, Invalid)),
343 },
344 _ => Err(err!("plugin did not respect the protocol"; Input, Invalid)),
345 }
346 }
347
348 fn snapshot(&self) -> Outcome<Snapshot> {
349 let mem = res!(self.memory());
350 Ok(Snapshot { pages: mem.size(&self.store), data: mem.data(&self.store).to_vec() })
351 }
352
353 fn restore(&mut self, s: &Snapshot) -> Outcome<()> {
354 let mem = res!(self.memory());
355 let now = mem.size(&self.store);
356 if now < s.pages {
357 if let Err(e) = mem.grow(&mut self.store, s.pages - now) {
358 return Err(err!("cannot restore the plugin's memory: {}", e; LimitReached));
359 }
360 }
361 let data = mem.data_mut(&mut self.store);
362 match data.get_mut(..s.data.len()) {
363 Some(d) => { d.copy_from_slice(&s.data); Ok(()) }
364 None => Err(err!("cannot restore the plugin's memory: {} bytes into {}", s.data.len(), data.len();
365 Bug)),
366 }
367 }
368}
369
370// A failure that one of Austenite's limits caused is named as such; any other keeps the message given.
371fn limit_or(store: &wasmi::Store<CallData>, e: &wasmi::Error, msg: String, fuel: u64) -> Error<ErrTag> {
372 if e.as_trap_code() == Some(wasmi::TrapCode::OutOfFuel) {
373 return err!("plugin exceeded its fuel of {} instructions, so it was stopped (does it loop forever?)",
374 fuel; LimitReached);
375 }
376 if store.data().cap.hit {
377 return err!("plugin exceeded its memory limit of {} MiB", MEMORY >> 20; LimitReached);
378 }
379 err!("{}", msg; Input, Invalid)
380}
381
382fn write_args(mut caller: wasmi::Caller<'_, CallData>, ptr: u32) {
383 let mem = match caller.get_export("memory").and_then(|e| e.into_memory()) {
384 Some(m) => m,
385 None => return,
386 };
387 let args = std::mem::take(&mut caller.data_mut().args);
388 let mut at = ptr as usize;
389 for a in args {
390 if mem.write(&mut caller, at, a.as_slice()).is_err() {
391 caller.data_mut().fault = Some(Fault { offset: at as u32, length: a.len() as u32, write: true });
392 return;
393 }
394 at += a.len();
395 }
396}
397
398fn send_result(mut caller: wasmi::Caller<'_, CallData>, ptr: u32, len: u32) {
399 let mem = match caller.get_export("memory").and_then(|e| e.into_memory()) {
400 Some(m) => m,
401 None => return,
402 };
403 // The bytes are read where they lie, so a length past the memory allocates nothing on the host.
404 let (lo, hi) = (ptr as usize, ptr as usize + len as usize);
405 let got = mem.data(&caller).get(lo..hi).map(|b| b.to_vec());
406 let buf = match got {
407 Some(b) => b,
408 None => {
409 caller.data_mut().fault = Some(Fault { offset: ptr, length: len, write: false });
410 return;
411 }
412 };
413 caller.data_mut().output = buf;
414}