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
@@ -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 }
|
||||
})
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user