feat(workspace): R2.4 core runtime — lazy load, poison on trap, offline re-instantiation, per-generation sheet handles
packages/core-wasm: browser-safe CoreRuntime (synchronous calls once ready; a WebAssembly.RuntimeError poisons the instance, the call answers internal, a fresh instance comes from the kept compiled module and a glue record imported in advance; at most 3 recoveries per page; retry after a load failure), SheetSession (handle rebuilt per instance generation, never called on a dropped one; invalid_sheet without poisoning), Node source. crates/wasm: SheetHandle (sheet held in the module memory). Two builds: pkg/ shipped without trap exports (checked), pkg-proofs/ for the trap tests; BUILD_STAMP (hash of the Rust sources) refused when missing or stale by the vitest global setup instead of skipping. Failure envelope carries a numeric found version; compact JS-number output.
This commit is contained in:
1 parent
22fea8736d
commit
343d6f4c1f
22 files changed
+783
-180
No files matched your search
@@ -20,5 +20,6 @@ docs/
|
||||
logos/
|
||||
target/
|
||||
packages/core-wasm/pkg/
|
||||
packages/core-wasm/pkg-proofs/
|
||||
docker/dev-gateway/htpasswd
|
||||
docker/dev-gateway/mailpit-password
|
||||
@@ -63,6 +63,7 @@ supabase/.temp/
|
||||
# Rust workspace (R0): build output and the generated browser module
|
||||
target/
|
||||
packages/core-wasm/pkg/
|
||||
packages/core-wasm/pkg-proofs/
|
||||
|
||||
# DEV gateway credentials (generated by scripts/dev-gateway.sh)
|
||||
docker/dev-gateway/htpasswd
|
||||
|
||||
+90
-32
@@ -1,18 +1,39 @@
|
||||
//! The call surface the wasm facade and the tools expose (review III.3): one operation
|
||||
//! name, one JSON text in, one JSON text out, closed outcome kinds, never a panic on
|
||||
//! content. The envelope is `{"ok":true,"value":…}` or `{"ok":false,"kind":…,"detail":…}`.
|
||||
//! content. The envelope is `{"ok":true,"value":…}` or `{"ok":false,"kind":…,"detail":…}`,
|
||||
//! plus `"found":<number>` when a failure names a document version.
|
||||
|
||||
use serde::Serialize;
|
||||
use serde::de::DeserializeOwned;
|
||||
use serde_json::{Value, json};
|
||||
use serde_json::{Map, Value};
|
||||
|
||||
use crate::domain::js::parse_json;
|
||||
use crate::domain::sheet::{BundledSheetData, LoadError, LoadedSheet};
|
||||
use crate::domain::{ReportZone, SheetRef};
|
||||
use crate::json::pretty_js_round_trip;
|
||||
use crate::json::{pretty_js_round_trip, to_js_compact};
|
||||
|
||||
/// Runs the operation `op` on the JSON text `input` and returns the outcome envelope.
|
||||
///
|
||||
/// Operations of R0: `core_version`, `pretty_json` (JavaScript pretty form of any JSON
|
||||
/// text), `sheet_ref` and `report_zone` (parse and re-emit a contract type).
|
||||
/// A closed failure of an operation.
|
||||
#[derive(Debug, Clone, PartialEq)]
|
||||
pub struct Failure {
|
||||
pub kind: &'static str,
|
||||
pub detail: String,
|
||||
/// The document version a reader refused, as the JavaScript number it was.
|
||||
pub found: Option<f64>,
|
||||
}
|
||||
|
||||
impl Failure {
|
||||
pub fn new(kind: &'static str, detail: impl std::fmt::Display) -> Self {
|
||||
Self {
|
||||
kind,
|
||||
detail: detail.to_string(),
|
||||
found: None,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
type Outcome = Result<Value, Failure>;
|
||||
|
||||
/// Runs the free operation `op` on the JSON text `input` and returns the outcome envelope.
|
||||
pub fn call(op: &str, input: &str) -> String {
|
||||
let outcome = match op {
|
||||
"core_version" => Ok(Value::String(crate::CORE_VERSION.to_owned())),
|
||||
@@ -21,47 +42,72 @@ pub fn call(op: &str, input: &str) -> String {
|
||||
.map_err(|error| Failure::new("invalid_json", error)),
|
||||
"sheet_ref" => echo::<SheetRef>(input),
|
||||
"report_zone" => echo::<ReportZone>(input),
|
||||
_ => Err(Failure::new(
|
||||
"unknown_op",
|
||||
format!("no operation named {op}"),
|
||||
)),
|
||||
_ => Err(unknown(op)),
|
||||
};
|
||||
render(outcome)
|
||||
}
|
||||
|
||||
fn echo<T: DeserializeOwned + Serialize>(input: &str) -> Result<Value, Failure> {
|
||||
let parsed: T =
|
||||
serde_json::from_str(input).map_err(|error| Failure::new("invalid_shape", error))?;
|
||||
serde_json::to_value(parsed).map_err(|error| Failure::new("internal", error))
|
||||
/// Reads the bundled sheet payload (`BundledSheetData` JSON) into a loaded, indexed sheet.
|
||||
pub fn load_sheet(bundle: &str) -> Result<LoadedSheet, Failure> {
|
||||
let data: BundledSheetData = parse_input(bundle)?;
|
||||
LoadedSheet::from_bundle(data).map_err(|error| match error {
|
||||
LoadError::Shape(error) => Failure::new("invalid_sheet", error),
|
||||
LoadError::NoMainView => Failure::new("invalid_sheet", "the sheet has no main view"),
|
||||
})
|
||||
}
|
||||
|
||||
struct Failure {
|
||||
kind: &'static str,
|
||||
detail: String,
|
||||
/// Runs the operation `op` that needs the session's sheet.
|
||||
pub fn call_with_sheet(sheet: &LoadedSheet, op: &str, _input: &str) -> String {
|
||||
let outcome = match op {
|
||||
"sheet.ref" => to_value(&sheet.reference),
|
||||
_ => Err(unknown(op)),
|
||||
};
|
||||
render(outcome)
|
||||
}
|
||||
|
||||
impl Failure {
|
||||
fn new(kind: &'static str, detail: impl std::fmt::Display) -> Self {
|
||||
Self {
|
||||
kind,
|
||||
detail: detail.to_string(),
|
||||
fn unknown(op: &str) -> Failure {
|
||||
Failure::new("unknown_op", format!("no operation named {op}"))
|
||||
}
|
||||
|
||||
/// Parses the JSON text of an operation input into its contract type.
|
||||
pub(crate) fn parse_input<T: DeserializeOwned>(input: &str) -> Result<T, Failure> {
|
||||
let value = parse_json(input).map_err(|error| Failure::new("invalid_json", error))?;
|
||||
serde_json::from_value(value).map_err(|error| Failure::new("invalid_shape", error))
|
||||
}
|
||||
|
||||
pub(crate) fn to_value<T: Serialize>(value: &T) -> Outcome {
|
||||
serde_json::to_value(value).map_err(|error| Failure::new("internal", error))
|
||||
}
|
||||
|
||||
fn echo<T: DeserializeOwned + Serialize>(input: &str) -> Outcome {
|
||||
let parsed: T = parse_input(input)?;
|
||||
to_value(&parsed)
|
||||
}
|
||||
|
||||
fn render(outcome: Outcome) -> String {
|
||||
let mut envelope = Map::new();
|
||||
match outcome {
|
||||
Ok(value) => {
|
||||
envelope.insert("ok".to_owned(), Value::Bool(true));
|
||||
envelope.insert("value".to_owned(), value);
|
||||
}
|
||||
Err(failure) => {
|
||||
envelope.insert("ok".to_owned(), Value::Bool(false));
|
||||
envelope.insert("kind".to_owned(), Value::from(failure.kind));
|
||||
envelope.insert("detail".to_owned(), Value::from(failure.detail));
|
||||
if let Some(found) = failure.found.and_then(serde_json::Number::from_f64) {
|
||||
envelope.insert("found".to_owned(), Value::Number(found));
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
fn render(outcome: Result<Value, Failure>) -> String {
|
||||
let envelope = match outcome {
|
||||
Ok(value) => json!({ "ok": true, "value": value }),
|
||||
Err(failure) => json!({ "ok": false, "kind": failure.kind, "detail": failure.detail }),
|
||||
};
|
||||
serde_json::to_string(&envelope).unwrap_or_else(|_| {
|
||||
to_js_compact(&Value::Object(envelope)).unwrap_or_else(|_| {
|
||||
r#"{"ok":false,"kind":"internal","detail":"outcome serialisation failed"}"#.to_owned()
|
||||
})
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::call;
|
||||
use super::{Failure, call, render};
|
||||
|
||||
#[test]
|
||||
fn unknown_operation_is_a_closed_kind() {
|
||||
@@ -87,4 +133,16 @@ mod tests {
|
||||
r#"{"ok":true,"value":{"annotationId":"a","viewId":"v","side":"left"}}"#
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_found_version_is_printed_as_a_javascript_number() {
|
||||
let failure = Failure {
|
||||
found: Some(4.0),
|
||||
..Failure::new("incompatible_version", "v4")
|
||||
};
|
||||
assert_eq!(
|
||||
render(Err(failure)),
|
||||
r#"{"ok":false,"kind":"incompatible_version","detail":"v4","found":4}"#
|
||||
);
|
||||
}
|
||||
}
|
||||
@@ -176,6 +176,34 @@ pub fn to_js_pretty<T: Serialize + ?Sized>(value: &T) -> Result<String, serde_js
|
||||
String::from_utf8(buffer).map_err(<serde_json::Error as serde::ser::Error>::custom)
|
||||
}
|
||||
|
||||
/// `serde_json`'s compact formatter with JavaScript float printing (`JSON.stringify(value)`).
|
||||
#[derive(Default)]
|
||||
pub struct JsCompactFormatter;
|
||||
|
||||
impl Formatter for JsCompactFormatter {
|
||||
fn write_f32<W>(&mut self, writer: &mut W, value: f32) -> io::Result<()>
|
||||
where
|
||||
W: ?Sized + io::Write,
|
||||
{
|
||||
writer.write_all(js_number(f64::from(value)).as_bytes())
|
||||
}
|
||||
|
||||
fn write_f64<W>(&mut self, writer: &mut W, value: f64) -> io::Result<()>
|
||||
where
|
||||
W: ?Sized + io::Write,
|
||||
{
|
||||
writer.write_all(js_number(value).as_bytes())
|
||||
}
|
||||
}
|
||||
|
||||
/// Serialises `value` as `JSON.stringify(value)` would.
|
||||
pub fn to_js_compact<T: Serialize + ?Sized>(value: &T) -> Result<String, serde_json::Error> {
|
||||
let mut buffer = Vec::new();
|
||||
let mut serializer = serde_json::Serializer::with_formatter(&mut buffer, JsCompactFormatter);
|
||||
value.serialize(&mut serializer)?;
|
||||
String::from_utf8(buffer).map_err(<serde_json::Error as serde::ser::Error>::custom)
|
||||
}
|
||||
|
||||
/// Parses JSON text and re-emits it in the JavaScript pretty form, keeping the key order.
|
||||
pub fn pretty_js_round_trip(text: &str) -> Result<String, serde_json::Error> {
|
||||
let value: serde_json::Value = serde_json::from_str(text)?;
|
||||
@@ -215,6 +243,15 @@ mod tests {
|
||||
assert_eq!(js_number(f64::INFINITY), "null");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn compact_output_prints_floats_as_javascript() {
|
||||
let value = serde_json::json!({"a": [1.0, 0.5, 1e21], "b": "\u{1}"});
|
||||
assert_eq!(
|
||||
to_js_compact(&value).ok().as_deref(),
|
||||
Some(r#"{"a":[1,0.5,1e+21],"b":"\u0001"}"#)
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn pretty_output_matches_the_javascript_shape() {
|
||||
let text = r#"{"b":[1,2.0,{"c":[]}],"a":{},"d":"é\u0001","e":-0.0}"#;
|
||||
|
||||
+29
-3
@@ -1,8 +1,10 @@
|
||||
//! 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`; loaded
|
||||
//! lazily by the application from R2 on (never at R0).
|
||||
//! 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 wasm_bindgen::prelude::wasm_bindgen;
|
||||
use faunosteo_core::domain::sheet::LoadedSheet;
|
||||
use wasm_bindgen::prelude::{JsError, wasm_bindgen};
|
||||
|
||||
/// Version of the core compiled into this module.
|
||||
#[wasm_bindgen]
|
||||
@@ -17,6 +19,30 @@ 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: <detail>` when the payload, the document or the map is refused.
|
||||
#[wasm_bindgen(constructor)]
|
||||
pub fn new(bundle: &str) -> Result<SheetHandle, JsError> {
|
||||
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)
|
||||
}
|
||||
}
|
||||
|
||||
/// 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")]
|
||||
|
||||
@@ -2,8 +2,8 @@ import globals from 'globals'
|
||||
import tseslint from 'typescript-eslint'
|
||||
|
||||
export default tseslint.config(
|
||||
// pkg/ is the wasm-bindgen output, types/ the ts-rs output: generated, never linted.
|
||||
{ ignores: ['node_modules/**', 'pkg/**', 'types/**'] },
|
||||
// pkg/ and pkg-proofs/ are the wasm-bindgen outputs, types/ the ts-rs output: generated, never linted.
|
||||
{ ignores: ['node_modules/**', 'pkg/**', 'pkg-proofs/**', 'types/**'] },
|
||||
{
|
||||
files: ['**/*.ts'],
|
||||
extends: [...tseslint.configs.recommended],
|
||||
|
||||
@@ -7,8 +7,11 @@
|
||||
"type": "module",
|
||||
"exports": {
|
||||
".": "./src/index.ts",
|
||||
"./node": "./src/node.ts",
|
||||
"./types": "./types/index.ts",
|
||||
"./n-1": "./tests/n-1/index.ts"
|
||||
"./n-1": "./tests/n-1/index.ts",
|
||||
"./vitest-global-setup": "./tests/global-setup.ts",
|
||||
"./pkg/*": "./pkg/*"
|
||||
},
|
||||
"scripts": {
|
||||
"typecheck": "tsc -p tsconfig.json --noEmit",
|
||||
|
||||
@@ -1,72 +1,21 @@
|
||||
/**
|
||||
* Loader of the Faunosteo core module (wasm-bindgen `--target web` output under `pkg/`,
|
||||
* built by `pnpm wasm:build`, git-ignored).
|
||||
* @faunosteo/core-wasm: the Faunosteo core (Rust) compiled to WebAssembly.
|
||||
*
|
||||
* The module is never imported statically: `pkg/` may be absent on a host without Docker,
|
||||
* and the application loads the core lazily behind the paths that need it (review III.3).
|
||||
* No file of this package is reachable from the application before R2.
|
||||
* Browser-safe entry: the runtime and the outcome types. The application gives the runtime
|
||||
* a source built from Vite asset URLs (`apps/app/src/core/`), so the module is fetched on
|
||||
* first need only; Node code (tests, scripts) uses `@faunosteo/core-wasm/node`.
|
||||
*/
|
||||
import { existsSync } from 'node:fs'
|
||||
import { readFile } from 'node:fs/promises'
|
||||
import { fileURLToPath } from 'node:url'
|
||||
|
||||
/** The functions the module exports (mirror of `pkg/faunosteo_wasm.d.ts`). */
|
||||
export interface CoreModule {
|
||||
core_version(): string
|
||||
call(op: string, input: string): string
|
||||
panic_for_test(): void
|
||||
recurse_for_test(depth: number): number
|
||||
}
|
||||
|
||||
/** Outcome envelope of every `call` (closed kinds, never an exception for content). */
|
||||
export type CoreOutcome<T = unknown> =
|
||||
| { ok: true; value: T }
|
||||
| { ok: false; kind: string; detail?: string }
|
||||
|
||||
const PKG_JS = new URL('../pkg/faunosteo_wasm.js', import.meta.url)
|
||||
const PKG_WASM = new URL('../pkg/faunosteo_wasm_bg.wasm', import.meta.url)
|
||||
|
||||
interface PkgModule extends CoreModule {
|
||||
default(input: { module_or_path: BufferSource }): Promise<unknown>
|
||||
}
|
||||
|
||||
/** True when `pnpm wasm:build` has produced the module. */
|
||||
export function isCoreBuilt(): boolean {
|
||||
return existsSync(fileURLToPath(PKG_WASM))
|
||||
}
|
||||
|
||||
let instances = 0
|
||||
|
||||
/**
|
||||
* Instantiates a fresh module (Node: bytes from disk). Each call is a new instance.
|
||||
*
|
||||
* The wasm-bindgen glue keeps its instance in a module-level variable and the ESM cache
|
||||
* returns the same module for the same URL, so a second plain `import()` would hand back
|
||||
* the previous (possibly trapped) instance: R0 proved that an instance is unusable after a
|
||||
* trap (`memory access out of bounds` in the allocator on the next call). A cache-busting
|
||||
* query gives a new module record, hence a new instance. The browser loader of R2 must do
|
||||
* the same (static glue URL imported with a query, or a Worker recreated on trap).
|
||||
*/
|
||||
export async function loadCore(): Promise<CoreModule> {
|
||||
instances += 1
|
||||
const pkg = (await import(
|
||||
`${PKG_JS.href}?instance=${instances}`
|
||||
)) as PkgModule
|
||||
const bytes = await readFile(PKG_WASM)
|
||||
await pkg.default({ module_or_path: bytes })
|
||||
return pkg
|
||||
}
|
||||
|
||||
/** Runs one operation and parses its envelope. */
|
||||
export function callCore<T = unknown>(
|
||||
core: CoreModule,
|
||||
op: string,
|
||||
input: string,
|
||||
): CoreOutcome<T> {
|
||||
return JSON.parse(core.call(op, input)) as CoreOutcome<T>
|
||||
}
|
||||
|
||||
/** Path of the built module on disk (size measurements). */
|
||||
export function coreWasmPath(): string {
|
||||
return fileURLToPath(PKG_WASM)
|
||||
}
|
||||
export {
|
||||
CoreRuntime,
|
||||
SheetSession,
|
||||
type CoreSource,
|
||||
type CoreStatus,
|
||||
type GlueModule,
|
||||
type GlueSheetHandle,
|
||||
} from './runtime'
|
||||
export {
|
||||
CORE_UNAVAILABLE,
|
||||
parseOutcome,
|
||||
type CoreFailure,
|
||||
type CoreOutcome,
|
||||
} from './outcome'
|
||||
@@ -0,0 +1,68 @@
|
||||
/**
|
||||
* Node source of the core module (vitest suites, scripts): the glue and the `.wasm` read
|
||||
* from `pkg/` (the shipped build) or `pkg-proofs/` (with the R0 trap exports). Never
|
||||
* imported by the application bundle.
|
||||
*/
|
||||
import { existsSync } from 'node:fs'
|
||||
import { readFile } from 'node:fs/promises'
|
||||
import { fileURLToPath } from 'node:url'
|
||||
|
||||
import { CoreRuntime, type CoreSource, type GlueModule } from './runtime'
|
||||
|
||||
export type CoreBuild = 'pkg' | 'pkg-proofs'
|
||||
|
||||
const glueUrl = (build: CoreBuild) =>
|
||||
new URL(`../${build}/faunosteo_wasm.js`, import.meta.url)
|
||||
const wasmUrl = (build: CoreBuild) =>
|
||||
new URL(`../${build}/faunosteo_wasm_bg.wasm`, import.meta.url)
|
||||
|
||||
/** Path of a built module on disk (size measurements). */
|
||||
export function coreWasmPath(build: CoreBuild = 'pkg'): string {
|
||||
return fileURLToPath(wasmUrl(build))
|
||||
}
|
||||
|
||||
/** True when `pnpm wasm:build` has produced the module. */
|
||||
export function isCoreBuilt(build: CoreBuild = 'pkg'): boolean {
|
||||
return existsSync(coreWasmPath(build))
|
||||
}
|
||||
|
||||
/** Each import gets its own query string, hence its own module record and instance. */
|
||||
let imports = 0
|
||||
|
||||
export function nodeCoreSource(build: CoreBuild = 'pkg'): CoreSource {
|
||||
return {
|
||||
compile: async () =>
|
||||
WebAssembly.compile(await readFile(coreWasmPath(build))),
|
||||
importGlue: async () => {
|
||||
imports += 1
|
||||
return (await import(
|
||||
`${glueUrl(build).href}?instance=${imports}`
|
||||
)) as GlueModule
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
/** A runtime over the Node source, loaded. */
|
||||
export async function nodeCoreRuntime(
|
||||
build: CoreBuild = 'pkg',
|
||||
): Promise<CoreRuntime> {
|
||||
const runtime = new CoreRuntime(nodeCoreSource(build))
|
||||
if (!(await runtime.ready())) {
|
||||
throw new Error(`core module ${build} failed to load`)
|
||||
}
|
||||
return runtime
|
||||
}
|
||||
|
||||
/** The functions of the proofs build (R0 trap proofs). */
|
||||
export interface ProofModule extends GlueModule {
|
||||
panic_for_test(): void
|
||||
recurse_for_test(depth: number): number
|
||||
}
|
||||
|
||||
/** A fresh, initialised glue of the proofs build, outside any runtime (R0 proofs). */
|
||||
export async function loadProofModule(): Promise<ProofModule> {
|
||||
const source = nodeCoreSource('pkg-proofs')
|
||||
const glue = (await source.importGlue(0)) as ProofModule
|
||||
await glue.default({ module_or_path: await source.compile() })
|
||||
return glue
|
||||
}
|
||||
@@ -0,0 +1,29 @@
|
||||
/**
|
||||
* Outcome envelope of every core call (closed kinds, never an exception for content):
|
||||
* `{ ok: true, value }` or `{ ok: false, kind, detail?, found? }`. Two kinds come from the
|
||||
* runtime itself: `core_unavailable` (the module is not loaded, failed to load or is being
|
||||
* re-created after a trap) and `internal` (the call trapped; the instance was dropped).
|
||||
*/
|
||||
export type CoreOutcome<T> =
|
||||
| { ok: true; value: T }
|
||||
| { ok: false; kind: string; detail?: string; found?: number }
|
||||
|
||||
export type CoreFailure = Extract<CoreOutcome<never>, { ok: false }>
|
||||
|
||||
export const CORE_UNAVAILABLE: CoreFailure = {
|
||||
ok: false,
|
||||
kind: 'core_unavailable',
|
||||
}
|
||||
|
||||
export function failure(kind: string, detail?: string): CoreFailure {
|
||||
return detail === undefined ? { ok: false, kind } : { ok: false, kind, detail }
|
||||
}
|
||||
|
||||
/** Parses the JSON text a core call returned. */
|
||||
export function parseOutcome<T>(text: string): CoreOutcome<T> {
|
||||
try {
|
||||
return JSON.parse(text) as CoreOutcome<T>
|
||||
} catch {
|
||||
return failure('internal', 'unreadable outcome')
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,220 @@
|
||||
import {
|
||||
CORE_UNAVAILABLE,
|
||||
failure,
|
||||
parseOutcome,
|
||||
type CoreOutcome,
|
||||
} from './outcome'
|
||||
|
||||
/**
|
||||
* Browser and Node runtime of the core module (RUST_ARCHITECTURE_REVIEW III.3 rules 5 and
|
||||
* 6, R2 plan P9 rev 2). The module is loaded on first need only; calls are synchronous once
|
||||
* it is ready. A `WebAssembly.RuntimeError` (a Rust panic or a stack overflow) poisons the
|
||||
* instance: the failing call answers `internal`, no further call reaches that instance, and
|
||||
* a fresh one is created from the compiled module kept in memory and a glue module record
|
||||
* imported in advance (a trap needs no network). Calls made while it is re-created answer
|
||||
* `core_unavailable`; after `maxRecoveries` traps the page stays unavailable until reload.
|
||||
*/
|
||||
|
||||
/** What the wasm-bindgen glue (`--target web`) exports. */
|
||||
export interface GlueModule {
|
||||
default(input: { module_or_path: WebAssembly.Module }): Promise<unknown>
|
||||
core_version(): string
|
||||
call(op: string, input: string): string
|
||||
SheetHandle: new (bundle: string) => GlueSheetHandle
|
||||
}
|
||||
|
||||
export interface GlueSheetHandle {
|
||||
call(op: string, input: string): string
|
||||
}
|
||||
|
||||
/** Where the module comes from: the browser (Vite asset URLs) or Node (files). */
|
||||
export interface CoreSource {
|
||||
/** Compiles the `.wasm` once; the runtime keeps the result for every instance. */
|
||||
compile(): Promise<WebAssembly.Module>
|
||||
/**
|
||||
* Imports a NEW glue module record: the glue keeps its instance in a module variable and
|
||||
* the ESM cache returns the same record for the same URL, so each `instance` number must
|
||||
* give a distinct URL (cache-busting query).
|
||||
*/
|
||||
importGlue(instance: number): Promise<GlueModule>
|
||||
}
|
||||
|
||||
export type CoreStatus =
|
||||
| 'idle'
|
||||
| 'loading'
|
||||
| 'ready'
|
||||
| 'recovering'
|
||||
| 'unavailable'
|
||||
|
||||
export interface CoreRuntimeOptions {
|
||||
/** Re-creations after a trap allowed for the page's lifetime. */
|
||||
maxRecoveries?: number
|
||||
}
|
||||
|
||||
export class CoreRuntime {
|
||||
private state: CoreStatus = 'idle'
|
||||
private glue: GlueModule | null = null
|
||||
private compiled: Promise<WebAssembly.Module> | null = null
|
||||
private spare: Promise<GlueModule | null> | null = null
|
||||
private pending: Promise<boolean> | null = null
|
||||
private imports = 0
|
||||
private recoveries = 0
|
||||
private readonly maxRecoveries: number
|
||||
/** Increments with every instance; sheet handles of an older generation are dropped. */
|
||||
generation = 0
|
||||
|
||||
constructor(
|
||||
private readonly source: CoreSource,
|
||||
options: CoreRuntimeOptions = {},
|
||||
) {
|
||||
this.maxRecoveries = options.maxRecoveries ?? 3
|
||||
}
|
||||
|
||||
get status(): CoreStatus {
|
||||
return this.state
|
||||
}
|
||||
|
||||
/** Loads the module on first use; true when calls can be made. */
|
||||
ready(): Promise<boolean> {
|
||||
if (this.state === 'ready') return Promise.resolve(true)
|
||||
if (this.state === 'unavailable') return Promise.resolve(false)
|
||||
this.pending ??= this.load()
|
||||
return this.pending
|
||||
}
|
||||
|
||||
/** After a load failure: forgets it and loads again (traps already spent stay spent). */
|
||||
retry(): Promise<boolean> {
|
||||
if (this.state !== 'unavailable') return this.ready()
|
||||
if (this.recoveries >= this.maxRecoveries) return Promise.resolve(false)
|
||||
this.state = 'idle'
|
||||
this.compiled = null
|
||||
this.pending = null
|
||||
return this.ready()
|
||||
}
|
||||
|
||||
/** Runs a free operation. */
|
||||
call<T>(op: string, input: string): CoreOutcome<T> {
|
||||
return this.invoke((glue) => parseOutcome<T>(glue.call(op, input)))
|
||||
}
|
||||
|
||||
/** A session bound to one sheet payload; the handle is rebuilt per instance. */
|
||||
sheet(bundleText: string): SheetSession {
|
||||
return new SheetSession(this, bundleText)
|
||||
}
|
||||
|
||||
/**
|
||||
* Runs `fn` on the live instance. Any exception from the module poisons the instance:
|
||||
* the result is `internal`, and the next calls wait for a fresh one.
|
||||
*/
|
||||
invoke<T>(fn: (glue: GlueModule) => CoreOutcome<T>): CoreOutcome<T> {
|
||||
const glue = this.glue
|
||||
if (this.state !== 'ready' || !glue) return CORE_UNAVAILABLE
|
||||
try {
|
||||
return fn(glue)
|
||||
} catch (error) {
|
||||
this.poison()
|
||||
return failure('internal', error instanceof Error ? error.name : 'error')
|
||||
}
|
||||
}
|
||||
|
||||
private async load(): Promise<boolean> {
|
||||
this.state = 'loading'
|
||||
try {
|
||||
await this.instantiate(await this.source.importGlue(this.nextImport()))
|
||||
return true
|
||||
} catch {
|
||||
this.state = 'unavailable'
|
||||
this.pending = null
|
||||
return false
|
||||
}
|
||||
}
|
||||
|
||||
private async instantiate(glue: GlueModule): Promise<void> {
|
||||
this.compiled ??= this.source.compile()
|
||||
await glue.default({ module_or_path: await this.compiled })
|
||||
this.glue = glue
|
||||
this.generation += 1
|
||||
this.state = 'ready'
|
||||
this.spare = this.source
|
||||
.importGlue(this.nextImport())
|
||||
.catch(() => null)
|
||||
}
|
||||
|
||||
private nextImport(): number {
|
||||
this.imports += 1
|
||||
return this.imports
|
||||
}
|
||||
|
||||
private poison(): void {
|
||||
this.glue = null
|
||||
if (this.recoveries >= this.maxRecoveries) {
|
||||
this.state = 'unavailable'
|
||||
return
|
||||
}
|
||||
this.recoveries += 1
|
||||
this.state = 'recovering'
|
||||
this.pending = this.recover()
|
||||
}
|
||||
|
||||
private async recover(): Promise<boolean> {
|
||||
try {
|
||||
const spare = await this.spare
|
||||
await this.instantiate(
|
||||
spare ?? (await this.source.importGlue(this.nextImport())),
|
||||
)
|
||||
return true
|
||||
} catch {
|
||||
this.state = 'unavailable'
|
||||
return false
|
||||
} finally {
|
||||
this.pending = null
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/** The calls that need the session's sheet (`SheetHandle` in the module's memory). */
|
||||
export class SheetSession {
|
||||
private handle: GlueSheetHandle | null = null
|
||||
private handleGeneration = -1
|
||||
|
||||
constructor(
|
||||
private readonly runtime: CoreRuntime,
|
||||
/** The bundled sheet payload, kept to rebuild the handle on a new instance. */
|
||||
readonly bundleText: string,
|
||||
) {}
|
||||
|
||||
/** Builds the handle now: `invalid_sheet` when the payload is refused. */
|
||||
open(): CoreOutcome<null> {
|
||||
const handle = this.current()
|
||||
return handle.ok ? { ok: true, value: null } : handle
|
||||
}
|
||||
|
||||
call<T>(op: string, input: string): CoreOutcome<T> {
|
||||
const handle = this.current()
|
||||
if (!handle.ok) return handle
|
||||
return this.runtime.invoke(() =>
|
||||
parseOutcome<T>(handle.value.call(op, input)),
|
||||
)
|
||||
}
|
||||
|
||||
/** The handle of the live instance; a handle of a dropped instance is never called. */
|
||||
private current(): CoreOutcome<GlueSheetHandle> {
|
||||
if (this.handle && this.handleGeneration === this.runtime.generation) {
|
||||
return this.runtime.status === 'ready'
|
||||
? { ok: true, value: this.handle }
|
||||
: CORE_UNAVAILABLE
|
||||
}
|
||||
this.handle = null
|
||||
return this.runtime.invoke((glue) => {
|
||||
try {
|
||||
this.handle = new glue.SheetHandle(this.bundleText)
|
||||
} catch (error) {
|
||||
if (error instanceof WebAssembly.RuntimeError) throw error
|
||||
const message = error instanceof Error ? error.message : ''
|
||||
return failure('invalid_sheet', message.replace(/^invalid_sheet: /, ''))
|
||||
}
|
||||
this.handleGeneration = this.runtime.generation
|
||||
return { ok: true, value: this.handle }
|
||||
})
|
||||
}
|
||||
}
|
||||
@@ -1,18 +1,18 @@
|
||||
import { readFileSync } from 'node:fs'
|
||||
import { fileURLToPath } from 'node:url'
|
||||
|
||||
import { callCore, loadCore } from '../src/index'
|
||||
import { coreBuilt } from './helpers/core'
|
||||
import { nodeCoreRuntime, nodeCoreSource } from '../src/node'
|
||||
|
||||
const CORE_MANIFEST = new URL(
|
||||
'../../../crates/core/Cargo.toml',
|
||||
import.meta.url,
|
||||
)
|
||||
const WORKSPACE_MANIFEST = new URL('../../../Cargo.toml', import.meta.url)
|
||||
const SHIPPED_DTS = new URL('../pkg/faunosteo_wasm.d.ts', import.meta.url)
|
||||
|
||||
describe.skipIf(!coreBuilt)('core facade (wasm)', () => {
|
||||
describe('core facade (shipped wasm build)', () => {
|
||||
it('reports the workspace version of the core', async () => {
|
||||
const core = await loadCore()
|
||||
const core = await nodeCoreRuntime()
|
||||
const workspace = readFileSync(fileURLToPath(WORKSPACE_MANIFEST), 'utf8')
|
||||
const version = /\[workspace\.package\][^[]*?version = "([^"]+)"/s.exec(
|
||||
workspace,
|
||||
@@ -21,36 +21,32 @@ describe.skipIf(!coreBuilt)('core facade (wasm)', () => {
|
||||
expect(readFileSync(fileURLToPath(CORE_MANIFEST), 'utf8')).toContain(
|
||||
'version.workspace = true',
|
||||
)
|
||||
expect(core.core_version()).toBe(version)
|
||||
expect(core.call('core_version', '')).toEqual({ ok: true, value: version })
|
||||
})
|
||||
|
||||
it('answers with a closed outcome envelope', async () => {
|
||||
const core = await loadCore()
|
||||
expect(callCore(core, 'core_version', '')).toEqual({
|
||||
ok: true,
|
||||
value: core.core_version(),
|
||||
})
|
||||
expect(callCore(core, 'nope', '{}')).toMatchObject({
|
||||
const core = await nodeCoreRuntime()
|
||||
expect(core.call('nope', '{}')).toMatchObject({
|
||||
ok: false,
|
||||
kind: 'unknown_op',
|
||||
})
|
||||
expect(callCore(core, 'pretty_json', '{ not json')).toMatchObject({
|
||||
expect(core.call('pretty_json', '{ not json')).toMatchObject({
|
||||
ok: false,
|
||||
kind: 'invalid_json',
|
||||
})
|
||||
})
|
||||
|
||||
it('exposes exactly the documented functions', async () => {
|
||||
const core = await loadCore()
|
||||
for (const name of [
|
||||
'core_version',
|
||||
'call',
|
||||
'panic_for_test',
|
||||
'recurse_for_test',
|
||||
]) {
|
||||
expect(typeof (core as unknown as Record<string, unknown>)[name]).toBe(
|
||||
'function',
|
||||
)
|
||||
it('ships no trap export (the proofs live in pkg-proofs only)', async () => {
|
||||
const glue = (await nodeCoreSource('pkg').importGlue(0)) as unknown as Record<
|
||||
string,
|
||||
unknown
|
||||
>
|
||||
for (const name of ['core_version', 'call', 'SheetHandle']) {
|
||||
expect(typeof glue[name]).toBe('function')
|
||||
}
|
||||
expect(glue.panic_for_test).toBeUndefined()
|
||||
expect(glue.recurse_for_test).toBeUndefined()
|
||||
const dts = readFileSync(fileURLToPath(SHIPPED_DTS), 'utf8')
|
||||
expect(dts).not.toMatch(/panic_for_test|recurse_for_test/)
|
||||
})
|
||||
})
|
||||
@@ -0,0 +1,25 @@
|
||||
/**
|
||||
* Vitest global setup of every suite that runs the core: refuses to run on a missing or
|
||||
* stale module instead of skipping (R2 plan rev 2). The stamp is the hash of the Rust
|
||||
* sources the module is compiled from (scripts/wasm-stamp.mjs), written by
|
||||
* `pnpm wasm:build` into both builds.
|
||||
*/
|
||||
import { existsSync, readFileSync } from 'node:fs'
|
||||
import { fileURLToPath } from 'node:url'
|
||||
|
||||
import { wasmStamp } from '../../../scripts/wasm-stamp.mjs'
|
||||
|
||||
export default function checkCoreBuilds(): void {
|
||||
const expected = wasmStamp()
|
||||
for (const build of ['pkg', 'pkg-proofs']) {
|
||||
const file = fileURLToPath(
|
||||
new URL(`../${build}/BUILD_STAMP`, import.meta.url),
|
||||
)
|
||||
const found = existsSync(file) ? readFileSync(file, 'utf8').trim() : null
|
||||
if (found !== expected) {
|
||||
throw new Error(
|
||||
`packages/core-wasm/${build} is ${found ? 'stale' : 'missing'}: run \`pnpm wasm:build\``,
|
||||
)
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -1,13 +0,0 @@
|
||||
import { isCoreBuilt } from '../../src/index'
|
||||
|
||||
/**
|
||||
* The proofs need the built module. On a host without Docker they are skipped with a
|
||||
* visible notice instead of failing `pnpm check`; CI always builds the module first.
|
||||
*/
|
||||
export const coreBuilt = isCoreBuilt()
|
||||
|
||||
if (!coreBuilt) {
|
||||
console.warn(
|
||||
'[core-wasm] pkg/ missing: run `pnpm wasm:build` (Docker builder); proofs skipped',
|
||||
)
|
||||
}
|
||||
@@ -10,10 +10,9 @@
|
||||
* (`memory access out of bounds`), deterministically;
|
||||
* - a genuinely new instance (new module record, new memory) recovers in full.
|
||||
*/
|
||||
import { loadCore } from '../src/index'
|
||||
import { coreBuilt } from './helpers/core'
|
||||
import { loadProofModule as loadCore } from '../src/node'
|
||||
|
||||
describe.skipIf(!coreBuilt)('panics and stack exhaustion (wasm)', () => {
|
||||
describe('panics and stack exhaustion (wasm)', () => {
|
||||
it('turns a panic into a WebAssembly.RuntimeError', async () => {
|
||||
const core = await loadCore()
|
||||
expect(() => core.panic_for_test()).toThrow(WebAssembly.RuntimeError)
|
||||
|
||||
@@ -0,0 +1,147 @@
|
||||
/**
|
||||
* The core runtime (R2 plan P9 rev 2) on the proofs build, whose trap exports make the
|
||||
* failure paths real: lazy load, poison on a trap, re-instantiation from the kept compiled
|
||||
* module and the pre-imported glue record (no network), handles rebuilt per instance and
|
||||
* never called on a dropped one, the recovery cap, load failure and retry.
|
||||
*/
|
||||
import { readFileSync } from 'node:fs'
|
||||
import { fileURLToPath } from 'node:url'
|
||||
|
||||
import { CoreRuntime, type CoreSource, type GlueModule } from '../src/index'
|
||||
import { nodeCoreSource, type ProofModule } from '../src/node'
|
||||
|
||||
const SEED = '../../../supabase/seed/anatomical-sheets/equine/draft/'
|
||||
|
||||
function seedJson(name: string): unknown {
|
||||
const path = fileURLToPath(new URL(`${SEED}${name}`, import.meta.url))
|
||||
return JSON.parse(readFileSync(path, 'utf8'))
|
||||
}
|
||||
|
||||
const BUNDLE = JSON.stringify({
|
||||
status: 'draft',
|
||||
ref: {
|
||||
sheet_id: 'sheet',
|
||||
version_id: null,
|
||||
document_sha256: '0'.repeat(64),
|
||||
schema_version: 2,
|
||||
species_id: 'equine',
|
||||
},
|
||||
document: seedJson('document.json'),
|
||||
migrationMap: seedJson('report-migration-map.json'),
|
||||
assets: {},
|
||||
assetHashes: {},
|
||||
})
|
||||
|
||||
/** Counts glue imports; imports after `offlineAfter` fail like a lost network. */
|
||||
function countingSource(offlineAfter = Infinity) {
|
||||
const inner = nodeCoreSource('pkg-proofs')
|
||||
const source = {
|
||||
imports: 0,
|
||||
compile: () => inner.compile(),
|
||||
importGlue: async (n: number): Promise<GlueModule> => {
|
||||
source.imports += 1
|
||||
if (source.imports > offlineAfter) throw new TypeError('offline')
|
||||
return inner.importGlue(n)
|
||||
},
|
||||
}
|
||||
return source
|
||||
}
|
||||
|
||||
/** Traps the live instance through the proofs build (stack exhaustion). */
|
||||
function trap(runtime: CoreRuntime) {
|
||||
return runtime.invoke((glue) => {
|
||||
;(glue as ProofModule).recurse_for_test(2_000_000)
|
||||
return { ok: true, value: null }
|
||||
})
|
||||
}
|
||||
|
||||
describe('core runtime', () => {
|
||||
it('loads on first need only', async () => {
|
||||
const source = countingSource()
|
||||
const runtime = new CoreRuntime(source)
|
||||
expect(runtime.status).toBe('idle')
|
||||
expect(runtime.call('core_version', '')).toMatchObject({
|
||||
ok: false,
|
||||
kind: 'core_unavailable',
|
||||
})
|
||||
expect(source.imports).toBe(0)
|
||||
expect(await runtime.ready()).toBe(true)
|
||||
expect(runtime.call('core_version', '')).toMatchObject({ ok: true })
|
||||
})
|
||||
|
||||
it('poisons on a trap and recovers offline from the spare glue record', async () => {
|
||||
const source = countingSource(2)
|
||||
const runtime = new CoreRuntime(source)
|
||||
await runtime.ready()
|
||||
expect(trap(runtime)).toMatchObject({ ok: false, kind: 'internal' })
|
||||
expect(runtime.status).toBe('recovering')
|
||||
expect(runtime.call('core_version', '')).toMatchObject({
|
||||
kind: 'core_unavailable',
|
||||
})
|
||||
expect(await runtime.ready()).toBe(true)
|
||||
expect(runtime.generation).toBe(2)
|
||||
expect(runtime.call('core_version', '')).toMatchObject({ ok: true })
|
||||
})
|
||||
|
||||
it('rebuilds a sheet handle on the new instance and never calls the dropped one', async () => {
|
||||
const runtime = new CoreRuntime(countingSource())
|
||||
await runtime.ready()
|
||||
const sheet = runtime.sheet(BUNDLE)
|
||||
expect(sheet.call('sheet.ref', '')).toMatchObject({
|
||||
ok: true,
|
||||
value: { sheetId: 'sheet', versionId: null },
|
||||
})
|
||||
trap(runtime)
|
||||
expect(sheet.call('sheet.ref', '')).toMatchObject({
|
||||
kind: 'core_unavailable',
|
||||
})
|
||||
await runtime.ready()
|
||||
// A call through the stack-trapped instance would fail in its allocator and poison
|
||||
// again: one generation more and a ready runtime prove the handle was rebuilt.
|
||||
expect(sheet.call('sheet.ref', '')).toMatchObject({ ok: true })
|
||||
expect(runtime.generation).toBe(2)
|
||||
expect(runtime.status).toBe('ready')
|
||||
})
|
||||
|
||||
it('stops recovering after the cap', async () => {
|
||||
const runtime = new CoreRuntime(countingSource(), { maxRecoveries: 1 })
|
||||
await runtime.ready()
|
||||
trap(runtime)
|
||||
expect(await runtime.ready()).toBe(true)
|
||||
trap(runtime)
|
||||
expect(runtime.status).toBe('unavailable')
|
||||
expect(await runtime.retry()).toBe(false)
|
||||
expect(runtime.call('core_version', '')).toMatchObject({
|
||||
kind: 'core_unavailable',
|
||||
})
|
||||
})
|
||||
|
||||
it('reports a load failure and loads again on retry', async () => {
|
||||
const inner = nodeCoreSource('pkg')
|
||||
let failNext = true
|
||||
const source: CoreSource = {
|
||||
compile: () => {
|
||||
if (failNext) {
|
||||
failNext = false
|
||||
return Promise.reject(new WebAssembly.CompileError('blocked'))
|
||||
}
|
||||
return inner.compile()
|
||||
},
|
||||
importGlue: (n) => inner.importGlue(n),
|
||||
}
|
||||
const runtime = new CoreRuntime(source)
|
||||
expect(await runtime.ready()).toBe(false)
|
||||
expect(runtime.status).toBe('unavailable')
|
||||
expect(await runtime.retry()).toBe(true)
|
||||
expect(runtime.call('core_version', '')).toMatchObject({ ok: true })
|
||||
})
|
||||
|
||||
it('refuses an invalid sheet payload without poisoning the instance', async () => {
|
||||
const runtime = new CoreRuntime(nodeCoreSource('pkg'))
|
||||
await runtime.ready()
|
||||
const outcome = runtime.sheet('{"status":"draft"}').open()
|
||||
expect(outcome).toMatchObject({ ok: false, kind: 'invalid_sheet' })
|
||||
expect(runtime.status).toBe('ready')
|
||||
expect(runtime.sheet(BUNDLE).open()).toEqual({ ok: true, value: null })
|
||||
})
|
||||
})
|
||||
@@ -9,8 +9,8 @@ import { fileURLToPath } from 'node:url'
|
||||
import { ReportZoneSchema, SheetRefSchema } from './n-1/domain'
|
||||
|
||||
import type { ReportZone, SheetRef } from '../types/index'
|
||||
import { callCore, loadCore, type CoreModule } from '../src/index'
|
||||
import { coreBuilt } from './helpers/core'
|
||||
import type { CoreRuntime } from '../src/index'
|
||||
import { nodeCoreRuntime } from '../src/node'
|
||||
|
||||
const FIXTURES = [
|
||||
'apps/app/tests/fixtures/report-v3.demo.json',
|
||||
@@ -32,17 +32,17 @@ function repoFile(relative: string): string {
|
||||
)
|
||||
}
|
||||
|
||||
function prettyByCore(core: CoreModule, text: string): string {
|
||||
const outcome = callCore<string>(core, 'pretty_json', text)
|
||||
function prettyByCore(core: CoreRuntime, text: string): string {
|
||||
const outcome = core.call<string>('pretty_json', text)
|
||||
if (!outcome.ok) throw new Error(`${outcome.kind}: ${outcome.detail ?? ''}`)
|
||||
return outcome.value
|
||||
}
|
||||
|
||||
describe.skipIf(!coreBuilt)('serialisation contract (wasm)', () => {
|
||||
describe('serialisation contract (wasm)', () => {
|
||||
it.each(FIXTURES)(
|
||||
'%s: core pretty output equals JSON.stringify(…, null, 2)',
|
||||
async (relative) => {
|
||||
const core = await loadCore()
|
||||
const core = await nodeCoreRuntime()
|
||||
const text = repoFile(relative)
|
||||
const expected = JSON.stringify(JSON.parse(text), null, 2)
|
||||
expect(prettyByCore(core, text)).toBe(expected)
|
||||
@@ -50,7 +50,7 @@ describe.skipIf(!coreBuilt)('serialisation contract (wasm)', () => {
|
||||
)
|
||||
|
||||
it('prints every number as JavaScript does', async () => {
|
||||
const core = await loadCore()
|
||||
const core = await nodeCoreRuntime()
|
||||
const text = JSON.stringify(NUMBER_CASES)
|
||||
expect(prettyByCore(core, text)).toBe(
|
||||
JSON.stringify(JSON.parse(text), null, 2),
|
||||
@@ -58,9 +58,8 @@ describe.skipIf(!coreBuilt)('serialisation contract (wasm)', () => {
|
||||
})
|
||||
|
||||
it('writes optional fields absent and nullable fields null, readable by the Zod schemas', async () => {
|
||||
const core = await loadCore()
|
||||
const bare = callCore<ReportZone>(
|
||||
core,
|
||||
const core = await nodeCoreRuntime()
|
||||
const bare = core.call<ReportZone>(
|
||||
'report_zone',
|
||||
JSON.stringify({ annotationId: 'hip', viewId: 'main' }),
|
||||
)
|
||||
@@ -72,8 +71,7 @@ describe.skipIf(!coreBuilt)('serialisation contract (wasm)', () => {
|
||||
expect(Object.keys(bare.value)).toEqual(['annotationId', 'viewId'])
|
||||
expect(ReportZoneSchema.parse(bare.value)).toEqual(bare.value)
|
||||
|
||||
const full = callCore<ReportZone>(
|
||||
core,
|
||||
const full = core.call<ReportZone>(
|
||||
'report_zone',
|
||||
JSON.stringify({
|
||||
viewId: 'main',
|
||||
@@ -93,8 +91,7 @@ describe.skipIf(!coreBuilt)('serialisation contract (wasm)', () => {
|
||||
},
|
||||
})
|
||||
|
||||
const sheet = callCore<SheetRef>(
|
||||
core,
|
||||
const sheet = core.call<SheetRef>(
|
||||
'sheet_ref',
|
||||
JSON.stringify({
|
||||
sheetId: 'faunosteo-cheval',
|
||||
@@ -105,8 +102,7 @@ describe.skipIf(!coreBuilt)('serialisation contract (wasm)', () => {
|
||||
expect(sheet.ok && sheet.value.versionId).toBeNull()
|
||||
if (sheet.ok) expect(SheetRefSchema.parse(sheet.value)).toEqual(sheet.value)
|
||||
|
||||
const refused = callCore(
|
||||
core,
|
||||
const refused = core.call(
|
||||
'report_zone',
|
||||
JSON.stringify({ annotationId: 'a', viewId: 'v', unresolved: false }),
|
||||
)
|
||||
|
||||
@@ -1,25 +1,26 @@
|
||||
/**
|
||||
* R0 measurement: served size of the module and instantiate time (D-R13 budget, enforced
|
||||
* from R2 on the real core; R0 records the skeleton's numbers).
|
||||
* D-R13 budget: the served module (gzip) stays under 600 KB; the numbers are printed for
|
||||
* RUST.md (raw and compressed size, compile + instantiate time on Node).
|
||||
*/
|
||||
import { readFileSync } from 'node:fs'
|
||||
import { gzipSync } from 'node:zlib'
|
||||
|
||||
import { coreWasmPath, loadCore } from '../src/index'
|
||||
import { coreBuilt } from './helpers/core'
|
||||
import { CoreRuntime } from '../src/index'
|
||||
import { coreWasmPath, nodeCoreSource } from '../src/node'
|
||||
|
||||
/** D-R13: the served module (compressed) stays under this many bytes. */
|
||||
const COMPRESSED_BUDGET_BYTES = 600_000
|
||||
|
||||
describe.skipIf(!coreBuilt)('module size and instantiate time (wasm)', () => {
|
||||
describe('module size and instantiate time (shipped wasm build)', () => {
|
||||
it('stays under the compressed budget and reports its numbers', async () => {
|
||||
const bytes = readFileSync(coreWasmPath())
|
||||
const bytes = readFileSync(coreWasmPath('pkg'))
|
||||
const gzip = gzipSync(bytes, { level: 9 }).length
|
||||
const started = performance.now()
|
||||
await loadCore()
|
||||
const instantiateMs = performance.now() - started
|
||||
const runtime = new CoreRuntime(nodeCoreSource('pkg'))
|
||||
expect(await runtime.ready()).toBe(true)
|
||||
const readyMs = performance.now() - started
|
||||
console.info(
|
||||
`[core-wasm] faunosteo_wasm_bg.wasm: ${bytes.length} bytes raw, ${gzip} bytes gzip-9, instantiate ${instantiateMs.toFixed(1)} ms`,
|
||||
`[core-wasm] faunosteo_wasm_bg.wasm: ${bytes.length} bytes raw, ${gzip} bytes gzip-9, compile + instantiate ${readyMs.toFixed(1)} ms`,
|
||||
)
|
||||
expect(gzip).toBeLessThanOrEqual(COMPRESSED_BUDGET_BYTES)
|
||||
})
|
||||
|
||||
+3
@@ -0,0 +1,3 @@
|
||||
declare module '*/scripts/wasm-stamp.mjs' {
|
||||
export function wasmStamp(): string
|
||||
}
|
||||
@@ -5,5 +5,6 @@ export default defineConfig({
|
||||
environment: 'node',
|
||||
globals: true,
|
||||
include: ['tests/**/*.test.ts'],
|
||||
globalSetup: ['tests/global-setup.ts'],
|
||||
},
|
||||
})
|
||||
+24
-9
@@ -21,14 +21,29 @@ if [ "$lock_version" != "$cli_version" ]; then
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# `proofs`: the R0 trap exports; dropped when R2 builds the module the application ships.
|
||||
cargo build -p faunosteo-wasm --release --target wasm32-unknown-unknown --locked --features proofs
|
||||
# Two modules from the same sources: pkg/ is the one the application ships (no trap export),
|
||||
# pkg-proofs/ adds the R0 trap exports for the poison-and-reinstantiate tests only (R2 plan P10).
|
||||
build_module() {
|
||||
local out="$1"
|
||||
shift
|
||||
cargo build -p faunosteo-wasm --release --target wasm32-unknown-unknown --locked "$@"
|
||||
rm -rf "$out"
|
||||
wasm-bindgen --target web --out-dir "$out" --out-name faunosteo_wasm \
|
||||
target/wasm32-unknown-unknown/release/faunosteo_wasm.wasm
|
||||
}
|
||||
|
||||
out=packages/core-wasm/pkg
|
||||
rm -rf packages/core-wasm/pkg
|
||||
wasm-bindgen --target web --out-dir "$out" --out-name faunosteo_wasm \
|
||||
target/wasm32-unknown-unknown/release/faunosteo_wasm.wasm
|
||||
stamp="$(node scripts/wasm-stamp.mjs)"
|
||||
build_module packages/core-wasm/pkg-proofs --features proofs
|
||||
echo "$stamp" > packages/core-wasm/pkg-proofs/BUILD_STAMP
|
||||
build_module packages/core-wasm/pkg
|
||||
echo "$stamp" > packages/core-wasm/pkg/BUILD_STAMP
|
||||
|
||||
raw=$(wc -c < "$out/faunosteo_wasm_bg.wasm")
|
||||
gz=$(gzip -9 -c "$out/faunosteo_wasm_bg.wasm" | wc -c)
|
||||
echo "faunosteo_wasm_bg.wasm: ${raw} bytes raw, ${gz} bytes gzip -9"
|
||||
# The shipped module must not carry a proof export.
|
||||
if grep -Eq 'panic_for_test|recurse_for_test' packages/core-wasm/pkg/faunosteo_wasm.d.ts; then
|
||||
echo "packages/core-wasm/pkg exports a proof function: refusing to ship it" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
raw=$(wc -c < packages/core-wasm/pkg/faunosteo_wasm_bg.wasm)
|
||||
gz=$(gzip -9 -c packages/core-wasm/pkg/faunosteo_wasm_bg.wasm | wc -c)
|
||||
echo "faunosteo_wasm_bg.wasm (shipped): ${raw} bytes raw, ${gz} bytes gzip -9"
|
||||
@@ -0,0 +1,41 @@
|
||||
// Build stamp of the browser module: sha256 over the sources that compile into it (the core
|
||||
// library, the wasm facade, the workspace manifests and lock, the cargo config). Written into
|
||||
// pkg/ and pkg-proofs/ by scripts/wasm-build.sh; packages/core-wasm/tests/global-setup.ts
|
||||
// recomputes it and refuses to run the suites on a missing or stale module.
|
||||
// Usage: node scripts/wasm-stamp.mjs → prints the stamp.
|
||||
import { createHash } from 'node:crypto'
|
||||
import { readdirSync, readFileSync, statSync } from 'node:fs'
|
||||
import { join, relative, resolve } from 'node:path'
|
||||
import { fileURLToPath } from 'node:url'
|
||||
|
||||
const ROOT = resolve(fileURLToPath(new URL('..', import.meta.url)))
|
||||
const INPUTS = [
|
||||
'Cargo.toml',
|
||||
'Cargo.lock',
|
||||
'.cargo/config.toml',
|
||||
'crates/core/Cargo.toml',
|
||||
'crates/core/src',
|
||||
'crates/wasm/Cargo.toml',
|
||||
'crates/wasm/src',
|
||||
]
|
||||
|
||||
function files(path) {
|
||||
const absolute = join(ROOT, path)
|
||||
if (!statSync(absolute).isDirectory()) return [path]
|
||||
return readdirSync(absolute).flatMap((name) => files(join(path, name)))
|
||||
}
|
||||
|
||||
export function wasmStamp() {
|
||||
const hash = createHash('sha256')
|
||||
const all = INPUTS.flatMap(files).map((f) => relative(ROOT, join(ROOT, f)))
|
||||
for (const file of all.sort()) {
|
||||
hash.update(`${file}\0`)
|
||||
hash.update(readFileSync(join(ROOT, file)))
|
||||
hash.update('\0')
|
||||
}
|
||||
return hash.digest('hex')
|
||||
}
|
||||
|
||||
if (process.argv[1] === fileURLToPath(import.meta.url)) {
|
||||
process.stdout.write(`${wasmStamp()}\n`)
|
||||
}
|
||||
Reference in new issue
Block a user