//! wasm-bindgen facade over `faunosteo-core` (review III.3): JSON strings in and out, closed //! outcome kinds. Built by `scripts/wasm-build.sh` into `packages/core-wasm/pkg` (shipped) //! and `packages/core-wasm/pkg-proofs` (with the trap exports, tests only); loaded lazily by //! the application behind the sheet and import paths (`packages/core-wasm/src/runtime.ts`). use faunosteo_core::domain::archive::SnapshotCaps; use faunosteo_core::domain::sheet::LoadedSheet; use faunosteo_core::domain::sheet::preview::{MAX_HELD_DRAWINGS, PreviewDrawing}; use faunosteo_core::pdf::read::MAX_PDF_BYTES; use wasm_bindgen::prelude::{JsError, wasm_bindgen}; /// Version of the core compiled into this module. #[wasm_bindgen] pub fn core_version() -> String { faunosteo_core::CORE_VERSION.to_owned() } /// Runs one core operation: `op` names it, `input` is its JSON text, the result is the /// JSON text of the outcome envelope (`{"ok":true,"value":…}` or `{"ok":false,"kind":…}`). #[wasm_bindgen] pub fn call(op: &str, input: &str) -> String { faunosteo_core::facade::call(op, input) } /// The session's anatomical sheet, held in the module's memory and built once from the /// bundled payload, so the per-action calls carry only the observation or the report. #[wasm_bindgen] pub struct SheetHandle { sheet: LoadedSheet, } #[wasm_bindgen] impl SheetHandle { /// Loads the bundled sheet payload; throws an `Error` whose message is /// `invalid_sheet: ` when the payload, the document or the map is refused. #[wasm_bindgen(constructor)] pub fn new(bundle: &str) -> Result { faunosteo_core::facade::load_sheet(bundle) .map(|sheet| SheetHandle { sheet }) .map_err(|failure| JsError::new(&format!("{}: {}", failure.kind, failure.detail))) } /// Runs one operation on this sheet; same envelope as `call`. pub fn call(&self, op: &str, input: &str) -> String { faunosteo_core::facade::call_with_sheet(&self.sheet, op, input) } /// Reads `bytes` as a Faunosteo PDF and imports its attachment onto this sheet (R4, plan /// §B.1.4): the envelope of `archive.import`, plus the reader's kinds (`PdfImportKind`). /// The bytes are copied once into the module's memory by the glue. pub fn import_pdf(&self, bytes: &[u8]) -> String { faunosteo_core::facade::import_pdf(&self.sheet, bytes) } /// The same import on bytes streamed into the module's memory (`FileBytes`), consumed: /// the file lives once, in linear memory, never as a JavaScript ArrayBuffer (R4.3a). pub fn import_pdf_bytes(&self, bytes: FileBytes) -> String { faunosteo_core::facade::import_pdf(&self.sheet, &bytes.data) } /// A rescue copy streamed into the module's memory, consumed: strict UTF-8, one BOM, /// the value budget, then `draft.restore` without an archive (R4.3a). pub fn restore_copy_bytes(&self, bytes: FileBytes) -> String { faunosteo_core::facade::restore_copy(&self.sheet, bytes.data) } } /// A stored sheet version being gathered for preview (V1-2.2, contract §10): the page adds /// each downloaded drawing with the sha256 of its row, then builds the `PreviewSheet` from /// the version's status, document text and stored fingerprint. The bytes are copied once /// into the module's memory by the glue; nothing is read before `build`. #[wasm_bindgen] pub struct PreviewBuilder { drawings: Vec, /// The cap a refused drawing passed: the build answers `caps` with it, as the core does. refused: Option<&'static str>, } #[wasm_bindgen] impl PreviewBuilder { #[wasm_bindgen(constructor)] pub fn new() -> PreviewBuilder { PreviewBuilder { drawings: Vec::new(), refused: None, } } /// `false` (nothing kept) past the preview's drawing count or a drawing over 2 MiB; the /// build then refuses with `caps` as the core does. pub fn add_drawing(&mut self, asset_id: &str, sha256: &str, bytes: &[u8]) -> bool { if bytes.len() > SnapshotCaps::ASSET_BYTES { self.refused = Some("drawing_bytes"); return false; } if self.drawings.len() >= MAX_HELD_DRAWINGS { self.refused = Some("drawings"); return false; } self.drawings.push(PreviewDrawing { asset_id: asset_id.to_owned(), sha256: sha256.to_owned(), bytes: bytes.to_vec(), }); true } /// Consumes the builder; throws an `Error` worded `: ` (`invalid_document`, /// `drawing_missing`, `drawing_hash_mismatch`, `fingerprint_mismatch`, `caps`, or /// `invalid_shape` / `invalid_json` for the input). pub fn build(self, input: &str) -> Result { if let Some(cap) = self.refused { return Err(JsError::new(&format!("caps: {cap}"))); } faunosteo_core::facade::load_preview(input, self.drawings) .map(|sheet| PreviewSheet { sheet }) .map_err(|failure| JsError::new(&format!("{}: {}", failure.kind, failure.detail))) } } impl Default for PreviewBuilder { fn default() -> Self { Self::new() } } /// A stored version loaded for the catalogue, the admin preview and the editor: no report /// migration map, never a report session. #[wasm_bindgen] pub struct PreviewSheet { sheet: faunosteo_core::domain::sheet::preview::PreviewSheet, } #[wasm_bindgen] impl PreviewSheet { /// `preview.state` or `view.canvas`; the envelope of `call`. pub fn call(&self, op: &str, input: &str) -> String { faunosteo_core::facade::call_with_preview(&self.sheet, op, input) } /// A draft's document after an edit; the drawings are not read again. pub fn replace_document(&mut self, text: &str) -> String { faunosteo_core::facade::replace_preview_document(&mut self.sheet, text) } /// A drawing uploaded while the draft is open. pub fn add_drawing(&mut self, asset_id: &str, sha256: &str, bytes: &[u8]) -> String { let drawing = PreviewDrawing { asset_id: asset_id.to_owned(), sha256: sha256.to_owned(), bytes: bytes.to_vec(), }; faunosteo_core::facade::add_preview_drawing(&mut self.sheet, drawing) } } /// The cleaning answer for a file picked for upload (contract §9.2): the envelope of `call` /// with an `SvgCleaning` value. #[wasm_bindgen] pub fn clean_svg(bytes: &[u8]) -> String { faunosteo_core::facade::clean_svg(bytes) } /// The incremental PDF export (R4.6, plan §B.1.4, OD-2): the application opens a session on /// its `ExportInput` JSON, then alternates `next()` (the rasters the next step needs) with /// `add_raster` or `raster_failed` per key, and closes with `finish()`. Every answer is the /// outcome envelope of the calls; a view raster is decoded and written into the file as it /// arrives (its bytes are copied into linear memory for the call by the glue, and freed /// with the decode before the call returns), so the session holds the file being written /// and nothing of the rasters. `free()` (the driver's `finally`) drops everything it holds. #[wasm_bindgen] pub struct ExportSession { inner: faunosteo_core::pdf::write::session::ExportSession, } #[wasm_bindgen] impl ExportSession { /// Every check of the input, the envelope under its cap, the file opened; throws an /// `Error` worded `: ` with today's export kinds when the input is refused. #[wasm_bindgen(constructor)] pub fn new(input: &str) -> Result { faunosteo_core::facade::export::open(input) .map(|inner| ExportSession { inner }) .map_err(|failure| JsError::new(&format!("{}: {}", failure.kind, failure.detail))) } /// `{"ok":true,"value":}`: the next batch of raster requests, or `done`. pub fn next_step(&mut self) -> String { faunosteo_core::facade::export::next_step(&mut self.inner) } /// The raster of `key` (a PNG); `{"ok":true}` or a closed refusal. pub fn add_raster(&mut self, key: &str, png: &[u8]) -> String { faunosteo_core::facade::export::add_raster(&mut self.inner, key, png) } /// `key` could not be rasterised (its warning); `{"ok":true}` or a closed refusal. pub fn raster_failed(&mut self, key: &str) -> String { faunosteo_core::facade::export::raster_failed(&mut self.inner, key) } /// Closes the file: the number of parts `take_part()` then gives; throws an `Error` /// worded `: ` (`out_of_order`, `self_check_failed`). pub fn finish(&mut self) -> Result { faunosteo_core::facade::export::finish(&mut self.inner) .map(|parts| u32::try_from(parts).unwrap_or(u32::MAX)) .map_err(|failure| JsError::new(&format!("{}: {}", failure.kind, failure.detail))) } /// The next part of the finished file, front to back, `undefined` once every part is /// out. Each part is copied out of linear memory by the glue and freed here, so the /// file is never held twice (`new Blob(parts)` takes them as they are). pub fn take_part(&mut self) -> Option> { self.inner.take_part() } /// `{"ok":true,"value":[…]}`, complete after `finish()`. pub fn warnings(&self) -> String { faunosteo_core::facade::export::warnings(&self.inner) } /// Bytes of the file written so far (DEV diagnostics only). pub fn written(&self) -> u32 { u32::try_from(self.inner.written()).unwrap_or(u32::MAX) } } /// A file's bytes gathered chunk by chunk in the module's memory (R4.3a): the worker reads /// `file.stream()` and pushes each chunk, so the only whole copy of the file is this one. /// The capacity is reserved up front from the file size the worker announces, capped at the /// PDF limit; a push past the announced size is refused (`false`) and the bytes dropped. #[wasm_bindgen] pub struct FileBytes { data: Vec, expected: usize, } #[wasm_bindgen] impl FileBytes { /// `expected` is the file size; above the PDF cap nothing is reserved and every push /// is refused, so the caller's own size check stays the only one that reads a file. #[wasm_bindgen(constructor)] pub fn new(expected: u32) -> FileBytes { let expected = expected as usize; let expected = if expected > MAX_PDF_BYTES { 0 } else { expected }; FileBytes { data: Vec::with_capacity(expected), expected, } } /// Appends a chunk; `false` (nothing appended) once the announced size would be passed. pub fn push(&mut self, chunk: &[u8]) -> bool { if self.data.len().saturating_add(chunk.len()) > self.expected { return false; } self.data.extend_from_slice(chunk); true } pub fn len(&self) -> u32 { u32::try_from(self.data.len()).unwrap_or(u32::MAX) } pub fn is_empty(&self) -> bool { self.data.is_empty() } } /// R4.2e proof: the import with the OD-3 value cap off, so that a token-dense document runs /// into the linear memory ceiling and traps (never in the module the application ships). #[cfg(feature = "proofs")] #[wasm_bindgen] pub fn import_pdf_unbounded_for_test(bundle: &str, bytes: &[u8]) -> Result { use faunosteo_core::pdf::import::import_pdf; use faunosteo_core::pdf::read::probe::ProbeLimits; let sheet = faunosteo_core::facade::load_sheet(bundle) .map_err(|failure| JsError::new(&format!("{}: {}", failure.kind, failure.detail)))?; Ok(match import_pdf(&sheet, bytes, ProbeLimits::UNBOUNDED) { Ok(_) => "ok".to_owned(), Err(failure) => format!("{failure:?}"), }) } /// R4.5 proof: one export through the module from an `ExportInput` JSON and the rasters /// as `{ "headerLogo"|"footerLogo"|"poweredBy"|"partner": base64|null, "views": [{ /// "observationId", "viewId", "png": base64 }] }`, so the wasm output can be compared to the /// native digests and the module's size with the writer linked be measured. Never shipped: /// the application's export goes through the R4.6 session. #[cfg(feature = "proofs")] #[wasm_bindgen] pub fn export_pdf_for_test(input: &str, rasters: &str) -> Result, JsError> { use faunosteo_core::domain::js::parse_json; use faunosteo_core::pdf::write::export::export_pdf; use faunosteo_core::pdf::write::input::{ExportInput, Rasters}; use faunosteo_core::pdf::write::layout::png::base64_bytes; let input: ExportInput = parse_json(input) .ok() .and_then(|v| serde_json::from_value(v).ok()) .ok_or_else(|| JsError::new("invalid input"))?; let spec = parse_json(rasters).map_err(|e| JsError::new(&e.to_string()))?; let slot = |key: &str| { spec.get(key) .and_then(|v| v.as_str()) .and_then(base64_bytes) }; let mut set = Rasters { header_logo: slot("headerLogo"), footer_logo: slot("footerLogo"), powered_by: slot("poweredBy"), partner: slot("partner"), views: Default::default(), }; for view in spec .get("views") .and_then(|v| v.as_array()) .into_iter() .flatten() { let key = ( view["observationId"].as_str().unwrap_or("").to_owned(), view["viewId"].as_str().unwrap_or("").to_owned(), ); if let Some(png) = view["png"].as_str().and_then(base64_bytes) { set.views.insert(key, png); } } export_pdf(input, &set) .map(|result| result.pdf) .map_err(|error| JsError::new(&format!("{}: {}", error.kind.as_str(), error.detail))) } /// R4.2e proof: the linear memory ceiling (`--max-memory`, `.cargo/config.toml`). Allocates /// and touches `mib` MiB; past the ceiling the allocation fails and Rust aborts, a trap. #[cfg(feature = "proofs")] #[wasm_bindgen] pub fn allocate_for_test(mib: u32) -> u32 { let bytes = vec![1u8; (mib as usize) * 1024 * 1024]; std::hint::black_box(&bytes); bytes .iter() .step_by(1024 * 1024) .map(|b| u32::from(*b)) .sum() } /// R0 proof: on wasm32 a panic is a trap (panic = abort), reaching JavaScript as a /// `WebAssembly.RuntimeError`; the caller re-instantiates the module. #[cfg(feature = "proofs")] #[wasm_bindgen] pub fn panic_for_test() { panic!("deliberate panic for the R0 proof"); } /// R0 proof: exhausting the shadow stack traps instead of corrupting memory. #[cfg(feature = "proofs")] #[wasm_bindgen] pub fn recurse_for_test(depth: u32) -> u32 { recurse(depth) } #[cfg(feature = "proofs")] #[inline(never)] fn recurse(depth: u32) -> u32 { let mut frame = [depth; 32]; if depth == 0 { return std::hint::black_box(&frame)[0]; } let below = recurse(depth - 1); frame[(below as usize) % 32] ^= below; std::hint::black_box(&frame); below.wrapping_add(1) }