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 | |
| 17 | use crate::eval::scope::Scope; |
| 18 | use crate::eval::value::{ |
| 19 | Module, |
| 20 | Value, |
| 21 | }; |
| 22 | use crate::eval::func::Func; |
| 23 | |
| 24 | use oxedyne_fe2o3_core::prelude::*; |
| 25 | use oxedyne_fe2o3_hash::fingerprint::Fingerprint; |
| 26 | use oxedyne_fe2o3_hash::fingerprint::Fingerprinter; |
| 27 | |
| 28 | use std::fmt; |
| 29 | use std::sync::{ |
| 30 | Arc, |
| 31 | Mutex, |
| 32 | }; |
| 33 | |
| 34 | use 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. |
| 43 | pub const FUEL: u64 = 1_000_000_000_000; |
| 44 | #[cfg(not(target_arch = "wasm32"))] |
| 45 | pub const MEMORY: usize = 1 << 30; // bytes of linear memory an instance may hold |
| 46 | #[cfg(target_arch = "wasm32")] |
| 47 | pub const MEMORY: usize = 256 << 20; // inside the tab's own linear memory, so lower |
| 48 | const TABLE_ELEMS: usize = 1 << 20; |
| 49 | const MAX_TABLES: usize = 8; |
| 50 | |
| 51 | const ENV: &str = "typst_env"; |
| 52 | const WRITE_ARGS: &str = "wasm_minimal_protocol_write_args_to_buffer"; |
| 53 | const 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. |
| 57 | pub 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 | |
| 64 | struct 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 | |
| 71 | struct Instance { |
| 72 | instance: wasmi::Instance, |
| 73 | store: wasmi::Store<CallData>, |
| 74 | } |
| 75 | |
| 76 | struct Snapshot { |
| 77 | pages: u64, |
| 78 | data: Vec<u8>, |
| 79 | } |
| 80 | |
| 81 | #[derive(Default)] |
| 82 | struct 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 | |
| 89 | struct 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)] |
| 99 | struct Cap { |
| 100 | hit: bool, |
| 101 | } |
| 102 | |
| 103 | impl 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)] |
| 131 | pub struct PluginFunc { |
| 132 | plugin: Arc<Plugin>, |
| 133 | name: String, |
| 134 | } |
| 135 | |
| 136 | impl 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 | |
| 159 | impl PartialEq for PluginFunc { |
| 160 | fn eq(&self, other: &Self) -> bool { self.fingerprint() == other.fingerprint() } |
| 161 | } |
| 162 | |
| 163 | impl fmt::Debug for PluginFunc { |
| 164 | fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { write!(f, "PluginFunc({})", self.name) } |
| 165 | } |
| 166 | |
| 167 | impl fmt::Debug for Plugin { |
| 168 | fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { f.pad("Plugin(..)") } |
| 169 | } |
| 170 | |
| 171 | impl 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 | |
| 268 | impl 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. |
| 371 | fn 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 | |
| 382 | fn 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 | |
| 398 | fn 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 | } |