diff --git a/ffi/README.md b/ffi/README.md index c951b9a45..6bc8d6871 100644 --- a/ffi/README.md +++ b/ffi/README.md @@ -48,9 +48,11 @@ those functions look up by name. `python/.py` holds it in Python, over a extension the crate builds with `--features python`, `swift/.swift` holds it in Swift, over the C header as a clang module, `go/` holds it in Go, a package per crate over the C ABI through cgo, and `dart/.dart` holds it in Dart, over the C ABI through -`dart:ffi` and what the crate builds with `--features dart`. +`dart:ffi` and what the crate builds with `--features dart`. When `wasm32-wasip1` is among +the targets, `web/` holds it in TypeScript for the web, ES modules over the `.wasm` the +crate builds with `--target wasm32-wasip1 --features web`. An export again rewrites only the files whose content changed, and removes from -`include//` and `go/` only what it no longer writes, so a build of an unchanged +`include//`, `go/`, and `web/` only what it no longer writes, so a build of an unchanged export stays fresh. The crate's version, `0.0.0+`, hashes its Rust sources and manifest, so exports that differ build apart in a target directory they share. @@ -1255,10 +1257,83 @@ would export, and fails on it, so the list holds only what the export refuses. I fails on an `instance not inferred` refusal, which is a bug in the exporter's inference rather than in the crate. +## TypeScript (web) + +`web/` is TypeScript over the C ABI of the crate built for `wasm32-wasip1` with `--features +web`, tested on Node 24, whose type stripping runs it as it is. Each file is an ES module a +bundler takes as it is, importing its neighbors by their `.ts` names; the `.wasm` needs no +tool run on it after `cargo build`, and no wasm-bindgen. The binding serves +`wasm32-wasip1` alone: an item another target has and it lacks is left out, not declared to +fail. `load(source)` of `index.ts` compiles and instantiates the module, from its bytes, a +`Response`, or a `WebAssembly.Module`, before any other call, and checks its contract and +target there. + +- **The platform** is the web's: the module's std is `wasm32-wasip1`'s, whose imports are a + detail between the generated module and its binding, which implements each with the web + API for it, so nothing of WASI ships. Its clocks are `performance.now`, from + `performance.timeOrigin` for the real-time one; its randomness `crypto.getRandomValues`; + its stdout and stderr `console.log` and `console.error`, a line at a time; its + environment and arguments empty; and its exit an abort. `load` refuses a module importing + anything else. Measured on the api fixture, stripped, with LTO at `opt-level = "s"`, that + std costs 24 KB over `wasm32-unknown-unknown`'s (3%), 9.5 KB gzipped, and the glue 2 KB + more; `wasm32-unknown-unknown` has no clock, so `Instant::now` panics there. +- **The API** is rust2-ts's shape: each type is a module of its own, `web/.ts`, which + exports the type by its name and its functions, each taking `self` first, so a caller + writes `import * as Counter from "./web/Counter.ts"` and `Counter.get(c)`, and a bundler + drops every function no caller names. `index.ts` holds the free functions, the constants, + and `load`. Names are the C names without the prefix: a type in Pascal case, and a + function in camel case, a constant's in upper case; a reserved word is exported as is + from a local with a trailing `$`, so `Counter.new("c", 1)` and `Point.default()` work + through the module's namespace. +- **Values**: a record is a plain object of its fields in camel case, positional ones `_0`, + `_1`, and so on; an opaque value an `rt.Opaque`, its bytes, which only Rust makes. A plain + enum is a union of its variants' names, and an enum with data a union of objects tagged + by `tag`. A tuple is an array, `Option` is `T | undefined`, or `T | rt.None` where `T` + can already be `undefined`, `Result` an `rt.Result`, `{ ok: true, value }` or `{ ok: + false, error }`, and an error is that value, never thrown. `u8` through `u32`, `usize`, + `isize`, `f32`, `f64`, and `char` are numbers, each checked as it crosses in; `u64`, `i64`, + and `u128` are rust2-ts's `rt.u64` and so on, a number while a safe integer and 32-bit + limbs past it, converted from the `bigint` a wasm `i64` is at the boundary, which costs a + getter 9% over returning that `bigint` as it is. `String` and `&str` are strings, bytes a + `Uint8Array`, a `Vec` of numbers the typed array holding them exactly, any other `Vec` an + array, a path an `rt.PathBuf` of its bytes, and `Duration`, the addresses, and the ranges + plain objects. A `&mut` value is an `rt.Place`, whose `v` the call writes back, and a + value's `&mut self` method returns it first, as Dart's does. +- **Memory**: each call lowers what it passes onto a stack of the binding's in linear + memory, which it gives back once the call returns, and reads what Rust returns at the + layouts C's wasm32 ABI gives the header's structs, passing a struct of one scalar as it, + any other through a pointer to a copy, and one returned through a pointer passed first. + Bytes and text Rust returns are copied out, and the buffer freed at once, so no view + outlives a growth of memory, which detaches it; what Rust lends a closure or trait is + copied before any call it makes can grow memory. A copy costs what V8's allocation of + the `ArrayBuffer` does, about 0.8 µs for 1 KiB on Node 24. +- **Objects** are an `rt.Handle`, disposed by `[Symbol.dispose]`, as `using` does. Of a + checked type, disposing it drops the value through Rust's own `_drop`, which fails while + a call borrows it; of any other, it throws while a call holds it. The handle is freed once + disposed and no call holds it, so one disposed while a later argument lowers fails the + call's check rather than reach Rust freed. A call that meets a disposed handle throws + ` is closed`, and a `FinalizationRegistry` frees one never disposed. On Node 24, a returned object disposed + costs 0.5 µs, 0.2 µs of it the registry's, against 0.1 µs for the C calls alone. +- **Traits** are interfaces JavaScript implements, with an optional `close()` Rust calls + once it drops an implementation, and **closures** are functions: each is a C function + the module imports from `rust2`, whose data is a token the binding finds the value by, so + JavaScript never writes the module's function table. Its std traits are functions of its + module: `toString`, `debug`, an object's `clone`, `eq`, with `Hash` `hash`, and `default`. +- **Futures** are an `rt.Call`, a `Promise` with `cancel()`: the call polls once as it is + made, and each wake polls again on a microtask, never inside the wake. Cancelling frees + the future in Rust, losing nothing, and rejects with `rt.Cancelled`. A future JavaScript + implements is any promise, a waker a function, and a reader an `rt.Reader`. +- **Failure**: a run-time check that fails throws an `Error` naming the C function and the + check, as each binding raises. Rust's panic aborts the module, as do a throw out of a + closure, trait, or reader, since Rust has nowhere to unwind to: the message goes to + `console.error`, and every later call throws, since nothing of Rust's state is sound. +- **Threads**: none. wasm32 runs Rust on JavaScript's one thread, with no shared memory and + no atomics, so no check of a value that is not `Send` or `Sync` can fail. + ## Tests ```bash -just ffi test # export the fixtures, build them, and drive api from C, C++, Kotlin, Python, Swift, Go, and Dart +just ffi test # export the fixtures, build them, and drive api from C, C++, Kotlin, Python, Swift, Go, Dart, and TypeScript on Node just ffi moq # export moq's crates at the pinned revision, build them, and run moq/moq.c, moq/moq.cpp, moq/moq.kt, moq/moq.py, moq/moq.swift, moq/moq.go, and moq/moq.dart just ffi moq-c # the same export, built in debug, running only moq/moq.c: `just ci`'s check on moq just ffi moq-cpp # the same export, running only moq/moq.cpp diff --git a/ffi/fixtures/api/examples/transcript.rs b/ffi/fixtures/api/examples/transcript.rs index ac43a06c8..fdb301600 100644 --- a/ffi/fixtures/api/examples/transcript.rs +++ b/ffi/fixtures/api/examples/transcript.rs @@ -1012,8 +1012,8 @@ fn main() { let nines = api::Mark::of(9); let (front, back) = (api::seat(nines, 1), api::seat(nines, 2)); println!("seat {front:?} {} {}", front == front.clone(), front == back); - // A kept closure, called on another thread after the call that took it returned. - println!("spawned {}", api::Spawned::new(|| 7).join()); + // A kept closure, called on another thread after the call that took it returned, is + // each native language's own check, since wasm32 has no thread to call it on. // A kept closure: called again at the instant it asks for, then once its waiter wakes. let start = api::Moment::new(0, 1000).unwrap(); let mut calls = 0; @@ -1086,15 +1086,15 @@ fn finish(future: F) -> F::Output { } } -/// A path no Rust string spells: on Unix, bytes that are not UTF-8; on Windows, a lone -/// surrogate, which is WTF-8's `ed a0 80`. -#[cfg(unix)] +/// A path no Rust string spells: on Unix and WASI, bytes that are not UTF-8; on Windows, a +/// lone surrogate, which is WTF-8's `ed a0 80`. +#[cfg(any(unix, target_os = "wasi"))] fn unspelled() -> std::path::PathBuf { api::stray() } -/// A path no Rust string spells: on Unix, bytes that are not UTF-8; on Windows, a lone -/// surrogate, which is WTF-8's `ed a0 80`. +/// A path no Rust string spells: on Unix and WASI, bytes that are not UTF-8; on Windows, a +/// lone surrogate, which is WTF-8's `ed a0 80`. #[cfg(windows)] fn unspelled() -> std::path::PathBuf { ::from_wide(&[0xd800]).into() diff --git a/ffi/fixtures/api/src/lib.rs b/ffi/fixtures/api/src/lib.rs index a8ff74935..bcfa58631 100644 --- a/ffi/fixtures/api/src/lib.rs +++ b/ffi/fixtures/api/src/lib.rs @@ -15,6 +15,9 @@ pub use dep::*; /// The largest value a [`Counter`] reaches. pub const LIMIT: u64 = 1000; +/// The largest `i64`, past what a binding's float holds exactly. +pub const FAR: i64 = i64::MAX; + /// A point: a record, since every field is `pub`. Its docs reach the header, where a /// comment such as `/* this */` must not close the header's own. #[derive(Clone, Copy, Debug, PartialEq, Default)] @@ -948,12 +951,14 @@ pub async fn drive(start: Moment, mut poll: impl FnMut(Moment, &Waiter) -> Re .await } +#[cfg(not(target_arch = "wasm32"))] /// A thread running a closure it keeps past the call that made it, which /// [`Spawned::join`] waits on. pub struct Spawned { thread: std::thread::JoinHandle, } +#[cfg(not(target_arch = "wasm32"))] impl Spawned { pub fn new(task: impl FnOnce() -> u32 + Send + 'static) -> Self { Self { @@ -1146,6 +1151,7 @@ impl Channel { /// Sends from another thread, before it returns, so the wake lands from that thread, as /// an async runtime's worker wakes a task: the one way Dart, whose isolates share no /// object, has to wake from another thread. + #[cfg(not(target_arch = "wasm32"))] pub fn send_from_thread(&self, payload: Bytes) { std::thread::scope(|scope| { scope.spawn(|| self.send(payload)); @@ -1713,17 +1719,20 @@ pub fn emit(log: impl Log, lines: Vec) -> u32 { lines.iter().filter(|&&n| log.log(n, &format!("line {n}"))).count() as u32 } +#[cfg(not(target_arch = "wasm32"))] /// [`emit`] on another thread, which the call waits on. pub fn emit_from_thread(log: impl Log, lines: Vec) -> u32 { on_thread(&log, &lines) } +#[cfg(not(target_arch = "wasm32"))] /// [`emit_from_thread`] before it returns its future, and again once polled. pub fn emit_later(log: Box, lines: Vec) -> impl Future + use<> { let eager = on_thread(&*log, &lines); async move { eager + on_thread(&*log, &lines) } } +#[cfg(not(target_arch = "wasm32"))] fn on_thread(log: &(impl Log + ?Sized), lines: &[u8]) -> u32 { std::thread::scope(|scope| { scope @@ -1748,10 +1757,12 @@ pub fn counted(n: u32, mut count: impl FnMut(u32)) -> std::future::Ready, mut keep: impl FnMut(u8, &str) -> bool + Send) -> u32 { - std::thread::scope(|scope| { - let kept = scope.spawn(move || lines.iter().filter(|&&n| keep(n, &format!("line {n}"))).count()); - kept.join().expect("the thread finishes") as u32 - }) + let kept = move || lines.iter().filter(|&&n| keep(n, &format!("line {n}"))).count() as u32; + // wasm32 has no other thread, so it runs there on the caller's. + #[cfg(target_arch = "wasm32")] + return { kept }(); + #[cfg(not(target_arch = "wasm32"))] + std::thread::scope(|scope| scope.spawn(kept).join().expect("the thread finishes")) } /// Logs a line once polled, returning whether it was kept: the future holds `log` until it @@ -1789,16 +1800,19 @@ impl Logger { } /// [`Logger::write`] on another thread, which the call waits on. + #[cfg(not(target_arch = "wasm32"))] pub fn write_from_thread(&self, line: &str) -> bool { std::thread::scope(|scope| scope.spawn(|| self.write(line)).join().expect("the thread finishes")) } } +#[cfg(not(target_arch = "wasm32"))] /// A thread logging a line to a foreign implementation, which [`LogThread::join`] waits on. pub struct LogThread { thread: std::thread::JoinHandle, } +#[cfg(not(target_arch = "wasm32"))] impl LogThread { pub fn new(log: Box, line: String) -> Self { Self { @@ -1812,6 +1826,7 @@ impl LogThread { } } +#[cfg(not(target_arch = "wasm32"))] /// A future that never finishes, whose drop logs a line to `log` on another thread it /// waits on. pub fn log_on_drop(log: Box) -> impl Future + use<> { @@ -1822,13 +1837,16 @@ pub fn log_on_drop(log: Box) -> impl Future + use<> { } } +#[cfg(not(target_arch = "wasm32"))] /// A waker whose wake and drop each log a line to `log` on another thread they wait on. pub fn log_waker(log: Box) -> Waker { Waker::from(Arc::new(LogWake(log))) } +#[cfg(not(target_arch = "wasm32"))] struct LogWake(Box); +#[cfg(not(target_arch = "wasm32"))] impl std::task::Wake for LogWake { fn wake(self: Arc) { self.wake_by_ref(); @@ -1839,14 +1857,17 @@ impl std::task::Wake for LogWake { } } +#[cfg(not(target_arch = "wasm32"))] impl Drop for LogWake { fn drop(&mut self) { on_thread(&*self.0, &[0]); } } +#[cfg(not(target_arch = "wasm32"))] struct LogOnDrop(Box); +#[cfg(not(target_arch = "wasm32"))] impl Drop for LogOnDrop { fn drop(&mut self) { on_thread(&*self.0, &[0]); @@ -3017,16 +3038,18 @@ pub fn file(dir: &std::path::Path, name: &str) -> std::path::PathBuf { dir.join(name) } -/// A path whose bytes are not UTF-8, as a Unix path may be. -#[cfg(unix)] +/// A path whose bytes are not UTF-8, as a Unix or WASI path may be. +#[cfg(any(unix, target_os = "wasi"))] pub fn stray() -> std::path::PathBuf { - std::path::PathBuf::from(::from_vec(vec![ - 0xff, - ])) + #[cfg(unix)] + use std::os::unix::ffi::OsStringExt; + #[cfg(target_os = "wasi")] + use std::os::wasi::ffi::OsStringExt; + std::path::PathBuf::from(std::ffi::OsString::from_vec(vec![0xff])) } /// Lends [`stray`]'s path to `visit`. -#[cfg(unix)] +#[cfg(any(unix, target_os = "wasi"))] pub fn visit_stray(visit: impl Fn(&std::path::Path)) { visit(&stray()); } @@ -3847,6 +3870,39 @@ pub fn pointer_bits(platform: Platform) -> u32 { } } +/// A variant whose field is named as a binding's tag naming the variant. +#[derive(Debug, PartialEq)] +pub enum Labelled { + Tagged { tag: u32 }, + Bare, +} + +/// `labelled`, as it came. +pub fn same_labelled(labelled: Labelled) -> Labelled { + labelled +} + +/// A core of a native target's CPU: a record wasm32 lacks. +#[cfg(not(target_arch = "wasm32"))] +pub struct Core { + pub id: u32, +} + +/// Where work runs, with a variant only native targets have holding a record only they +/// have, which wasm32's binding reads no field of. +pub enum Placement { + /// Wherever the target runs it. + Anywhere, + /// On one core of a native target. + #[cfg(not(target_arch = "wasm32"))] + Pinned(Core), +} + +/// Where the library's target runs work. +pub fn placement() -> Placement { + Placement::Anywhere +} + /// The family of the library's target, a plain enum with a variant only wasm32 has. #[derive(Clone, Copy, PartialEq, Eq, Debug)] pub enum Family { diff --git a/ffi/runtime/rt.rs b/ffi/runtime/rt.rs index 065de10d1..ff32a1560 100644 --- a/ffi/runtime/rt.rs +++ b/ffi/runtime/rt.rs @@ -353,7 +353,7 @@ impl Buf { } } - /// As [`Self::vec_in`], as a path: its bytes as the OS holds them on Unix, WTF-8 on + /// As [`Self::vec_in`], as a path: its bytes as the OS holds them on Unix and WASI, WTF-8 on /// Windows, else UTF-8. /// /// # Safety @@ -361,12 +361,12 @@ impl Buf { pub unsafe fn path_in(self, what: &str, take: bool) -> std::path::PathBuf { // SAFETY: the caller's contract. let bytes = unsafe { self.vec_in(what, take) }; - #[cfg(unix)] + #[cfg(any(unix, target_os = "wasi"))] { - use std::os::unix::ffi::OsStringExt; + use bytes_os::OsStringExt; std::path::PathBuf::from(std::ffi::OsString::from_vec(bytes)) } - #[cfg(not(unix))] + #[cfg(not(any(unix, target_os = "wasi")))] match String::from_utf8(bytes) { Ok(s) => std::path::PathBuf::from(s), Err(err) => decoded(err.as_bytes(), what), @@ -380,7 +380,7 @@ impl Buf { pub unsafe fn hold_path<'a>(self, what: &str) -> HeldPath<'a> { // SAFETY: the caller's contract. let held = unsafe { self.hold(what) }; - #[cfg(not(unix))] + #[cfg(not(any(unix, target_os = "wasi")))] if std::str::from_utf8(held.bytes()).is_err() { return HeldPath::Decoded(decoded(held.bytes(), what)); } @@ -473,7 +473,7 @@ impl Buf { Self::owned(vec.into()) } - /// A path handed to the caller: its bytes as the OS holds them on Unix, else as + /// A path handed to the caller: its bytes as the OS holds them on Unix and WASI, else as /// Rust encodes them: WTF-8 on Windows, which is UTF-8 for any path that has a UTF-8 /// form. pub fn path_buf(path: std::path::PathBuf) -> Self { @@ -541,26 +541,32 @@ impl Hold<'_> { } } +/// The `OsStr` extensions of a platform whose paths are any bytes, as Unix's and WASI's are. +#[cfg(unix)] +use std::os::unix::ffi as bytes_os; +#[cfg(target_os = "wasi")] +use std::os::wasi::ffi as bytes_os; + /// A path passed in for a call: the bytes [`Hold`] holds, or on a platform whose paths /// are not bytes, what they decode to where they are not UTF-8. pub enum HeldPath<'a> { Held(Hold<'a>), - #[cfg(not(unix))] + #[cfg(not(any(unix, target_os = "wasi")))] Decoded(std::path::PathBuf), } impl HeldPath<'_> { pub fn path(&self) -> &std::path::Path { match self { - #[cfg(unix)] + #[cfg(any(unix, target_os = "wasi"))] Self::Held(held) => { - use std::os::unix::ffi::OsStrExt; + use bytes_os::OsStrExt; std::path::Path::new(std::ffi::OsStr::from_bytes(held.bytes())) } // UTF-8, or else decoded. - #[cfg(not(unix))] + #[cfg(not(any(unix, target_os = "wasi")))] Self::Held(held) => std::path::Path::new(std::str::from_utf8(held.bytes()).unwrap_or_default()), - #[cfg(not(unix))] + #[cfg(not(any(unix, target_os = "wasi")))] Self::Decoded(path) => path, } } @@ -568,7 +574,7 @@ impl HeldPath<'_> { /// The path a caller's bytes encode that are not UTF-8: on Windows, WTF-8, as Rust /// encodes a name that is not UTF-16, any other aborting; elsewhere, none. -#[cfg(not(unix))] +#[cfg(not(any(unix, target_os = "wasi")))] #[cold] fn decoded(bytes: &[u8], what: &str) -> std::path::PathBuf { #[cfg(windows)] diff --git a/ffi/runtime/rt.ts b/ffi/runtime/rt.ts new file mode 100644 index 000000000..fc04e89e7 --- /dev/null +++ b/ffi/runtime/rt.ts @@ -0,0 +1,1321 @@ +// The runtime every generated web binding imports, which rust2-ffi copies beside it: the +// module and its memory, the stack a call lowers its values into, handles, Rust's integers +// past 32 bits, futures as promises, what JavaScript implements for Rust, and the web APIs +// that stand in for what the module's std imports. + +declare const brand: unique symbol; + +/** A `u64` past 2^53: its high and low 32 bits, each a uint32. */ +export type U64Limbs = { readonly hi: number; readonly lo: number; readonly [brand]: "u64" }; +/** An `i64` past 2^53 in magnitude: its high 32 bits as an int32, and its low as a uint32. */ +export type I64Limbs = { readonly hi: number; readonly lo: number; readonly [brand]: "i64" }; +/** A `u128` past 2^53: four 32-bit limbs, `hi`, `w2`, `w1`, and `lo`, each a uint32. */ +export type U128Limbs = { + readonly hi: number; + readonly w2: number; + readonly w1: number; + readonly lo: number; + readonly [brand]: "u128"; +}; + +/** + * A number of the Rust integer type `T`: its brand is type-only, so a plain number, such + * as a literal, passes for any. + */ +type Num = number & { readonly [brand]?: T }; + +/** + * Rust's `u64`: a number while it is a safe integer, at most 2^53 - 1, and its limbs past + * that. Each value has one form, so two compare with `===` only as numbers. + */ +export type u64 = Num<"u64"> | U64Limbs; +/** Rust's `i64`: a number while it is a safe integer, and its limbs past that. */ +export type i64 = Num<"i64"> | I64Limbs; +/** Rust's `u128`: a number while it is a safe integer, and its limbs past that. */ +export type u128 = Num<"u128"> | U128Limbs; + +/** Rust's `Result`: `{ ok: true, value }` or `{ ok: false, error }`. */ +export type Result = { readonly ok: true; readonly value: T } | { readonly ok: false; readonly error: E }; + +/** An `Ok`. */ +export function Ok(value: T): Result { + return { ok: true, value }; +} + +/** An `Err`. */ +export function Err(error: E): Result { + return { ok: false, error }; +} + +/** The `None` of an `Option` whose `Some` may be `undefined`, as `Option<()>`'s is. */ +export const None: unique symbol = Symbol("None"); +export type None = typeof None; + +/** A place a call writes back what Rust left a `&mut` value as, in `v`. */ +export type Place = { v: T }; + +// The key only `opaqueMade` holds, and the private field's accessors. +const minting: unique symbol = Symbol("minting"); +let made: (bytes: Uint8Array) => Opaque; +let bytesOf: (v: Opaque) => Uint8Array | undefined; + +/** + * A `Copy` type whose fields are private: its bytes, which only Rust makes or reads, so + * JavaScript copies one but never makes one. + */ +export class Opaque { + declare readonly [brand]: T; + // Private, so no caller makes or changes one: the bytes may hold what Rust forbids, such + // as a zero `NonZero`. + readonly #bytes: Uint8Array; + private constructor(bytes: Uint8Array, key: symbol) { + if (key !== minting) throw new TypeError("only Rust makes an opaque value"); + this.#bytes = bytes; + } + static { + made = (bytes) => new Opaque(bytes, minting); + bytesOf = (v) => (#bytes in v ? v.#bytes : undefined); + } +} + +/** The generated glue's only: the opaque value of bytes Rust wrote. */ +export function opaqueMade(bytes: Uint8Array): Opaque { + return made(bytes); +} + +/** + * Copy an opaque value's bytes into memory at `p`, throwing unless it is one Rust made, of + * `n` bytes. It returns nothing, so the bytes never reach a caller to change. + */ +export function opaquePut(v: Opaque, n: number, p: number): void { + const bytes = bytesOf(v); + if (bytes === undefined || bytes.length !== n) throw new RangeError("a value Rust made is no other's"); + mem().set(bytes, p); +} + +/** Rust's `Duration`: whole seconds, and the nanoseconds below one. */ +export type Duration = { readonly secs: u64; readonly nanos: number }; + +/** Rust's `PathBuf`: the path's bytes as the OS holds them, which may not be UTF-8. */ +export type PathBuf = { readonly bytes: Uint8Array }; + +/** The path of `text`, as UTF-8: a lone surrogate throws, as no Rust string holds one. */ +export function pathFrom(text: string): PathBuf { + return { bytes: encoded(text) }; +} + +/** A path's text: what is not UTF-8 is replaced, as Rust's `Path::display` shows it. */ +export function pathText(path: PathBuf): string { + return loose.decode(path.bytes); +} + +/** Rust's `Ipv4Addr`: its 4 bytes in network order. */ +export type Ipv4Addr = { readonly octets: Uint8Array }; +/** Rust's `Ipv6Addr`: its 16 bytes in network order. */ +export type Ipv6Addr = { readonly octets: Uint8Array }; +/** Rust's `IpAddr`. */ +export type IpAddr = { readonly tag: "V4"; readonly _0: Ipv4Addr } | { readonly tag: "V6"; readonly _0: Ipv6Addr }; +/** Rust's `SocketAddrV4`. */ +export type SocketAddrV4 = { readonly ip: Ipv4Addr; readonly port: number }; +/** Rust's `SocketAddrV6`: with its flow label and scope. */ +export type SocketAddrV6 = { + readonly ip: Ipv6Addr; + readonly port: number; + readonly flowinfo: number; + readonly scopeId: number; +}; +/** Rust's `SocketAddr`. */ +export type SocketAddr = + | { readonly tag: "V4"; readonly _0: SocketAddrV4 } + | { readonly tag: "V6"; readonly _0: SocketAddrV6 }; + +/** Where a reader's seek counts from, as Rust's `SeekFrom` does. */ +export type SeekFrom = "Start" | "Current" | "End"; + +/** + * Bytes Rust reads and seeks, as its `Read + Seek`, lent for the call it is passed to. + * What either method throws reaches Rust as an `io::Error` of its message. + */ +export interface Reader { + /** Read up to `buffer.length` bytes into `buffer`, returning how many: 0 only at the end. */ + read(buffer: Uint8Array): number; + /** + * Move to `offset` from `from`, returning the position from the start. From `"Start"`, + * `offset` is a `u64`, else an `i64`. + */ + seek(offset: u64 | i64, from: SeekFrom): u64; +} + +/** The value of a call into Rust's async API: a promise of its result, which `cancel` cancels. */ +export type Call = Promise & { + /** Cancel it in Rust unless it finished, losing nothing: it then rejects with `Cancelled`. */ + cancel(): void; +}; + +/** What a cancelled `Call` rejects with. */ +export class Cancelled extends Error { + constructor() { + super("Cancelled"); + this.name = "Cancelled"; + } +} + +/** A waker Rust returned: `wake` wakes its task through Rust, and disposing it drops it. */ +export type Waker = { wake(): void; [Symbol.dispose](): void }; + +/** The module's exports, which generated code calls by their C names. */ +type Exports = Record; + +/** The module's exports, once `load` instantiated it. */ +export let w: Exports = new Proxy( + {}, + { + get(_, name) { + throw new Error(`${String(name)}: the module is not loaded: call load first`); + }, + }, +); + +let memory: WebAssembly.Memory; +let view = new DataView(new ArrayBuffer(0)); +let bytes: Uint8Array = new Uint8Array(0); + +/** A view of the module's memory, made again once memory grows, which detaches the last. */ +export function dv(): DataView { + if (view.buffer !== memory.buffer) { + view = new DataView(memory.buffer); + bytes = new Uint8Array(memory.buffer); + } + return view; +} + +/** The module's memory as bytes, as [dv] keeps it. */ +export function mem(): Uint8Array { + dv(); + return bytes; +} + +/** + * The state calls share: how many calls into the module are running less how many calls + * out of it, which each call into it from JavaScript finds at 0 unless a call trapped, + * when a call in did not return. + */ +export const s = { d: 0 }; + +/** Why the module aborted, after which every call throws: nothing of Rust's state is sound. */ +let aborted: unknown; + +/** + * Whether Rust may run: no call aborted, nor trapped, which unwinds past the `s.d--` after + * it and leaves `s.d` raised wherever JavaScript runs next. + */ +function live(): boolean { + if (s.d !== 0) aborted ??= new Error("a call into the module trapped"); + return aborted === undefined; +} + +/** The error of a call into a module that aborted. */ +function dead(): Error { + return new Error("the module aborted, so no call into it runs", { cause: aborted }); +} + +/** Abort the module with `message`: Rust's own abort, which prints it and traps. */ +export function abort(message: string): never { + if (aborted === undefined) { + const m = top; + const max = message.length * 3; + const p = alloc(max, 1); + const { written } = encoder.encodeInto(message, mem().subarray(p, p + max)); + try { + w[`${space}_abort`](p, written); + } catch (e) { + aborted = e; + } + top = m; + } + aborted ??= new Error(message); + throw dead(); +} + +// The stack: memory each call lowers its values into, taking what it needs from the top and +// giving it back once it returns, so a call Rust makes into JavaScript meanwhile takes and +// gives back above it. +const STACK = 1 << 16; +let base = 0; +let top = 0; +/** What did not fit, each its pointer, size, and alignment, freed as the stack falls back. */ +const big: number[] = []; +/** The handles each running call holds, released once it returns. */ +const held: Handle[] = []; +/** The tokens of what each running call lends Rust, forgotten once it returns. */ +const lent: number[] = []; +/** Where each running call found the stack: its top, then the length of each list. */ +const frames: number[] = []; + +/** Start a call: what [leave] takes back to. */ +export function enter(): number { + if (aborted !== undefined) throw dead(); + if (s.d !== 0) { + aborted = new Error("a call into the module trapped"); + throw dead(); + } + frames.push(top, big.length, held.length, lent.length); + return frames.length; +} + +/** End the call [enter] started, giving back what it took. */ +export function leave(mark: number): void { + frames.length = mark; + const l = frames.pop()!; + const h = frames.pop()!; + const b = frames.pop()!; + top = frames.pop()!; + while (lent.length > l) tokens.delete(lent.pop()!); + // After a trap, Rust's state is unsound: forget what the call took, calling none of it. + if (!live()) { + held.length = h; + big.length = b; + return; + } + while (held.length > h) held.pop()!.release(); + while (big.length > b) { + const align = big.pop()!; + const size = big.pop()!; + w[`${space}_free`](big.pop()!, size, align); + } +} + +/** `size` bytes aligned to `align`, a power of two, until the running call returns. */ +export function alloc(size: number, align: number): number { + const at = (top + align - 1) & -align; + if (at + size <= STACK) { + top = at + size; + return base + at; + } + const p = w[`${space}_alloc`](size, align) as number; + big.push(p, size, align); + return p; +} + +/** Throw unless the call `what` wrote no status at `p`: a run-time check failed. */ +export function status(p: number, what: string): void { + const n = dv().getInt32(p, true); + if (n !== 0) throw new Error(`${what}: ${STATUSES[n - 1] ?? "an unknown status"}`); +} + +const STATUSES = [ + "a handle's value was moved out", + "a handle is borrowed exclusively", + "a handle is already borrowed", + "a handle is borrowed on another thread", + "a handle a call lent is borrowed exclusively or moved out", + "a handle lent from another outlived it: the other was borrowed exclusively, moved out, or freed", + "a value that is not Send is used on another thread than the one that made it", +]; + +/** What each object type's handles do: its name, its free, and its drop, if Rust checks it. */ +export type Kind = { + readonly name: string; + readonly free: string; + readonly drop?: string; +}; + +/** The handles' frees the garbage collector makes, of each that was never disposed. */ +const collected = new FinalizationRegistry<[number, string]>(([p, free]) => { + if (!live()) return; + s.d++; + w[free](p); + s.d--; +}); + +/** + * A handle to a Rust object, which counts the calls holding it. An owned one of a value + * Rust checks is Rust's to account: disposing it drops the value as Rust's own drop does, + * failing while a call borrows it, so a call after it throws. Any other throws if disposed + * while a call holds it. Either is freed once disposed and no call holds it, since a call + * still lowering its arguments has passed its pointer, or once the garbage collector finds + * it unreachable, if it was never disposed. + */ +export class Handle { + declare readonly [brand]: T; + /** The handle's pointer. */ + readonly p: number; + readonly k: Kind; + /** The owner's hold until disposed, and one for each call. */ + h = 1; + closed = false; + readonly owned: boolean; + /** Whether disposing it drops its value through Rust's `_drop`. */ + readonly checked: boolean; + + constructor(p: number, k: Kind, owned: boolean) { + this.p = p; + this.k = k; + this.owned = owned; + this.checked = owned && k.drop !== undefined; + if (owned) collected.register(this, [p, k.free], this); + } + + hold(): number { + if (this.closed) throw new Error(`${this.k.name} is closed`); + this.h++; + return this.p; + } + + release(): void { + if (--this.h === 0 && this.owned) this.free(); + } + + free(): void { + collected.unregister(this); + const m = enter(); + s.d++; + w[this.k.free](this.p); + s.d--; + leave(m); + } + + /** Close it as `Handle` says; again, it does nothing. */ + [Symbol.dispose](): void { + if (this.closed) return; + if (this.checked) { + const m = enter(); + try { + const st = alloc(4, 4); + dv().setInt32(st, 0, true); + s.d++; + w[this.k.drop!](this.p, st); + s.d--; + status(st, this.k.drop!); + } finally { + leave(m); + } + // Dropped, so a call that still holds it fails Rust's check, and none can hold it + // again: it is freed with its last hold, rather than by the garbage collector, whose + // registry costs a returned object ten times its call once it holds many. + } else if (this.h !== 1) { + throw new Error(`${this.k.name}: a handle is already borrowed`); + } + this.closed = true; + this.release(); + } +} + +/** `handle`'s pointer, held until the running call returns: a closed one throws. */ +export function hold(handle: Handle): number { + const p = handle.hold(); + held.push(handle); + return p; +} + +/** [hold] of a handle, or 0 for none. */ +export function holdOr(handle: Handle | undefined): number { + return handle === undefined ? 0 : hold(handle); +} + +/** A handle Rust lends for a call, closed after it. */ +export function lentHandle(p: number, k: Kind): Handle { + return new Handle(p, k, false); +} + +// Integers. + +const TWO32 = 4294967296; + +/** `v`, unless it is no integer from `min` through `max`, which throws naming `what`. */ +export function int(v: number, min: number, max: number, what: string): number { + if (Number.isInteger(v) && v >= min && v <= max) return v; + throw new RangeError(`${v} is no ${what}`); +} + +/** A `NonZero`'s integer, which throws if zero. */ +export function nonZero(v: T): T { + if (v === 0) throw new RangeError("a NonZero is zero"); + return v; +} + +/** An `f32`: a number a single holds exactly, or NaN. */ +export function f32(v: number): number { + if (Math.fround(v) === v || v !== v) return v; + throw new RangeError(`${v} is no f32`); +} + +/** A `char`: a Unicode scalar value. */ +export function char(v: number): number { + if (Number.isInteger(v) && v >= 0 && v <= 0x10ffff && (v < 0xd800 || v > 0xdfff)) return v; + throw new RangeError(`${v} is no char`); +} + +/** The `u64` of its halves, each a uint32. */ +export function u64Of(hi: number, lo: number): u64 { + return hi < 0x200000 ? hi * TWO32 + lo : ({ hi, lo } as U64Limbs); +} + +/** The `i64` of its halves, `hi` an int32 and `lo` a uint32. */ +export function i64Of(hi: number, lo: number): i64 { + if (hi >= -0x200000 && hi < 0x200000) { + const v = hi * TWO32 + lo; + if (Number.isSafeInteger(v)) return v; + } + return { hi, lo } as I64Limbs; +} + +/** A `u64`'s halves, `[hi, lo]`, each a uint32: one out of range throws. */ +export function u64Halves(v: u64): [number, number] { + if (typeof v === "number") { + if (!Number.isSafeInteger(v) || v < 0) throw new RangeError(`${v} is no u64`); + return [Math.floor(v / TWO32), v % TWO32]; + } + if (!(v.hi >= 0x200000 && v.hi <= 0xffffffff && Number.isInteger(v.hi) && v.lo >>> 0 === v.lo)) { + throw new RangeError(`${JSON.stringify(v)} is no u64 in its one form`); + } + return [v.hi, v.lo]; +} + +/** An `i64`'s halves, `[hi, lo]`, `hi` an int32 and `lo` a uint32: one out of range throws. */ +export function i64Halves(v: i64): [number, number] { + if (typeof v === "number") { + if (!Number.isSafeInteger(v)) throw new RangeError(`${v} is no i64`); + const hi = Math.floor(v / TWO32); + return [hi | 0, v - hi * TWO32]; + } + const safe = v.hi >= -0x200000 && v.hi < 0x200000 && Number.isSafeInteger(v.hi * TWO32 + v.lo); + if (safe || v.hi !== (v.hi | 0) || v.lo >>> 0 !== v.lo) { + throw new RangeError(`${JSON.stringify(v)} is no i64 in its one form`); + } + return [v.hi, v.lo]; +} + +/** The `u64` at `p`. */ +export function u64Get(p: number): u64 { + const d = dv(); + return u64Of(d.getUint32(p + 4, true), d.getUint32(p, true)); +} + +/** The `i64` at `p`. */ +export function i64Get(p: number): i64 { + const d = dv(); + return i64Of(d.getInt32(p + 4, true), d.getUint32(p, true)); +} + +/** Write the `u64` `v` at `p`. */ +export function u64Put(p: number, v: u64): void { + const [hi, lo] = u64Halves(v); + const d = dv(); + d.setUint32(p, lo, true); + d.setUint32(p + 4, hi, true); +} + +/** Write the `i64` `v` at `p`. */ +export function i64Put(p: number, v: i64): void { + const [hi, lo] = i64Halves(v); + const d = dv(); + d.setUint32(p, lo, true); + d.setInt32(p + 4, hi, true); +} + +/** A `u64` as the `bigint` a wasm `i64` takes. */ +export function u64Big(v: u64): bigint { + if (typeof v === "number" && Number.isSafeInteger(v) && v >= 0) return BigInt(v); + const [hi, lo] = u64Halves(v); + return BigInt.asIntN(64, (BigInt(hi) << 32n) | BigInt(lo)); +} + +/** An `i64` as the `bigint` a wasm `i64` takes. */ +export function i64Big(v: i64): bigint { + if (typeof v === "number" && Number.isSafeInteger(v)) return BigInt(v); + const [hi, lo] = i64Halves(v); + return (BigInt(hi) << 32n) | BigInt(lo); +} + +/** The `u64` of what a wasm `i64` returned. */ +export function u64OfBig(v: bigint): u64 { + const u = BigInt.asUintN(64, v); + return u <= 0x1fffffffffffffn ? Number(u) : u64Of(Number(u >> 32n), Number(u & 0xffffffffn)); +} + +/** The `i64` of what a wasm `i64` returned. */ +export function i64OfBig(v: bigint): i64 { + return v >= -0x1fffffffffffffn && v <= 0x1fffffffffffffn + ? Number(v) + : i64Of(Number(v >> 32n), Number(BigInt.asUintN(32, v))); +} + +/** The `u128` at `p`, as its low then high 64 bits. */ +export function u128Get(p: number): u128 { + const d = dv(); + const lo = d.getUint32(p, true); + const w1 = d.getUint32(p + 4, true); + const w2 = d.getUint32(p + 8, true); + const hi = d.getUint32(p + 12, true); + if (hi === 0 && w2 === 0 && w1 < 0x200000) return w1 * TWO32 + lo; + return { hi, w2, w1, lo } as U128Limbs; +} + +/** Write the `u128` `v` at `p`. */ +export function u128Put(p: number, v: u128): void { + let words: number[]; + if (typeof v === "number") { + if (!Number.isSafeInteger(v) || v < 0) throw new RangeError(`${v} is no u128`); + words = [v % TWO32, Math.floor(v / TWO32), 0, 0]; + } else { + words = [v.lo, v.w1, v.w2, v.hi]; + const one = words.every((x) => x >>> 0 === x) && (v.hi !== 0 || v.w2 !== 0 || v.w1 >= 0x200000); + if (!one) throw new RangeError(`${JSON.stringify(v)} is no u128 in its one form`); + } + const d = dv(); + for (let i = 0; i < 4; i++) d.setUint32(p + 4 * i, words[i], true); +} + +/** A `u64` as a `bigint`, for printing or arithmetic. */ +export function u64ToBig(v: u64): bigint { + return BigInt.asUintN(64, u64Big(v)); +} + +/** An `i64` as a `bigint`. */ +export function i64ToBig(v: i64): bigint { + return i64Big(v); +} + +/** A `u128` as a `bigint`. */ +export function u128ToBig(v: u128): bigint { + if (typeof v === "number") return BigInt(v); + return (BigInt(v.hi) << 96n) | (BigInt(v.w2) << 64n) | (BigInt(v.w1) << 32n) | BigInt(v.lo); +} + +/** The `u64` of a `bigint`, which throws outside its range. */ +export function u64FromBig(v: bigint): u64 { + if (v < 0n || v > 0xffffffffffffffffn) throw new RangeError(`${v} is no u64`); + return u64OfBig(v); +} + +/** The `i64` of a `bigint`, which throws outside its range. */ +export function i64FromBig(v: bigint): i64 { + if (v < -0x8000000000000000n || v > 0x7fffffffffffffffn) throw new RangeError(`${v} is no i64`); + return i64OfBig(v); +} + +/** The `u128` of a `bigint`, which throws outside its range. */ +export function u128FromBig(v: bigint): u128 { + if (v < 0n || v >> 128n !== 0n) throw new RangeError(`${v} is no u128`); + if (v <= 0x1fffffffffffffn) return Number(v); + const word = (n: bigint) => Number(BigInt.asUintN(32, v >> n)); + return { hi: word(96n), w2: word(64n), w1: word(32n), lo: word(0n) } as U128Limbs; +} + +// Text and bytes. + +const encoder = new TextEncoder(); +// A leading U+FEFF is text Rust holds, not a mark to drop. +const strict = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }); +const loose = new TextDecoder("utf-8", { ignoreBOM: true }); + +/** `text`'s UTF-8, throwing where it holds a lone surrogate, which no Rust string does. */ +export function encoded(text: string): Uint8Array { + if (!text.isWellFormed()) throw new RangeError("a string holds a lone surrogate, which no Rust string does"); + return encoder.encode(text); +} + +/** Write a view of `text`'s UTF-8 on the stack into the buffer at `dst`. */ +export function putStr(dst: number, text: string): void { + if (!text.isWellFormed()) throw new RangeError("a string holds a lone surrogate, which no Rust string does"); + const max = text.length * 3; + const p = alloc(max, 1); + const { written } = encoder.encodeInto(text, mem().subarray(p, p + max)); + const d = dv(); + d.setUint32(dst, p, true); + d.setUint32(dst + 4, written, true); + d.setUint32(dst + 8, 0, true); +} + +/** Write a view of a copy of `data` on the stack into the buffer at `dst`. */ +export function putBytes(dst: number, data: Uint8Array): void { + const p = alloc(data.length, 1); + mem().set(data, p); + const d = dv(); + d.setUint32(dst, p, true); + d.setUint32(dst + 4, data.length, true); + d.setUint32(dst + 8, 0, true); +} + +/** Write the null buffer, `None`, at `dst`. */ +export function putNone(dst: number): void { + const d = dv(); + d.setUint32(dst, 0, true); + d.setUint32(dst + 4, 0, true); + d.setUint32(dst + 8, 0, true); +} + +/** Whether the buffer at `p` is `None`. */ +export function isNone(p: number): boolean { + return dv().getUint32(p, true) === 0; +} + +/** A copy of the bytes the buffer at `p` views. */ +export function bytesLent(p: number): Uint8Array { + const d = dv(); + const ptr = d.getUint32(p, true); + const len = d.getUint32(p + 4, true); + return mem().slice(ptr, ptr + len); +} + +/** The text of the UTF-8 the buffer at `p` views. */ +export function strLent(p: number): string { + const d = dv(); + const ptr = d.getUint32(p, true); + const len = d.getUint32(p + 4, true); + return len === 0 ? "" : strict.decode(mem().subarray(ptr, ptr + len)); +} + +/** A copy of the bytes of the buffer Rust returned at `p`, which it frees. */ +export function bytes_(p: number): Uint8Array { + const out = bytesLent(p); + w[`${prefix}_buf_free`](p); + return out; +} + +/** The text of the buffer Rust returned at `p`, which it frees. */ +export function str(p: number): string { + const out = strLent(p); + w[`${prefix}_buf_free`](p); + return out; +} + +/** Rust's own copy of `text`, as `buf_copy` makes it, written at `dst`: what a closure returns. */ +export function copied(dst: number, text: string, message = false): void { + const m = top; + const view = alloc(12, 4); + if (message) putBytes(view, encoder.encode(text)); + else putStr(view, text); + s.d++; + w[`${prefix}_buf_copy`](dst, view); + s.d--; + top = m; +} + +/** Rust's own copy of `data`, as `buf_copy` makes it, written at `dst`. */ +export function copiedBytes(dst: number, data: Uint8Array): void { + const m = top; + const view = alloc(12, 4); + putBytes(view, data); + s.d++; + w[`${prefix}_buf_copy`](dst, view); + s.d--; + top = m; +} + +/** `bytes`, which throws unless it holds exactly `n`. */ +export function array(data: Uint8Array, n: number): Uint8Array { + if (data.length !== n) throw new RangeError(`${data.length} bytes are no [u8; ${n}]`); + return data; +} + +/** A path's bytes, which may be any on wasm32, as on Unix. */ +export function pathBytes(path: PathBuf): Uint8Array { + return path.bytes; +} + +// Values of std's types, as the C ABI lays them out. + +/** The `Duration` at `p`. */ +export function durationGet(p: number): Duration { + return { secs: u64Get(p), nanos: dv().getUint32(p + 8, true) }; +} + +/** Write the `Duration` `v` at `p`: nanoseconds of a second or more throw. */ +export function durationPut(p: number, v: Duration): void { + int(v.nanos, 0, 999999999, "Duration's nanoseconds"); + u64Put(p, v.secs); + dv().setUint32(p + 8, v.nanos, true); +} + +function octets(p: number, n: number): Uint8Array { + return mem().slice(p, p + n); +} + +function putOctets(p: number, v: Uint8Array, n: number): void { + if (!(v instanceof Uint8Array) || v.length !== n) throw new RangeError(`an address is no ${n} bytes`); + mem().set(v, p); +} + +export function ipv4Get(p: number): Ipv4Addr { + return { octets: octets(p, 4) }; +} + +export function ipv4Put(p: number, v: Ipv4Addr): void { + putOctets(p, v.octets, 4); +} + +export function ipv6Get(p: number): Ipv6Addr { + return { octets: octets(p, 16) }; +} + +export function ipv6Put(p: number, v: Ipv6Addr): void { + putOctets(p, v.octets, 16); +} + +export function ipGet(p: number): IpAddr { + return dv().getUint8(p) !== 0 ? { tag: "V6", _0: ipv6Get(p + 1) } : { tag: "V4", _0: ipv4Get(p + 1) }; +} + +export function ipPut(p: number, v: IpAddr): void { + dv().setUint8(p, v.tag === "V6" ? 1 : 0); + if (v.tag === "V6") ipv6Put(p + 1, v._0); + else if (v.tag === "V4") ipv4Put(p + 1, v._0); + else throw new RangeError("an IpAddr is V4 or V6"); +} + +export function socketV4Get(p: number): SocketAddrV4 { + return { ip: ipv4Get(p), port: dv().getUint16(p + 4, true) }; +} + +export function socketV4Put(p: number, v: SocketAddrV4): void { + ipv4Put(p, v.ip); + dv().setUint16(p + 4, int(v.port, 0, 0xffff, "port"), true); +} + +export function socketV6Get(p: number): SocketAddrV6 { + const d = dv(); + return { + ip: ipv6Get(p), + port: d.getUint16(p + 16, true), + flowinfo: d.getUint32(p + 20, true), + scopeId: d.getUint32(p + 24, true), + }; +} + +export function socketV6Put(p: number, v: SocketAddrV6): void { + ipv6Put(p, v.ip); + const d = dv(); + d.setUint16(p + 16, int(v.port, 0, 0xffff, "port"), true); + d.setUint32(p + 20, int(v.flowinfo, 0, 0xffffffff, "flow label"), true); + d.setUint32(p + 24, int(v.scopeId, 0, 0xffffffff, "scope"), true); +} + +export function socketGet(p: number): SocketAddr { + return dv().getUint8(p) !== 0 ? { tag: "V6", _0: socketV6Get(p + 4) } : { tag: "V4", _0: socketV4Get(p + 4) }; +} + +export function socketPut(p: number, v: SocketAddr): void { + dv().setUint8(p, v.tag === "V6" ? 1 : 0); + if (v.tag === "V6") socketV6Put(p + 4, v._0); + else if (v.tag === "V4") socketV4Put(p + 4, v._0); + else throw new RangeError("a SocketAddr is V4 or V6"); +} + +// What JavaScript implements for Rust, each found by its token. + +/** Each value Rust holds or a call lends, by token, and what Rust's drop of it calls. */ +const tokens = new Map(); +const drops = new Map void>(); +let token = 0; + +/** A token for `value`, which Rust frees through `free`, calling `drop` then. */ +export function give(value: unknown, drop?: () => void): number { + const t = ++token; + tokens.set(t, value); + if (drop) drops.set(t, drop); + return t; +} + +/** A token for `value`, forgotten once the running call returns. */ +export function lend(value: unknown): number { + const t = ++token; + tokens.set(t, value); + lent.push(t); + return t; +} + +/** The value of `t`. */ +export function find(t: number): T { + return tokens.get(t) as T; +} + +/** The table index of each C function the runtime's values take, as `fns` gives them. */ +export const fn = { wake: 0, wakerDrop: 0, free: 0, poll: 0, read: 0, seek: 0 }; + +/** + * Run `f`, which JavaScript does for Rust inside a call, aborting the module on what it + * throws, since Rust has nowhere to unwind to. + */ +export function out(what: string, f: () => T): T { + // What `f` takes of the stack, it gives back: a value lowered there is read by now. + const m = top; + s.d--; + try { + return f(); + } catch (e) { + if (aborted !== undefined) throw e; + return abort(`${what}: a call into JavaScript threw ${e instanceof Error ? (e.stack ?? e) : String(e)}`); + } finally { + s.d++; + top = m; + } +} + +/** Write a waker of `t`'s wakes at `dst`. */ +function putWaker(dst: number, t: number): void { + const d = dv(); + d.setUint32(dst, fn.wake, true); + d.setUint32(dst + 4, fn.wakerDrop, true); + d.setUint32(dst + 8, t, true); +} + +/** What each token's wake calls, and what dropping its last waker calls. */ +const wakes = new Map void>(); + +/** Write at `dst` a waker Rust holds until it drops it, calling `wake` on a microtask. */ +export function wakerOf(dst: number, wake: () => void): void { + const t = ++token; + wakes.set(t, wake); + drops.set(t, () => wakes.delete(t)); + putWaker(dst, t); +} + +/** A waker Rust returned at `p`, the caller's to wake through Rust and drop once. */ +export function wakerGet(p: number): Waker { + const d = dv(); + const wake = d.getUint32(p, true); + const drop = d.getUint32(p + 4, true); + const data = d.getUint32(p + 8, true); + let dropped = false; + const waker = { + wake() { + if (dropped) throw new Error("Waker is closed"); + const m = enter(); + s.d++; + w[`${space}_call`](wake, data); + s.d--; + leave(m); + }, + [Symbol.dispose]() { + if (dropped) return; + dropped = true; + wakers.unregister(waker); + const m = enter(); + s.d++; + w[`${space}_call`](drop, data); + s.d--; + leave(m); + }, + }; + wakers.register(waker, [drop, data], waker); + return waker; +} + +const wakers = new FinalizationRegistry<[number, number]>(([drop, data]) => { + if (!live()) return; + s.d++; + w[`${space}_call`](drop, data); + s.d--; +}); + +/** A future JavaScript gave Rust: its promise's outcome, and the waker of Rust's last poll. */ +type Foreign = { done: boolean; failed: unknown; wake: number; drop: number; data: number; call?: Call }; + +/** Write at `dst` the future Rust polls of `promise`, until it completes. */ +export function futureOf(dst: number, promise: Promise): void { + const f: Foreign = { done: false, failed: undefined, wake: 0, drop: 0, data: 0 }; + if (calls.has(promise)) f.call = promise as Call; + const t = give(f, () => { + f.done = true; + release(f); + f.call?.cancel(); + }); + promise.then( + () => settle(f, undefined), + (e) => settle(f, e ?? new Error("a future given to Rust rejected")), + ); + const d = dv(); + d.setUint32(dst, fn.poll, true); + d.setUint32(dst + 4, fn.free, true); + d.setUint32(dst + 8, t, true); +} + +function settle(f: Foreign, failed: unknown): void { + if (f.done) return; + if (failed !== undefined) { + if (!(failed instanceof Cancelled)) abort(`a future given to Rust: it rejected with ${failed}`); + } + f.done = true; + const { wake, data } = f; + if (data === 0 || aborted !== undefined) return; + const m = enter(); + s.d++; + w[`${space}_call`](wake, data); + s.d--; + leave(m); + release(f); +} + +/** Drop the waker `f` holds, if any. */ +function release(f: Foreign): void { + if (f.data === 0 || aborted !== undefined) return; + const { drop, data } = f; + f.data = 0; + const m = enter(); + s.d++; + w[`${space}_call`](drop, data); + s.d--; + leave(m); +} + +/** Write at `dst` `reader`, lent to Rust for the running call. */ +export function readerOf(dst: number, reader: Reader): void { + const d = dv(); + d.setUint32(dst, fn.read, true); + d.setUint32(dst + 4, fn.seek, true); + d.setUint32(dst + 8, lend(reader), true); +} + +/** Write the error `e` a reader threw at `err`, as an `io::Error`'s message. */ +function readerError(err: number, e: unknown): false { + copied(err, e instanceof Error ? e.message : String(e), true); + return false; +} + +/** The functions the module imports from `rust2`: the C functions of what JavaScript implements. */ +function rust2(extra: Record unknown>): Record { + return { + ...extra, + rust2_wake(t: number) { + const wake = wakes.get(t); + if (wake) queueMicrotask(wake); + }, + rust2_waker_drop(t: number) { + drops.get(t)?.(); + drops.delete(t); + }, + rust2_free(t: number) { + out("a drop", () => { + const drop = drops.get(t); + tokens.delete(t); + drops.delete(t); + drop?.(); + }); + }, + rust2_future_poll(t: number, waker: number): number { + return out("a future's poll", () => { + const f = find(t); + release(f); + const d = dv(); + if (f.done) { + s.d++; + w[`${space}_call`](d.getUint32(waker + 4, true), d.getUint32(waker + 8, true)); + s.d--; + return 1; + } + f.wake = d.getUint32(waker, true); + f.drop = d.getUint32(waker + 4, true); + f.data = d.getUint32(waker + 8, true); + return 0; + }); + }, + rust2_reader_read(t: number, buf: number, len: number, n: number, err: number): number { + return out("a reader's read", () => { + const owned = new Uint8Array(len); + let got: number; + try { + got = find(t).read(owned); + } catch (e) { + return readerError(err, e) ? 1 : 0; + } + if (Number.isInteger(got) && got > 0 && got <= len) mem().set(owned.subarray(0, got), buf); + dv().setUint32(n, got >>> 0 === got ? got : 0xffffffff, true); + return 1; + }); + }, + rust2_reader_seek(t: number, whence: number, offset: bigint, position: number, err: number): number { + return out("a reader's seek", () => { + const from: SeekFrom = whence === 0 ? "Start" : whence === 1 ? "Current" : "End"; + let at: u64; + try { + at = find(t).seek(from === "Start" ? u64OfBig(offset) : i64OfBig(offset), from); + } catch (e) { + return readerError(err, e) ? 1 : 0; + } + u64Put(position, at); + return 1; + }); + }, + }; +} + +// Futures: a call into Rust's async API polls its future once as it is made, and again on a +// microtask each time Rust wakes it, never inside the wake. + +/** The calls pending in Rust, by their promise. */ +const calls = new Map, Pending>(); + +/** A future in Rust that pended, until it finishes. */ +class Pending { + f: number; + /** The waker's token, whose wakes poll it again. */ + t = 0; + polling = false; + cancelled = false; + resolve!: (value: T) => void; + reject!: (error: unknown) => void; + promise!: Call; + readonly poll: (f: number, waker: number) => [boolean, T]; + readonly free: string; + + constructor(f: number, poll: (f: number, waker: number) => [boolean, T], free: string) { + this.f = f; + this.poll = poll; + this.free = free; + } + + wake = () => { + if (this.f !== 0 && !this.polling) this.step(); + }; + + step(): void { + this.polling = true; + let done: boolean; + let value: T; + let m = 0; + try { + m = enter(); + const waker = alloc(12, 4); + putWaker(waker, this.t); + [done, value] = this.poll(this.f, waker); + } catch (e) { + // The promise settles whatever the cleanup throws. + try { + if (m !== 0) leave(m); + this.polling = false; + this.finish(); + } finally { + this.reject(e); + } + return; + } + leave(m); + this.polling = false; + if (done) { + this.finish(); + this.resolve(value); + } else if (this.cancelled) { + this.cancel(); + } + } + + finish(): void { + if (this.f === 0) return; + const f = this.f; + this.f = 0; + calls.delete(this.promise); + wakes.delete(this.t); + if (!live()) return; + const m = enter(); + s.d++; + w[this.free](f); + s.d--; + leave(m); + } + + cancel(): void { + this.finish(); + this.promise.catch(() => {}); + this.reject(new Cancelled()); + } +} + +/** + * The `Call` of a future whose first poll gave `first`: its value if ready, or else the + * handle of the future that pended, which `poll` polls with a waker and `free` frees. + */ +export function pending(f: number, poll: (f: number, waker: number) => [boolean, T], free: string): Call { + const p = new Pending(f, poll, free); + const promise = new Promise((resolve, reject) => { + p.resolve = resolve; + p.reject = reject; + }) as Call; + promise.cancel = () => { + if (p.f === 0 || p.cancelled) return; + p.cancelled = true; + if (!p.polling) p.cancel(); + }; + p.promise = promise; + calls.set(promise, p as Pending); + p.t = ++token; + wakes.set(p.t, p.wake); + p.step(); + return promise; +} + +/** The `Call` of a future ready at its first poll, with `value`. */ +export function ready(value: T): Call { + const promise = Promise.resolve(value) as Call; + promise.cancel = () => {}; + return promise; +} + +/** The `Call` of a future whose first poll failed with `error`. */ +export function failed(error: unknown): Call { + const promise = Promise.reject(error) as Call; + promise.cancel = () => {}; + return promise; +} + +// The module, and the web APIs its std imports. + +let prefix = ""; +/** The namespace of the glue's C names. */ +let space = ""; + +const text = { out: "", err: "" }; + +/** A line of what the module wrote to stdout or stderr, to `console.log` or `console.error`. */ +/** Stdout's and stderr's decoders, each keeping a character a write splits for the next. */ +const streams = [new TextDecoder("utf-8", { ignoreBOM: true }), new TextDecoder("utf-8", { ignoreBOM: true })]; + +function written(fd: number, chunk: string): void { + const key = fd === 1 ? "out" : "err"; + let pending = text[key] + chunk; + for (let at = pending.indexOf("\n"); at >= 0; at = pending.indexOf("\n")) { + (fd === 1 ? console.log : console.error)(pending.slice(0, at)); + pending = pending.slice(at + 1); + } + text[key] = pending; +} + +/** What the module's std imports, each the web API standing in for it. */ +const wasi = { + clock_time_get(id: number, _precision: bigint, out: number): number { + // The realtime clock from `Date.now`'s origin, at `performance.now`'s precision; every + // other clock is monotonic. + const ms = id === 0 ? performance.timeOrigin + performance.now() : performance.now(); + const ns = BigInt(Math.floor(ms * 1e6)); + dv().setBigUint64(out, ns, true); + return 0; + }, + clock_res_get(_id: number, out: number): number { + dv().setBigUint64(out, 1000n, true); + return 0; + }, + random_get(buf: number, len: number): number { + // `getRandomValues` fills at most 64 KiB at a time. + for (let at = 0; at < len; at += 65536) { + crypto.getRandomValues(mem().subarray(buf + at, buf + Math.min(len, at + 65536))); + } + return 0; + }, + fd_write(fd: number, iovs: number, n: number, nwritten: number): number { + // A web page has no stream but the console's. + if (fd !== 1 && fd !== 2) return 8; + const d = dv(); + let total = 0; + for (let i = 0; i < n; i++) { + const ptr = d.getUint32(iovs + 8 * i, true); + const len = d.getUint32(iovs + 8 * i + 4, true); + written(fd, streams[fd - 1].decode(mem().subarray(ptr, ptr + len), { stream: true })); + total += len; + } + dv().setUint32(nwritten, total, true); + return 0; + }, + // A web page has no environment and no arguments. + environ_sizes_get(count: number, size: number): number { + const d = dv(); + d.setUint32(count, 0, true); + d.setUint32(size, 0, true); + return 0; + }, + environ_get(): number { + return 0; + }, + args_sizes_get(count: number, size: number): number { + return wasi.environ_sizes_get(count, size); + }, + args_get(): number { + return 0; + }, + // One thread, with nothing to yield to. + sched_yield(): number { + return 0; + }, + proc_exit(code: number): never { + aborted ??= new Error(`the module exited with ${code}`); + throw dead(); + }, +}; + +/** What `load` takes the module from. */ +export type Source = WebAssembly.Module | BufferSource | Response | PromiseLike; + +/** What a binding's `load` passes: its C prefix and glue's namespace, its contract and target, and its imports. */ +export type Glue = { + readonly prefix: string; + readonly space: string; + readonly file: string; + readonly contract: bigint; + readonly target: number; + readonly imports: Record unknown>; +}; + +/** + * Compile and instantiate the module from `source`, checking it is the build `glue` was + * generated with, before any call. It refuses an import with no web API standing in for it. + */ +export async function load(source: Source, glue: Glue): Promise { + if (loading || loaded) throw new Error(`${glue.file}: the module is loaded already`); + // Taken before the first await, so a second load meanwhile is refused; given back on a + // failure, so a load after one may succeed. + loading = true; + try { + await instantiate(source, glue); + loaded = true; + } catch (e) { + // What the refused instance left, such as a `proc_exit` in its initializer, is not + // the next one's. + aborted = undefined; + s.d = 0; + throw e; + } finally { + loading = false; + } +} + +let loading = false; +let loaded = false; + +async function instantiate(source: Source, glue: Glue): Promise { + let module: WebAssembly.Module; + if (source instanceof WebAssembly.Module) module = source; + else if (source instanceof ArrayBuffer || ArrayBuffer.isView(source)) module = await WebAssembly.compile(source); + else module = await WebAssembly.compileStreaming(source as Response | PromiseLike); + const rust = rust2(glue.imports as Record unknown>); + for (const i of WebAssembly.Module.imports(module)) { + // Its own, not what every object inherits, such as `toString`. + const known = + i.module === "wasi_snapshot_preview1" ? Object.hasOwn(wasi, i.name) : i.module === "rust2" && Object.hasOwn(rust, i.name); + if (!known) { + throw new Error(`${glue.file}: the module imports ${i.module}.${i.name}, which no web API stands in for`); + } + } + const instance = await WebAssembly.instantiate(module, { + wasi_snapshot_preview1: wasi, + rust2: rust as WebAssembly.ModuleImports, + }); + const exports = instance.exports as Exports; + memory = exports.memory as WebAssembly.Memory; + prefix = glue.prefix; + space = glue.space; + exports._initialize?.(); + if (exports[`${prefix}_contract`]() !== BigInt.asIntN(64, glue.contract)) { + throw new Error(`${glue.file} and the module are from different builds`); + } + if (exports[`${prefix}_target`]() !== glue.target) { + throw new Error(`${glue.file}: the module was built for another target than wasm32-wasip1`); + } + w = exports; + base = exports[`${space}_alloc`](STACK, 16); + const p = exports[`${space}_fns`](); + const d = dv(); + const names = ["wake", "wakerDrop", "free", "poll", "read", "seek"] as const; + names.forEach((name, i) => { + fn[name] = d.getUint32(p + 4 * i, true); + }); +} diff --git a/ffi/runtime/web.rs b/ffi/runtime/web.rs new file mode 100644 index 000000000..72368fae4 --- /dev/null +++ b/ffi/runtime/web.rs @@ -0,0 +1,78 @@ +//! What `web/rt.ts` calls that the C ABI lacks, which the crate's `web` feature builds for +//! wasm32: memory the binding lowers values into, a call through a C function pointer, +//! and the C functions of what JavaScript implements. Each of those is a function the +//! module imports from `rust2`, whose data is a token the binding finds its value by, so +//! JavaScript never puts a function in the module's table. + +use std::alloc::Layout; +use std::ffi::c_void; + +use crate::rt; + +// Each named apart from every C symbol the module links, as libc's `free`, which a +// declaration of the same name would resolve to whatever its import module. +#[link(wasm_import_module = "rust2")] +unsafe extern "C" { + /// Wake the token a waker JavaScript made holds. + fn rust2_wake(data: *mut c_void); + /// Drop a waker JavaScript made. + fn rust2_waker_drop(data: *mut c_void); + /// Rust dropped what JavaScript implements and gave it: a trait's implementation, a kept + /// closure, or a future. + fn rust2_free(data: *mut c_void); + /// Poll a future JavaScript implements. + fn rust2_future_poll(data: *mut c_void, waker: rt::Waker) -> bool; + /// Read and seek a reader JavaScript implements. + fn rust2_reader_read(data: *mut c_void, buf: *mut u8, len: usize, n: *mut usize, err: *mut rt::Buf) -> bool; + fn rust2_reader_seek( + data: *mut c_void, + whence: std::ffi::c_int, + offset: i64, + position: *mut u64, + err: *mut rt::Buf, + ) -> bool; +} + +/// The imported C functions every API's values take, as `rt.ts` reads their table indices. +#[repr(C)] +pub struct Fns { + wake: unsafe extern "C" fn(*mut c_void), + waker_drop: unsafe extern "C" fn(*mut c_void), + free: unsafe extern "C" fn(*mut c_void), + future_poll: unsafe extern "C" fn(*mut c_void, rt::Waker) -> bool, + reader_read: unsafe extern "C" fn(*mut c_void, *mut u8, usize, *mut usize, *mut rt::Buf) -> bool, + reader_seek: unsafe extern "C" fn(*mut c_void, std::ffi::c_int, i64, *mut u64, *mut rt::Buf) -> bool, +} + +pub static FNS: Fns = Fns { + wake: rust2_wake, + waker_drop: rust2_waker_drop, + free: rust2_free, + future_poll: rust2_future_poll, + reader_read: rust2_reader_read, + reader_seek: rust2_reader_seek, +}; + +/// What a trait's table names for `free`. +pub const FREE: unsafe extern "C" fn(*mut c_void) = rust2_free; + +/// `len` bytes aligned to `align`, a power of two, which [`dealloc`] frees. +pub fn alloc(len: usize, align: usize) -> *mut u8 { + let layout = Layout::from_size_align(len.max(1), align).unwrap_or_else(|_| rt::fail("alloc", "a bad layout")); + // SAFETY: the layout is not empty. + let ptr = unsafe { std::alloc::alloc(layout) }; + if ptr.is_null() { + std::alloc::handle_alloc_error(layout); + } + ptr +} + +/// Free what [`alloc`] gave for `len` and `align`. +/// +/// # Safety +/// `ptr` came from [`alloc`] with these, freed once. +pub unsafe fn dealloc(ptr: *mut u8, len: usize, align: usize) { + let layout = Layout::from_size_align(len.max(1), align).unwrap_or_else(|_| rt::fail("free", "a bad layout")); + // SAFETY: the caller's contract. + unsafe { std::alloc::dealloc(ptr, layout) } +} diff --git a/ffi/src/abi.rs b/ffi/src/abi.rs index caccb2f5f..8f0a91dcf 100644 --- a/ffi/src/abi.rs +++ b/ffi/src/abi.rs @@ -771,6 +771,46 @@ impl<'a> Abi<'a> { .collect() } + /// The namespace of `language`'s glue: `_`, with a trailing `_` until no C name is it + /// or starts with it and a `_`. + pub fn space(&self, language: &str) -> String { + let abi = self; + let api = abi.api; + let mut names: Vec = Vec::new(); + let mut functions: Vec<(&Function, Option)> = Vec::new(); + for (i, record) in api.records.iter().enumerate() { + names.push(abi.record(i)); + functions.extend(record.methods.iter().map(|m| (m, Some(Ty::Struct(abi.record(i)))))); + } + for (i, e) in api.enums.iter().enumerate() { + names.push(abi.enumeration(i)); + functions.extend(e.methods.iter().map(|m| (m, Some(abi.ty(&Type::Enum(i)))))); + } + for (i, object) in api.objects.iter().enumerate() { + names.push(abi.object(i)); + let owner = Ty::Handle { + name: abi.object(i), + constant: false, + }; + functions.extend(object.methods.iter().map(|m| (m, Some(owner.clone())))); + } + names.extend((0..api.callbacks.len()).map(|i| abi.callback(i))); + functions.extend(api.functions.iter().map(|f| (f, None))); + names.extend( + functions + .into_iter() + .map(|(function, owner)| abi.export(function, owner.as_ref()).call.name), + ); + let mut space = abi.rt(language); + while names + .iter() + .any(|name| *name == space || name.starts_with(&format!("{space}_"))) + { + space.push('_'); + } + space + } + /// The prefixed name of a runtime item: `buf` is `moq_buf`. pub fn rt(&self, name: &str) -> String { format!("{}_{name}", self.prefix) diff --git a/ffi/src/dart.rs b/ffi/src/dart.rs index 3f53999d6..d4ab02849 100644 --- a/ffi/src/dart.rs +++ b/ffi/src/dart.rs @@ -87,7 +87,7 @@ pub fn generate(abi: &Abi<'_>, packages: &str, contract: u64) -> Result Gen<'a> { type_name(&self.classes.get(c).cloned().unwrap_or_else(|| pascal(self.bare(c)))) } - /// The glue's namespace: `_dart`, with a trailing `_` until no C name is it - /// or starts with it and a `_`. - fn space(abi: &Abi<'_>) -> String { - let api = abi.api; - let mut names: Vec = Vec::new(); - let mut functions: Vec<(&Function, Option)> = Vec::new(); - for (i, record) in api.records.iter().enumerate() { - names.push(abi.record(i)); - functions.extend(record.methods.iter().map(|m| (m, Some(Ty::Struct(abi.record(i)))))); - } - for (i, e) in api.enums.iter().enumerate() { - names.push(abi.enumeration(i)); - functions.extend(e.methods.iter().map(|m| (m, Some(abi.ty(&Type::Enum(i)))))); - } - for (i, object) in api.objects.iter().enumerate() { - names.push(abi.object(i)); - let owner = Ty::Handle { - name: abi.object(i), - constant: false, - }; - functions.extend(object.methods.iter().map(|m| (m, Some(owner.clone())))); - } - names.extend((0..api.callbacks.len()).map(|i| abi.callback(i))); - functions.extend(api.functions.iter().map(|f| (f, None))); - names.extend( - functions - .into_iter() - .map(|(function, owner)| abi.export(function, owner.as_ref()).call.name), - ); - let mut space = abi.rt("dart"); - while names - .iter() - .any(|name| *name == space || name.starts_with(&format!("{space}_"))) - { - space.push('_'); - } - space - } - /// The top-level Dart name `what` takes, `name` unless that is taken. fn claim(&mut self, name: &str, what: String) -> String { abi::claim(&mut self.names, |name| TAKEN.contains(&name), name, what) diff --git a/ffi/src/glue.rs b/ffi/src/glue.rs index 87a18930a..a9632beea 100644 --- a/ffi/src/glue.rs +++ b/ffi/src/glue.rs @@ -347,6 +347,8 @@ impl Crate<'_> { python = [\"dep:pyo3-ffi\", \"dep:pyo3-build-config\", \"dep:smallvec\"]\n\ # What dart/{lib}.dart calls that `dart:ffi` lacks.\n\ dart = []\n\ + # What web/index.ts calls that the C ABI lacks, built for wasm32-wasip1.\n\ + web = []\n\ \n\ {targeted}\ [workspace]\n\ @@ -368,7 +370,8 @@ impl Crate<'_> { let (module, go_mod) = go_module(out, &self.abi.prefix)?; let go = crate::go::generate(&rest, &self.packages(), contract, &module)?; let dart = crate::dart::generate(&rest, &self.packages(), contract)?; - let names = [ + let web = crate::web::generate(&rest, &self.packages(), contract)?; + let mut names: std::collections::BTreeMap> = [ ("C++", cpp.names), ("Kotlin", kotlin.names), ("Python", python.names), @@ -379,10 +382,18 @@ impl Crate<'_> { .into_iter() .map(|(language, names)| (language.to_string(), names)) .collect(); + if let Some(web) = &web { + names.insert("TypeScript".to_string(), web.names.clone()); + } let mut output = Output { names, files: Vec::new(), - stale: vec![out.join("include").join(&self.abi.prefix), out.join("go")], + stale: vec![ + out.join("include").join(&self.abi.prefix), + out.join("go"), + out.join("web"), + out.join("src").join("web"), + ], }; let mut generator = Gen { abi: self.abi, @@ -394,6 +405,7 @@ impl Crate<'_> { out: String::new(), checking: Cell::new(false), reserved: Cell::new(false), + web: web.is_some(), }; generator.lib(); output.file(&out.join("Cargo.toml"), &manifest("0.0.0")); @@ -425,6 +437,13 @@ impl Crate<'_> { output.file(&out.join("src/dart/mod.rs"), &dart.glue); output.file(&out.join("src/dart/runtime.rs"), crate::dart::GLUE_RUNTIME); output.file(&out.join("dart").join(format!("{}.dart", self.abi.prefix)), &dart.dart); + if let Some(web) = web { + output.file(&out.join("src/web/mod.rs"), &web.glue); + output.file(&out.join("src/web/runtime.rs"), crate::web::GLUE_RUNTIME); + for (path, text) in &web.files { + output.file(&out.join("web").join(path), text); + } + } let swift_dir = out.join("swift"); output.file(&swift_dir.join(format!("{}.swift", self.abi.prefix)), &swift.swift); output.file(&swift_dir.join("module.modulemap"), &swift.modulemap); @@ -565,6 +584,8 @@ struct Gen<'a> { /// Whether the argument being lifted had its moved handles reserved, so its lift moves /// their values out unchecked. reserved: Cell, + /// Whether the API serves the web, whose glue the crate's `web` feature builds. + web: bool, } impl Gen<'_> { @@ -1266,6 +1287,9 @@ impl Gen<'_> { self.line("#[cfg(feature = \"kotlin\")]\nmod jni;\n"); self.line("#[cfg(feature = \"python\")]\nmod python;\n"); self.line("#[cfg(feature = \"dart\")]\nmod dart;\n"); + if self.web { + self.line("#[cfg(all(feature = \"web\", target_arch = \"wasm32\"))]\nmod web;\n"); + } // The facade may export nothing, which cargo would call unused. self.line(format!("use {} as _;\n", self.dependency)); diff --git a/ffi/src/main.rs b/ffi/src/main.rs index b4887789a..bf5f8a9ad 100644 --- a/ffi/src/main.rs +++ b/ffi/src/main.rs @@ -40,6 +40,7 @@ mod lock; mod merge; mod python; mod swift; +mod web; use std::process::ExitCode; diff --git a/ffi/src/web.rs b/ffi/src/web.rs new file mode 100644 index 000000000..8b4efdb41 --- /dev/null +++ b/ffi/src/web.rs @@ -0,0 +1,2649 @@ +//! TypeScript over the C ABI of a `wasm32-wasip1` build, for the web: `web/`, ES modules a +//! bundler takes as they are, over the `.wasm` that `cargo build --target wasm32-wasip1 +//! --features web` makes of the crate, with no tool run on it after. +//! +//! The binding's API is rust2-ts's: each type is a module of its own, `web/.ts`, +//! exporting the type by its name and its functions, each taking `self` first, so a caller +//! writes `import * as Counter from "./web/Counter.ts"` and `Counter.get(c)`. `web/index.ts` +//! holds the free functions, the constants, and `load`, which instantiates the module before +//! any call. A record is a plain object, an enum without data a union of its variants' names, +//! an enum a union of objects tagged by variant, an object a handle disposed by +//! `[Symbol.dispose]` or freed by the garbage collector, a trait an interface JavaScript +//! implements, a `Result` an `rt.Result`, and an async function's value a promise that +//! cancels. Names are each item's C name without the prefix: a type's in Pascal case, and a +//! function's in camel case. +//! +//! Each call reads and writes linear memory at the layouts C's wasm32 ABI gives the C +//! header's structs, which [`Gen::layout`] computes, and passes each by that ABI: a struct +//! of one scalar as the scalar, any other through a pointer to a copy, and one returned +//! through a pointer the caller passes first. What JavaScript implements, a trait, a closure, +//! a waker, a future, or a reader, is a C function the module imports from `rust2`, whose +//! data is a token the binding finds its value by. The runtime they share is +//! [`runtime/rt.ts`](../runtime/rt.ts), and the module's std imports only web APIs: its +//! clock is `performance.now`, its randomness `crypto.getRandomValues`, and its output the +//! console. + +use std::collections::{BTreeMap, BTreeSet, HashMap}; +use std::fmt::Write; + +use crate::abi::{self, Abi, Ty, pascal}; +use crate::glue::rs; +use crate::ir::{Access, Closure, Family, Function, Int, Literal, Type}; +use crate::kotlin::strip_refs; + +const RUNTIME: &str = include_str!("../runtime/rt.ts"); + +/// The Rust runtime the crate's `web` feature builds. +pub const GLUE_RUNTIME: &str = include_str!("../runtime/web.rs"); + +/// The target the binding serves: wasm32, against the std that imports its platform, which +/// the binding implements with web APIs. +pub const TARGET: &str = "wasm32-wasip1"; + +/// What the generator writes: each TypeScript file by its name under `web/`, and the Rust +/// glue the crate's `web` feature builds. +pub struct Output { + pub names: BTreeMap, + pub files: Vec<(String, String)>, + pub glue: String, +} + +/// Names a type may not take: a file beside it, case aside, as a case-insensitive file +/// system sees them, and the globals the generated modules name. +const TAKEN: &[&str] = &[ + "Index", + "Rt", + "Glue", + "Array", + "ArrayBuffer", + "BigInt", + "BigInt64Array", + "BigUint64Array", + "Boolean", + "DataView", + "Error", + "Float32Array", + "Float64Array", + "Function", + "Int8Array", + "Int16Array", + "Int32Array", + "Map", + "Math", + "Number", + "Object", + "Promise", + "RangeError", + "Record", + "Set", + "String", + "Symbol", + "Uint8Array", + "Uint16Array", + "Uint32Array", + "WebAssembly", +]; + +/// Words no parameter may be, which take a trailing `_`: TypeScript's reserved words and +/// the modules every generated file imports. +const RESERVED: &[&str] = &[ + "break", + "case", + "catch", + "class", + "const", + "continue", + "debugger", + "default", + "delete", + "do", + "else", + "enum", + "export", + "extends", + "false", + "finally", + "for", + "function", + "if", + "import", + "in", + "instanceof", + "new", + "null", + "return", + "super", + "switch", + "this", + "throw", + "true", + "try", + "typeof", + "var", + "void", + "while", + "with", + "let", + "static", + "yield", + "await", + "implements", + "interface", + "package", + "private", + "protected", + "public", + "arguments", + "eval", + "undefined", + "rt", + "g", +]; + +/// How a C value crosses a wasm call: as one scalar, or through a pointer to its memory. +#[derive(Clone, Copy, PartialEq, Debug)] +enum Wasm { + I32, + I64, + F32, + F64, +} + +/// A C type's size and alignment on wasm32. +#[derive(Clone, Copy, Debug)] +struct Layout { + size: u32, + align: u32, +} + +fn round(n: u32, align: u32) -> u32 { + n.div_ceil(align) * align +} + +/// The TypeScript for `abi`'s items on [`TARGET`], whose header's contract is `contract`, +/// or none if the API does not serve it. +pub fn generate(abi: &Abi<'_>, packages: &str, contract: u64) -> Result, String> { + let api = abi.api; + let Some(web) = api.targets.iter().position(|t| t == TARGET) else { + return Ok(None); + }; + let ranges: BTreeSet = (abi.ranges.keys()) + .map(|c| pascal(&c[abi.prefix.len() + 1..])) + .collect(); + let taken = |name: &str| TAKEN.contains(&name) || ranges.contains(name); + let mut g = Gen { + abi, + web, + space: abi.space("web"), + classes: abi.classes(|_| (String::new(), 0), taken), + module: String::new(), + modules: BTreeMap::new(), + helpers: BTreeMap::new(), + readers: HashMap::new(), + writers: HashMap::new(), + imports: BTreeMap::new(), + rust: String::new(), + relays: Vec::new(), + trampolines: Vec::new(), + names: BTreeMap::new(), + locked: BTreeMap::new(), + errors: Vec::new(), + }; + g.locked = crate::lock::types(abi, &g.classes); + g.items(); + if !g.errors.is_empty() { + return Err(g.errors.join("\n")); + } + let p = &abi.prefix; + let space = g.space.clone(); + let mut files = Vec::new(); + files.push(("rt.ts".to_string(), RUNTIME.to_string())); + // The glue's helpers, which the modules import whole. + let refs = g.modules.remove("glue").map(|m| m.refs).unwrap_or_default(); + let mut body = String::new(); + for code in g.helpers.values() { + body.push_str(code); + } + // What the module imports from `rust2` for what JavaScript implements. + let imports: Vec = g + .imports + .iter() + .map(|(name, code)| format!("\t{name}: {code},")) + .collect(); + let _ = write!( + body, + "/** What the module imports for what JavaScript implements. */\nexport const imports = {{\n{}\n}};\n", + imports.join("\n") + ); + let glue = format!( + "// Generated by rust2-ffi: what the modules of the pub API of {packages} share. Do not edit.\n\n{}{}\n{body}", + module_imports(&body), + type_imports(&refs, "glue") + ); + files.push(("glue.ts".to_string(), glue)); + let mut index = g.modules.remove("index").unwrap_or_default(); + let mut out = format!( + "// Generated by rust2-ffi: TypeScript over the C ABI of the pub API of {packages}, for the web. Do not edit.\n\n\ + import * as rt from \"./rt.ts\";\n\ + import * as g from \"./glue.ts\";\n" + ); + out.push_str(&type_imports(&index.refs, "index")); + if !index.renames.is_empty() { + let renames: Vec = (index.renames.iter()) + .map(|(local, name)| format!("{local} as {name}")) + .collect(); + let _ = writeln!(index.body, "export {{ {} }};", renames.join(", ")); + } + let _ = write!( + out, + "\n/**\n * Compile and instantiate the module `cargo build --target {TARGET} --features web` made of\n * the crate this binding was generated with, from `source`, before any other call: its\n * bytes, a `Response` such as `fetch` gives, or a compiled `WebAssembly.Module`.\n */\nexport function load(source: rt.Source): Promise {{\n\treturn rt.load(source, {{ prefix: \"{p}\", space: \"{space}\", file: \"index.ts\", contract: 0x{contract:016x}n, target: {}, imports: g.imports }});\n}}\n\n{}", + g.web, index.body + ); + files.push(("index.ts".to_string(), trim(out))); + for (name, module) in std::mem::take(&mut g.modules) { + let mut out = format!( + "// Generated by rust2-ffi: TypeScript over the C ABI of the pub API of {packages}, for the web. Do not edit.\n\n{}", + module_imports(&module.body) + ); + out.push_str(&type_imports(&module.refs, &name)); + out.push('\n'); + out.push_str(&module.body); + if !module.renames.is_empty() { + let renames: Vec = (module.renames.iter()) + .map(|(local, name)| format!("{local} as {name}")) + .collect(); + let _ = writeln!(out, "export {{ {} }};", renames.join(", ")); + } + files.push((format!("{name}.ts"), trim(out))); + } + let glue = format!( + "//! Generated by rust2-ffi: what web/index.ts calls that the C ABI lacks. Do not edit.\n\n\ + mod runtime;\n\n\ + #[allow(unused_imports, reason = \"the C ABI's structs\")]\n\ + use crate::*;\n\n\ + use std::ffi::c_void;\n\n\ + use crate::rt;\n\n\ + #[unsafe(no_mangle)]\npub extern \"C\" fn {space}_fns() -> *const runtime::Fns {{\n\t&runtime::FNS\n}}\n\n\ + #[unsafe(no_mangle)]\npub extern \"C\" fn {space}_alloc(len: usize, align: usize) -> *mut u8 {{\n\truntime::alloc(len, align)\n}}\n\n\ + #[unsafe(no_mangle)]\npub unsafe extern \"C\" fn {space}_free(ptr: *mut u8, len: usize, align: usize) {{\n\tunsafe {{ runtime::dealloc(ptr, len, align) }}\n}}\n\n\ + #[unsafe(no_mangle)]\npub unsafe extern \"C\" fn {space}_call(f: Option, data: *mut c_void) {{\n\tif let Some(f) = f {{\n\t\tunsafe {{ f(data) }}\n\t}}\n}}\n\n\ + #[unsafe(no_mangle)]\npub unsafe extern \"C\" fn {space}_abort(ptr: *const u8, len: usize) {{\n\tlet text = unsafe {{ std::slice::from_raw_parts(ptr, len) }};\n\trt::fail(\"web\", &String::from_utf8_lossy(text))\n}}\n\n{}", + g.rust + ); + Ok(Some(Output { + names: g.locked, + files, + glue, + })) +} + +/// The imports of the runtime and the glue that `code` names. +fn module_imports(code: &str) -> String { + let mut out = String::new(); + // Each use of either is a member's, which a field or parameter of that name is not. + if uses(code, "rt.") { + out.push_str("import * as rt from \"./rt.ts\";\n"); + } + if uses(code, "g.") { + out.push_str("import * as g from \"./glue.ts\";\n"); + } + out +} + +/// Whether `code` names `name` as a whole identifier, not a property, or for a `name` +/// ending in `.`, reads a member of it. +fn uses(code: &str, name: &str) -> bool { + let ident = |c: char| c.is_ascii_alphanumeric() || c == '_' || c == '$'; + code.match_indices(name).any(|(at, _)| { + let before = code[..at].chars().next_back(); + let after = code[at + name.len()..].chars().next(); + let whole = name.ends_with('.') || !after.is_some_and(ident); + !before.is_some_and(|c| ident(c) || c == '.' || c == '"') && whole + }) +} + +/// The type-only imports of `refs`, by the module each type is, but `module`'s own. +fn type_imports(refs: &BTreeSet, module: &str) -> String { + (refs.iter()) + .filter(|name| name.as_str() != module) + .map(|name| format!("import type {{ {name} }} from \"./{name}.ts\";\n")) + .collect() +} + +/// Code ending in one newline. +fn trim(mut code: String) -> String { + while code.ends_with("\n\n") { + code.pop(); + } + if !code.ends_with('\n') { + code.push('\n'); + } + code +} + +/// A module's code, the types it names of other modules, and what it exports by another +/// name than its local one, as a reserved word must. +#[derive(Default)] +struct Module { + refs: BTreeSet, + body: String, + /// Each export by its local name. + renames: BTreeMap, + /// The names it exports. + exports: BTreeSet, +} + +struct Gen<'a> { + abi: &'a Abi<'a>, + /// The index of [`TARGET`] among the API's targets. + web: usize, + /// The namespace of the glue's C names, apart from the export's. + space: String, + /// Each exported type's name, by its C name. + classes: HashMap, + /// The module being written, whose types its code names are imported. + module: String, + modules: BTreeMap, + /// The glue's readers, writers, trampolines, and tables, by name. + helpers: BTreeMap, + /// Each reader's name, by the type it reads. + readers: HashMap, + /// Each writer's name, by the type it writes. + writers: HashMap, + /// What the module imports from `rust2`, by name: the JavaScript calling what implements it. + imports: BTreeMap, + /// The Rust glue: the imports and tables of what JavaScript implements. + rust: String, + /// Each C signature of a closure, whose import is `fn_`. + relays: Vec, + /// Each closure type, whose trampoline is `t`. + trampolines: Vec, + /// Each name `index.ts` exports, with what claimed it. + names: BTreeMap, + locked: BTreeMap, + errors: Vec, +} + +impl<'a> Gen<'a> { + /// A C name without the prefix. + fn bare<'n>(&self, c: &'n str) -> &'n str { + &c[self.abi.prefix.len() + 1..] + } + + /// The TypeScript name of the C type `c`. + fn class(&self, c: &str) -> String { + self.classes.get(c).cloned().unwrap_or_else(|| pascal(self.bare(c))) + } + + /// Whether an item on `on` is on the binding's target. + fn here(&self, on: crate::ir::On) -> bool { + on.0 >> self.web & 1 == 1 + } + + fn out(&mut self) -> &mut Module { + self.modules.entry(self.module.clone()).or_default() + } + + /// The type `name`, named in the module being written. + fn named(&mut self, name: String) -> String { + let module = self.module.clone(); + self.modules.entry(module).or_default().refs.insert(name.clone()); + name + } + + // Types. + + /// The TypeScript type of `ty`, as a value, a parameter, or a result. + fn tt(&mut self, ty: &Type) -> String { + let abi = self.abi; + match ty { + Type::Const(_) => unreachable!("a const argument is no value"), + Type::Jni(_) => unreachable!("only Kotlin exports what takes a JNI value"), + Type::Unit => "void".to_string(), + Type::Bool => "boolean".to_string(), + Type::Int(Int::U64) | Type::NonZero(Int::U64) => "rt.u64".to_string(), + Type::Int(Int::I64) | Type::NonZero(Int::I64) => "rt.i64".to_string(), + Type::Int(_) | Type::NonZero(_) | Type::F32 | Type::F64 | Type::Char => "number".to_string(), + Type::U128 => "rt.u128".to_string(), + Type::Str | Type::String => "string".to_string(), + Type::Slice | Type::Vec | Type::Bytes | Type::Array(_) => "Uint8Array".to_string(), + Type::Path | Type::PathBuf => "rt.PathBuf".to_string(), + Type::Duration => "rt.Duration".to_string(), + Type::SocketAddr(Family::Any) => "rt.SocketAddr".to_string(), + Type::SocketAddr(Family::V4) => "rt.SocketAddrV4".to_string(), + Type::SocketAddr(Family::V6) => "rt.SocketAddrV6".to_string(), + Type::IpAddr(Family::Any) => "rt.IpAddr".to_string(), + Type::IpAddr(Family::V4) => "rt.Ipv4Addr".to_string(), + Type::IpAddr(Family::V6) => "rt.Ipv6Addr".to_string(), + Type::List(..) if let Some(block) = ty.block() => typed_array(block).to_string(), + Type::List(_, inner) => { + let inner = self.tt(inner); + match inner.contains(' ') { + true => format!("({inner})[]"), + false => format!("{inner}[]"), + } + } + Type::Waker => "() => void".to_string(), + Type::Reader => "rt.Reader".to_string(), + Type::Future => "Promise".to_string(), + Type::Option(inner) => { + let none = match undefinable(inner) { + true => "rt.None", + false => "undefined", + }; + format!("{} | {none}", self.tt(inner)) + } + Type::Box(inner) | Type::Ref(_, inner) => self.tt(inner), + Type::Record(i) => self.named(self.class(&abi.record(*i))), + Type::Enum(i) => self.named(self.class(&abi.enumeration(*i))), + Type::Object(i) => self.named(self.class(&abi.object(*i))), + Type::Callback(i, _) => self.named(self.class(&abi.callback(*i))), + Type::Closure(closure) => { + let params: Vec = (closure.params.iter().enumerate()) + .map(|(n, p)| format!("a{n}: {}", self.tt(p))) + .collect(); + let ok = match &closure.ok { + Type::Unit => "void".to_string(), + ok => self.tt(ok), + }; + let ret = match &closure.err { + Some(err) => format!("rt.Result<{}, {}>", self.value(&closure.ok, &ok), self.tt(err)), + None => ok, + }; + format!("({}) => {ret}", params.join(", ")) + } + Type::Range(int) => { + let int = self.tt(&Type::Int(*int)); + format!("{{ start: {int}; end: {int} }}") + } + Type::Bound(int) => { + let int = self.tt(&Type::Int(*int)); + format!( + "{{ readonly tag: \"Included\"; readonly _0: {int} }} | {{ readonly tag: \"Excluded\"; readonly _0: {int} }} | {{ readonly tag: \"Unbounded\" }}" + ) + } + Type::Bounds(int) => { + let bound = self.tt(&Type::Bound(*int)); + format!("{{ start: {bound}; end: {bound} }}") + } + Type::Tuple(elements) => { + let elements: Vec = elements.iter().map(|e| self.tt(e)).collect(); + format!("[{}]", elements.join(", ")) + } + } + } + + /// The type of a value `tt` gave `ty` as `t`: `undefined` for `()`, which is `void` returned. + fn value(&mut self, ty: &Type, t: &str) -> String { + match ty { + Type::Unit => "undefined".to_string(), + _ => t.to_string(), + } + } + + // The C ABI on wasm32. + + /// The size and alignment of a C type on wasm32. + fn layout(&self, ty: &Ty) -> Layout { + let l = |size, align| Layout { size, align }; + match ty { + Ty::Void => l(0, 1), + Ty::Bool => l(1, 1), + Ty::Int(Int::U8 | Int::I8) => l(1, 1), + Ty::Int(Int::U16 | Int::I16) => l(2, 2), + Ty::Int(Int::U64 | Int::I64) => l(8, 8), + Ty::Int(_) | Ty::F32 | Ty::Char | Ty::Enum(_) | Ty::Poll | Ty::Status => l(4, 4), + Ty::F64 => l(8, 8), + Ty::Handle { .. } + | Ty::Future(_) + | Ty::Out(_) + | Ty::In(_) + | Ty::InOut(_) + | Ty::Fn(..) + | Ty::Data + | Ty::Jni(_) => l(4, 4), + Ty::Buf | Ty::Waker | Ty::ForeignFuture | Ty::ForeignReader => l(12, 4), + Ty::U128 => l(16, 8), + Ty::Duration => l(16, 8), + Ty::IpAddr(Family::V4) => l(4, 1), + Ty::IpAddr(Family::V6) => l(16, 1), + Ty::IpAddr(Family::Any) => l(17, 1), + Ty::SocketAddr(Family::V4) => l(6, 2), + Ty::SocketAddr(Family::V6) => l(28, 4), + Ty::SocketAddr(Family::Any) => l(32, 4), + Ty::Struct(name) => self.struct_layout(name), + } + } + + /// The size and alignment of a struct of `fields`, and each field's offset. + fn place(&self, fields: &[Ty]) -> (Layout, Vec) { + let mut at = 0; + let mut align = 1; + let mut offsets = Vec::new(); + for field in fields { + let l = self.layout(field); + at = round(at, l.align); + offsets.push(at); + at += l.size; + align = align.max(l.align); + } + ( + Layout { + size: round(at, align), + align, + }, + offsets, + ) + } + + /// What the C struct `name` is. + fn shape(&self, name: &str) -> Shape { + let abi = self.abi; + if let Some(n) = abi.arrays.get(name) { + return Shape::Bytes(*n as u32); + } + if let Some(ty) = abi.ranges.get(name) { + return Shape::Fields(match ty { + Type::Range(int) => vec![Ty::Int(*int), Ty::Int(*int)], + Type::Bound(int) => vec![Ty::Enum(abi.rt("bound")), Ty::Int(*int)], + Type::Bounds(int) => { + let bound = Ty::Struct(abi.range(&Type::Bound(*int))); + vec![bound.clone(), bound] + } + other => unreachable!("{other:?} is no range"), + }); + } + if let Some(elem) = abi.lists.get(name) { + return Shape::Fields(vec![Ty::In(Box::new(abi.ty(elem))), Ty::Int(Int::Usize), Ty::Data]); + } + if let Some(inner) = abi.options.get(name) { + return Shape::Fields(vec![Ty::Bool, abi.ty(inner)]); + } + if let Some(elements) = abi.tuples.get(name) { + return Shape::Fields(elements.iter().map(|e| abi.ty(e)).collect()); + } + if let Some(i) = (0..abi.api.records.len()).find(|&i| abi.record(i) == name) { + let record = &abi.api.records[i]; + if let Some(opaque) = &record.opaque { + return Shape::Units(opaque.unit() as u32, opaque.units() as u32); + } + return Shape::Fields(record.fields.iter().map(|f| abi.ty(&f.ty)).collect()); + } + if let Some(i) = (0..abi.api.enums.len()).find(|&i| abi.enumeration(i) == name) { + let payloads = (abi.api.enums[i].variants.iter()) + .filter(|v| !v.fields.is_empty()) + .map(|v| v.fields.iter().map(|f| abi.ty(&f.ty)).collect()) + .collect(); + return Shape::Union(payloads); + } + if (0..abi.api.callbacks.len()).any(|i| abi.callback(i) == name) { + return Shape::Fields(vec![Ty::Data, Ty::Data]); + } + unreachable!("`{name}` is no struct of the API") + } + + fn struct_layout(&self, name: &str) -> Layout { + match self.shape(name) { + Shape::Bytes(n) => Layout { size: n, align: 1 }, + Shape::Units(unit, units) => Layout { + size: unit * units, + align: unit, + }, + Shape::Fields(fields) => self.place(&fields).0, + Shape::Union(payloads) => { + let (union, _) = self.union(&payloads); + let align = union.align.max(4); + Layout { + size: round(round(4, union.align) + union.size, align), + align, + } + } + } + } + + /// The layout of a union of `payloads`, each a struct of its fields, and where the union + /// sits after an `int` tag. + fn union(&self, payloads: &[Vec]) -> (Layout, u32) { + let mut size = 0; + let mut align = 1; + for payload in payloads { + let (l, _) = self.place(payload); + size = size.max(l.size); + align = align.max(l.align); + } + let l = Layout { + size: round(size, align), + align, + }; + (l, round(4, align)) + } + + /// The scalar a C type crosses a wasm call as, if it is one, or a struct of exactly one. + fn scalar(&self, ty: &Ty) -> Option { + match ty { + Ty::Void => None, + Ty::Int(Int::U64 | Int::I64) => Some(Wasm::I64), + Ty::F32 => Some(Wasm::F32), + Ty::F64 => Some(Wasm::F64), + Ty::Bool + | Ty::Int(_) + | Ty::Char + | Ty::Enum(_) + | Ty::Poll + | Ty::Status + | Ty::Handle { .. } + | Ty::Future(_) + | Ty::Out(_) + | Ty::In(_) + | Ty::InOut(_) + | Ty::Fn(..) + | Ty::Data + | Ty::Jni(_) => Some(Wasm::I32), + Ty::Buf | Ty::Waker | Ty::ForeignFuture | Ty::ForeignReader | Ty::Duration | Ty::U128 => None, + Ty::IpAddr(_) | Ty::SocketAddr(_) => None, + Ty::Struct(name) => match self.shape(name) { + Shape::Bytes(1) => Some(Wasm::I32), + Shape::Units(unit, 1) => Some(if unit == 8 { Wasm::I64 } else { Wasm::I32 }), + Shape::Fields(fields) if fields.len() == 1 => self.scalar(&fields[0]), + _ => None, + }, + } + } + + /// Whether a C type is a plain scalar, not a struct. + fn plain(ty: &Ty) -> bool { + !matches!( + ty, + Ty::Buf + | Ty::U128 + | Ty::Duration + | Ty::SocketAddr(_) + | Ty::IpAddr(_) + | Ty::Struct(_) + | Ty::Waker + | Ty::ForeignFuture + | Ty::ForeignReader + ) + } + + /// The `DataView` method suffix reading or writing the scalar `w` a struct of one holds. + fn word(w: Wasm) -> (&'static str, &'static str) { + match w { + Wasm::I32 => ("Int32", ""), + Wasm::I64 => ("BigInt64", ""), + Wasm::F32 => ("Float32", ""), + Wasm::F64 => ("Float64", ""), + } + } + + // Reading and writing values in memory. + + /// The value of type `ty` at the address `p`, its C value laid out as C's: Rust's to free + /// where `own`, else lent. + fn get(&mut self, ty: &Type, p: &str, own: bool) -> String { + let abi = self.abi; + let o = if own { "true" } else { "false" }; + match ty { + Type::Unit => "undefined".to_string(), + Type::Bool => format!("rt.dv().getUint8({p}) !== 0"), + Type::Int(int) | Type::NonZero(int) => match int { + Int::U8 => format!("rt.dv().getUint8({p})"), + Int::I8 => format!("rt.dv().getInt8({p})"), + Int::U16 => format!("rt.dv().getUint16({p}, true)"), + Int::I16 => format!("rt.dv().getInt16({p}, true)"), + Int::U32 | Int::Usize => format!("rt.dv().getUint32({p}, true)"), + Int::I32 | Int::Isize => format!("rt.dv().getInt32({p}, true)"), + Int::U64 => format!("rt.u64Get({p})"), + Int::I64 => format!("rt.i64Get({p})"), + }, + Type::F32 => format!("rt.dv().getFloat32({p}, true)"), + Type::F64 => format!("rt.dv().getFloat64({p}, true)"), + Type::Char => format!("rt.dv().getUint32({p}, true)"), + Type::U128 => format!("rt.u128Get({p})"), + Type::Str | Type::String => match own { + true => format!("rt.str({p})"), + false => format!("rt.strLent({p})"), + }, + Type::Slice | Type::Vec | Type::Bytes => match own { + true => format!("rt.bytes_({p})"), + false => format!("rt.bytesLent({p})"), + }, + Type::Path | Type::PathBuf => match own { + true => format!("{{ bytes: rt.bytes_({p}) }}"), + false => format!("{{ bytes: rt.bytesLent({p}) }}"), + }, + Type::Duration => format!("rt.durationGet({p})"), + Type::Array(n) => format!("rt.mem().slice({p}, {p} + {n})"), + Type::SocketAddr(Family::Any) => format!("rt.socketGet({p})"), + Type::SocketAddr(Family::V4) => format!("rt.socketV4Get({p})"), + Type::SocketAddr(Family::V6) => format!("rt.socketV6Get({p})"), + Type::IpAddr(Family::Any) => format!("rt.ipGet({p})"), + Type::IpAddr(Family::V4) => format!("rt.ipv4Get({p})"), + Type::IpAddr(Family::V6) => format!("rt.ipv6Get({p})"), + Type::Waker => format!("rt.wakerGet({p})"), + Type::Object(_) => self.lift(ty, &format!("rt.dv().getUint32({p}, true)"), own), + Type::Option(inner) if matches!(inner.base(), Type::Object(_)) => { + self.lift(ty, &format!("rt.dv().getUint32({p}, true)"), own) + } + Type::Option(inner) if Abi::is_buf(inner) || matches!(inner.base(), Type::List(..)) => { + let value = self.get(inner.base(), p, own); + format!("(rt.isNone({p}) ? undefined : {value})") + } + Type::Box(inner) | Type::Ref(_, inner) => self.get(inner, p, own), + Type::Enum(i) if abi.api.enums[*i].plain() => { + let lift = self.enum_lift(*i); + format!("{lift}(rt.dv().getInt32({p}, true))") + } + Type::Record(_) + | Type::Enum(_) + | Type::Option(_) + | Type::List(..) + | Type::Tuple(_) + | Type::Range(_) + | Type::Bound(_) + | Type::Bounds(_) => { + let r = self.reader(ty); + format!("{r}({p}, {o})") + } + other => unreachable!("{other:?} is never read"), + } + } + + /// Statements writing the value `e` of type `ty` at the address `p`: bytes and text as a + /// view of a copy on the stack, unless `take`, where Rust takes a buffer of its own. + fn put(&mut self, ty: &Type, e: &str, p: &str, take: bool) -> String { + let abi = self.abi; + match ty { + Type::Unit => String::new(), + Type::Bool => format!("rt.dv().setUint8({p}, {e} ? 1 : 0);"), + Type::Int(_) | Type::NonZero(_) | Type::F32 | Type::F64 | Type::Char => { + let (set, lowered) = match ty { + Type::Int(Int::U64) | Type::NonZero(Int::U64) => { + return format!("rt.u64Put({p}, {});", self.checked(ty, e)); + } + Type::Int(Int::I64) | Type::NonZero(Int::I64) => { + return format!("rt.i64Put({p}, {});", self.checked(ty, e)); + } + Type::Int(int) | Type::NonZero(int) => (int_view(*int), self.checked(ty, e)), + Type::F32 => ("Float32", self.checked(ty, e)), + Type::F64 => ("Float64", e.to_string()), + _ => ("Uint32", self.checked(ty, e)), + }; + match set { + "Uint8" | "Int8" => format!("rt.dv().set{set}({p}, {lowered});"), + _ => format!("rt.dv().set{set}({p}, {lowered}, true);"), + } + } + Type::U128 => format!("rt.u128Put({p}, {e});"), + Type::Str | Type::String => match take { + true => format!("rt.copied({p}, {e});"), + false => format!("rt.putStr({p}, {e});"), + }, + Type::Slice | Type::Vec | Type::Bytes => match take { + true => format!("rt.copiedBytes({p}, {e});"), + false => format!("rt.putBytes({p}, {e});"), + }, + Type::Path | Type::PathBuf => format!("rt.putBytes({p}, {e}.bytes);"), + Type::Duration => format!("rt.durationPut({p}, {e});"), + Type::Array(n) => format!("rt.mem().set(rt.array({e}, {n}), {p});"), + Type::SocketAddr(Family::Any) => format!("rt.socketPut({p}, {e});"), + Type::SocketAddr(Family::V4) => format!("rt.socketV4Put({p}, {e});"), + Type::SocketAddr(Family::V6) => format!("rt.socketV6Put({p}, {e});"), + Type::IpAddr(Family::Any) => format!("rt.ipPut({p}, {e});"), + Type::IpAddr(Family::V4) => format!("rt.ipv4Put({p}, {e});"), + Type::IpAddr(Family::V6) => format!("rt.ipv6Put({p}, {e});"), + Type::Object(_) => format!("rt.dv().setUint32({p}, rt.hold({e}), true);"), + Type::Option(inner) if matches!(inner.base(), Type::Object(_)) => { + format!("rt.dv().setUint32({p}, rt.holdOr({e}), true);") + } + Type::Option(inner) if Abi::is_buf(inner) || matches!(inner.base(), Type::List(..)) => { + let some = self.put(inner.base(), e, p, take); + match matches!(inner.base(), Type::List(..)) { + true => some, + false => format!( + "if ({e} === undefined) rt.putNone({p});\nelse {{\n{}\n}}", + indent(&some) + ), + } + } + Type::Box(inner) | Type::Ref(_, inner) => self.put(inner, e, p, take), + Type::Enum(i) if abi.api.enums[*i].plain() => { + let lower = self.enum_lower(*i); + format!("rt.dv().setInt32({p}, {lower}({e}), true);") + } + Type::Callback(i, _) => { + let vtable = self.vtable(*i); + format!( + "rt.dv().setUint32({p}, {vtable}(), true);\nrt.dv().setUint32({p} + 4, rt.give({e}, () => {e}.close?.()), true);" + ) + } + Type::Waker => format!("rt.wakerOf({p}, {e});"), + Type::Future => format!("rt.futureOf({p}, {e});"), + Type::Reader => format!("rt.readerOf({p}, {e});"), + Type::Record(_) + | Type::Enum(_) + | Type::Option(_) + | Type::List(..) + | Type::Tuple(_) + | Type::Range(_) + | Type::Bound(_) + | Type::Bounds(_) => { + let w = self.writer(ty, take); + format!("{w}({p}, {e});") + } + other => unreachable!("{other:?} is never written"), + } + } + + /// `e`, a value of the scalar type `ty`, checked to be one of Rust's. + fn checked(&self, ty: &Type, e: &str) -> String { + match ty { + Type::NonZero(int) => format!("rt.nonZero({})", self.checked(&Type::Int(*int), e)), + Type::Int(int) => { + let (min, max): (i64, i64) = match int { + Int::U8 => (0, 0xff), + Int::U16 => (0, 0xffff), + Int::U32 | Int::Usize => (0, 0xffff_ffff), + Int::I8 => (-0x80, 0x7f), + Int::I16 => (-0x8000, 0x7fff), + Int::I32 | Int::Isize => (-0x8000_0000, 0x7fff_ffff), + Int::U64 | Int::I64 => return e.to_string(), + }; + format!("rt.int({e}, {min}, {max}, \"{}\")", int.rust()) + } + Type::F32 => format!("rt.f32({e})"), + Type::Char => format!("rt.char({e})"), + _ => e.to_string(), + } + } + + /// The wasm argument of the value `e` of type `ty`, whose C type is a plain scalar. + fn lower(&mut self, ty: &Type, e: &str) -> String { + match ty { + Type::Bool => format!("({e} ? 1 : 0)"), + Type::Int(Int::U64) | Type::NonZero(Int::U64) => format!("rt.u64Big({})", self.checked(ty, e)), + Type::Int(Int::I64) | Type::NonZero(Int::I64) => format!("rt.i64Big({})", self.checked(ty, e)), + Type::Int(_) | Type::NonZero(_) | Type::F32 | Type::Char => self.checked(ty, e), + Type::F64 => e.to_string(), + Type::Enum(i) => { + let lower = self.enum_lower(*i); + format!("{lower}({e})") + } + Type::Object(_) => format!("rt.hold({e})"), + Type::Option(inner) if matches!(inner.base(), Type::Object(_)) => format!("rt.holdOr({e})"), + Type::Box(inner) | Type::Ref(_, inner) => self.lower(inner, e), + other => unreachable!("{other:?} is no scalar"), + } + } + + /// The value of type `ty` of what a wasm call returned, `e`, whose C type is a plain + /// scalar: a handle owned where `own`, else lent. + fn lift(&mut self, ty: &Type, e: &str, own: bool) -> String { + match ty { + Type::Unit => "undefined".to_string(), + Type::Bool => format!("{e} !== 0"), + Type::Int(int) | Type::NonZero(int) => match int { + Int::U8 => format!("{e} & 0xff"), + Int::U16 => format!("{e} & 0xffff"), + Int::U32 | Int::Usize => format!("{e} >>> 0"), + Int::I8 => format!("({e} << 24) >> 24"), + Int::I16 => format!("({e} << 16) >> 16"), + Int::I32 | Int::Isize => format!("{e} | 0"), + Int::U64 => format!("rt.u64OfBig({e})"), + Int::I64 => format!("rt.i64OfBig({e})"), + }, + Type::F32 | Type::F64 => e.to_string(), + Type::Char => format!("{e} >>> 0"), + Type::Enum(i) => { + let lift = self.enum_lift(*i); + format!("{lift}({e})") + } + Type::Object(i) => { + let kind = self.kind(*i); + let t = self.tt(ty); + match own { + true => format!("new rt.Handle({e}, {kind}, true) as {t}"), + false => format!("rt.lentHandle({e}, {kind}) as {t}"), + } + } + Type::Option(inner) if matches!(inner.base(), Type::Object(_)) => { + let some = self.lift(inner.base(), "h$", own); + format!("((h$) => h$ === 0 ? undefined : {some})({e})") + } + Type::Box(inner) | Type::Ref(_, inner) => self.lift(inner, e, own), + other => unreachable!("{other:?} is no scalar"), + } + } + + /// The kind of object `i`'s handles, defined once in the glue. + fn kind(&mut self, i: usize) -> String { + let abi = self.abi; + let c = abi.object(i); + let name = format!("k_{}", self.bare(&c)); + if !self.helpers.contains_key(&name) { + let class = self.class(&c); + let drop = match abi.checked[i] { + true => format!(", drop: \"{c}_drop\""), + false => String::new(), + }; + self.helpers.insert( + name.clone(), + format!("export const {name}: rt.Kind = {{ name: \"{class}\", free: \"{c}_free\"{drop} }};\n\n"), + ); + } + format!("g.{name}") + } + + /// The glue's function lowering a plain enum `i`'s value to its discriminant. + fn enum_lower(&mut self, i: usize) -> String { + let abi = self.abi; + let c = abi.enumeration(i); + let name = format!("e_{}", self.bare(&c)); + if !self.helpers.contains_key(&name) { + let module = std::mem::replace(&mut self.module, "glue".to_string()); + let t = self.tt(&Type::Enum(i)); + self.module = module; + let e = &abi.api.enums[i]; + let cases: Vec = (e.variants.iter()) + .filter(|v| self.here(v.on)) + .map(|v| format!("\t\tcase \"{}\":\n\t\t\treturn {};", v.name, v.discriminant)) + .collect(); + self.helpers.insert( + name.clone(), + format!( + "export function {name}(v: {t}): number {{\n\tswitch (v) {{\n{}\n\t\tdefault:\n\t\t\tthrow new RangeError(`${{String(v)}} is no {t}`);\n\t}}\n}}\n\n", + cases.join("\n") + ), + ); + } + format!("g.{name}") + } + + /// The glue's function lifting a plain enum `i`'s value from its discriminant. + fn enum_lift(&mut self, i: usize) -> String { + let abi = self.abi; + let c = abi.enumeration(i); + let name = format!("f_{}", self.bare(&c)); + if !self.helpers.contains_key(&name) { + let module = std::mem::replace(&mut self.module, "glue".to_string()); + let t = self.tt(&Type::Enum(i)); + self.module = module; + let e = &abi.api.enums[i]; + let cases: Vec = (e.variants.iter()) + .filter(|v| self.here(v.on)) + .map(|v| format!("\t\tcase {}:\n\t\t\treturn \"{}\";", v.discriminant, v.name)) + .collect(); + self.helpers.insert( + name.clone(), + format!( + "export function {name}(c: number): {t} {{\n\tswitch (c) {{\n{}\n\t\tdefault:\n\t\t\tthrow new RangeError(`{c}: an invalid value ${{c}}`);\n\t}}\n}}\n\n", + cases.join("\n") + ), + ); + } + format!("g.{name}") + } + + /// A helper's name for `ty`, `base` and a number apart from every other's. + fn helper_name(&mut self, base: &str) -> String { + let mut name = base.to_string(); + for k in 2.. { + if !self.helpers.contains_key(&name) { + break; + } + name = format!("{base}_{k}"); + } + self.helpers.insert(name.clone(), String::new()); + name + } + + /// The glue's function reading a value of type `ty`, a struct's, at a pointer. + fn reader(&mut self, ty: &Type) -> String { + if let Some(name) = self.readers.get(ty) { + return format!("g.{name}"); + } + let abi = self.abi; + let c = match abi.ty(ty) { + Ty::Struct(c) => c, + other => unreachable!("{other:?} is no struct"), + }; + let name = self.helper_name(&format!("r_{}", self.bare(&c))); + self.readers.insert(ty.clone(), name.clone()); + let module = std::mem::replace(&mut self.module, "glue".to_string()); + let t = self.tt(ty); + let body = self.read_body(ty, &c).replace("void o;\n\t", ""); + let body = match uses(&body, "o") { + true => body, + false => format!("void o;\n\t{body}"), + }; + self.module = module; + self.helpers.insert( + name.clone(), + format!( + "/** A `{}` at `p`. */\nexport function {name}(p: number, o: boolean): {t} {{\n\t{body}\n}}\n\n", + abi.spell(ty) + ), + ); + format!("g.{name}") + } + + fn read_body(&mut self, ty: &Type, c: &str) -> String { + let abi = self.abi; + let offsets = |g: &Self| match g.shape(c) { + Shape::Fields(fields) => g.place(&fields).1, + _ => Vec::new(), + }; + match ty { + Type::Record(i) if abi.api.records[*i].opaque.is_some() => { + let size = self.layout(&Ty::Struct(c.to_string())).size; + let t = self.tt(ty); + format!("void o;\n\treturn rt.opaqueMade(rt.mem().slice(p, p + {size})) as {t};") + } + Type::Record(i) => { + let record = &abi.api.records[*i]; + let at = offsets(self); + let names = field_names(&record.fields); + let fields: Vec = (record.fields.iter().zip(at).zip(names)) + .map(|((f, at), name)| { + let value = self.get_o(&f.ty, &format!("p + {at}")); + format!("{name}: {value}") + }) + .collect(); + format!("void o;\n\treturn {{ {} }};", fields.join(", ")) + } + Type::Enum(i) => { + let e = &abi.api.enums[*i]; + let Shape::Union(payloads) = self.shape(c) else { + unreachable!("a data enum is a union") + }; + let (_, u) = self.union(&payloads); + let mut cases = Vec::new(); + for (n, variant) in e.variants.iter().enumerate() { + // A variant the target lacks reads no fields, whose types it may lack too. + if !self.here(variant.on) { + continue; + } + let mut fields = vec![format!("tag: \"{}\"", variant.name)]; + if !variant.fields.is_empty() { + let tys: Vec = variant.fields.iter().map(|f| abi.ty(&f.ty)).collect(); + let (_, at) = self.place(&tys); + for ((f, at), name) in variant.fields.iter().zip(at).zip(variant_fields(&variant.fields)) { + let value = self.get_o(&f.ty, &format!("p + {}", u + at)); + fields.push(format!("{name}: {value}")); + } + } + cases.push(format!("\t\tcase {n}:\n\t\t\treturn {{ {} }};", fields.join(", "))); + } + format!( + "switch (rt.dv().getInt32(p, true)) {{\n{}\n\t\tdefault:\n\t\t\tthrow new RangeError(\"{c}: an invalid tag\");\n\t}}", + cases.join("\n") + ) + } + Type::Option(inner) => { + let at = offsets(self)[1]; + let value = self.get_o(inner, &format!("p + {at}")); + let none = match undefinable(inner) { + true => "rt.None", + false => "undefined", + }; + format!("return rt.dv().getUint8(p) !== 0 ? {value} : {none};") + } + Type::List(..) if let Some(block) = ty.block() => { + let array = typed_array(block); + let size = self.layout(&abi.ty(block)).size; + format!( + "const d = rt.dv();\n\tconst ptr = d.getUint32(p, true);\n\tconst len = d.getUint32(p + 4, true);\n\tconst out = new {array}(rt.mem().buffer.slice(ptr, ptr + len * {size}));\n\tif (o) rt.w.{c}_free(p);\n\treturn out;" + ) + } + Type::List(_, elem) => { + let stride = { + let l = self.layout(&abi.ty(elem)); + round(l.size, l.align) + }; + let item = self.get_o(elem, &format!("ptr + i * {stride}")); + let t = self.tt(elem); + format!( + "const d = rt.dv();\n\tconst ptr = d.getUint32(p, true);\n\tconst len = d.getUint32(p + 4, true);\n\tconst out: ({t})[] = [];\n\tfor (let i = 0; i < len; i++) out.push({item});\n\tif (o) {{\n\t\trt.dv().setUint32(p + 4, 0, true);\n\t\trt.w.{c}_free(p);\n\t}}\n\treturn out;" + ) + } + Type::Tuple(elements) => { + let at = offsets(self); + let values: Vec = (elements.iter().zip(at)) + .map(|(e, at)| self.get_o(e, &format!("p + {at}"))) + .collect(); + format!("return [{}];", values.join(", ")) + } + Type::Range(int) => { + let at = offsets(self); + let int = Type::Int(*int); + let start = self.get(&int, &format!("p + {}", at[0]), true); + let end = self.get(&int, &format!("p + {}", at[1]), true); + format!("void o;\n\treturn {{ start: {start}, end: {end} }};") + } + Type::Bound(int) => { + let at = offsets(self); + let value = self.get(&Type::Int(*int), &format!("p + {}", at[1]), true); + format!( + "void o;\n\tswitch (rt.dv().getInt32(p, true)) {{\n\t\tcase 0:\n\t\t\treturn {{ tag: \"Unbounded\" }};\n\t\tcase 1:\n\t\t\treturn {{ tag: \"Included\", _0: {value} }};\n\t\tcase 2:\n\t\t\treturn {{ tag: \"Excluded\", _0: {value} }};\n\t\tdefault:\n\t\t\tthrow new RangeError(\"{c}: an invalid kind\");\n\t}}" + ) + } + Type::Bounds(int) => { + let at = offsets(self); + let bound = Type::Bound(*int); + let start = self.get_o(&bound, &format!("p + {}", at[0])); + let end = self.get_o(&bound, &format!("p + {}", at[1])); + format!("return {{ start: {start}, end: {end} }};") + } + other => unreachable!("{other:?} has no reader"), + } + } + + /// [`Self::get`] of a value a reader reads, owned as its `o` says. + fn get_o(&mut self, ty: &Type, p: &str) -> String { + let owned = self.get(ty, p, true); + let lent = self.get(ty, p, false); + match owned == lent { + true => owned, + false => format!("(o ? {owned} : {lent})"), + } + } + + /// The glue's function writing a value of type `ty`, a struct's, at a pointer: buffers + /// Rust takes where `take`. + fn writer(&mut self, ty: &Type, take: bool) -> String { + let key = match take { + true => Type::Tuple(vec![ty.clone(), Type::Unit]), + false => ty.clone(), + }; + if let Some(name) = self.writers.get(&key) { + return format!("g.{name}"); + } + let abi = self.abi; + let c = match abi.ty(ty) { + Ty::Struct(c) => c, + other => unreachable!("{other:?} is no struct"), + }; + let base = match take { + true => format!("t_{}", self.bare(&c)), + false => format!("w_{}", self.bare(&c)), + }; + let name = self.helper_name(&base); + self.writers.insert(key, name.clone()); + let module = std::mem::replace(&mut self.module, "glue".to_string()); + let t = self.tt(ty); + let body = self.write_body(ty, &c, take); + self.module = module; + self.helpers.insert( + name.clone(), + format!( + "/** Write the `{}` `v` at `p`. */\nexport function {name}(p: number, v: {t}{}): void {{\n{}\n}}\n\n", + abi.spell(ty), + match ty { + Type::List(..) => " | undefined", + _ => "", + }, + indent(&body) + ), + ); + format!("g.{name}") + } + + fn write_body(&mut self, ty: &Type, c: &str, take: bool) -> String { + let abi = self.abi; + let offsets = |g: &Self| match g.shape(c) { + Shape::Fields(fields) => g.place(&fields).1, + _ => Vec::new(), + }; + match ty { + Type::Record(i) if abi.api.records[*i].opaque.is_some() => { + let size = self.layout(&Ty::Struct(c.to_string())).size; + format!("rt.opaquePut(v, {size}, p);") + } + Type::Record(i) => { + let record = &abi.api.records[*i]; + let at = offsets(self); + let names = field_names(&record.fields); + let lines: Vec = (record.fields.iter().zip(at).zip(names)) + .map(|((f, at), name)| self.put(&f.ty, &format!("v.{name}"), &format!("p + {at}"), take)) + .collect(); + lines.join("\n") + } + Type::Enum(i) => { + let e = &abi.api.enums[*i]; + let Shape::Union(payloads) = self.shape(c) else { + unreachable!("a data enum is a union") + }; + let (_, u) = self.union(&payloads); + let mut cases = Vec::new(); + for (n, variant) in e.variants.iter().enumerate() { + if !self.here(variant.on) { + continue; + } + let mut body = vec![format!("rt.dv().setInt32(p, {n}, true);")]; + if !variant.fields.is_empty() { + let tys: Vec = variant.fields.iter().map(|f| abi.ty(&f.ty)).collect(); + let (_, at) = self.place(&tys); + for ((f, at), name) in variant.fields.iter().zip(at).zip(variant_fields(&variant.fields)) { + body.push(self.put(&f.ty, &format!("v.{name}"), &format!("p + {}", u + at), take)); + } + } + body.push("return;".to_string()); + cases.push(format!("case \"{}\":\n{}", variant.name, indent(&body.join("\n")))); + } + cases.push(format!( + "default:\n\tthrow new RangeError(`${{String((v as {{ tag: unknown }}).tag)}} is no variant of {c}`);" + )); + format!("switch (v.tag) {{\n{}\n}}", indent(&cases.join("\n"))) + } + Type::Option(inner) => { + let at = offsets(self)[1]; + let some = self.put(inner, "v", &format!("p + {at}"), take); + let none = match undefinable(inner) { + true => "rt.None", + false => "undefined", + }; + let narrowed = match undefinable(inner) { + true => { + let t = self.tt(inner); + format!( + "\nconst s = v as {t};\n{}", + some.replace("(v", "(s").replace(" v,", " s,").replace(", v)", ", s)") + ) + } + false => format!("\n{some}"), + }; + let some = indent(&format!("rt.dv().setUint8(p, 1);{narrowed}")); + format!("if (v === {none}) rt.dv().setUint8(p, 0);\nelse {{\n{some}\n}}") + } + Type::List(..) if take => { + self.errors.push(format!( + "`{}` returned from JavaScript to Rust has no web form yet, which rust2-ffi should give it", + abi.spell(ty) + )); + String::new() + } + Type::List(..) if let Some(block) = ty.block() => { + let size = self.layout(&abi.ty(block)).size; + format!( + "const d = rt.dv();\nif (v === undefined) {{\n\td.setUint32(p, 0, true);\n\td.setUint32(p + 4, 0, true);\n\td.setUint32(p + 8, 0, true);\n\treturn;\n}}\nconst ptr = rt.alloc(Math.max(v.length * {size}, 1), {size});\nrt.mem().set(new Uint8Array(v.buffer, v.byteOffset, v.length * {size}), ptr);\nconst e = rt.dv();\ne.setUint32(p, ptr, true);\ne.setUint32(p + 4, v.length, true);\ne.setUint32(p + 8, 0, true);" + ) + } + Type::List(_, elem) => { + let l = self.layout(&abi.ty(elem)); + let stride = round(l.size, l.align); + let item = self.put(elem, "v[i]", &format!("ptr + i * {stride}"), false); + format!( + "if (v === undefined) {{\n\tconst d = rt.dv();\n\td.setUint32(p, 0, true);\n\td.setUint32(p + 4, 0, true);\n\td.setUint32(p + 8, 0, true);\n\treturn;\n}}\nconst ptr = rt.alloc(Math.max(v.length * {stride}, 1), {});\nfor (let i = 0; i < v.length; i++) {{\n{}\n}}\nconst d = rt.dv();\nd.setUint32(p, ptr, true);\nd.setUint32(p + 4, v.length, true);\nd.setUint32(p + 8, 0, true);", + l.align, + indent(&item) + ) + } + Type::Tuple(elements) => { + let at = offsets(self); + let lines: Vec = (elements.iter().enumerate().zip(at)) + .map(|((n, e), at)| self.put(e, &format!("v[{n}]"), &format!("p + {at}"), take)) + .collect(); + lines.join("\n") + } + Type::Range(int) => { + let at = offsets(self); + let int = Type::Int(*int); + let start = self.put(&int, "v.start", &format!("p + {}", at[0]), take); + let end = self.put(&int, "v.end", &format!("p + {}", at[1]), take); + format!("{start}\n{end}") + } + Type::Bound(int) => { + let at = offsets(self); + let value = self.put(&Type::Int(*int), "v._0", &format!("p + {}", at[1]), take); + format!( + "switch (v.tag) {{\n\tcase \"Unbounded\":\n\t\trt.dv().setInt32(p, 0, true);\n\t\treturn;\n\tcase \"Included\":\n\t\trt.dv().setInt32(p, 1, true);\n\t\t{value}\n\t\treturn;\n\tcase \"Excluded\":\n\t\trt.dv().setInt32(p, 2, true);\n\t\t{value}\n\t\treturn;\n\tdefault:\n\t\tthrow new RangeError(\"a Bound is Included, Excluded, or Unbounded\");\n}}" + ) + } + Type::Bounds(int) => { + let at = offsets(self); + let bound = Type::Bound(*int); + let start = self.put(&bound, "v.start", &format!("p + {}", at[0]), take); + let end = self.put(&bound, "v.end", &format!("p + {}", at[1]), take); + format!("{start}\n{end}") + } + other => unreachable!("{other:?} has no writer"), + } + } +} + +/// What a C struct of the API is. +enum Shape { + /// `[u8; N]`'s bytes. + Bytes(u32), + /// An opaque value's units, of their size each. + Units(u32, u32), + /// A struct of these fields. + Fields(Vec), + /// A data enum: an `int` tag, then a union of each variant's fields. + Union(Vec>), +} + +/// Whether a value of `ty` can be `undefined`, so its `Option` keeps `None` apart as `rt.None`. +fn undefinable(ty: &Type) -> bool { + matches!(ty.base(), Type::Unit | Type::Option(_)) +} + +/// The typed array holding a block's elements exactly. +fn typed_array(elem: &Type) -> &'static str { + match elem { + Type::Int(Int::U8) => "Uint8Array", + Type::Int(Int::U16) => "Uint16Array", + Type::Int(Int::U32) => "Uint32Array", + Type::Int(Int::U64) => "BigUint64Array", + Type::Int(Int::I8) => "Int8Array", + Type::Int(Int::I16) => "Int16Array", + Type::Int(Int::I32) => "Int32Array", + Type::Int(Int::I64) => "BigInt64Array", + Type::F32 => "Float32Array", + Type::F64 => "Float64Array", + other => unreachable!("{other:?} is no block"), + } +} + +/// The `DataView` accessor of an integer no wider than 32 bits. +fn int_view(int: Int) -> &'static str { + match int { + Int::U8 => "Uint8", + Int::I8 => "Int8", + Int::U16 => "Uint16", + Int::I16 => "Int16", + Int::U32 | Int::Usize => "Uint32", + Int::I32 | Int::Isize => "Int32", + Int::U64 | Int::I64 => unreachable!("a u64 is two words"), + } +} + +/// A snake-case name in camel case: `into_label` is `intoLabel`, and `0` is `_0`. +fn camel(name: &str) -> String { + if name.starts_with(|c: char| c.is_ascii_digit()) { + return format!("_{name}"); + } + let pascal = pascal(name); + let mut chars = pascal.chars(); + match chars.next() { + Some(first) => first.to_lowercase().chain(chars).collect(), + None => name.to_string(), + } +} + +/// A field's name: in camel case, and `_0` for a positional one. +fn field_name(name: &str) -> String { + camel(name) +} + +/// The names of a record's fields, each a field's, and distinct: `foo` and `foo_`, both +/// `foo` in camel case, are `foo` and `foo2`. +fn field_names(fields: &[crate::ir::Field]) -> Vec { + abi::distinct(fields.iter().map(|f| field_name(&f.name))) +} + +/// The names of a data enum variant's fields: a record's, but `tag$` for one named `tag`, +/// which names the variant. +fn variant_fields(fields: &[crate::ir::Field]) -> Vec { + abi::distinct(fields.iter().map(|f| match field_name(&f.name) { + name if name == "tag" => "tag$".to_string(), + name => name, + })) +} + +/// A parameter's name: in camel case, with `_` appended if a reserved word. +fn param_name(name: &str) -> String { + let name = camel(name); + match RESERVED.contains(&name.as_str()) { + true => format!("{name}_"), + false => name, + } +} + +/// JSDoc holding `docs`, each line indented by `indent`, or nothing for none. +fn docs(docs: &str, indent: &str) -> String { + let docs = docs.trim(); + if docs.is_empty() { + return String::new(); + } + let lines: String = (docs.lines()) + .map(|line| match line.is_empty() { + true => format!("{indent} *\n"), + false => format!("{indent} * {}\n", line.replace("*/", "* /")), + }) + .collect(); + format!("{indent}/**\n{lines}{indent} */\n") +} + +/// Code indented by one tab more, but for blank lines. +fn indent(code: &str) -> String { + let mut out: String = (code.lines()) + .map(|l| match l.is_empty() { + true => "\n".to_string(), + false => format!("\t{l}\n"), + }) + .collect(); + if !code.ends_with('\n') { + out.pop(); + } + out +} + +/// What a call into the module returned: nothing, a scalar, or a value at a pointer. +enum Ret { + None, + Value(String), + At(String), +} + +impl Gen<'_> { + /// Statements making `local` the wasm argument, of the C type `c`, of `e` of type `ty`: + /// a struct is copied onto the stack, and passed there, or as its one scalar. + fn pass(&mut self, ty: &Type, c: &Ty, e: &str, local: &str) -> String { + if Self::plain(c) { + return format!("const {local} = {};", self.lower(ty, e)); + } + let l = self.layout(c); + match self.scalar(c) { + Some(w) => { + let p = format!("{local}p"); + let put = self.put(ty, e, &p, false); + format!( + "const {p} = rt.alloc({}, {});\n{put}\nconst {local} = rt.dv().get{}({p}, true);", + l.size.max(8), + l.align.max(4), + Self::word(w).0 + ) + } + None => { + let put = self.put(ty, e, local, false); + format!("const {local} = rt.alloc({}, {});\n{put}", l.size.max(1), l.align) + } + } + } + + /// Statements calling the C function `name` with `args`, returning `ret`, into `lines`: a + /// struct it returns is written through a pointer passed first, and with `status`, a check + /// it fails throws once it returns. + fn invoke(&mut self, name: &str, mut args: Vec, ret: &Ty, status: bool, lines: &mut Vec) -> Ret { + if status { + lines.push("const s$ = rt.alloc(4, 4);\nrt.dv().setInt32(s$, 0, true);".to_string()); + args.push("s$".to_string()); + } + let sret = !Self::plain(ret) && self.scalar(ret).is_none(); + if sret { + let l = self.layout(ret); + lines.push(format!("const rp$ = rt.alloc({}, {});", l.size, l.align)); + args.insert(0, "rp$".to_string()); + } + let call = format!("rt.w.{name}({})", args.join(", ")); + let ret = match ret { + Ty::Void => { + lines.push(format!("rt.s.d++;\n{call};\nrt.s.d--;")); + Ret::None + } + _ if sret => { + lines.push(format!("rt.s.d++;\n{call};\nrt.s.d--;")); + Ret::At("rp$".to_string()) + } + ret if Self::plain(ret) => { + lines.push(format!("rt.s.d++;\nconst r$ = {call};\nrt.s.d--;")); + Ret::Value("r$".to_string()) + } + ret => { + // A struct of one scalar comes back as it, which is read as the struct once + // written back. + let l = self.layout(ret); + let w = self.scalar(ret).expect("a struct of one scalar"); + lines.push(format!( + "rt.s.d++;\nconst r$ = {call};\nrt.s.d--;\nconst rp$ = rt.alloc({}, {});\nrt.dv().set{}(rp$, r$, true);", + l.size.max(8), + l.align.max(4), + Self::word(w).0 + )); + Ret::At("rp$".to_string()) + } + }; + if status { + lines.push(format!("rt.status(s$, \"{name}\");")); + } + ret + } + + /// The value of type `ty` a call returned as `ret`, which the caller owns. + fn result(&mut self, ty: &Type, ret: &Ret) -> String { + match ret { + Ret::None => "undefined".to_string(), + Ret::Value(e) => self.lift(ty, e, true), + Ret::At(p) => self.get(ty, p, true), + } + } + + /// The value of type `ty` in the wasm parameter `e` of C type `c` of a call into + /// JavaScript, which Rust lends if bytes or text, and else gives. + fn incoming(&mut self, ty: &Type, c: &Ty, e: &str, lines: &mut Vec) -> String { + if Self::plain(c) { + return self.lift(ty, e, true); + } + match self.scalar(c) { + Some(w) => { + let l = self.layout(c); + let p = format!("{e}p"); + lines.push(format!( + "const {p} = rt.alloc({}, {});\nrt.dv().set{}({p}, {e}, true);", + l.size.max(8), + l.align.max(4), + Self::word(w).0 + )); + self.get_lent(ty, &p) + } + None => self.get_lent(ty, e), + } + } + + /// [`Self::get`] of what Rust passes a call into JavaScript: bytes and text lent, which + /// it copies, and any other value given. + fn get_lent(&mut self, ty: &Type, p: &str) -> String { + match ty { + Type::Ref(_, inner) => self.get_lent(inner, p), + ty if Abi::is_buf(ty) => self.get(ty, p, false), + Type::Option(inner) if Abi::is_buf(inner) => self.get(ty, p, false), + ty => self.get(ty, p, true), + } + } + + /// Statements returning `e` of type `ty` from a call into JavaScript, as the C type `c`, + /// which Rust then owns: through `sret` if a struct it returns that way. + fn outgoing(&mut self, ty: &Type, c: &Ty, e: &str, lines: &mut Vec) { + if matches!(ty.base(), Type::Object(_)) { + self.errors.push(format!( + "`{}` returned from JavaScript to Rust has no web form yet, which rust2-ffi should give it", + self.abi.spell(ty) + )); + return; + } + match c { + Ty::Void => lines.push(format!("{e};")), + c if Self::plain(c) => lines.push(format!("return {};", self.lower(ty, e))), + c => { + // The implementation runs once, though a writer may read what it returns twice. + lines.push(format!("const v$ = {e};")); + match self.scalar(c) { + Some(w) => { + let l = self.layout(c); + let put = self.put(ty, "v$", "o$", true); + lines.push(format!( + "const o$ = rt.alloc({}, {});\n{put}\nreturn rt.dv().get{}(o$, true);", + l.size.max(8), + l.align.max(4), + Self::word(w).0 + )); + } + None => lines.push(self.put(ty, "v$", "r$", true)), + } + } + } + } + + /// The wasm parameters of a C function JavaScript implements taking `params` after its + /// data and returning `ret`: `r$` first for a struct it returns through a pointer, then + /// `data`, then `p0` and on. + fn imported(&self, params: &[Ty], ret: &Ty) -> Vec { + let mut names = Vec::new(); + if !Self::plain(ret) && self.scalar(ret).is_none() { + names.push("r$".to_string()); + } + names.push("data".to_string()); + names.extend((0..params.len()).map(|n| format!("p{n}"))); + names + } + + /// The wasm type of what a C function JavaScript implements returns, as TypeScript. + fn wasm_ret(&self, ret: &Ty) -> &'static str { + match ret { + Ty::Void => "void", + ret => match self.scalar(ret) { + Some(Wasm::I64) => "bigint", + Some(_) => "number", + None => "void", + }, + } + } + + /// The wasm type of a parameter of a C function JavaScript implements, as TypeScript. + fn wasm_param(&self, ty: &Ty) -> &'static str { + match self.scalar(ty) { + Some(Wasm::I64) => "bigint", + _ => "number", + } + } + + /// The Rust glue's declaration of `name`, a C function the module imports from `rust2` + /// taking `params` after its data and returning `ret`. + fn import_decl(&mut self, name: &str, params: &[Ty], ret: &Ty) { + let decls: String = (params.iter().enumerate()) + .map(|(n, ty)| format!(", p{n}: {}", rs(ty))) + .collect(); + let _ = write!( + self.rust, + "#[link(wasm_import_module = \"rust2\")]\nunsafe extern \"C\" {{\n\tfn {name}(data: *mut c_void{decls}) -> {};\n}}\n\n", + rs(ret) + ); + } + + /// The glue's function giving the table index of the C function the Rust glue's `export` + /// returns, read once. + fn index_fn(&mut self, local: &str, export: &str) -> String { + if !self.helpers.contains_key(local) { + self.helpers.insert( + local.to_string(), + format!( + "let {local}$ = 0;\nexport function {local}(): number {{\n\tif ({local}$ === 0) {local}$ = rt.w.{export}();\n\treturn {local}$;\n}}\n\n" + ), + ); + } + format!("g.{local}") + } + + /// The glue's function giving the table of the trait `i`, whose methods JavaScript + /// implements, made once with the module's imports. + fn vtable(&mut self, i: usize) -> String { + let abi = self.abi; + let c = abi.callback(i); + let bare = self.bare(&c).to_string(); + let local = format!("vt_{bare}"); + if self.helpers.contains_key(&local) { + return format!("g.{local}"); + } + let space = self.space.clone(); + let callback = &abi.api.callbacks[i]; + let rust = callback.path.join("::"); + let class = self.class(&c); + let mut fields = vec!["free: Some(runtime::FREE)".to_string()]; + for method in &callback.methods { + let m = method.name(); + let name = format!("{space}_cb_{bare}_{m}"); + let params: Vec = method.params.iter().map(|p| abi.ty(&p.ty)).collect(); + let ret = abi.ty(&method.ok); + self.import_decl(&name, ¶ms, &ret); + fields.push(format!("{m}: Some({name})")); + // The import, which calls the implementation the token names. + let module = std::mem::replace(&mut self.module, "glue".to_string()); + let t = self.named(class.clone()); + let wasm = self.imported(¶ms, &ret); + let mut lines = Vec::new(); + let mut lent = Vec::new(); + let mut args = Vec::new(); + for (n, (param, c)) in method.params.iter().zip(¶ms).enumerate() { + args.push(self.arg_in(¶m.ty, c, &format!("p{n}"), &mut lines, &mut lent)); + } + let member = method_name(m); + let call = format!("rt.find<{t}>(data).{member}({})", args.join(", ")); + let mut body = Vec::new(); + self.outgoing(&method.ok, &ret, &call, &mut body); + self.module = module; + let typed: Vec = (wasm.iter()) + .map(|p| match p.strip_prefix('p').and_then(|n| n.parse::().ok()) { + Some(n) => format!("{p}: {}", self.wasm_param(¶ms[n])), + None => format!("{p}: number"), + }) + .collect(); + let code = closed(&lines, &body, &lent); + self.imports.insert( + name, + format!( + "({}): {} =>\n\t\trt.out(\"{rust}::{m}\", () => {{\n{}\n\t\t}})", + typed.join(", "), + self.wasm_ret(&ret), + indent(&indent(&indent(&code))) + ), + ); + } + let _ = write!( + self.rust, + "static {}: crate::{c}_vtable = crate::{c}_vtable {{\n\t{},\n}};\n\n#[unsafe(no_mangle)]\npub extern \"C\" fn {space}_vtable_{bare}() -> *const crate::{c}_vtable {{\n\t&{}\n}}\n\n", + format!("VTABLE_{bare}").to_uppercase(), + fields.join(",\n\t"), + format!("VTABLE_{bare}").to_uppercase(), + ); + let export = format!("{space}_vtable_{bare}"); + self.index_fn(&local, &export) + } + + /// The value a call into JavaScript passes its implementation for the parameter `e` of + /// type `ty` and C type `c`: an object Rust lends for the call is closed after it. + fn arg_in(&mut self, ty: &Type, c: &Ty, e: &str, lines: &mut Vec, lent: &mut Vec) -> String { + if let Type::Ref(_, inner) = ty + && let Type::Object(i) = **inner + { + let kind = self.kind(i); + let t = self.tt(inner); + let l = format!("l{}", lent.len()); + lines.push(format!("const {l} = rt.lentHandle({e}, {kind}) as {t};")); + lent.push(l.clone()); + return l; + } + self.incoming(ty, c, e, lines) + } + + /// The trampoline of the closure type `ty`, `g.t`, and the glue's function giving the + /// table index of the C function of its signature, which calls it. + fn closure(&mut self, ty: &Type, closure: &Closure) -> (String, String) { + let abi = self.abi; + let space = self.space.clone(); + let sig = abi.closure(closure); + let Ty::Fn(c_params, c_ret) = &sig else { + unreachable!("a closure is a function") + }; + let (c_params, c_ret) = (c_params.clone(), (**c_ret).clone()); + let wasm = self.imported(&c_params, &c_ret); + let k = match self.relays.iter().position(|r| *r == sig) { + Some(k) => k, + None => { + self.relays.push(sig.clone()); + let k = self.relays.len() - 1; + let name = format!("{space}_i_fn_{k}"); + self.import_decl(&name, &c_params, &c_ret); + let fn_ty = format!( + "unsafe extern \"C\" fn(*mut c_void{}) -> {}", + c_params.iter().map(|ty| format!(", {}", rs(ty))).collect::(), + rs(&c_ret) + ); + let _ = write!( + self.rust, + "#[unsafe(no_mangle)]\npub extern \"C\" fn {space}_fn_{k}() -> usize {{\n\t{name} as {fn_ty} as usize\n}}\n\n" + ); + // The import, which calls the trampoline the token names with the closure. + let typed: Vec = (wasm.iter()) + .map(|p| match p.strip_prefix('p').and_then(|n| n.parse::().ok()) { + Some(n) => format!("{p}: {}", self.wasm_param(&c_params[n])), + None => format!("{p}: number"), + }) + .collect(); + let rest: Vec<&String> = wasm.iter().filter(|p| *p != "data").collect(); + let rest: String = rest.iter().map(|p| format!(", {p}")).collect(); + self.imports.insert( + name, + format!( + "({}): {} => {{\n\t\tconst [t, f] = rt.find<[(...a: any[]) => any, unknown]>(data);\n\t\treturn t(f{rest});\n\t}}", + typed.join(", "), + self.wasm_ret(&c_ret) + ), + ); + k + } + }; + let relay = self.index_fn(&format!("f{k}"), &format!("{space}_fn_{k}")); + // The trampoline, per closure type, since two of one C signature may lift apart. + let t = match self.trampolines.iter().position(|t| t == ty) { + Some(t) => t, + None => { + self.trampolines.push(ty.clone()); + let t = self.trampolines.len() - 1; + let module = std::mem::replace(&mut self.module, "glue".to_string()); + let tt = self.tt(ty); + let mut lines = Vec::new(); + let mut lent = Vec::new(); + let mut args = Vec::new(); + for (n, (param, c)) in closure.params.iter().zip(&c_params).enumerate() { + args.push(self.arg_in(param, c, &format!("p{n}"), &mut lines, &mut lent)); + } + let call = format!("f({})", args.join(", ")); + let mut body = Vec::new(); + match &closure.err { + None => self.outgoing(&closure.ok, &c_ret, &call, &mut body), + // Its value goes to the out before last, and its error to the last. + Some(err) => { + let at = closure.params.len(); + body.push(format!("const v$ = {call};")); + let mut ok = String::new(); + if closure.ok != Type::Unit { + ok = format!("{}\n", self.put(&closure.ok, "v$.value", &format!("p{at}"), true)); + } + let err_at = c_params.len() - 1; + let error = self.put(err, "v$.error", &format!("p{err_at}"), true); + let ok = indent(&format!("{ok}return 1;")); + body.push(format!("if (v$.ok) {{\n{ok}\n}}\n{error}\nreturn 0;")); + } + } + self.module = module; + let typed: Vec = std::iter::once(format!("f: {tt}")) + .chain(wasm.iter().filter(|p| *p != "data").map(|p| { + match p.strip_prefix('p').and_then(|n| n.parse::().ok()) { + Some(n) => format!("{p}: {}", self.wasm_param(&c_params[n])), + None => format!("{p}: number"), + } + })) + .collect(); + let ret = match &closure.err { + Some(_) => "number", + None => self.wasm_ret(&c_ret), + }; + let code = closed(&lines, &body, &lent); + self.helpers.insert( + format!("t{t}"), + format!( + "export function t{t}({}): {ret} {{\n\treturn rt.out(\"a closure\", () => {{\n{}\n\t}});\n}}\n\n", + typed.join(", "), + indent(&indent(&code)) + ), + ); + t + } + }; + (relay, format!("g.t{t}")) + } +} + +/// Statements running `lines`, then `body`, closing each handle of `lent` after `body`. +fn closed(lines: &[String], body: &[String], lent: &[String]) -> String { + let mut code: Vec = lines.to_vec(); + match lent.is_empty() { + true => code.extend(body.iter().cloned()), + false => { + let closes: Vec = lent.iter().map(|l| format!("{l}[Symbol.dispose]();")).collect(); + code.push(format!( + "try {{\n{}\n}} finally {{\n\t{}\n}}", + indent(&body.join("\n")), + closes.join("\n\t") + )); + } + } + code.join("\n") +} + +/// A trait method's name in camel case, with `$` appended if a reserved word or `close`. +fn method_name(name: &str) -> String { + let name = camel(name); + // `close` is the hook Rust calls once it drops an implementation. + match RESERVED.contains(&name.as_str()) || name == "close" { + true => format!("{name}$"), + false => name, + } +} + +impl Gen<'_> { + fn items(&mut self) { + let abi = self.abi; + let api = abi.api; + self.names.insert("load".to_string(), "the binding's load".to_string()); + self.module = "index".to_string(); + for constant in &api.constants { + if !self.here(constant.on) { + continue; + } + let name = abi::snake(self.bare(&abi.name(&constant.path))).to_uppercase(); + let name = abi::claim( + &mut self.names, + |n| RESERVED.contains(&n), + &name, + format!("const `{}`", constant.path.join("::")), + ); + self.locked + .insert(format!("const {}", constant.path.join("::")), name.clone()); + let value = match constant.value { + Literal::Bool(b) => b.to_string(), + // Past a safe integer, the type's constructor of its halves, by the type and + // not the sign: `i64::MAX` is an `rt.i64`. + Literal::Int(int @ (Int::U64 | Int::I64), v) if v.unsigned_abs() > (1 << 53) - 1 => { + let bits = v as u64; + match int { + Int::I64 => format!("rt.i64Of({}, {})", (bits >> 32) as u32 as i32, bits as u32), + _ => format!("rt.u64Of({}, {})", bits >> 32, bits as u32), + } + } + Literal::Int(_, v) => v.to_string(), + }; + let ty = match constant.value { + Literal::Bool(_) => "boolean", + Literal::Int(Int::U64, _) => "rt.u64", + Literal::Int(Int::I64, _) => "rt.i64", + Literal::Int(..) => "number", + }; + let code = format!("{}export const {name}: {ty} = {value};\n\n", docs(&constant.docs, "")); + self.out().body.push_str(&code); + } + for i in 0..api.records.len() { + self.record(i); + } + for i in 0..api.enums.len() { + self.enumeration(i); + } + for i in 0..api.objects.len() { + self.object(i); + } + for i in 0..api.callbacks.len() { + self.callback(i); + } + self.module = "index".to_string(); + let mut taken = BTreeSet::new(); + for function in &api.functions { + if let Some(code) = self.function(function, None, None, &mut taken) { + self.module = "index".to_string(); + self.out().body.push_str(&code); + self.out().body.push('\n'); + } + } + } + + /// Start the module of the type `name`, writing its declaration. + fn start(&mut self, name: &str, declaration: String) { + self.module = name.to_string(); + let module = self.out(); + module.exports.insert(name.to_string()); + module.body.push_str(&declaration); + } + + /// Each method of a type, into its module. + fn methods(&mut self, methods: &[Function], owner: &Ty, ty: &Type, taken: &mut BTreeSet) { + let module = self.module.clone(); + for method in methods { + if let Some(code) = self.function(method, Some(owner), Some(ty), taken) { + self.module = module.clone(); + self.out().body.push_str(&code); + self.out().body.push('\n'); + } + } + self.module = module; + } + + fn record(&mut self, i: usize) { + let abi = self.abi; + let record = &abi.api.records[i]; + if !self.here(record.on) { + return; + } + let c = abi.record(i); + let name = self.class(&c); + let rust = abi.api.rust(&record.path, &record.args); + let ty = Type::Record(i); + self.module = name.clone(); + let declaration = match &record.opaque { + Some(_) => { + let text = format!( + "{rust}\n\nIts bytes, which only Rust makes or reads: copy it, but never make one.\n\n{}", + record.docs + ); + format!("{}export type {name} = rt.Opaque<\"{name}\">;\n\n", docs(&text, "")) + } + None => { + let fields: Vec = (record.fields.iter().zip(field_names(&record.fields))) + .map(|(f, name)| format!("{}\t{name}: {};\n", docs(&f.docs, "\t"), self.tt(&f.ty))) + .collect(); + let text = format!("{rust}\n\n{}", record.docs); + format!("{}export type {name} = {{\n{}}};\n\n", docs(&text, ""), fields.concat()) + } + }; + self.start(&name, declaration); + let mut taken = BTreeSet::new(); + self.traits(&ty, &c, record.traits, &mut taken); + self.methods(&record.methods, &Ty::Struct(c.clone()), &ty, &mut taken); + } + + fn enumeration(&mut self, i: usize) { + let abi = self.abi; + let e = &abi.api.enums[i]; + if !self.here(e.on) { + return; + } + let c = abi.enumeration(i); + let name = self.class(&c); + let rust = abi.api.rust(&e.path, &e.args); + let ty = Type::Enum(i); + self.module = name.clone(); + let variants: Vec = match e.plain() { + true => (e.variants.iter()) + .filter(|v| self.here(v.on)) + .map(|v| format!("\"{}\"", v.name)) + .collect(), + false => { + let mut cases = Vec::new(); + let here: Vec<_> = e.variants.iter().filter(|v| self.here(v.on)).collect(); + for variant in here { + let mut fields = vec![format!("tag: \"{}\"", variant.name)]; + for (field, name) in variant.fields.iter().zip(variant_fields(&variant.fields)) { + fields.push(format!("{name}: {}", self.tt(&field.ty))); + } + cases.push(format!("{{ {} }}", fields.join("; "))); + } + cases + } + }; + let union = match variants.is_empty() { + true => "never".to_string(), + false => format!("\n\t| {}", variants.join("\n\t| ")), + }; + let text = format!("{rust}\n\n{}", e.docs); + self.start(&name, format!("{}export type {name} = {union};\n\n", docs(&text, ""))); + let mut taken = BTreeSet::new(); + self.traits(&ty, &c, e.traits, &mut taken); + self.methods(&e.methods, &abi.ty(&ty), &ty, &mut taken); + } + + fn object(&mut self, i: usize) { + let abi = self.abi; + let object = &abi.api.objects[i]; + if !self.here(object.on) { + return; + } + let c = abi.object(i); + let name = self.class(&c); + let rust = abi.api.rust(&object.path, &object.args); + let ty = Type::Object(i); + self.module = name.clone(); + let text = format!( + "{rust}\n\nA handle to it: `[Symbol.dispose]` drops it, as does the garbage collector one never disposed.\n\n{}", + object.docs + ); + self.start( + &name, + format!("{}export type {name} = rt.Handle<\"{name}\">;\n\n", docs(&text, "")), + ); + let owner = Ty::Handle { + name: c.clone(), + constant: false, + }; + let mut taken = BTreeSet::new(); + self.traits(&ty, &c, object.traits, &mut taken); + self.methods(&object.methods, &owner, &ty, &mut taken); + } + + /// The TypeScript type of what a function returns: a waker Rust returns is one + /// JavaScript can wake and drop, unlike the function a parameter takes. + fn returned_t(&mut self, ty: &Type) -> String { + match ty { + Type::Waker => "rt.Waker".to_string(), + _ => self.tt(ty), + } + } + + fn callback(&mut self, i: usize) { + let abi = self.abi; + let callback = &abi.api.callbacks[i]; + if !self.here(callback.on) { + return; + } + let c = abi.callback(i); + let name = self.class(&c); + let rust = callback.path.join("::"); + self.module = name.clone(); + let mut members = Vec::new(); + for method in &callback.methods { + let member = method_name(method.name()); + crate::lock::function(&mut self.locked, method, &member); + let params: Vec = (method.params.iter()) + .map(|p| format!("{}: {}", param_name(&p.name), self.tt(&p.ty))) + .collect(); + let ok = self.tt(&method.ok); + members.push(format!( + "{}\t{member}({}): {ok};\n", + docs(&method.docs, "\t"), + params.join(", ") + )); + } + members.push( + "\t/** Called once Rust drops this implementation, to free what it holds. */\n\tclose?(): void;\n" + .to_string(), + ); + let text = format!("{rust}: implemented in JavaScript.\n\n{}", callback.docs); + self.start( + &name, + format!( + "{}export interface {name} {{\n{}}}\n\n", + docs(&text, ""), + members.join("\n") + ), + ); + } + + /// The functions a type's std traits export, into its module: `Display` is `toString`, + /// `Debug` `debug`, `Clone` an object's `clone`, `PartialEq` `eq`, with `Hash` `hash`, + /// and `Default` `default`. + fn traits(&mut self, ty: &Type, c: &str, t: crate::ir::Traits, taken: &mut BTreeSet) { + let abi = self.abi; + let name = self.tt(ty); + let object = matches!(ty, Type::Object(_)); + let c_ty = abi.ty(ty); + let recv = match object { + true => Ty::Handle { + name: c.to_string(), + constant: true, + }, + false => Ty::In(Box::new(c_ty.clone())), + }; + let status = abi.traits_status_of(ty); + // The statements passing `e` as the receiver, making `local`. + let this = |g: &mut Self, e: &str, local: &str| -> String { + match object { + true => format!("const {local} = rt.hold({e});"), + false => { + let l = g.layout(&c_ty); + let put = g.put(ty, e, local, false); + format!("const {local} = rt.alloc({}, {});\n{put}", l.size.max(1), l.align) + } + } + }; + let mut emit = |g: &mut Self, member: &str, doc: &str, params: &str, ret_t: &str, body: Vec| { + taken.insert(member.to_string()); + let (local, rename) = match RESERVED.contains(&member) { + true => (format!("{member}$"), true), + false => (member.to_string(), false), + }; + let code = format!( + "/** {doc} */\nexport function {local}({params}): {ret_t} {{\n{}\n}}\n\n", + indent(&wrap(&body)) + ); + let module = g.out(); + module.body.push_str(&code); + if rename { + module.renames.insert(local, member.to_string()); + } + }; + let text = |g: &mut Self, what: &str| -> Vec { + let mut lines = vec![this(g, "self", "a$")]; + let ret = g.invoke( + &format!("{c}_{what}"), + vec!["a$".to_string()], + &Ty::Buf, + status, + &mut lines, + ); + let value = g.result(&Type::String, &ret); + lines.push(format!("return {value};")); + lines + }; + if t.display { + let body = text(self, "to_string"); + emit( + self, + "toString", + "Rust's `Display` form.", + &format!("self: {name}"), + "string", + body, + ); + } + if t.debug { + let body = text(self, "debug"); + emit( + self, + "debug", + "Rust's `Debug` form.", + &format!("self: {name}"), + "string", + body, + ); + } + if object && t.clone { + let mut lines = vec![this(self, "self", "a$")]; + let ret = self.invoke(&format!("{c}_clone"), vec!["a$".to_string()], &recv, status, &mut lines); + let value = self.result(ty, &ret); + lines.push(format!("return {value};")); + emit( + self, + "clone", + "A new handle to a clone.", + &format!("self: {name}"), + &name, + lines, + ); + } + let plain = matches!(ty, Type::Enum(i) if abi.api.enums[*i].plain()); + if t.eq && !plain { + let mut lines = vec![this(self, "a", "a$"), this(self, "b", "b$")]; + let args = vec!["a$".to_string(), "b$".to_string()]; + let ret = self.invoke(&format!("{c}_eq"), args, &Ty::Bool, status, &mut lines); + let value = self.result(&Type::Bool, &ret); + lines.push(format!("return {value};")); + emit( + self, + "eq", + "Rust's `PartialEq`.", + &format!("a: {name}, b: {name}"), + "boolean", + lines, + ); + if t.hash { + let mut lines = vec![this(self, "self", "a$")]; + let u64 = Ty::Int(Int::U64); + let ret = self.invoke(&format!("{c}_hash"), vec!["a$".to_string()], &u64, status, &mut lines); + let value = self.result(&Type::Int(Int::U64), &ret); + lines.push(format!("return {value};")); + emit( + self, + "hash", + "Rust's `Hash`, which values Rust calls equal share.", + &format!("self: {name}"), + "rt.u64", + lines, + ); + } + } + if t.default { + let ret_c = match object { + true => Ty::Handle { + name: c.to_string(), + constant: false, + }, + false => c_ty.clone(), + }; + let mut lines = Vec::new(); + let ret = self.invoke(&format!("{c}_default"), Vec::new(), &ret_c, false, &mut lines); + let value = self.result(ty, &ret); + lines.push(format!("return {value};")); + emit(self, "default", "Rust's `Default`.", "", &name, lines); + } + } +} + +/// Statements running `lines` in a call's frame, which gives back what it took. +fn wrap(lines: &[String]) -> String { + format!( + "const m$ = rt.enter();\ntry {{\n{}\n}} finally {{\n\trt.leave(m$);\n}}", + indent(&lines.join("\n")) + ) +} + +impl Gen<'_> { + /// `function`'s TypeScript, a function of the module of its type `owner_ty` if it has + /// one, whose C type is `owner`, named apart from `taken`; none if not on the target. + fn function( + &mut self, + function: &Function, + owner: Option<&Ty>, + owner_ty: Option<&Type>, + taken: &mut BTreeSet, + ) -> Option { + let abi = self.abi; + if !self.here(function.on) { + return None; + } + let module = self.module.clone(); + // A value is copied into JavaScript, so its `&mut self` method returns it as the call + // left it, calling the C function in place on a copy the glue hands back. + let handed = (owner.zip(owner_ty)).and_then(|(owner, ty)| abi.handed_back(function, owner, ty)); + let (handed, export, call_name) = match handed { + Some((back, export, handed)) => { + let name = format!("{}_h_{}", self.space, self.bare(&export.call.name)); + let decls: Vec = (export.call.params.iter().enumerate()) + .map(|(n, (_, ty))| format!("p{n}: {}", rs(ty))) + .collect(); + let args: Vec = (0..export.call.params.len()).map(|n| format!("p{n}")).collect(); + let _ = write!( + self.rust, + "#[unsafe(no_mangle)]\npub unsafe extern \"C\" fn {name}({}) -> {} {{\n\t{}\n}}\n\n", + decls.join(", "), + rs(&export.call.ret), + handed.call(&args) + ); + (Some(back), export, name) + } + None => { + let export = abi.export(function, owner); + let name = export.call.name.clone(); + (None, export, name) + } + }; + let function = handed.as_ref().unwrap_or(function); + let c_name = export.call.name.clone(); + let owner_c = match owner { + Some(Ty::Struct(n) | Ty::Enum(n) | Ty::Handle { name: n, .. }) => Some(n.clone()), + _ => None, + }; + let own = match &owner_c { + Some(o) => export.named.strip_prefix(o.as_str()).and_then(|r| r.strip_prefix('_')), + None => None, + }; + // Named as Rust's path is, whatever C's clashes rename. + let named = self.bare(&export.named).to_string(); + let snake = own.unwrap_or(&named); + let base = match function.access { + Access::Const => abi::snake(snake).to_uppercase(), + _ => camel(snake), + }; + let member = match owner { + None => abi::claim( + &mut self.names, + |_| false, + &base, + format!("fn `{}`", function.path.join("::")), + ), + Some(_) => { + let mut member = base; + while taken.contains(&member) { + member.push('_'); + } + member + } + }; + taken.insert(member.clone()); + crate::lock::function(&mut self.locked, function, &member); + let local = match RESERVED.contains(&member.as_str()) { + true => format!("{member}$"), + false => member.clone(), + }; + + let receiver = function.receiver.filter(|_| owner.is_some()); + let mut params = Vec::new(); + let mut lines = Vec::new(); + let mut gives = Vec::new(); + let mut args = Vec::new(); + let mut c_params = export.call.params.iter(); + if receiver.is_some() { + let (_, c) = c_params.next().expect("a method has its receiver"); + let ty = owner_ty.expect("a method has its type").clone(); + let t = self.tt(&ty); + params.push(format!("self: {t}")); + match c { + Ty::Handle { .. } => lines.push("const self$ = rt.hold(self);".to_string()), + Ty::In(inner) => { + let l = self.layout(inner); + let put = self.put(&ty, "self", "self$", false); + lines.push(format!( + "const self$ = rt.alloc({}, {});\n{put}", + l.size.max(1), + l.align + )); + } + other => unreachable!("a receiver is {other:?}"), + } + args.push("self$".to_string()); + } + // Distinct from each other, and from the receiver's `self`. + let receiving = receiver.is_some() as usize; + let names = (function.params.iter()).map(|param| param_name(¶m.name)); + let names = abi::distinct(["self".to_string()].into_iter().take(receiving).chain(names)); + let names = names.into_iter().skip(receiving); + let mut writes = Vec::new(); + for (k, (param, name)) in function.params.iter().zip(names).enumerate() { + let (_, c) = c_params.next().expect("each parameter has its C one"); + let a = format!("a{k}$"); + // A value passed for `&mut`, in a place that takes what Rust writes back. + if param.ty.written() { + let inner = param.ty.base(); + let t = self.tt(inner); + params.push(format!("{name}: rt.Place<{t}>")); + let value = format!("{name}.v"); + lines.push(self.pass(inner, c, &value, &a)); + args.push(a); + let out = Abi::written(function, &abi::escape(¶m.name)); + let read = self.get(inner, &format!("o_{out}"), true); + writes.push(format!("{value} = {read};")); + continue; + } + let t = self.tt(¶m.ty); + params.push(format!("{name}: {t}")); + match (¶m.ty, c) { + (Type::Closure(closure), Ty::Fn(..)) => { + c_params.next().expect("a closure has its data"); + let (relay, trampoline) = self.closure(¶m.ty, closure); + args.push(format!("{relay}()")); + if closure.kept { + // Given to Rust, which frees it through `free`. + c_params.next().expect("a kept closure has its free"); + gives.push(format!("const {a} = rt.give([{trampoline}, {name}]);")); + args.push(a); + args.push("rt.fn.free".to_string()); + } else { + lines.push(format!("const {a} = rt.lend([{trampoline}, {name}]);")); + args.push(a); + } + } + (_, Ty::ForeignReader) => { + lines.push(format!("const {a} = rt.alloc(12, 4);\nrt.readerOf({a}, {name});")); + args.push(a); + } + (Type::Callback(..), c) | (Type::Box(_), c @ Ty::Struct(_)) + if matches!(param.ty.base(), Type::Callback(..)) => + { + let l = self.layout(c); + let put = self.put(param.ty.base(), &name, &a, false); + gives.push(format!("const {a} = rt.alloc({}, {});\n{put}", l.size, l.align)); + args.push(a); + } + (Type::Waker, _) => { + gives.push(format!("const {a} = rt.alloc(12, 4);\nrt.wakerOf({a}, {name});")); + args.push(a); + } + (Type::Future, _) => { + gives.push(format!("const {a} = rt.alloc(12, 4);\nrt.futureOf({a}, {name});")); + args.push(a); + } + (ty, c) => { + lines.push(self.pass(ty, c, &name, &a)); + args.push(a); + } + } + } + let outs: Vec<(String, Ty)> = c_params.filter(|(_, ty)| !abi::is_status(ty)).cloned().collect(); + let status = export.call.status().is_some(); + lines.extend(gives); + + let ok = strip_refs(&function.ok); + let err = function.err.as_ref().map(strip_refs); + let ok_t = self.returned_t(&ok); + let value_t = match &err { + Some(err) => { + let err_t = self.tt(err); + format!("rt.Result<{}, {err_t}>", self.value(&ok, &ok_t)) + } + None => ok_t.clone(), + }; + let ret_t; + if let Some(abi::Future { start, poll, free, .. }) = &export.future { + ret_t = format!("rt.Call<{value_t}>"); + // Its outputs, without the thread check a future that is not `Send` polls with. + let poll_outs: Vec<(String, Ty)> = poll.params[2..] + .iter() + .filter(|(_, ty)| !abi::is_status(ty)) + .cloned() + .collect(); + // The poll, which completes the future. + let poll_name = format!("p_{}", self.bare(&c_name)); + let mut poll_lines = Vec::new(); + let mut poll_args = vec!["f".to_string(), "w$".to_string()]; + for (n, ty) in &poll_outs { + poll_lines.push(out_decl(self, n, ty)); + poll_args.push(format!("o_{n}")); + } + let ready = match &ok { + Type::Unit => "undefined".to_string(), + _ => self.lift_outs(&function.ok, &ok), + }; + let ready = match &err { + Some(_) => format!("rt.Ok({ready})"), + None => ready, + }; + let failed = err + .as_ref() + .map(|err| format!("rt.Err({})", self.get(err, "o_err", true))); + let ret = self.invoke( + &poll.name, + poll_args, + &poll.ret, + poll.status().is_some(), + &mut poll_lines, + ); + let Ret::Value(r) = ret else { + unreachable!("a poll returns its state") + }; + let mut cases = vec![format!("case 1:\n\treturn [true, {ready}];")]; + if let Some(failed) = &failed { + cases.push(format!("case 2:\n\treturn [true, {failed}];")); + } + cases.push("default:\n\treturn [false, undefined as never];".to_string()); + poll_lines.push(format!("switch ({r}) {{\n{}\n}}", indent(&cases.join("\n")))); + let module_ = std::mem::replace(&mut self.module, "glue".to_string()); + let value_g = match &err { + Some(err) => { + let err_t = self.tt(err); + let ok_t = self.returned_t(&ok); + format!("rt.Result<{}, {err_t}>", self.value(&ok, &ok_t)) + } + None => self.returned_t(&ok), + }; + self.module = module_; + self.helpers.insert( + poll_name.clone(), + format!( + "export function {poll_name}(f: number, w$: number): [boolean, {value_g}] {{\n{}\n}}\n\n", + indent(&poll_lines.join("\n")) + ), + ); + // The call and its first poll in one, which completes the call if ready, or else + // leaves it the future to poll. + for (n, ty) in &poll_outs { + lines.push(out_decl(self, n, ty)); + args.push(format!("o_{n}")); + } + lines.push("const of$ = rt.alloc(4, 4);".to_string()); + args.push("of$".to_string()); + let started = self.invoke(&start.name, args, &start.ret, status, &mut lines); + let Ret::Value(r) = started else { + unreachable!("a start returns its state") + }; + let mut cases = vec![format!("case 1:\n\treturn rt.ready({ready});")]; + if let Some(failed) = &failed { + cases.push(format!("case 2:\n\treturn rt.ready({failed});")); + } + cases.push(format!( + "default:\n\treturn rt.pending(rt.dv().getUint32(of$, true), g.{poll_name}, \"{}\");", + free.name + )); + lines.push(format!("switch ({r}) {{\n{}\n}}", indent(&cases.join("\n")))); + } else { + ret_t = value_t; + for (n, ty) in &outs { + lines.push(out_decl(self, n, ty)); + args.push(format!("o_{n}")); + } + let ret = self.invoke(&call_name, args, &export.call.ret, status, &mut lines); + lines.extend(writes.iter().cloned()); + match &err { + Some(err) => { + let Ret::Value(r) = &ret else { + unreachable!("a call that fails returns whether it did") + }; + let value = match &ok { + Type::Unit => "undefined".to_string(), + _ => self.lift_outs(&function.ok, &ok), + }; + let error = self.get(err, "o_err", true); + lines.push(format!("return {r} !== 0 ? rt.Ok({value}) : rt.Err({error});")); + } + None if ok == Type::Unit => {} + None if outs.len() > writes.len() => { + let value = self.lift_outs(&function.ok, &ok); + lines.push(format!("return {value};")); + } + None => { + let value = match ok { + Type::Waker => self.result(&Type::Waker, &ret), + _ => self.result(&ok, &ret), + }; + lines.push(format!("return {value};")); + } + } + } + self.module = module; + + let mut text = function.docs.clone(); + if handed.is_some() { + text.push_str( + "\n\nRust changes a copy of this value, which it returns first, as the call left it: this one never changes.", + ); + } + for param in &function.params { + let name = param_name(¶m.name); + if let Type::Closure(closure) = ¶m.ty { + text.push_str(&match closure.kept { + true => format!("\n\nRust keeps `{name}` until it drops it."), + false => format!("\n\nRust calls `{name}` only during the call."), + }); + if closure.params.iter().any(|p| matches!(p.base(), Type::Object(_))) { + text.push_str(&format!( + "\nAn object it lends lives only for that call of `{name}`: keep none past it." + )); + } + if closure.err.is_some() { + text.push_str("\nIt fails by returning an `Err`; anything it throws aborts."); + } + } + } + if function.future { + text.push_str("\n\nCancelling it cancels it in Rust, losing nothing."); + } + let ret_t = match ok { + Type::Unit if err.is_none() && !function.future => "void".to_string(), + _ => ret_t, + }; + if local != member { + self.out().renames.insert(local.clone(), member.clone()); + } + Some(format!( + "{}export function {local}({}): {ret_t} {{\n{}\n}}\n", + docs(&text, ""), + params.join(", "), + indent(&wrap(&lines)) + )) + } + + /// The value of a call's outs, which return `ok`, or each element of a tuple. + fn lift_outs(&mut self, declared: &Type, ok: &Type) -> String { + match declared { + Type::Tuple(elements) => { + let lifted: Vec = (elements.iter().enumerate()) + .map(|(n, e)| self.get(&strip_refs(e), &format!("o_out{n}"), true)) + .collect(); + format!("[{}]", lifted.join(", ")) + } + _ => self.get(ok, "o_out", true), + } + } +} + +/// The declaration of the local the call writes the out `name` of C type `ty` to. +fn out_decl(g: &Gen<'_>, name: &str, ty: &Ty) -> String { + let Ty::Out(inner) = ty else { + unreachable!("an out parameter is a pointer") + }; + let l = g.layout(inner); + format!("const o_{name} = rt.alloc({}, {});", l.size.max(1), l.align) +} + +#[cfg(test)] +mod tests { + use super::*; + + /// A field or parameter named as a namespace imports nothing; a member read imports it. + #[test] + fn imports_follow_member_reads() { + assert_eq!( + module_imports("type Rgb = { r: number; g: number };\nfunction f(rt: number) {}"), + "" + ); + assert_eq!( + module_imports("return g.f(rt.alloc(4, 4));"), + "import * as rt from \"./rt.ts\";\nimport * as g from \"./glue.ts\";\n" + ); + assert!(!uses("x.rt.y", "rt.")); + } + + fn fields(names: &[&str]) -> Vec { + (names.iter()) + .map(|name| crate::ir::Field { + name: name.to_string(), + docs: String::new(), + ty: Type::Unit, + }) + .collect() + } + + /// A variant's field named `tag` keeps clear of the tag naming the variant, and fields + /// alike in camel case keep apart. + #[test] + fn field_names_distinct() { + assert_eq!(variant_fields(&fields(&["tag", "tag_name"])), ["tag$", "tagName"]); + assert_eq!(field_names(&fields(&["tag", "foo", "foo_"])), ["tag", "foo", "foo2"]); + } +} diff --git a/ffi/tests/api.c b/ffi/tests/api.c index 661316a5d..d3cd365a3 100644 --- a/ffi/tests/api.c +++ b/ffi/tests/api.c @@ -449,9 +449,9 @@ static bool closures(void) { /* A kept closure, called on another thread after the call that took it returned. */ bool spawned_freed = false; api_Spawned *spawned = api_Spawned_new(spawned_task, &spawned_freed, spawned_free); - printf("spawned %u\n", (unsigned)api_Spawned_join(spawned, NULL)); + uint32_t joined = api_Spawned_join(spawned, NULL); api_Spawned_free(spawned); - if (!spawned_freed) { + if (joined != 7 || !spawned_freed) { return false; } diff --git a/ffi/tests/api.cpp b/ffi/tests/api.cpp index 24e813740..c4384d21f 100644 --- a/ffi/tests/api.cpp +++ b/ffi/tests/api.cpp @@ -1460,7 +1460,10 @@ int script() { } #endif // A kept closure, called on another thread after the call that took it returned. - std::printf("spawned %u\n", static_cast(api::Spawned::new_([] { return 7; }).join())); + if (api::Spawned::new_([] { return 7; }).join() != 7) { + std::fprintf(stderr, "failed: a kept closure runs on another thread\n"); + return 1; + } // A kept closure: called again at the instant it asks for, then once its waiter wakes. { api::Moment began = *api::Moment::new_(0, 1000); diff --git a/ffi/tests/api.dart b/ffi/tests/api.dart index dc82e9e9d..d70e884c9 100644 --- a/ffi/tests/api.dart +++ b/ffi/tests/api.dart @@ -878,7 +878,7 @@ Future script() async { print('seat ${front.debug()} ${front == api.seat(nines, 1)} ${front == back}'); // A kept closure, called on another thread after the call that took it returned. final spawned = api.Spawned(() => 7); - print('spawned ${spawned.join()}'); + check(spawned.join() == 7, 'a kept closure runs on another thread'); // A kept closure: called again at the instant it asks for, then once its waiter wakes, // failing with the exception the binding throws for Rust's error. final start = api.Moment.new_(api.U64(0), api.U64(1000))!; diff --git a/ffi/tests/api.go b/ffi/tests/api.go index ffd081f1b..7a355f8a6 100644 --- a/ffi/tests/api.go +++ b/ffi/tests/api.go @@ -726,9 +726,9 @@ func script() { return escaped(*p) }), ",", ""), "[]")) // A path that is no UTF-8 is a Go string all the same. - check(must(api.Stray()) == "\xff", "a path that is not UTF-8 crosses as its bytes") + check(api.Stray() == "\xff", "a path that is not UTF-8 crosses as its bytes") var lent string - ok(api.VisitStray(func(path string) { lent = path })) + api.VisitStray(func(path string) { lent = path }) check(lent == "\xff", "a path Rust lends that is not UTF-8 crosses as its bytes") // An error Rust returns only boxed is its type. _, err = api.Refuse("why") @@ -948,7 +948,7 @@ func script() { fmt.Printf(" %x", must(api.SameChar(c))) } fmt.Println() - fmt.Printf("lossless path %x %x\n", must(api.SamePath("a/é")), must(api.SamePath(must(api.Stray())))) + fmt.Printf("lossless path %x %x\n", must(api.SamePath("a/é")), must(api.SamePath(api.Stray()))) sameV4 := api.SameSocketAddrV4(rt.SocketAddrV4{IP: rt.Ipv4Addr{255, 255, 255, 255}, Port: math.MaxUint16}) sameV6 := api.SameSocketAddrV6(rt.SocketAddrV6{ IP: rt.Ipv6Addr{0, 1, 15: 2}, @@ -1023,8 +1023,8 @@ func script() { } check(nines.Close() == nil, "a mark closes") // A kept closure, called on another thread after the call that took it returned. - spawned := api.NewSpawned(func() uint32 { return 7 }) - fmt.Printf("spawned %d\n", must(spawned.Join())) + spawned := must(api.NewSpawned(func() uint32 { return 7 })) + check(must(spawned.Join()) == 7, "a kept closure runs on another thread") // A kept closure: called again at the instant it asks for, then once its waiter wakes. driven := *api.NewMoment(0, 1000) calls := 0 @@ -1160,7 +1160,7 @@ func closures() { // A kept closure Rust releases once it drops it, after its thread called it. { marker, freed := marked() - spawned := api.NewSpawned(func() uint32 { return uint32(marker[0]) + 1 }) + spawned := must(api.NewSpawned(func() uint32 { return uint32(marker[0]) + 1 })) check(must(spawned.Join()) == 1, "a kept closure runs on Rust's thread") released(freed, "Rust releases a kept closure it dropped") } diff --git a/ffi/tests/api.kt b/ffi/tests/api.kt index 9eb13d6c9..b7380a2e4 100644 --- a/ffi/tests/api.kt +++ b/ffi/tests/api.kt @@ -740,7 +740,7 @@ fun script() { val rear = seat(nines, 2u) println("seat ${front.debug()} ${front == front.copy()} ${front == rear}") // A kept closure, called on another thread after the call that took it returned. - println("spawned ${Spawned.new { 7u }.join()}") + check(Spawned.new { 7u }.join() == 7u, "a kept closure runs on another thread") // A kept closure: called again at the instant it asks for, then once its waiter wakes. Moment.new(0u, 1000u)!!.let { start -> var calls = 0 diff --git a/ffi/tests/api.py b/ffi/tests/api.py index fc62a9947..259ef0d6d 100644 --- a/ffi/tests/api.py +++ b/ffi/tests/api.py @@ -811,7 +811,7 @@ async def polls(): front, back = api.seat(nines, 1), api.seat(nines, 2) print(f"seat {front!r} {str(front == api.seat(nines, 1)).lower()} {str(front == back).lower()}") # A kept closure, called on another thread after the call that took it returned. - print(f"spawned {api.Spawned.new(lambda: 7).join()}") + check(api.Spawned.new(lambda: 7).join() == 7, "a kept closure runs on another thread") # A kept closure: called again at the instant it asks for, then once its waiter wakes. start = api.Moment.new(0, 1000) calls = 0 diff --git a/ffi/tests/api.swift b/ffi/tests/api.swift index f17d15bc4..55bdc3c18 100644 --- a/ffi/tests/api.swift +++ b/ffi/tests/api.swift @@ -997,7 +997,7 @@ func script() { let back = try! seat(nines, 2) print("seat \(try! front.debugDescription) \(try! front == front) \(try! front == back)") // A kept closure, called on another thread after the call that took it returned. - print("spawned \(try! Spawned.new { 7 }.join())") + check(try! Spawned.new { 7 }.join() == 7, "a kept closure runs on another thread") // A kept closure: called again at the instant it asks for, then once its waiter wakes. let start = Moment.new(0, 1000)! let calls = Cell(0) @@ -1418,7 +1418,7 @@ func futures() { // Closures Rust keeps, released once Rust drops them, holding the only reference. do { let freed = Cell(false) - let spawned = Spawned.new { [held = Released(freed)] in + let spawned = try! Spawned.new { [held = Released(freed)] in _ = held return 1 } @@ -1638,11 +1638,11 @@ func lossless() { print("lossless char \(chars.map { String(sameChar($0).value, radix: 16) }.joined(separator: " "))") check(sameString("a\u{0}é\u{10ffff}") == "a\u{0}é\u{10ffff}", "text crosses") // A path that is not UTF-8, which no String holds, keeps its bytes. - let strayPath = try! stray() + let strayPath = stray() check(strayPath.string == nil && PathBuf("a/é").string == "a/é", "a path's text is nil unless UTF-8") print("lossless path \(hexBytes(samePath("a/é").bytes)) \(hexBytes(samePath(strayPath).bytes))") check(samePath(strayPath) == strayPath, "a path that is not UTF-8 crosses back") - try! visitStray { path in check(path == strayPath, "a lent path that is not UTF-8 keeps its bytes") } + visitStray { path in check(path == strayPath, "a lent path that is not UTF-8 keeps its bytes") } check(samePath(PathBuf(bytes: Bytes([0xff]))) == strayPath, "a caller's bytes make a path") let v4 = sameSocketAddrV4(SocketAddrV4(ip: Ipv4Addr(bits: .max), port: .max)) let ip6 = Ipv6Addr(bits: U128(high: 1 << 48, low: 2)) diff --git a/ffi/tests/api.ts b/ffi/tests/api.ts new file mode 100644 index 000000000..06f8ffbc1 --- /dev/null +++ b/ffi/tests/api.ts @@ -0,0 +1,1795 @@ +// The api fixture's web test: the script fixtures/api/examples/transcript.rs runs as +// native Rust does on wasm32-wasip1, through the generated TypeScript on Node, from beside +// the binding's `web` directory. RUST2_WASM is the path of the module, built with the +// crate's `web` feature. tests/fixtures.rs compares the transcripts. +// +// With an argument, it instead checks the futures' semantics, what disposing and the +// garbage collector free, what a closed object refuses, how returned bytes cross, or what +// a call lent bytes or text reads once memory grows, or breaks a contract, which must fail. + +import * as api from "./web/index.ts"; +import * as rt from "./web/rt.ts"; +import * as g from "./web/glue.ts"; +import * as Area from "./web/Area.ts"; +import * as Atlas from "./web/Atlas.ts"; +import * as Batch from "./web/Batch.ts"; +import * as Batch2 from "./web/Batch2.ts"; +import * as Berth from "./web/Berth.ts"; +import * as Board from "./web/Board.ts"; +import * as Cancelled from "./web/Cancelled.ts"; +import * as Channel from "./web/Channel.ts"; +import * as ClashSpan from "./web/ClashSpan.ts"; +import * as ClashStore from "./web/ClashStore.ts"; +import * as ClashTone from "./web/ClashTone.ts"; +import * as ClashTone_ from "./web/ClashTone_.ts"; +import * as Codecs from "./web/Codecs.ts"; +import * as Counter from "./web/Counter.ts"; +import * as Cursor from "./web/Cursor.ts"; +import * as Der from "./web/Der.ts"; +import * as Digest from "./web/Digest.ts"; +import * as Error_ from "./web/Error_.ts"; +import type * as Event from "./web/Event.ts"; +import * as Extent from "./web/Extent.ts"; +import * as Gap from "./web/Gap.ts"; +import * as Hits from "./web/Hits.ts"; +import * as Instant from "./web/Instant.ts"; +import * as Json from "./web/Json.ts"; +import * as Key from "./web/Key.ts"; +import * as Label from "./web/Label.ts"; +import * as Labelled from "./web/Labelled.ts"; +import * as Local from "./web/Local.ts"; +import type { Log } from "./web/Log.ts"; +import * as Logger from "./web/Logger.ts"; +import * as Mark from "./web/Mark.ts"; +import * as Measure from "./web/Measure.ts"; +import * as Message from "./web/Message.ts"; +import * as Meter from "./web/Meter.ts"; +import * as Meters from "./web/Meters.ts"; +import * as Moment from "./web/Moment.ts"; +import * as Name from "./web/Name.ts"; +import * as Node from "./web/Node.ts"; +import * as Numbers from "./web/Numbers.ts"; +import * as OuterInnerU8 from "./web/OuterInnerU8.ts"; +import * as PairSizeU8 from "./web/PairSizeU8.ts"; +import * as PairU32 from "./web/PairU32.ts"; +import * as PairU8Size from "./web/PairU8Size.ts"; +import * as Peer from "./web/Peer.ts"; +import * as Point from "./web/Point.ts"; +import * as Registry from "./web/Registry.ts"; +import * as Retry from "./web/Retry.ts"; +import * as Score from "./web/Score.ts"; +import * as Seat from "./web/Seat.ts"; +import * as Shape from "./web/Shape.ts"; +import * as Site from "./web/Site.ts"; +import * as SlotU8 from "./web/SlotU8.ts"; +import * as Span from "./web/Span.ts"; +import * as Stack from "./web/Stack.ts"; +import * as Stamp from "./web/Stamp.ts"; +import * as Tallies from "./web/Tallies.ts"; +import * as Tally from "./web/Tally.ts"; +import * as Ticket from "./web/Ticket.ts"; +import * as TlsConfig from "./web/TlsConfig.ts"; +import * as TlsSession from "./web/TlsSession.ts"; +import * as Token from "./web/Token.ts"; +import * as Trail from "./web/Trail.ts"; +import * as Url from "./web/Url.ts"; +import * as Verbosity from "./web/Verbosity.ts"; +import * as Waiter from "./web/Waiter.ts"; +import * as Weighted from "./web/Weighted.ts"; +import * as Window from "./web/Window.ts"; + +// Node's globals, which the binding's types leave out. +declare const process: { + readonly argv: string[]; + readonly env: Record; + exit(code: number): never; + readonly stderr: { write(text: string): boolean }; + getBuiltinModule(id: "node:fs"): { readFileSync(path: string): Uint8Array }; + getBuiltinModule(id: "node:v8"): { setFlagsFromString(flags: string): void }; + getBuiltinModule(id: "node:vm"): { runInNewContext(code: string): () => void }; +}; + +const print = (line: string) => console.log(line); + +/** A `u64` in decimal. */ +const dec = (v: rt.u64) => (typeof v === "number" ? `${v}` : `${rt.u64ToBig(v)}`); + +/** A `u64` as a number, which it must be. */ +function num(v: rt.u64): number { + if (typeof v !== "number") throw new RangeError(`${dec(v)} is past a safe integer`); + return v; +} + +const U64_MAX = rt.u64FromBig(0xffffffffffffffffn); + +/** A `u128` in hex, as transcript.rs prints it. */ +function hex128(v: rt.u128): string { + return rt.u128ToBig(v).toString(16).padStart(32, "0"); +} + +const encoder = new TextEncoder(); +const decoder = new TextDecoder(); +const enc = (text: string) => encoder.encode(text); +const text = (data: Uint8Array) => decoder.decode(data); +const bytes = (...values: number[]) => new Uint8Array(values); + +/** A list as Rust's `Debug` prints one. */ +function list(values: Iterable): string { + return `[${[...values].map((v) => `${v}`).join(", ")}]`; +} + +/** Bytes in hex, as transcript.rs prints them. */ +function hex(data: Uint8Array): string { + return [...data].map((b) => b.toString(16).padStart(2, "0")).join(""); +} + +/** A socket address as its IP's bytes in hex, its port, flow label, and scope, each IPv6's alone. */ +function socketHex(addr: rt.SocketAddr): string { + if (addr.tag === "V4") return `${hex(addr._0.ip.octets)}:${addr._0.port}`; + const v6 = addr._0; + return `${hex(v6.ip.octets)}:${v6.port}:${v6.flowinfo}:${v6.scopeId}`; +} + +const quoted = (values: string[]) => `[${values.map((v) => `"${v}"`).join(", ")}]`; + +/** A path's bytes as Rust's `escape_ascii` prints them. */ +function escaped(path: rt.PathBuf): string { + let out = ""; + for (const b of path.bytes) { + if (b === 0x09) out += "\\t"; + else if (b === 0x0d) out += "\\r"; + else if (b === 0x0a) out += "\\n"; + else if (b === 0x5c || b === 0x27 || b === 0x22) out += `\\${String.fromCharCode(b)}`; + else if (b >= 0x20 && b < 0x7f) out += String.fromCharCode(b); + else out += `\\x${b.toString(16).padStart(2, "0")}`; + } + return out; +} + +type Bound = ReturnType; + +function bound(b: Bound): string { + return b.tag === "Unbounded" ? "Unbounded" : `${b.tag}(${dec(b._0)})`; +} + +/** Each float's bits, as transcript.rs prints them. */ +const bits32 = (v: Float32Array) => list(new Uint32Array(v.buffer, v.byteOffset, v.length)); +const bits64 = (v: Float64Array) => list(new BigUint64Array(v.buffer, v.byteOffset, v.length)); + +function f64(bits: bigint): number { + return new Float64Array(new BigUint64Array([bits]).buffer)[0]; +} + +/** Print each of `n`'s lists, its floats as their bits, as transcript.rs does. */ +function numbers(what: string, n: Numbers.Numbers): void { + print(`${what} u16 ${list(n.u16s)}`); + print(`${what} u32 ${list(n.u32s)}`); + print(`${what} u64 ${list(n.u64s)}`); + print(`${what} i8 ${list(n.i8s)}`); + print(`${what} i16 ${list(n.i16s)}`); + print(`${what} i32 ${list(n.i32s)}`); + print(`${what} i64 ${list(n.i64s)}`); + print(`${what} f32 ${bits32(n.f32s)}`); + print(`${what} f64 ${bits64(n.f64s)}`); + print(`${what} some ${n.some === undefined ? "None" : `Some(${list(n.some)})`}`); +} + +/** The value of a result that must be `Ok`. */ +function unwrap(r: rt.Result): T { + if (!r.ok) throw new Error(`an unexpected Err: ${String(r.error)}`); + return r.value; +} + +/** The Log callback: keeps even levels. */ +class PrintLog implements Log { + log(level: number, line: string): boolean { + print(`log ${level} ${line}`); + return level % 2 === 0; + } + + // Rust closes it once it drops the implementation. + close(): void { + print("freed"); + } +} + +/** A Log that counts the lines it keeps and its closes, running `then` on each line. */ +class CountLog implements Log { + lines = 0; + closes = 0; + readonly then: (line: string) => void; + + constructor(then: (line: string) => void = () => {}) { + this.then = then; + } + + log(_level: number, line: string): boolean { + this.lines++; + this.then(line); + return true; + } + + close(): void { + this.closes++; + } +} + +const close = (handle: Disposable) => handle[Symbol.dispose](); + +function check(ok: boolean, what: string): void { + if (!ok) { + process.stderr.write(`failed: ${what}\n`); + process.exit(1); + } +} + +/** `f` throws an error of `type`, whose message `message` accepts. */ +function throws(f: () => unknown, type: new (...args: never[]) => Error, what: string, message?: (m: string) => boolean): void { + try { + f(); + } catch (e) { + check(e instanceof type && (message === undefined || message(e.message)), `${what}: ${String(e)}`); + return; + } + check(false, what); +} + +/** `f` throws the error of a closed `type`: the binding's own, for a value whose calls only + * borrow it, or else Rust's check of a moved value, naming the function. */ +function closed(f: () => unknown, type: string, what: string): void { + throws( + f, + Error, + what, + (m) => m === `${type} is closed` || (m.startsWith("api_") && m.endsWith(": a handle's value was moved out")), + ); +} + +/** `f` throws the error `message` of a close under a borrow. */ +function borrowed(f: () => unknown, message: string, what: string): void { + throws(f, Error, what, (m) => m === message); +} + +/** Let the event loop run what is ready. */ +const step = () => new Promise((resolve) => setTimeout(resolve, 0)); + +/** Run the event loop until `done()`, failing after a deadline. */ +async function until(done: () => boolean, what: string): Promise { + const deadline = Date.now() + 5000; + while (!done()) { + check(Date.now() < deadline, what); + await step(); + } +} + +/** `promise`'s value, failing past a deadline rather than waiting for a wake that never lands. */ +async function within(promise: Promise, what: string): Promise { + let timer: ReturnType | undefined; + const late = new Promise((_, reject) => { + timer = setTimeout(() => reject(new Error(`timed out: ${what}`)), 5000); + }); + try { + return await Promise.race([promise, late]); + } finally { + clearTimeout(timer); + } +} + +/** `promise` rejects with `rt.Cancelled`. */ +async function cancelled(promise: Promise, what: string): Promise { + try { + await within(promise, what); + } catch (e) { + check(e instanceof rt.Cancelled, `${what}: ${String(e)}`); + return; + } + check(false, what); +} + +/** Bytes a reader of `data` reads and seeks, as Rust's `Cursor` does. */ +class BytesReader implements rt.Reader { + at = 0n; + readonly data: Uint8Array; + readonly then: () => void; + + constructor(data: Uint8Array, then: () => void = () => {}) { + this.data = data; + this.then = then; + } + + read(buffer: Uint8Array): number { + this.then(); + const start = Number(this.at < BigInt(this.data.length) ? this.at : BigInt(this.data.length)); + const n = Math.min(buffer.length, this.data.length - start); + buffer.set(this.data.subarray(start, start + n)); + this.at += BigInt(n); + return n; + } + + seek(offset: rt.u64 | rt.i64, from: rt.SeekFrom): rt.u64 { + const by = from === "Start" ? rt.u64ToBig(offset as rt.u64) : rt.i64ToBig(offset as rt.i64); + const base = from === "Start" ? 0n : from === "Current" ? this.at : BigInt(this.data.length); + if (base + by < 0n) throw new Error("invalid seek to a negative or overflowing position"); + this.at = base + by; + return rt.u64FromBig(this.at); + } +} + +/** A reader whose reads fail, as the transcript's: each seek lands at 0. */ +class Broken implements rt.Reader { + read(_buffer: Uint8Array): number { + throw new Error("broken"); + } + + seek(_offset: rt.u64 | rt.i64, _from: rt.SeekFrom): rt.u64 { + return 0; + } +} + +/** A reader of nothing, which seeks anywhere from its start, as Rust's `Cursor` does. */ +class Far implements rt.Reader { + read(_buffer: Uint8Array): number { + return 0; + } + + seek(offset: rt.u64 | rt.i64, _from: rt.SeekFrom): rt.u64 { + return offset as rt.u64; + } +} + +async function script(): Promise { + print(`limit ${dec(api.LIMIT)}`); + check(`${rt.i64ToBig(api.FAR)}` === "9223372036854775807", "a constant past a safe integer keeps its type"); + + const p = Point.offset({ x: 1, y: 2 }, 2, 3); + print(`offset ${p.x} ${p.y}`); + print(`debug ${Point.debug(p)}`); + print(`eq ${Point.eq(p, { x: 3, y: 5 })}`); + const d = Point.default(); + print(`default ${d.x} ${d.y}`); + + const c = Counter.new("c", 5); + print(`get ${dec(Counter.get(c))}`); + print(`name ${Counter.name(c)}`); + print(`add ok ${dec(unwrap(Counter.add(c, 10)))}`); + const over = Counter.add(c, 2000); + if (!over.ok) print(`add err ${Error_.toString(over.error)} ${Error_.debug(over.error)}`); + const under = Counter.sub(c, 20); + if (!under.ok) print(`sub err ${Error_.toString(under.error)} ${Error_.debug(under.error)}`); + Counter.rename(c, "d"); + print(`name ${Counter.name(c)}`); + print(`is d ${Counter.is(c, "d")}`); + const copy = Counter.clone(c); + Counter.add(copy, 1); + print(`clone ${dec(Counter.get(copy))} original ${dec(Counter.get(c))}`); + close(copy); + print(`debug ${Counter.debug(c)}`); + const label = Counter.intoLabel(c, p); + print(`label ${Label.debug(label)}`); + print(`note ${api.hasText({ text: "" })} ${api.hasText({ text: undefined })}`); + + const [below, above] = Counter.split(Counter.new("s", 7), 5); + print(`split ${Counter.name(below)} ${dec(Counter.get(below))} ${Counter.name(above)} ${dec(Counter.get(above))}`); + const [only] = api.only(Counter.new("o", 3)); + print(`only ${Counter.name(only)} ${dec(Counter.get(only))}`); + const [w8, w16, w32, w64] = api.widths(98305); + print(`widths ${w8} ${w16} ${w32} ${dec(w64)}`); + for (const b of [2, 0]) { + const r = api.divide(7, b); + print(r.ok ? `divide ${dec(r.value[0])} ${dec(r.value[1])}` : `divide err ${Error_.toString(r.error)}`); + } + for (const n of [98305, 0]) { + const spread = api.spread(n); + print(spread === undefined ? "spread none" : `spread ${spread[0]} ${spread[1]} ${spread[2]} ${dec(spread[3])}`); + } + for (const needle of ["lo", "x"]) { + const found = api.find(enc("hello"), enc(needle)); + print(found === undefined ? "find none" : `find ${found[0]} ${found[1]}`); + } + const statRows = api.rows([ + { x: 1, y: 2 }, + { x: 3, y: 3 }, + ]); + print(`rows ${statRows.map(([n, s, at]) => `${n} ${Shape.debug(s)} ${at.x} ${at.y}`).join(", ")}`); + // Each handle in a tuple moves in, as one taken by value does, and the counters a board + // returns build another, each moved back in. + const first = Board.new([ + ["low", Counter.new("l", 1)], + ["high", Counter.new("h", 9)], + ]); + const board = Board.new(Board.intoCounters(first)); + const ranked = Board.ranked(board); + print(`ranked ${ranked.map(([n, r]) => `${n} ${Counter.name(r)} ${dec(Counter.get(r))}`).join(", ")}`); + const best = Board.best(board); + print(`best ${Counter.name(best)} ${dec(Counter.get(best))}`); + close(best); + close(board); + // A map crosses as its pairs and a set as its items, which Rust collects in order, each + // key once, the last kept. + const atlas = Atlas.with( + { + points: [ + ["b", { x: 1, y: 1 }], + ["ab", { x: 2, y: 3 }], + ["b", { x: 4, y: 4 }], + ], + ids: [3, 1, 3], + }, + "c", + { x: 5, y: 6 }, + ); + print(`atlas ${atlas.points.map(([n, at]) => `${n} ${at.x} ${at.y}`).join(", ")}; ids ${atlas.ids.join(" ")}`); + // Another crate's error crosses as its message. + for (const t of ["80", "x"]) { + const r = api.port(t); + print(r.ok ? `port ${r.value}` : `port err ${r.error}`); + } + const span: Span.Span = { bounds: [2, 10], named: ["s", "Square"] }; + const [lowerHalf, upperHalf] = api.halves(span); + print(`halves ${lowerHalf[0]} ${lowerHalf[1]} ${upperHalf[0]} ${upperHalf[1]} ${Span.debug(span)}`); + const [swappedN, swappedText] = api.swapped(["t", 4]); + print(`swapped ${swappedN} ${swappedText}`); + for (const value of [undefined, [undefined], [3]] as ([number | undefined] | undefined)[]) { + const doubled = api.doubled(value); + if (doubled === undefined) print("doubled None"); + else print(`doubled Some((${doubled[0] === undefined ? "None" : `Some(${doubled[0]})`},))`); + } + // A borrowed or boxed tuple of one is a tuple, not its element. + const [lentOne] = api.lentBack([bytes(1, 2)]); + const [boxedOne] = api.boxedTuple(bytes(3)); + print(`lent back ${list(lentOne)} boxed ${list(boxedOne)}`); + // A borrowed string and an owned one share a tuple struct. + print( + `title Some(("${api.title(true)![0]}",)) ${api.title(false) === undefined ? "None" : "Some"} ` + + `named Some(("${api.named("x")![0]}",))`, + ); + + // Each lent counter is a new handle to a clone. + const registry = Registry.new(Counter.new("first", 1)); + print(`last ${Registry.last(registry) !== undefined}`); + Registry.push(registry, Counter.new("last", 2)); + const lentFirst = Registry.firstGet(registry); + Counter.add(lentFirst, 10); + print(`first ${dec(Counter.get(Registry.firstGet(registry)))} lent ${dec(Counter.get(lentFirst))}`); + const last = Registry.last(registry)!; + Counter.add(last, 10); + print(`last ${dec(Counter.get(Registry.last(registry)!))} lent ${dec(Counter.get(last))}`); + // A closure lent for the call edits the first counter through a handle. + const by = 5; + const edited = Registry.edit(registry, (counter) => { + Counter.add(counter, by); + return Counter.edited(counter) && Counter.get(counter) === 6; + }); + print(`edit ${edited} ${dec(Counter.get(Registry.firstGet(registry)))}`); + // A setter moves an object in, as assignment does, closing it. + Registry.firstSet(registry, Counter.new("second", 3)); + print(`set first ${dec(Counter.get(Registry.firstGet(registry)))} ${Counter.name(Registry.firstGet(registry))}`); + print(`walk ${dec(api.walk(3, (cursor) => num(Cursor.at(cursor)) * 2))}`); + print(`each ${api.each(2, (at) => print(`visit ${at}`))}`); + print(`offset ${api.offset(() => 7, 3)}`); + print(`shift ${api.shift(() => 7, 4)}`); + + const name = Name.owned("a"); + const joined = Name.join(name, Name.owned("b")); + print(`joined ${Name.asStr(joined)} ${Name.debug(joined)} ${Name.eq(joined, name)}`); + Name.rename(joined, "c"); + print(`renamed ${Name.asStr(joined)}`); + const long = api.longer(joined, Name.owned("dd")); + print(`longer ${Name.asStr(long)}`); + print(`unnamed [${Name.asStr(api.unnamed())}]`); + const lit = Name.borrowed("lit"); + print(`borrowed ${Name.asStr(lit)} ${Name.shares(lit, Name.borrowed("lit"))} ${Name.shares(lit, Name.borrowed("other"))}`); + + print(`total ${dec(api.total({ start: 2, end: 5 }))}`); + print(`reach ${api.reach(2, 5)}`); + const scaled = [ + api.scaled(rt.u128FromBig((1n << 128n) - 1n), 1), + api.scaled(rt.u128FromBig((1n << 64n) + 1n), rt.u64FromBig(1n << 63n)), + api.scaled(rt.u128FromBig(1n << 127n), 2), + ]; + print(`scaled ${scaled.map((v) => (v === undefined ? "none" : hex128(v))).join(" ")}`); + const digest = Digest.new(); + Digest.sumSet(digest, unwrap(api.fingerprint("deadbeef"))); + const unparsed = api.fingerprint("zz"); + print( + `digest ${hex(Digest.sumGet(digest))} ${hex(Digest.flipped(digest, bytes(0xff, 0, 0xff, 0)))} ` + + `${unparsed.ok ? "" : unparsed.error}`, + ); + close(digest); + const batch = Batch.new(); + const batch2 = api.pair(); + let accepted = 0; + for (let v = 1; v <= 5; v++) if (Batch.push(batch, v)) accepted++; + let paired = 0; + for (let v = 1; v <= 3; v++) if (Batch2.push(batch2, v)) paired++; + const emptied = api.drain4(batch); + print( + `batch ${Batch.capacity(batch)} ${accepted} ${dec(emptied)} ${dec(api.drain4(batch))} ` + + `${Batch2.capacity(batch2)} ${paired} ${dec(api.drain2(batch2))}`, + ); + print(`capacities ${api.capacities42(batch, batch2)} ${api.capacities22(batch2, batch2)}`); + close(batch); + close(batch2); + const wide = api.widen({ start: 2, end: 5 }, 1); + print(`widen ${dec(wide.start)} ${dec(wide.end)}`); + const counts = ( + [ + [{ tag: "Included", _0: 2 }, { tag: "Excluded", _0: 5 }], + [{ tag: "Included", _0: 2 }, { tag: "Included", _0: 5 }], + [{ tag: "Included", _0: 3 }, { tag: "Unbounded" }], + [{ tag: "Unbounded" }, { tag: "Unbounded" }], + [{ tag: "Excluded", _0: 2 }, { tag: "Included", _0: 4 }], + ] as [Bound, Bound][] + ).map(([start, end]) => api.count({ start, end })); + print(`count ${counts.map(dec).join(" ")}`); + print(`end ${bound(api.end(3))} ${bound(api.end(0))}`); + const [endsStart, endsEnd] = api.ends(3); + print(`ends ${bound(endsStart)} ${bound(endsEnd)}`); + for (const n of [2, 5]) { + const r = api.below(n, 3); + print(r.ok ? `below ${dec(r.value)}` : `below err ${bound(r.error.start)} ${bound(r.error.end)}`); + } + const window: Window.Window = { range: { start: 2, end: 8 }, end: api.end(5) }; + print(`window ${Window.contains(window, 4)} ${Window.contains(window, 6)} ${Window.debug(window)}`); + + print(api.greet("x", "Square")); + print(`len ${api.len(enc("abc"))}`); + const binary = bytes(0xff, 0, 0x61); + print(`hex ${api.hex(binary)}`); + print(`timed hex ${api.timedHex(binary)}`); + print(`sample hex ${api.sampleHex(binary)}`); + print(`queued hex ${api.queuedHex(binary)}`); + print(`tick ${api.tickName({ name: "tick", at: undefined, ttl: undefined })}`); + print(`rooted ${api.rootedName({ name: "rooted", at: undefined, ttl: undefined })}`); + print(`stored ${api.storedText("stored")}`); + print(`layer ${api.layerName({ name: "layer", at: undefined, ttl: undefined })}`); + for (const event of [{ tag: "Moved", _0: p }, { tag: "Named", name: "n" }, { tag: "Done" }] as const) { + print(api.describe(event)); + } + + // A `Copy` value passed by value is copied, so it stays usable. + const stamp = Stamp.fromMillis(2500); + print(`secs ${dec(Stamp.secs(stamp))}`); + print(`later ${Stamp.later(Stamp.fromMillis(3000), stamp)}`); + print(`secs ${dec(Stamp.secs(stamp))}`); + print(`whole ${Stamp.debug(Stamp.whole(stamp))}`); + const message = Message.new(stamp, enc("body")); + print(`payload ${text(Message.payloadGet(message))}`); + print(`stamp ${Stamp.debug(Message.stampGet(message)!)}`); + print(`sent ${Message.sent(message)}`); + // Setters assign in place: the bytes are copied in, and a `Copy` value copied. + const reset = Stamp.fromMillis(4000); + Message.stampSet(message, reset); + Message.payloadSet(message, enc("edited")); + print(`payload ${text(Message.payloadGet(message))}`); + print(`stamp ${Stamp.debug(Message.stampGet(message)!)}`); + print(`secs ${dec(Stamp.secs(reset))}`); + Message.stampSet(message, undefined); + print(`stamp ${Message.stampGet(message) !== undefined}`); + + // A value past a word, copied across: a closure takes and returns one by value. + const moment = Moment.new(1500, 1000)!; + const Forged = rt.Opaque as unknown as new (bytes: Uint8Array) => Moment.Moment; + throws(() => new Forged(new Uint8Array(16)), TypeError, "a caller's opaque value"); + throws(() => Moment.millis({ bytes: new Uint8Array(16) } as unknown as Moment.Moment), RangeError, "a lookalike"); + print(`moment ${dec(Moment.millis(moment))} ${Moment.new(1, 0) === undefined}`); + const shifted = api.shifted(moment, (m) => Moment.after(m, 500)); + print(`shifted ${dec(Moment.millis(shifted))} ${Moment.eq(shifted, Moment.after(moment, 500))}`); + print(`wrapped ${dec(Moment.millis(Moment.after(moment, U64_MAX)))} ${Moment.eq(moment, shifted)}`); + + // A value with padding, or bytes that vary, is a handle, as no table says where padding is. + const gap = Gap.new(7, 3); + print(`gap ${dec(Gap.sum(gap))} ${Gap.eq(gap, Gap.new(7, 3))}`); + const berth = Berth.new(4); + print(`berth Some(${Berth.at(berth)}) ${Berth.at(Berth.new(undefined)) === undefined ? "None" : "Some"}`); + + // A `Copy` type changed in place is a value, which a `&mut self` method returns as the + // call left it, Rust's own return beside it: a change reaches only the copy it replaces. + let score = Score.of(2); + const increment = Score.of(3); + score = Score.add(score, increment); + score = Score.add(score, increment); + print(`score ${dec(Score.count(score))} ${dec(Score.count(Score.doubled(increment)))} ${dec(Score.count(increment))}`); + let [scoreCopy, taken] = Score.take(score); + print(`taken ${dec(taken)} ${dec(Score.count(scoreCopy))} ${dec(Score.count(score))}`); + const otherScore = { v: increment }; + const [absorbed, before0, before1] = Score.absorb(scoreCopy, otherScore); + scoreCopy = absorbed; + print( + `absorbed ${dec(before0)} ${dec(before1)} ${dec(Score.count(scoreCopy))} ` + + `${dec(Score.count(otherScore.v))} ${dec(Score.count(increment))}`, + ); + let hits = Hits.of(1, 2); + const keptHits = hits; + hits = Hits.add(hits, Hits.of(10, 20)); + hits = Hits.hitsSet(hits, 7); + print( + `hits ${dec(Hits.hitsGet(hits))} ${dec(Hits.missesGet(hits))} ${dec(Hits.hitsGet(keptHits))} ` + + `${dec(Hits.missesGet(keptHits))} ${Hits.eq(hits, keptHits)}`, + ); + const [counted, countedSame] = Hits.eq_(keptHits, keptHits); + print(`counted ${countedSame} ${dec(Hits.hitsGet(counted))}`); + let extent = Extent.new(5, 3); + const extentStart = extent; + const [slid, old] = Extent.slide(extent, 10); + extent = slid; + extent = Extent.startSet(extent, num(Extent.startGet(extent)) + 1); + print( + `extent ${dec(old)} ${dec(Extent.startGet(extent))} ${dec(Extent.end(extent))} ` + + `${dec(Extent.startGet(extentStart))} ${dec(Extent.end(extentStart))}`, + ); + const weighted = { score: increment, weight: 4 }; + print(`weighted ${dec(Weighted.total(weighted))} ${num(Score.count(weighted.score)) + num(Score.count(increment))}`); + // A checked mark beside bytes in a tuple and in a record lent, and bytes beside a move. + const mark = Mark.of(1); + Mark.add(mark, 2); + const parcel = { mark, payload: bytes(97, 98, 99) }; + print(`heft ${dec(api.heft([mark, bytes(97, 98)], parcel, [Counter.new("w", 1), bytes(97, 98, 99, 100)]))}`); + // A value's `&mut self` beside a checked handle. + const [noted, notedBefore] = Score.note(Score.of(2), Mark.of(5)); + print(`noted ${dec(notedBefore)} ${dec(Score.count(noted))}`); + + print(`kept ${api.emit(new PrintLog(), bytes(1, 2, 3, 4))}`); + const logger = Logger.new(new PrintLog()); + print(`write ${Logger.write(logger, "hi")}`); + close(logger); + print("dropped"); + const threshold = 2; + const filtered = api.filter(bytes(1, 2, 3, 4), (level, line) => { + print(`filter ${level} ${line}`); + return level > threshold; + }); + print(`filtered ${filtered}`); + + const channel = Channel.new(); + let wakes = 0; + // Polled at the call, it pends, and the wake the send posts resumes it from the event loop. + let got: Uint8Array | undefined; + const recv = Channel.recv(channel); + void recv.then((payload) => (got = payload)); + await step(); + print(`recv pending ${got === undefined}`); + Channel.send(channel, enc("hi")); + check(got === undefined, "recv never resumes inside the wake"); + await recv; + wakes++; + print(`woken ${wakes}`); + print(`recv ${text(got!)}`); + Channel.send(channel, new Uint8Array(0)); + const nonempty = await Channel.recvNonempty(channel); + print(nonempty.ok ? `nonempty ${nonempty.value.length}` : `nonempty err ${Error_.toString(nonempty.error)}`); + const fill4 = Batch.new(); + const fill2 = api.pair(); + print(`fill ${[...(await api.fill4(fill4, 9)), ...(await api.fill2(fill2, 1))].join(" ")}`); + close(fill4); + close(fill2); + // The send happens at the call: the future is dropped unawaited. + void Channel.sendLater(channel, enc("eager")); + print(`recv ${text(await Channel.recv(channel))}`); + // The send happens at the call, and the future borrows the channel and the tag. + print(`tagged ${await Channel.tagged(channel, "tag")}`); + print(`itemized ${await Channel.itemized(channel, new Uint32Array([1, 2, 3]))}`); + print(`byte_len ${await api.byteLen(enc("abc"))}`); + Channel.send(channel, enc("sized")); + const [payload, size] = await Channel.recvSized(channel); + print(`sized ${text(payload)} ${size}`); + // The waker moves into Rust, which keeps it until the send wakes it. + Channel.notify(channel, () => wakes++); + Channel.send(channel, enc("rung")); + await until(() => wakes === 2, "the send wakes the waker Rust keeps"); + print(`woken ${wakes}`); + // A poll with no async twin is a future. + print(`take ${text(await Channel.pollTake(channel))}`); + Channel.send(channel, enc("measured")); + print(`measure ${unwrap(await Channel.pollMeasure(channel, 2))}`); + // A context is made of the waker, which Rust keeps until the send wakes it. + Channel.listen(channel, () => wakes++); + Channel.send(channel, enc("heard")); + await until(() => wakes === 3, "the send wakes the context Rust keeps"); + print(`woken ${wakes}`); + // A returned waker wakes the waiter's task through Rust until it is disposed, after which + // a wake throws. + const waiter = Waiter.new(() => wakes++); + const waker = Waiter.waker(waiter); + const context = Waiter.context(waiter); + waker.wake(); + context.wake(); + close(waiter); + close(waker); + close(context); + close(context); + throws(() => waker.wake(), Error, "a closed waker throws", (m) => m === "Waker is closed"); + await until(() => wakes === 5, "a returned waker wakes the waiter"); + print(`woken ${wakes}`); + + const nodes = Node.new(1, undefined); + Node.push(nodes, 2); + print(`node ${dec(Node.sum(nodes))}`); + + const tally = Tally.new(); + Tally.bump(tally); + print(`tally ${Tally.bump(tally)} ${Tally.eq(tally, tally)}`); + print(`both ${api.bumpBoth(tally, tally)}`); + print(`peek ${api.peek(tally, (lent) => Tally.bump(lent))}`); + + const area = api.grow(Area.new({ width: 2, height: 3 }), 1); + const areaSize = Area.size(area); + print(`area ${areaSize.width} ${areaSize.height} ${dec(Area.pixels(area))}`); + + // Generic types, each at the instances it infers, named by their arguments. + const pair = { left: 2, right: 5 }; + const swapped = PairU32.swap(pair); + print(`pair ${swapped.left} ${swapped.right} sum ${PairU32.sum(pair)} ${PairU32.debug(pair)} ${PairU32.eq(pair, swapped)}`); + print(`even ${PairU32.even(pair)} ${PairU32.even({ left: 7, right: 7 })}`); + // An instance renamed alone, beside another of `Pair` that keeps its name. + const sized = api.tag({ width: 1, height: 2 }, 3); + const flipped = PairSizeU8.swap(sized); + print(`sized ${flipped.left} ${flipped.right.width} ${PairU8Size.debug(flipped)}`); + const beside = PairU32.besideSize({ left: 258, right: 9 }, sized.left); + print(`beside ${beside.left} ${PairU8Size.debug(beside)}`); + // At its default, named as the type itself. + const stack = Stack.new(); + ["a", "b"].forEach((n, i) => Stack.push(stack, Counter.new(n, i + 1))); + const top = dec(Counter.get(Stack.pop(stack)!)); + print(`stack ${Stack.depth(stack)} Some(${top}) ${Stack.pop(stack) !== undefined} ${Stack.pop(stack) === undefined}`); + // Generic functions and methods, at each implementation of the trait bounding them, by + // reference, which leaves JavaScript its object. + const fromPoint = Counter.seededPoint("p", { x: -3, y: 4 }); + const fromSize = Counter.seededSize("s", { width: 5, height: 6 }); + const fromCounter = Counter.seededCounter("c", fromPoint); + const fromPolar = Counter.seededPolarPoint("q", { turns: 1, distance: 2 }); + print( + `seeded ${dec(Counter.get(fromPoint))} ${dec(Counter.get(fromSize))} ${dec(Counter.get(fromCounter))} ` + + `${dec(Counter.get(fromPolar))} past ${dec(Stack.depthPastPoint(stack, { x: 1, y: 2 }))} ` + + `seeds ${dec(api.seedsPointSize({ width: 2, height: 3 }))}`, + ); + + // A trait implemented for `Point` and `&Point` apart: one instance. + print(`weigh ${api.weighPoint({ x: -1, y: 2 })}`); + // A function named as the type it returns, and one named as a type it does not. + print( + `polar ${api.polarPoint(2)!.distance} ${api.polarPoint(0) === undefined} ` + + `area ${dec(api.area({ width: 2, height: 3 }))}`, + ); + // Two types whose paths join alike, the second kept apart where its path splits. + print(`wind ${api.wind({ whole: 2 }, { part: 3 })}`); + // Names that clash in some language, each kept apart there. + const clashSpan = { width: 4 }; + const clashStore = ClashStore.new(7); + print( + `clash ${ClashTone.debug({ hz: 440 })} ${ClashTone_.debug({ db: 3 })} ${Cancelled.debug({ step: 2 })} ` + + `span ${ClashSpan.width(clashSpan)} ${ClashSpan.toString_(clashSpan)} ${ClashSpan.toString(clashSpan)} ` + + `store ${ClashStore.free(clashStore)} ${ClashStore.close(clashStore)} ` + + `audio ${api.clashAudioEncoderFinish()} ${api.clashAudioEncoderFinish_()} ` + + `nested ${api.clashNested([[1, 2], 3], [[1, 2, 3]])}`, + ); + close(clashStore); + // Instances that name each other, and one made only by an impl of it. + const cross = api.cross({ value: { value: 1 } }, { value: { value: 2 } }); + print(`cross ${cross} outer ${OuterInnerU8.get(OuterInnerU8.new(4))}`); + // A bound that outlives the call takes a value, and an instance only a constant names. + print(`kept ${dec(api.keptPoint({ x: 1, y: -2 }))} boxed ${api.BOXED().value}`); + print(`keep ${api.keepPoint({ x: 1, y: -2 })}`); + const five = { x: 5, y: 2 }; + print(`kept or ${api.keptOrPoint(five)} ${api.keptOrPoint(undefined)} keeper ${api.keeperPoint(five)}`); + // Inferred instances taking a lent closure and a foreign implementation, and one only its + // impl of a trait names. + const sides = { left: 2, right: 5 }; + print(`apply ${api.applyU32(sides, (side) => side * 3)}`); + print(`report ${api.reportU32(sides, new PrintLog())}`); + print(`wrapped ${dec(api.keptWrapU32({ value: 4 }))}`); + print(`keeps ${api.keeps(new PrintLog()).value}`); + + // Its Drop runs when JavaScript disposes it, not before. + const token = Token.new(7); + print(`token ${Token.idGet(token)} dropped ${api.dropped()}`); + close(token); + print(`dropped ${api.dropped()}`); + + // A field and the method of its name, each its own member. + const retry = Retry.new(5); + const limit = Retry.limitGet(retry); + print(`retry ${limit === undefined ? 0 : 1} ${limit ?? 0} ${Retry.limit(retry)} ${Retry.delay(retry)}`); + // The renamed field's setter, named as its getter. + Retry.limitSet(retry, undefined); + print(`retry ${Retry.limit(retry)}`); + print(`slot ${SlotU8.value(SlotU8.new(200))}`); + + // Foreign types: a URL parsed from text, socket addresses, OS paths, and lists. + const base = unwrap(Url.parse("https://example.com/a/b")); + const host = api.host(base); + print(`url ${Url.toString(base)} host ${host === undefined ? "None" : `Some("${host}")`}`); + const url = unwrap(api.resolve(Url.clone(base), "c?d")); + print(`resolve ${Url.toString(url)} ${Url.eq(url, base)}`); + close(url); + const unparsedUrl = Url.parse("no scheme"); + if (!unparsedUrl.ok) print(`parse err ${unparsedUrl.error}`); + const v4: rt.SocketAddrV4 = { ip: { octets: bytes(127, 0, 0, 1) }, port: 8080 }; + const v6: rt.SocketAddrV6 = { ip: { octets: ipv6(1) }, port: 443, flowinfo: 0, scopeId: 3 }; + print(`ports ${list(api.ports([{ tag: "V4", _0: v4 }, { tag: "V6", _0: v6 }]))}`); + const peer = Peer.next({ addr: { tag: "V6", _0: v6 }, names: ["a", "b"] }, "c"); + print(`peer ${Peer.debug(peer)} ${quoted(Peer.aliases(peer))}`); + const file = api.file(rt.pathFrom("dir"), "f\\'\"\t"); + print(`file ${escaped(file)}`); + print(`parents ${api.parents([file, rt.pathFrom("/")]).map((at) => (at === undefined ? "none" : escaped(at))).join(" ")}`); + const words = api.words(" one two three "); + print(`words ${words.length} ${quoted(words)}`); + print(`sentence ${api.sentence(words)} ${api.sentence(undefined)}`); + print(`sentence ${api.sentence([])}|`); + print(`either ${api.either("abc")} ${api.either(undefined)}`); + print(`prefixed ${text(api.prefixed(enc("cd"), enc("ab")))} ${text(api.prefixed(enc("cd"), undefined))}`); + print(`coordinates ${api.coordinates({ x: 2, y: 3 })} ${api.coordinates(undefined)}`); + const two = Counter.new("two", 2); + const three = Counter.new("three", 3); + print(`plus ${dec(Counter.plus(two, three))} ${dec(Counter.plus(two, undefined))}`); + print(`add_to ${Counter.addTo(two, three)} ${Counter.addTo(two, undefined)} ${dec(Counter.get(three))}`); + close(two); + close(three); + const encoded = { v: enc("0,") }; + api.putNumber(1, encoded); + api.putNumber(23, encoded); + print(`put_number ${text(encoded.v)}`); + const entry: rt.Place<[Uint8Array, number]> = { v: [enc("ab"), 1] }; + const stamps = api.pushCounted(entry, 0x63); + print(`push_counted ${stamps} ${text(entry.v[0])} ${entry.v[1]}`); + const digits = { v: enc("7x9") }; + const firstDigit = unwrap(api.digit(digits)); + const skipped = !api.digit(digits).ok; + print(`digit ${firstDigit} ${skipped} ${unwrap(api.digit(digits))} ${digits.v.length}`); + const nudged = { v: { x: 1, y: 2 } }; + api.nudge(nudged, 3); + print(`nudge ${nudged.v.x} ${nudged.v.y}`); + const config = api.secure("h3"); + print(`secure ${api.alpnLent(config)} ${api.alpn(TlsConfig.clone(config))}`); + const cert = api.certify(enc("der")); + const certLen = api.certLen(cert); + print(`cert ${certLen} ${text(api.certDer(cert))} ${api.chainLen([api.certify(enc("a")), api.certify(enc("bc"))])}`); + close(config); + // Another crate's trait objects: an `Arc`, taken back, and `'static` ones, held by value. + print(`resolver ${api.resolved(api.resolver("r1"))}`); + const codecs = Codecs.new(); + print(`codecs ${Codecs.ids(codecs)}`); + Codecs.listSet(codecs, Codecs.listGet(codecs).reverse()); + print(`codecs reversed ${Codecs.ids(codecs)}`); + close(codecs); + // A standard library value no type maps, in a handle. + const failure = api.failure("boom"); + print(`failure ${api.failureMessage(failure)} ${api.failureKind(failure)}`); + // Iterators, passed as the arrays of their items. + print(`sum_all ${api.sumAll([1, 2, 3])}`); + print(`weigh_all ${dec(api.weighAllCounter([Counter.new("w", 3)]))}`); + print(`offered_len ${api.offeredLen([enc("h3"), enc("moq-00")])}`); + print(`join_words ${api.joinWords(["a", "b", "c"])}`); + // Bytes that must be `'static`, interned. + for (const what of ["der", "der again"]) { + const der = Der.fromSlice(enc("der")); + print(`${what} ${text(Der.bytes(der))}`); + close(der); + } + const session = unwrap(api.resume("h3", 60)); + print(`resume ${TlsSession.alpn(session)} ${TlsSession.lifetime(session).seconds}`); + close(session); + const unresumed = api.resume("", 60); + if (!unresumed.ok) print(`resume err ${unresumed.error}`); + const meters = Meters.new(); + const lentMeter = Meters.first(meters); + Meter.add(lentMeter, 2); + print(`lent ${dec(Meter.add(lentMeter, 3))} ${dec(Meter.count(Meters.first(meters)))}`); + close(lentMeter); + Meters.clear(meters); + print(`cleared ${dec(Meter.count(Meters.first(meters)))}`); + const lastMeter = Meters.lastGet(meters); + Meter.add(lastMeter, 4); + print(`field lent ${dec(Meter.add(lastMeter, 1))}`); + close(lastMeter); + // An optional field that is not Clone, lent as a handle. + print(`spare ${Meters.spareGet(meters) !== undefined}`); + Meters.spareSet(meters, Meter.default()); + const spare = Meters.spareGet(meters)!; + Meter.add(spare, 5); + print(`spare lent ${dec(Meter.add(spare, 1))}`); + close(spare); + close(meters); + const tallies = Tallies.new(); + Tally.bump(Tallies.first(tallies)); + print(`tallied ${Tally.bump(Tallies.first(tallies))}`); + close(tallies); + print(`chunks ${list(api.chunks(enc("abcde"), 2).map(list))}`); + const counters = api.counters(["x", "y"]); + print(`counters ${counters.map((n) => `${Counter.name(n)} ${dec(Counter.get(n))}`).join(", ")}`); + // Each counter moves in, so a later call throws. + print(`worth ${dec(api.worth([counters[0]], [counters[1]]))} ${dec(api.worth(undefined, []))}`); + for (const counter of counters) closed(() => Counter.get(counter), "Counter", "a counter moved in is closed"); + const held = [api.heldCount([Counter.new("h", 4)]), api.heldCount(undefined)]; + print(`held ${held.map((n) => (n === undefined ? "None" : `Some(${dec(n)})`)).join(" ")}`); + print( + `boxed Some("${api.boxedName(api.boxedCounter("b"))}") ` + + `${api.boxedName(undefined) === undefined ? "None" : "Some"} ${api.boxedCounter(undefined) === undefined}`, + ); + print(`less ${api.less(5, 2)}`); + print(`sums ${list(api.sums([new Uint32Array([1, 2]), new Uint32Array(0), new Uint32Array([3])]))}`); + print(`least ${api.least([[3, 1], [], [2]]).map(list).join(" ")}`); + numbers("edges", Numbers.edges()); + numbers("reversed", Numbers.reversed(Numbers.edges())); + const edges = Numbers.edges(); + const nan = Measure.new(NaN, false); + print( + `float equal ${Numbers.eq(edges, edges)} ${Numbers.eq(edges, Numbers.edges())} ` + + `${Numbers.eq(Numbers.zero(true), Numbers.zero(false))} ${Measure.eq(nan, nan)} ` + + `${Measure.eq(Measure.new(-0, true), Measure.new(0, false))}`, + ); + print(`sum u32 ${dec(api.sumU32(new Uint32Array(0)))} ${dec(api.sumU32(new Uint32Array([0xffffffff, 0xffffffff, 2])))}`); + print(`doubled i64 ${list(api.doubledI64(new BigInt64Array([-(1n << 63n), -1n, 0n, (1n << 63n) - 1n])))}`); + const floats = api.boxedFloats(new Float64Array([-0, f64(0x7ff8000000000001n)])); + print(`boxed floats ${bits64(floats)}`); + const summed = api.summed([ + { x: 1, y: 2 }, + { x: -4, y: 6 }, + ]); + const noneSummed = api.summed([]); + print(`summed ${summed.x} ${summed.y} ${noneSummed.x} ${noneSummed.y}`); + print(`longest ${api.longest(["a", "abc"])} ${api.longest([])}`); + print(`first of Some("${api.firstOf(["a", "b"])}") ${api.firstOf([]) ?? "None"}`); + const limits = api.byteLimits(enc("a"), enc("bc")); + const waits = api.breadth({ low: { secs: 0, nanos: 5_000_000 }, high: { secs: 2, nanos: 0 } }); + print(`limits ${text(limits.low)} ${text(limits.high)} breadth ${num(waits.secs) * 1000 + Math.floor(waits.nanos / 1e6)}`); + const parts = text(api.joined([enc("ab"), new Uint8Array(0), enc("c")])); + print(`joined ${parts} ${api.joined([]).length} read ${dec(api.readLen(enc("hello")))}`); + const doc = unwrap(Json.parse('{"b": [1, 2.5, null], "a": "é"}')); + print(`json ${api.encode(doc)}`); + print(`timed text ${api.timedText(doc)}`); + const tagged = api.tagged(doc, "t"); + print(`tagged ${Json.toText(tagged)}`); + close(tagged); + // A JSON object's entries cross as pairs of a key and its document, each moved in. + const entries = api.entries( + [ + ["b", unwrap(Json.parse("[1]"))], + ["a", unwrap(Json.parse("2"))], + ], + "t", + ); + print(`entries ${entries.map(([k, v]) => `${k} ${Json.toText(v)}`).join(", ")}`); + for (const [, v] of entries) close(v); + const unparsedJson = Json.parse('{"a":'); + if (!unparsedJson.ok) print(`json parse err ${unparsedJson.error}`); + const site = Site.new(base); + print(`site ${Url.toString(Site.homeGet(site))} ${Url.toString(Site.homeGet(site))}`); + + // Slices, passed in and returned as clones, and the socket address of each family. + const shapes = (values: Shape.Shape[]) => list(values.map(Shape.debug)); + const points = (values: Point.Point[]) => list(values.map(Point.debug)); + const labels = (values: Label.Label[]) => list(values.map(Label.debug)); + print(`shapes ${shapes(Shape.ALL())} greetings ${quoted(api.GREETINGS())}`); + print(`both ${shapes(Shape.BOTH())} primes ${list(api.PRIMES())}`); + const trail = Trail.new( + [ + { x: 1, y: 2 }, + { x: 3, y: 4 }, + ], + ["a", "b"], + ); + print(`trail ${points(Trail.points(trail))} ${labels(Trail.labels(trail))}`); + // Returned iterators, each collected at the call: drained labels are gone after. + print(`iterated ${points(Trail.iter(trail))} ${quoted(Trail.names(trail))} ${list(Trail.bytes(trail))}`); + print(`drained ${labels(Trail.drain(trail))} then ${labels(Trail.labels(trail))}`); + // A filter, collected at the call. + print(`beyond ${Trail.beyond(trail, 1).map((at) => `${at.x} ${at.y}`).join(", ")}`); + close(trail); + const numbered = api.numbered(["p", "q"]); + print(`numbered ${numbered.map((n) => `${Counter.name(n)} ${dec(Counter.get(n))}`).join(", ")}`); + const [next4, next6] = api.nexts(v4, v6); + print(`nexts ${next4.ip.octets.join(".")} ${next4.port} ${next6.port} ${next6.scopeId}`); + const [nextIp4, nextIp6] = api.nextIps({ octets: bytes(10, 0, 0, 255) }, { octets: ipv6(0xffff) }); + const mapped = api.flip({ tag: "V4", _0: { octets: bytes(127, 0, 0, 1) } }); + const ips = [nextIp4, nextIp6, mapped._0, api.flip(mapped)._0, api.flip({ tag: "V6", _0: { octets: ipv6(1) } })._0]; + print(`ips ${ips.map((ip) => hex(ip.octets)).join(" ")}`); + + // Lossless round trips: each type's edge values, passed through Rust and back. + const durations = ( + [ + { secs: 0, nanos: 0 }, + { secs: 0, nanos: 1 }, + { secs: 9223372036, nanos: 854775808 }, + { secs: U64_MAX, nanos: 999999999 }, + ] as rt.Duration[] + ).map(api.sameDuration); + print(`lossless duration ${durations.map((t) => `${dec(t.secs)}.${`${t.nanos}`.padStart(9, "0")}`).join(" ")}`); + const u64s = [0, rt.u64FromBig(1n << 63n), U64_MAX]; + print(`lossless u64 ${u64s.map((v) => dec(api.sameU64(v))).join(" ")}`); + // wasm32's `usize` and `isize` are 32 bits. + print(`lossless usize ${[0, 0xffffffff].map(api.sameUsize).join(" ")}`); + print(`lossless isize ${api.sameIsize(-0x80000000)} ${api.sameIsize(0x7fffffff)}`); + const u128s = [0n, 1n << 64n, (1n << 128n) - 1n].map(rt.u128FromBig); + print(`lossless u128 ${u128s.map((v) => hex128(api.sameU128(v))).join(" ")}`); + print(`lossless char ${[0, 0xd7ff, 0xe000, 0x10ffff].map((v) => api.sameChar(v).toString(16)).join(" ")}`); + // A path no Rust string spells: bytes that are not UTF-8. + const paths = [rt.pathFrom("a/é"), { bytes: bytes(0xff) }]; + print(`lossless path ${paths.map((at) => hex(api.samePath(at).bytes)).join(" ")}`); + const sockV4 = api.sameSocketAddrV4({ ip: { octets: bytes(255, 255, 255, 255) }, port: 65535 }); + const sockV6 = api.sameSocketAddrV6({ + ip: { octets: bytes(0, 1, ...new Array(13).fill(0), 2) }, + port: 3, + flowinfo: 0xffffffff, + scopeId: 0xffffffff, + }); + const socks = [api.sameSocketAddr({ tag: "V4", _0: sockV4 }), api.sameSocketAddr({ tag: "V6", _0: sockV6 })]; + print( + `lossless socket ${socketHex({ tag: "V4", _0: sockV4 })} ${socketHex({ tag: "V6", _0: sockV6 })} ` + + `${socks.map(socketHex).join(" ")}`, + ); + // A key hashes by Rust's `Hash`: equal keys alike, and these two apart. + const hash = (n: string) => dec(Key.hash(Key.new(n))); + print(`key ${hash("a") === hash("a")} ${hash("a") === hash("b")}`); + const sameIps = [ + api.sameIpAddr({ tag: "V4", _0: { octets: bytes(255, 255, 255, 255) } }), + api.sameIpAddr({ tag: "V6", _0: { octets: bytes(0xff, 0xff, ...new Array(13).fill(0), 1) } }), + ]; + print(`lossless ip ${sameIps.map((ip) => hex(ip._0.octets)).join(" ")}`); + + // serde_json's map iterator, collected as pairs of a key and its document. + const sections = api.sections([ + ["b", unwrap(Json.parse("[1]"))], + ["a", unwrap(Json.parse("2"))], + ]); + print(`sections ${sections.map(([k, v]) => `${k} ${Json.toText(v)}`).join(", ")}`); + for (const [, v] of sections) close(v); + // An instant only Rust makes, which each call copies out of its handle, and compares. + const began = api.now(); + const ended = api.later(began, { secs: 1, nanos: 500_000_000 }); + const same = api.later(began, { secs: 0, nanos: 0 }); + const millis = (t: rt.Duration) => num(t.secs) * 1000 + Math.floor(t.nanos / 1e6); + print( + `instants ${millis(api.since(ended, began))} ${millis(api.since(began, ended))} ` + + `${Instant.eq(began, same)} ${Instant.eq(began, ended)}`, + ); + print(`has_instant ${api.hasInstant(began)} ${api.hasInstant(undefined)}`); + // tracing's level, and its filter as an optional level whose undefined is `OFF`. + const verbosity = Verbosity.new("Warn"); + print(`verbosity ${api.spell(Verbosity.filter(verbosity))} ${api.spell(api.louder(Verbosity.filter(verbosity)))}`); + Verbosity.levelSet(verbosity, "Trace"); + print( + `verbosity ${Verbosity.levelGet(verbosity) === "Trace"} ${api.spell(Verbosity.filter(verbosity))} ` + + `${api.spell(api.louder(Verbosity.filter(verbosity)))} ${api.spell(api.louder(undefined))}`, + ); + close(verbosity); + + // A closure's string, which Rust takes. + print(`made ${api.made(3, (n) => `${n} times`)}`); + // A closure taking and returning `Copy` values copies them, never running their `Clone`. + const nine = Ticket.new(9); + const renewed = Ticket.number(api.reissue(Ticket.new(7), (t) => Ticket.new(Ticket.number(t) + 1))); + const copied = Ticket.number(api.reissue(Ticket.new(7), () => nine)); + print(`reissued ${renewed} ${copied}, cloned ${Ticket.clones()}`); + // A record's traits borrow the checked handle it holds. + const nines = Mark.of(9); + const front = api.seat(nines, 1); + const back = api.seat(nines, 2); + print(`seat ${Seat.debug(front)} ${Seat.eq(front, api.seat(nines, 1))} ${Seat.eq(front, back)}`); + // A kept closure: called again at the instant it asks for, then once its waiter wakes, + // failing with Rust's error. + const start = Moment.new(0, 1000)!; + let calls = 0; + const stopped = await within( + api.drive(start, (now, waiter) => { + calls++; + if (calls === 1) return rt.Ok(Moment.after(now, 5)); + if (calls === 2) { + print(`drive ${num(Moment.millis(now)) - num(Moment.millis(start))}`); + const woken = Waiter.waker(waiter); + woken.wake(); + close(woken); + return rt.Ok(undefined); + } + return rt.Err(`stopped after ${calls}`); + }), + "a kept closure wakes its future", + ); + print(`drive ${stopped}`); + // A reader the caller implements, then one whose reads fail. + for (const reader of [new BytesReader(enc("hello world")), new Broken()]) { + const r = api.tail(reader, 5); + print(r.ok ? `tail ${text(r.value[0])} ${dec(r.value[1])}` : `tail error ${r.error}`); + } + // A seek from the start reaches the reader whole, past `i64::MAX`, as `Cursor` takes one. + const sought = api.seekTo(new Far(), U64_MAX); + print(sought.ok ? `sought ${dec(sought.value)}` : `sought error ${sought.error}`); + print(`non zeros ${api.describeNonZeros(api.nonZeros())}`); + for (const hop of [undefined, 1, U64_MAX]) { + const next = api.nextHop(hop); + print(next === undefined ? "hop None" : `hop Some(${dec(next)})`); + } + print(`farther hop ${api.fartherHop({ left: 3, right: 0xffff })}`); + const local = Local.new(); + const shared = api.localOrNew(local); + const bumped = Local.bump(local); + print(`local ${bumped} ${Local.bump(shared)}`); + print(`local fresh ${Local.bump(api.localOrNew(undefined))}`); + print(`local either ${api.bumpEither(undefined, shared)}`); + print(`local later ${Local.bump(await api.localOrNewLater(local))}`); + print(`local later fresh ${Local.bump(await api.localOrNewLater(undefined))}`); +} + +/** The IPv6 address whose last 16 bits are `last`. */ +function ipv6(last: number): Uint8Array { + const octets = new Uint8Array(16); + octets[14] = last >> 8; + octets[15] = last & 0xff; + return octets; +} + +/** The futures' semantics beyond the transcript, each checked by an assertion. wasm32 has no + * threads, so none of the native script's from another thread is here. */ +async function futures(): Promise { + const channel = Channel.new(); + + // A wake that lands while the future polls, before it returns pending, as each of + // `yielded`'s does, is kept: the future polls again rather than waiting for a wake that + // already happened. + check((await within(api.yielded(7), "a wake during the poll polls again")) === 7, "yielded returns its value"); + + // A value that is not Send stays on JavaScript's one thread, so its check never fails: + // its futures poll, a callback calls back into it, and disposing it drops it there. + { + const local = Local.new(); + const shared = Local.share(local); + Local.bump(local); + check(Local.bump(shared) === 2, "a shared local counts together"); + check((await within(Local.later(local), "a local's future")) === 3, "a local's future polls on its thread"); + check((await within(api.localLater(5), "a future that is not Send")) === 10, "a future that is not Send polls"); + check((await Local.pollCount(local)) === 4, "a local's poll counts"); + check(Local.visit(local, () => Local.bump(local)) === 5, "a callback calls back into its local"); + check(Local.onOwnThread(local), "a local stays on its thread"); + const before = api.localsDropped(); + close(local); + check(api.localsDropped() === before + 1, "a disposed local drops"); + close(shared); + } + + // A future's output of None is undefined, and its error is its Err. + check((await api.halved(3)) === undefined, "a future ready with None returns undefined"); + check((await api.halved(4)) === 2, "a future ready with Some returns its value"); + const corner = await api.cornerLater(); + check(corner[0] === 1 && corner[1] === 1, "a future's borrowed tuple returns whole"); + // A future's error borrowing its argument crosses as its message, as `parseCert`'s does. + const parsed = await api.parseLater("cert"); + check(parsed.ok && parsed.value === 4, "a future with a borrowing error returns Ok"); + const unparsed = await api.parseLater(""); + check(!unparsed.ok && unparsed.error === "malformed: ", "a future's borrowing error is its message"); + Channel.send(channel, new Uint8Array(0)); + const empty = await Channel.recvNonempty(channel); + check(!empty.ok && empty.error.tag === "Underflow" && empty.error.by === 1, "a future's error reads back"); + + // Cancelled between its wake and its poll, a receive loses nothing: the payload stays + // for the next. + const woken = Channel.recv(channel); + Channel.send(channel, enc("kept")); + woken.cancel(); + await cancelled(woken, "a receive cancelled after its wake rejects with Cancelled"); + // Its wake, still queued, finds it gone. + await step(); + check(text(await within(Channel.recv(channel), "the next receive")) === "kept", "a cancelled receive loses nothing"); + + // Cancelling a receive that waits for no wake ends it. + const waiting = Channel.recv(channel); + await step(); + waiting.cancel(); + waiting.cancel(); + await cancelled(waiting, "a waiting receive cancelled rejects with Cancelled"); + + // Cancelling a finished future does nothing. + const done = api.halved(4); + check((await done) === 2, "halved returns its value"); + done.cancel(); + check((await done) === 2, "a finished future cancelled keeps its value"); + + // Disposing a handle a call awaiting on it borrows throws, as Rust refuses a drop under a + // borrow, and changes nothing: the call ends as it would, and then the dispose passes. + const other = Channel.new(); + const held = Channel.recv(other); + const sender = Channel.clone(other); + borrowed(() => close(other), "api_Channel_drop: a handle is already borrowed", "a dispose under an awaiting call"); + Channel.send(sender, enc("held")); + check(text(await within(held, "a receive the dispose left")) === "held", "the awaiting call ends as it would"); + close(other); + closed(() => Channel.clear(other), "Channel", "a call after the dispose"); + close(sender); + + // A future holding an implementation drops it as it finishes, closing it. + const log = new CountLog(); + check(await api.logLater(log), "the future returns what its log kept"); + check(log.lines === 1 && log.closes === 1, "a finished future closes the implementation it held"); + + // Promises Rust polls, whose settling wakes it. + let ran = false; + const first = step().then(() => { + ran = true; + }); + check((await api.after(first, 4)) === 8 && ran, "Rust awaits a promise"); + const gate = Promise.withResolvers(); + let after = 0; + const doubled = api.after(gate.promise, 5).then((value) => (after = value)); + await step(); + await step(); + check(after === 0, "Rust waits on a promise"); + gate.resolve(); + await within(doubled, "a promise's settling wakes Rust"); + check(after === 10, "a promise's settling wakes Rust"); + + // Given up on, a call into Rust passed back as a promise is cancelled. + const kept = Channel.new(); + const recv = Channel.recv(kept); + const gaveUp = await api.within(0, recv); + check(!gaveUp.ok && gaveUp.error.tag === "Overflow", "Rust gives up on a promise"); + await cancelled(recv, "Rust's drop of a call into Rust it was given cancels it"); + close(kept); + + // A promise that rejects once Rust dropped it aborts nothing. + const late = Promise.withResolvers(); + const lateGaveUp = await api.within(0, late.promise); + check(!lateGaveUp.ok && lateGaveUp.error.tag === "Overflow", "Rust gives up on a promise"); + late.reject(new Error("failed after Rust dropped it")); + await step(); + check(api.halved(4) !== undefined, "a call after a dropped promise rejected"); + + // A poll of a waiter, of a promise, which its future owns. + const gated = Promise.withResolvers(); + let polled = false; + const polling = Waiter.pollFuture(gated.promise).then(() => (polled = true)); + await step(); + await step(); + check(!polled, "a poll of a pending promise pends"); + gated.resolve(); + await within(polling, "a promise's settling wakes the poll of it"); + // Cancelled before it finishes, it drops the future it owns: here a call into Rust, + // which is cancelled in turn. + const inner = Waiter.pollFuture(Promise.withResolvers().promise); + const outer = Waiter.pollFuture(inner); + await step(); + outer.cancel(); + await cancelled(outer, "a poll of a promise cancels"); + await cancelled(inner, "a cancelled poll drops the future it owns"); + close(channel); + print("futures ok"); +} + +/** Node's garbage collector, which a flag exposes. */ +let gc: (() => void) | undefined; + +/** Run the garbage collector until `done()`, failing past a deadline. */ +async function collect(done: () => boolean, what: string): Promise { + if (gc === undefined) { + process.getBuiltinModule("node:v8").setFlagsFromString("--expose-gc"); + gc = process.getBuiltinModule("node:vm").runInNewContext("gc"); + } + const deadline = Date.now() + 10000; + while (!done()) { + check(Date.now() < deadline, what); + gc!(); + await step(); + } +} + +/** Collect a few times, and let what the collector found finalize. */ +async function settle(): Promise { + for (let i = 0; i < 3; i++) await collect(() => true, "a collection"); + for (let i = 0; i < 3; i++) { + gc!(); + await step(); + } +} + +/** What frees an object nobody disposed: disposing at once, or the garbage collector once it + * is unreachable, and only what disposing did not free already. */ +async function owned(): Promise { + for (let n = 65535; n <= 65537; n++) { + const payload = new Uint8Array(n).map((_, i) => i % 256); + const packet = api.nextPacket({ seq: 1, payload }); + check( + packet.seq === 2 && packet.payload.length === n && packet.payload.every((b, i) => b === i % 256), + `a record's ${n} bytes cross both ways`, + ); + } + const before = api.dropped(); + const token = Token.new(1); + close(token); + check(api.dropped() === before + 1, "disposing frees at once"); + close(token); + check(api.dropped() === before + 1, "disposing again frees nothing"); + closed(() => Token.idGet(token), "Token", "a disposed token refuses a read"); + + unclosed(); + await collect(() => api.dropped() >= before + 2, "the garbage collector frees what nobody disposed"); + await settle(); + check(api.dropped() === before + 2, "the garbage collector frees each once"); + + // An implementation an object the garbage collector frees held is closed. + const log = new CountLog(); + unclosedLogger(log); + await collect(() => log.closes === 1, "the garbage collector frees what an object it frees holds"); + // So is a returned waker nobody disposed, once. + let wakes = 0; + unclosedWaker(() => wakes++); + await settle(); + check(wakes === 0, "a collected waker never wakes"); + targets(); + print("owned ok"); +} + +function unclosed(): void { + Token.new(3); +} + +function unclosedLogger(log: Log): void { + Logger.new(log); +} + +function unclosedWaker(wake: () => void): void { + Waiter.waker(Waiter.new(wake)); +} + +/** The binding serves wasm32 alone, whose items are each here. */ +function targets(): void { + check(api.pointerBits(api.platform()) === 32, "wasm32's variant crosses"); + check(api.placement().tag === "Anywhere", "a variant wasm32 lacks is left out with its record"); + const labelled = api.sameLabelled({ tag: "Tagged", tag$: 7 }); + check(Labelled.debug(labelled) === "Tagged { tag: 7 }", "a variant's field named `tag` crosses as Rust reads it"); + check(api.pointerBits({ tag: "Native", _0: 64 }) === 64, "the native variant crosses too"); + check(api.isFamily("Wasm") && !api.isFamily("Native"), "wasm32's plain variant crosses"); + check(api.wasmOnly() === 32, "an item only wasm32 has"); + const taken = api.wasmTake(Counter.new("t", 5)); + check(taken.ok && taken.value === 5, "an item only wasm32 has takes a counter"); + const log = new CountLog(); + api.wasmLog(log); + check(log.lines === 1 && log.closes === 1, "an item only wasm32 has takes an implementation"); +} + +/** Each call taking a closed object throws, however it was closed, and moves nothing. */ +async function closedObjects(): Promise { + const c = Counter.new("c", 1); + close(c); + closed(() => Counter.get(c), "Counter", "a method of a disposed object"); + closed(() => Counter.clone(c), "Counter", "clone of a disposed object"); + closed(() => Counter.debug(c), "Counter", "debug of a disposed object"); + const url = unwrap(Url.parse("https://example.com")); + close(url); + closed(() => Url.toString(url), "Url", "toString of a disposed object"); + const tally = Tally.new(); + close(tally); + closed(() => Tally.eq(tally, Tally.new()), "Tally", "eq of a disposed object"); + closed(() => Tally.eq(Tally.new(), tally), "Tally", "eq with a disposed object"); + const registry = Registry.new(Counter.new("first", 1)); + close(registry); + closed(() => Registry.firstGet(registry), "Registry", "a field's getter of a disposed object"); + const second = Counter.new("second", 2); + closed(() => Registry.firstSet(registry, second), "Registry", "a field's setter of a disposed object"); + check(Counter.get(second) === 2, "a call that throws moves nothing in"); + + // An argument, alone, or in a list, beside others the call then moves none of. + closed(() => api.bumpBoth(Tally.new(), tally), "Tally", "a disposed argument"); + const open = Counter.new("open", 3); + closed(() => api.worth([open, c], []), "Counter", "a disposed object in a list"); + closed(() => api.worth([open], [c]), "Counter", "a disposed object in a later list"); + // Disposed while a later argument lowers, after its pointer was passed: the call fails + // Rust's check of it, and its handle is freed only once the call lets it go, so no other + // handle made meanwhile takes its place. + const early = Counter.new("early", 4); + const kept: Counter.Counter[] = []; + const disposing = new Proxy([] as Counter.Counter[], { + get(target, key, receiver) { + if (key === "length") { + close(early); + kept.push(Counter.new("meanwhile", 5)); + } + return Reflect.get(target, key, receiver); + }, + }); + closed(() => api.worth([early], disposing), "Counter", "an object disposed while a later argument lowers"); + check(Counter.get(kept[0]!) === 5, "a handle made meanwhile is its own"); + close(kept[0]!); + closed( + () => + Board.new([ + ["open", open], + ["closed", c], + ]), + "Counter", + "a disposed object in a tuple", + ); + check(Counter.get(open) === 3, "a call that throws moves none of its other arguments"); + + // Nor keeps an implementation beside an argument that throws: one the binding refuses + // Rust never takes, and one Rust's check refuses Rust drops. + const spared = new CountLog(); + const digest = Digest.new(); + throws(() => Digest.flipped(digest, bytes(1, 2, 3)), RangeError, "3 bytes are no [u8; 4]"); + close(digest); + throws(() => api.logCounts(spared, 256, open, []), RangeError, "an integer out of range beside an implementation"); + closed(() => api.logCounts(spared, 0, c, []), "Counter", "a disposed object beside an implementation"); + check(spared.closes === 0, "a call the binding refuses gives Rust no implementation"); + // A moved value's handle stays open, so Rust's own check refuses it. + const taken = Counter.new("taken", 1); + Counter.intoLabel(taken, undefined); + closed(() => api.logCounts(spared, 0, taken, []), "Counter", "a moved object beside an implementation"); + closed(() => api.logCounts(spared, 0, open, [taken]), "Counter", "a moved object in a list beside an implementation"); + check(spared.closes === 2, "a call whose check throws drops the implementation it gave Rust"); + check(api.onFirstThread(), "a call after one that threw"); + check(api.logCounts(spared, 0, open, []) === 1, "an implementation a call that threw gave none of"); + check(spared.lines === 1 && spared.closes === 3, "an implementation given once is closed once"); + + // An async call. + const channel = Channel.new(); + close(channel); + await closedCall(() => Channel.recv(channel), "Channel", "an async call of a disposed object"); + + // Closed by a call that moved it, plain or boxed, or once the closure it was lent to + // returned. + const moved = Counter.new("m", 0); + Counter.intoLabel(moved, undefined); + closed(() => Counter.get(moved), "Counter", "a method of a moved object"); + const tail = Node.new(1, undefined); + Node.new(2, tail); + closed(() => Node.sum(tail), "Node", "a method of a boxed moved object"); + let lent: Counter.Counter | undefined; + Registry.edit(Registry.new(Counter.new("c", 0)), (counter) => { + lent = counter; + return false; + }); + closed(() => Counter.get(lent!), "Counter", "a lent object kept past its closure"); + + // Disposed from the closure a call lends while the call borrows it, an object throws, as + // Rust refuses a drop under a borrow, and changes nothing; disposed after, it closes. + const editing = Registry.new(Counter.new("e", 4)); + const edited = Registry.edit(editing, (counter) => { + borrowed(() => close(editing), "api_Registry_drop: a handle is already borrowed", "a dispose in a closure the call lends"); + return Counter.get(counter) === 4; + }); + check(edited, "the call whose object a dispose failed on runs on"); + close(editing); + closed(() => Registry.firstGet(editing), "Registry", "an object disposed after the call"); + // The same for one the binding counts, as the drop of what it holds shows: once, at the + // dispose. + let logger: Logger.Logger | undefined; + const log = new CountLog(() => + borrowed(() => close(logger!), "Logger: a handle is already borrowed", "a dispose during a call it is held by"), + ); + logger = Logger.new(log); + check(Logger.write(logger, "x"), "the call whose object a dispose failed on returns"); + check(log.closes === 0, "a dispose that failed frees nothing"); + close(logger); + check(log.closes === 1, "a dispose after the call frees it"); + close(logger); + check(log.closes === 1, "disposing it again frees nothing"); + closed(() => Logger.write(logger!, "x"), "Logger", "a call after the dispose"); + print("closed ok"); +} + +/** The call `f` throws, or rejects with, the error of a closed `type`, as [closed] says. */ +async function closedCall(f: () => Promise, type: string, what: string): Promise { + let call: Promise; + try { + call = f(); + } catch { + closed(f, type, what); + return; + } + try { + await within(call, what); + } catch (e) { + closed(() => { + throw e; + }, type, what); + return; + } + check(false, what); +} + +/** Returned bytes are a copy, so Rust's buffer is freed at the call, whatever their length, + * and a change to them reaches nothing of Rust's. */ +async function lent(): Promise { + let before = api.dropped(); + for (const n of [65536, 65537]) { + const got = api.tokenBytes(1, n); + check(api.dropped() === ++before, `${n} bytes are copied and Rust's freed at the call`); + check(got.length === n && got.every((b) => b === 1), `${n} copied bytes read back`); + } + // A copy is the caller's to change, and passes back to Rust as it was left. + const channel = Channel.new(); + const sent = api.tokenBytes(5, 65537); + before++; + sent[0] = 6; + Channel.send(channel, sent); + sent[1] = 7; + const got = await within(Channel.recv(channel), "a receive of what was sent"); + check(got.length === 65537 && got[0] === 6 && got[1] === 5 && sent[1] === 7, "bytes sent are copied in at the call"); + const carried = api.nextPacket({ seq: 1, payload: got }).payload; + check(carried.length === 65537 && carried[0] === 6 && carried.subarray(1).every((b) => b === 5), "bytes carried in a record"); + close(channel); + // No copy holds anything of Rust's, so collecting frees nothing more. + await settle(); + check(api.dropped() === before, "returned bytes hold nothing of Rust's"); + print("bytes ok"); +} + +/** Values at the edges of what Rust takes and returns, and each value Rust's type lacks, + * which throws the language's own error rather than reaching Rust. */ +function bounds(): void { + // A char is a Unicode scalar value: a surrogate, or a number past one, is none. + check(api.nextChar(0x61) === 0x62 && api.nextChar(0x1f600) === 0x1f601, "a char"); + for (const c of [0xd800, 0xdfff, 0x110000, -1, 1.5]) throws(() => api.nextChar(c), RangeError, `${c} is no char`); + check(api.nextChar(0xd7ff) === undefined, "the scalar before the surrogates"); + throws(() => rt.u128FromBig(1n << 128n), RangeError, "an int past u128"); + throws(() => rt.u128FromBig(-1n), RangeError, "a negative int for a u128"); + + // Text is UTF-8 in Rust, which a lone surrogate has no form in. + check(api.sameString("\u{1f600}é\u{10ffff}") === "\u{1f600}é\u{10ffff}", "a pair of surrogates"); + check(api.sameString("\u{feff}hi") === "\u{feff}hi", "a leading U+FEFF is text"); + check(rt.pathText(api.samePath(rt.pathFrom("\u{feff}a"))) === "\u{feff}a", "a path's leading U+FEFF is text"); + for (const lone of ["\ud800", "a\udc00", "\udbff\ud800", "\udc00\ud800", "é\ud800"]) { + throws(() => api.sameString(lone), RangeError, `a lone surrogate in ${[...lone].map((u) => u.charCodeAt(0))}`); + } + throws(() => rt.pathFrom("\udc00"), RangeError, "a path of a lone surrogate"); + throws(() => api.nextHop(0), RangeError, "a zero NonZero"); + throws(() => api.fartherHop({ left: 0, right: 1 }), RangeError, "a zero NonZero field"); + + // An integer is a number of its range, or for one past 2^53, its limbs. + const max = rt.u64FromBig(0xffffffffffffffffn); + check(rt.u64ToBig(api.sameU64(max)) === 0xffffffffffffffffn, "u64::MAX crosses whole"); + check(api.sameU64(2 ** 53 - 1) === 2 ** 53 - 1, "the last safe integer is a number"); + check(rt.u64ToBig(api.sameU64(rt.u64FromBig(2n ** 53n))) === 2n ** 53n, "the first unsafe one is limbs"); + for (const v of [-1, 1.5, 2 ** 53, NaN]) throws(() => api.sameU64(v), RangeError, `${v} is no u64`); + throws(() => rt.u64FromBig(1n << 64n), RangeError, "a bigint past u64"); + throws(() => rt.u64FromBig(-1n), RangeError, "a negative bigint for a u64"); + throws(() => rt.i64FromBig(1n << 63n), RangeError, "a bigint past i64"); + check(rt.i64ToBig(rt.i64FromBig(-(1n << 63n))) === -(1n << 63n), "i64::MIN as its limbs"); + for (const v of [-1, 2 ** 32]) throws(() => api.sameUsize(v), RangeError, `${v} is no usize`); + for (const v of [-(2 ** 31) - 1, 2 ** 31]) throws(() => api.sameIsize(v), RangeError, `${v} is no isize`); + throws(() => Point.offset({ x: 2 ** 31, y: 0 }, 0, 0), RangeError, "a field past i32"); + throws(() => api.greet("x", "Triangle" as Shape.Shape), RangeError, "no variant of a plain enum"); + throws(() => api.describe({ tag: "Gone" } as unknown as Event.Event), RangeError, "no variant of a data enum"); + throws(() => Score.count(Moment.new(1, 1)! as unknown as Score.Score), RangeError, "a value Rust made of another type"); + + // A Rust Duration is its seconds and nanoseconds, each checked. + const longest = { secs: max, nanos: 999999999 }; + const same = api.extended(longest, { secs: 0, nanos: 0 })!; + check(rt.u64ToBig(same.secs) === 0xffffffffffffffffn && same.nanos === 999999999, "the longest Duration crosses whole"); + check(api.extended(longest, { secs: 0, nanos: 1 }) === undefined, "past the longest"); + for (const nanos of [1000000000, -1, 0.5]) { + throws(() => api.sameDuration({ secs: 0, nanos }), RangeError, `${nanos} nanoseconds`); + } + + // A path is its bytes, which a string may not hold. + const stray = { bytes: bytes(0xff) }; + const back = api.samePath(stray); + check(back.bytes.length === 1 && back.bytes[0] === 0xff, "a path that is not UTF-8"); + check(rt.pathText(back) === "�", "a path's text replaces what is not UTF-8"); + check(rt.pathText(rt.pathFrom("a/é")) === "a/é", "a UTF-8 path as text"); + + // An address is its family's octets, and a port, flow label, and scope their ranges. + throws(() => api.sameIpAddr({ tag: "V4", _0: { octets: bytes(1, 2, 3) } }), RangeError, "three octets"); + throws(() => api.sameIpAddr({ tag: "V6", _0: { octets: bytes(1, 2, 3, 4) } }), RangeError, "four octets for IPv6"); + const ip = { octets: ipv6(1) }; + const v6 = (port: number, flowinfo: number, scopeId: number) => ({ ip, port, flowinfo, scopeId }); + check(api.ports([{ tag: "V6", _0: v6(65535, 0, 0) }])[0] === 65535, "the last port"); + throws(() => api.sameSocketAddrV6(v6(65536, 0, 0)), RangeError, "a port past u16"); + throws(() => api.sameSocketAddrV6(v6(1, 0, -1)), RangeError, "a negative scope"); + throws(() => api.sameSocketAddrV6(v6(1, 2 ** 32, 0)), RangeError, "a flow label past u32"); + + // A key hashes by Rust's Hash, so its hash keys a Set. + const hashes = new Set(["a", "a", "b"].map((n) => dec(Key.hash(Key.new(n))))); + check(hashes.size === 2, "a set of keys' hashes"); + + // A block crosses whole: an empty one stays apart from none, and a u64 keeps its bits. + const blocks = (some: Int32Array | undefined): Numbers.Numbers => ({ + u16s: new Uint16Array(0), + u32s: new Uint32Array(0), + u64s: new BigUint64Array([0xffffffffffffffffn]), + i8s: new Int8Array(0), + i16s: new Int16Array(0), + i32s: new Int32Array(0), + i64s: new BigInt64Array(0), + f32s: new Float32Array(0), + f64s: new Float64Array(0), + some, + }); + check(Numbers.reversed(blocks(undefined)).some === undefined, "no block crosses as none"); + check(Numbers.reversed(blocks(new Int32Array(0))).some?.length === 0, "an empty block crosses as itself"); + check(Numbers.reversed(blocks(undefined)).u64s[0] === 0xffffffffffffffffn, "u64::MAX crosses whole in a block"); + const thousand = new Uint32Array(1000).map((_, i) => i); + check(api.sumU32(thousand) === 499500, "a thousand u32s cross whole"); + check(api.sumU32(thousand.subarray(1, 3)) === 3, "a view of a block crosses as itself"); + print("ok"); +} + +/** The bytes the last [grow] asked Rust for. */ +let growth = 0; + +/** Grow memory from a call into JavaScript, by asking Rust for more bytes than it has free: + * at first as many as memory holds, then a MiB more each time. */ +function grow(): void { + const was = rt.mem().buffer.byteLength; + growth = Math.max(growth + (1 << 20), was); + check(api.tokenBytes(2, growth).length === growth, "the bytes asked for"); + check(rt.mem().buffer.byteLength > was, "the call grew memory"); +} + +/** What a callback or closure is lent, bytes or text, reads the same once it grows memory, + * and what it returns or writes lands. */ +function grown(): void { + let lines = 0; + const log = new CountLog((line) => { + grow(); + check(line === `line ${++lines}`, `a callback's lent text after memory grew: ${line}`); + }); + check(api.emit(log, bytes(1, 2, 3)) === 3, "a callback that grew memory returns"); + const filtered = api.filter(bytes(1, 2, 3), (level, line) => { + grow(); + check(line === `line ${level}`, `a closure's lent text after memory grew: ${line}`); + return level > 1; + }); + check(filtered === 2, "a closure that grew memory returns"); + const registry = Registry.new(Counter.new("grown", 3)); + const edited = Registry.edit(registry, (counter) => { + grow(); + return Counter.name(counter) === "grown" && unwrap(Counter.add(counter, 1)) === 4; + }); + check(edited && Counter.get(Registry.firstGet(registry)) === 4, "a lent handle after memory grew"); + close(registry); + check(api.made(2, (n) => (grow(), `${n} grown`)) === "2 grown", "a closure's text returned after memory grew"); + // A reader fills the buffer Rust lends it after growing memory. + const tail = api.tail(new BytesReader(enc("hello world"), grow), 5); + check(tail.ok && text(tail.value[0]) === "world" && tail.value[1] === 6, "a reader's read after memory grew"); + print("grown ok"); +} + +/** A reader whose seek throws. */ +class Thrower implements rt.Reader { + read(_buffer: Uint8Array): number { + return 0; + } + + seek(_offset: rt.u64 | rt.i64, _from: rt.SeekFrom): rt.u64 { + throw new Error("a seek failed"); + } +} + +/** A reader that reads more than it was asked. */ +class Overreader implements rt.Reader { + read(buffer: Uint8Array): number { + return buffer.length + 1; + } + + seek(_offset: rt.u64 | rt.i64, _from: rt.SeekFrom): rt.u64 { + return 0; + } +} + +/** Each breaks a contract, which must fail with a message naming it. */ +async function broken(which: string): Promise { + switch (which) { + case "moved": { + const c = Counter.new("c", 0); + Counter.intoLabel(c, undefined); + Counter.get(c); + break; + } + case "boxed moved": { + const tail = Node.new(1, undefined); + Node.new(2, tail); + Node.sum(tail); + break; + } + case "outlived": { + const meters = Meters.new(); + const first = Meters.first(meters); + Meters.clear(meters); + Meter.count(first); + break; + } + case "lent moved": + Registry.edit(Registry.new(Counter.new("c", 0)), (counter) => { + Counter.intoLabel(counter, undefined); + return false; + }); + break; + case "lent kept": { + let kept: Counter.Counter | undefined; + Registry.edit(Registry.new(Counter.new("c", 0)), (counter) => { + kept = counter; + return false; + }); + Counter.get(kept!); + break; + } + case "callback threw": + api.emit( + new CountLog(() => { + throw new Error("a log failed"); + }), + bytes(1), + ); + break; + case "later poll trapped": { + // A trap in a later poll, Rust's own with nothing of JavaScript's thrown, rejects its + // call, and a call woken behind it rejects too. + // Each pends, keeping its last waker, until both are woken at once. + let woken = false; + const wakers: { wake(): void }[] = []; + const pend = (fail: boolean) => + api.drive(Moment.new(0, 1000)!, (_now, waiter) => { + if (!woken) { + wakers[Number(fail)] = Waiter.waker(waiter); + return rt.Ok(undefined); + } + if (fail) api.tail(new Overreader(), 1); + return rt.Err("woken"); + }); + const settled = (p: Promise) => + p.then( + () => "resolved", + (e: unknown) => (e instanceof Error ? e.message : String(e)), + ); + const failing = settled(pend(true)); + const queued = settled(pend(false)); + setTimeout(() => { + woken = true; + wakers[1].wake(); + wakers[0].wake(); + }); + const [first, second] = await Promise.all([failing, queued]); + check(first === "unreachable", `a later poll's trap rejects: ${first}`); + check(second === "the module aborted, so no call into it runs", `a call woken behind it rejects: ${second}`); + print("later poll checked"); + throw new Error(second); + } + case "closure threw": + await api.drive(Moment.new(0, 1000)!, () => { + throw new Error("a poll failed"); + }); + break; + // What a reader throws is its io::Error, as rt.Reader says, so what breaks its contract + // is a read of more than it was asked. + case "reader threw": { + const r = api.tail(new Thrower(), 1); + check(!r.ok && r.error === "a seek failed", "a reader's throw is its error"); + api.tail(new Overreader(), 1); + break; + } + default: + check(false, `no case ${which}`); + } +} + +async function main(): Promise { + const path = process.env["RUST2_WASM"]; + check(path !== undefined, "RUST2_WASM names the module"); + const module = await WebAssembly.compile(process.getBuiltinModule("node:fs").readFileSync(path!)); + // A load that fails leaves the next free to succeed, and a load while one runs is refused. + const glue = { prefix: "api", space: "api_web", file: "stale.ts", contract: 1n, target: 0, imports: g.imports }; + const message = (p: Promise) => p.then(() => "", (e: unknown) => (e instanceof Error ? e.message : String(e))); + check((await message(rt.load(module, glue))) === "stale.ts and the module are from different builds", "a stale load"); + const first = api.load(module); + check((await message(api.load(module))) === "index.ts: the module is loaded already", "a load meanwhile"); + await first; + const which = process.argv[2]; + switch (which) { + case undefined: + return script(); + case "futures": + return futures(); + case "owned": + return owned(); + case "closed": + return closedObjects(); + case "bytes": + return lent(); + case "bounds": + return bounds(); + case "grown": + return grown(); + default: + return broken(which); + } +} + +await main(); diff --git a/ffi/tests/fixtures.rs b/ffi/tests/fixtures.rs index 1b75107b1..d9e25c625 100644 --- a/ffi/tests/fixtures.rs +++ b/ffi/tests/fixtures.rs @@ -38,10 +38,13 @@ fn host() -> &'static str { }) } -/// The target the api fixture's binding serves besides the host's, which has an item the -/// host lacks and a variant of an enum. +/// A wasm32 target, which has an item the host lacks and a variant of an enum. const WASM: &str = "wasm32-unknown-unknown"; +/// The target the api fixture's binding serves besides the host's: wasm32, whose std +/// imports its platform, which the web binding implements with web APIs. +const WEB: &str = "wasm32-wasip1"; + /// Cargo, on a `PATH` without what changes each run, as a Cargo shim's session does: build /// scripts that read `PATH`, such as pyo3's, would otherwise run again each time, and /// rebuild the glue. @@ -124,8 +127,8 @@ fn api() -> &'static Api { // A feature of the facade's that enables one in a crate it re-exports, which the C // library must build with. let features = ["--features", "doubled"]; - // One binding for the host and wasm32, which only the host builds and runs. - let output = export("api", &out, &[host(), WASM], &features); + // One binding for the host and wasm32, which the web binding runs. + let output = export("api", &out, &[host(), WEB], &features); assert!( output.status.success(), "exporting failed:\n{}", @@ -725,7 +728,7 @@ fn api_android() { abi => panic!("the android shell's toolchain has no target for the device's ABI {abi}"), }; let out = dir.join("out"); - let output = export("api", &out, &[target, WASM], &["--features", "doubled"]); + let output = export("api", &out, &[target, WEB], &["--features", "doubled"]); assert!( output.status.success(), "exporting for {target} failed:\n{}", @@ -1222,6 +1225,169 @@ fn api_swift() { ); } +/// The fixture's script compiled for wasm32-wasip1 and run under Node's WASI: native Rust on +/// the target the web binding serves, whose `usize` is 32 bits. +fn wasm_transcript() -> String { + let built = run(cargo() + .args([ + "build", + "--quiet", + "--locked", + "--package", + "api-fixture", + "--example", + "transcript", + "--features", + "doubled", + "--target", + WEB, + "--target-dir", + ]) + .arg(scratch().join("api").join("transcript-wasm")) + .current_dir(manifest_dir())); + assert!(built.status.success()); + let wasm = scratch() + .join("api") + .join("transcript-wasm") + .join(WEB) + .join("debug") + .join("examples") + .join("transcript.wasm"); + let script = "import { WASI } from 'node:wasi';\n\ + import { readFileSync } from 'node:fs';\n\ + const wasi = new WASI({ version: 'preview1', args: [], env: {}, returnOnExit: false });\n\ + const module = await WebAssembly.compile(readFileSync(process.argv[1]));\n\ + wasi.start(await WebAssembly.instantiate(module, wasi.getImportObject()));\n"; + let transcript = run(Command::new("node") + .args(["--no-warnings", "--input-type=module", "-e", script]) + .arg(wasm)); + String::from_utf8_lossy(&transcript.stdout).into_owned() +} + +/// The generated TypeScript, type-checked with no issue, runs `tests/api.ts`'s script on +/// Node over the module the crate's `web` feature builds for wasm32-wasip1: it prints what +/// native Rust prints on that target, then checks its futures, what disposing and the +/// garbage collector free, what a closed object refuses, how bytes cross, and what a call +/// lent bytes reads once memory grows, and fails loud on each contract it breaks; a binding +/// of another contract refuses the module. +#[test] +fn api_web() { + let api = api(); + let dir = scratch().join("api").join("web"); + let target = scratch().join("api").join("glue-web"); + run(cargo() + .args(["build", "--quiet", "--locked", "--manifest-path"]) + .arg(api.out.join("Cargo.toml")) + .arg("--target-dir") + .arg(&target) + .args(["--target", WEB, "--features", "web"]) + .env("RUSTFLAGS", "-D warnings")); + let wasm = target.join(WEB).join("debug").join("api.wasm"); + // The script beside a copy of the binding, as a caller's project holds it. + step::mirror(&api.out.join("web"), &dir.join("web")); + step::copy(&manifest_dir().join("tests").join("api.ts"), &dir.join("api.ts")); + step::write(&dir.join("tsconfig.json"), TSCONFIG); + run(Command::new("tsc").arg("-p").arg(&dir)); + let node = |case: Option<&str>| { + let mut cmd = Command::new("node"); + cmd.arg("api.ts").args(case).current_dir(&dir).env("RUST2_WASM", &wasm); + cmd + }; + let transcript = run(&mut node(None)); + assert_eq!( + String::from_utf8_lossy(&transcript.stdout), + wasm_transcript(), + "the TypeScript transcript differs from native Rust's on {WEB}" + ); + for case in ["futures", "owned", "closed", "bytes", "bounds", "grown"] { + run(&mut node(Some(case))); + } + for (case, message) in [ + ("moved", "api_Counter_get: a handle's value was moved out"), + ("boxed moved", "api_Node_sum: a handle's value was moved out"), + ("lent kept", "Counter is closed"), + ( + "lent moved", + "a closure: a call into JavaScript threw Error: api_Counter_into_label: a handle a call lent is borrowed exclusively or moved out", + ), + ( + "callback threw", + "api::Log::log: a call into JavaScript threw Error: a log failed", + ), + ( + "closure threw", + "a closure: a call into JavaScript threw Error: a poll failed", + ), + ("later poll trapped", "api_tail: a reader read more than it was asked"), + ("reader threw", "api_tail: a reader read more than it was asked"), + ("outlived", OUTLIVED), + ] { + let output = node(Some(case)).output().unwrap(); + assert!(!output.status.success(), "TypeScript {case} did not fail"); + let stderr = String::from_utf8_lossy(&output.stderr); + assert!(stderr.contains(message), "TypeScript {case} printed {stderr}"); + // A case checking what follows the failure says it got that far. + if case == "later poll trapped" { + let stdout = String::from_utf8_lossy(&output.stdout); + assert!( + stdout.contains("later poll checked"), + "TypeScript {case} printed {stdout}" + ); + } + } + + // The same binding, with another contract than the module's in place of its own, + // refuses it as it loads. + let contract = dir.join("contract"); + step::mirror(&api.out.join("web"), &contract.join("web")); + let index = contract.join("web").join("index.ts"); + let source = std::fs::read_to_string(api.out.join("web").join("index.ts")).unwrap(); + let at = source.find("contract: 0x").expect("the binding checks its contract") + "contract: 0x".len(); + let mut mismatched = source.clone(); + let digit = if &source[at..at + 1] == "0" { "1" } else { "0" }; + mismatched.replace_range(at..at + 1, digit); + step::write(&index, mismatched); + step::write( + &contract.join("main.ts"), + "import { readFileSync } from \"node:fs\";\nimport * as api from \"./web/index.ts\";\n\nawait api.load(readFileSync(process.env.RUST2_WASM!));\n", + ); + let output = Command::new("node") + .arg("main.ts") + .current_dir(&contract) + .env("RUST2_WASM", &wasm) + .output() + .unwrap(); + assert!(!output.status.success(), "a mismatched contract loaded"); + let stderr = String::from_utf8_lossy(&output.stderr); + assert!( + stderr.contains("index.ts and the module are from different builds"), + "a mismatched contract printed {stderr}" + ); +} + +/// What `tsc` checks a web binding and its caller with: strict, with no name unused, on the +/// ES2024 a binding needs, as Node runs it, with no ambient types but the DOM's and Node's. +const TSCONFIG: &str = r#"{ + "compilerOptions": { + "strict": true, + "noEmit": true, + "pretty": false, + "noUnusedLocals": true, + "noUnusedParameters": true, + "target": "es2024", + "lib": ["es2024", "esnext.disposable", "dom"], + "module": "esnext", + "moduleResolution": "bundler", + "allowImportingTsExtensions": true, + "verbatimModuleSyntax": true, + "erasableSyntaxOnly": true, + "skipLibCheck": true, + "types": [] + }, + "include": ["api.ts", "web/*.ts"] +} +"#; + /// The generated Dart, analyzed with no issue, runs `tests/api.dart`'s script, which prints /// the native transcript, then its futures, what closing and the garbage collector free, /// and each contract it fails loud on, and a Dart file of another contract fails to load. diff --git a/quest/m2/wasm/README.md b/quest/m2/wasm/README.md index 1c8503628..e0f3d290d 100644 --- a/quest/m2/wasm/README.md +++ b/quest/m2/wasm/README.md @@ -35,6 +35,9 @@ Decided with the maintainer on 2026-11-09, in the quest audit: [the WASI target](/quest/m3/wasi.md) serves hosts with no JavaScript, in m3 as the other targets planned ahead of a consumer are. Rejected: one `wasm32-wasip1` module for both, with the binding implementing its imports. + On 2026-11-16 the maintainer let [#847](https://github.com/kixel-ai/rust2/pull/847)'s + first slice land on `wasm32-wasip1`'s std, its imports implemented with web APIs, for now: + [the backend](/quest/m2/wasm/backend.md) moves the web target off it. - ✅ m2, with per-target export in m1, which landed in [#689](https://github.com/kixel-ai/rust2/pull/689) and [#700](https://github.com/kixel-ai/rust2/pull/700). Rejected: all of it in m1; all of it diff --git a/quest/m2/wasm/backend.md b/quest/m2/wasm/backend.md index fa3d29dd3..fd2cca148 100644 --- a/quest/m2/wasm/backend.md +++ b/quest/m2/wasm/backend.md @@ -1,18 +1,39 @@ -# [L] The exporter's web target +# [L] The exporter's web target off WASI, in browsers, on the benchmark, and refusing what the web lacks ## Goal -rust2-ffi's web target writes, beside the glue crate, a TypeScript binding over the -`.wasm` that `cargo build` makes of it: ES modules a bundler takes as is, typed as the -other languages' bindings are, with no wasm-bindgen and no tool run on the `.wasm` -afterwards. What the module needs of its platform comes from web APIs, called directly: -its clock is `performance.now` and `Date.now`, its randomness `crypto.getRandomValues`, -and its stderr `console.error`, with no WASI runtime or polyfill in the bundle. The `api` -fixture's script runs through it in Node, Chrome, and -Firefox, its transcript matching native Rust's line for line, with its futures checked as -the other languages' are. The fixture spawns a thread (`ffi/fixtures/api/src/lib.rs`), -which wasm32 cannot, so what needs one moves to a fixture of its own that the native -languages keep running. +rust2-ffi's web target ([`ffi/src/web.rs`](/ffi/src/web.rs), documented in +[the README](/ffi/README.md#typescript-web)) runs the `api` fixture's script in Node, its +transcript matching native Rust's on `wasm32-wasip1`. What remains: + +- The web module ships nothing of WASI, as [the epic](/quest/m2/wasm/README.md) decided on + 2026-11-09: its clock, randomness, and output reach web APIs through the binding's own + `rust2_*` imports, and `rt.ts` implements no `wasi_snapshot_preview1` import. Today the + binding builds on `wasm32-wasip1`'s std, and `rt.ts` implements its six imports + (`clock_time_get`, `environ_get`, `environ_sizes_get`, `fd_write`, `proc_exit`, + `sched_yield`) with web APIs. + +- The same script runs headless in Chrome and Firefox from the dev shell (`pkgs.chromium`, + `pkgs.firefox`), in `just ffi test`, with its futures and its `grown` case checked as in + Node. Deno runs it too, or the [epic's](/quest/m2/wasm/README.md) Goal drops Deno. +- [The binding benchmark](/bench/ffi/README.md) gains a TypeScript column, in Node and a + browser, as every generator is measured. Its stand-in must build for wasm32, which + moq-tokio does not: export the crates of it that do, and say which. The column joins + CodSpeed under the A/A rule of [the benchmark's README](/bench/ffi/README.md#codspeed). + Its payload rows find the crossover for bytes Rust returns: below it they are copied out + and freed at once, as today; above it they are lent, a view over Rust's buffer kept alive + until a `FinalizationRegistry` frees it, as Dart lends past 64 KiB. +- What has no web API (the file system, sockets, a process) is refused at export, at the + span of the call that reaches it. Today the module imports it, and `load` refuses the + module, naming the import: loud, but at load, not at export. That needs every reachable + body's MIR, which rust2-ts reads through its own MIR sysroot (`ts/src/profile.toml`, + `ts/src/cli.rs`) and the exporter does not read at all: size it first, and split it out + if it is most of the work, since [WASI](/quest/m3/wasi.md) needs the same. +- A crate that imports browser APIs through wasm-bindgen (web-sys) is refused at the + import's span, until a consumer needs both. Today its module imports + `__wbindgen_placeholder__`, which `load` refuses. +- A trait method or closure returning an object or a `Vec` from JavaScript to Rust has a + web form: the generator refuses one today, and the api fixture has none. ## Plan @@ -21,84 +42,50 @@ web's uses web APIs wherever one exists ("like performance.now()"). Rejected: on `wasm32-wasip1` module for both, whose imports the binding satisfies, as this quest first recommended. [The WASI target](/quest/m3/wasi.md) is its own quest. -Decided with the maintainer on 2026-11-09: planned in -[the rust2-wasm epic](/quest/m2/wasm/README.md). The rules every generator follows -([the exporter epic](/quest/m1/ffi-export/README.md)) apply: the contract check at load, -bulk payloads, native futures, lossless types, and checks that raise. - -Recommended design, from the audit's survey, for the implementer to confirm by -measurement on [the benchmark](/quest/m2/wasm/routes.md): - -- Records are read from and written to linear memory at the layouts rustc computed for - the target, with no serialization and no JS object per field until one is read. -- A `Uint8Array` view of linear memory detaches whenever memory grows, which any call - into Rust can cause, one a callback makes while it holds lent bytes included. So bytes - Rust returns or lends are an object of their pointer and length that makes its view - from the current `memory.buffer` at each read, and hands out a copy where a caller - wants a `Uint8Array` to keep. Test a callback that grows memory while it reads what it - was lent. Bytes passed in are copied once into memory the call frees. Text is one - `TextDecoder` or `TextEncoder` call; JS string builtins do not help UTF-8 held in - linear memory. -- A handle is an integer in an object whose only method is `[Symbol.dispose]`, and a - `FinalizationRegistry` frees one never disposed, as the other languages' garbage - collectors do. Measure a returned object with and without the registry: the same - pattern is what [object ownership](/quest/m1/ffi-speed/object-ownership.md) found - costing ten times a C return in Go and Dart. -- A future is a `Promise`: the binding polls once at the call, and an imported `wake` - schedules the next poll on a microtask, never inside the wake. Cancelling frees the - future and loses nothing. JSPI is not needed, since no Rust code blocks on JS. -- One thread: no atomics, no shared memory, no COOP or COEP headers. A type that is not - `Send` exports with no thread check, which the native targets make ([#844](https://github.com/kixel-ai/rust2/pull/844)). -- The runtime's `fail` writes its message to `console.error`. -- A struct passed by value is passed indirectly in wasm's C ABI, which the binding must - match from the target's layouts, not the host's. - Decided with the maintainer on 2026-11-12, in the quest audit -([the epic](/quest/m2/wasm/README.md) records the reasons): +([the epic](/quest/m2/wasm/README.md) records the reasons): ✅ the binding's API is the +translator's shape, a module of functions per type. ✅ This quest adds the TypeScript +column to the binding benchmark. -- ✅ The binding's API is the translator's shape, not a class per type: a module of - functions per type that take the handle first, plain objects for records, and a - `Promise` from an async function, so one caller's code runs on either route and a - bundler drops the glue of every function it never calls. Rejected: classes with - methods, as this quest first planned and the other languages' bindings have. -- ✅ This quest adds a TypeScript column to [the binding benchmark](/bench/ffi/README.md), - in Node and a browser, as every generator is measured. Its stand-in must build for - wasm32, which moq-tokio does not: export the crates of it that do, and say which. The - column joins CodSpeed under the A/A rule of - [the benchmark's README](/bench/ffi/README.md#codspeed). +Decided by the implementer on 2026-11-15, under the maintainer's standing instruction to +take the recommendation on each open decision, in +[#847](https://github.com/kixel-ai/rust2/pull/847), which landed the generator: -Open, for the maintainer once the implementer has the facts: +- ✅ A 64-bit integer crosses as the translator's `rt.u64`, a number while safe and limbs + past it, converted from the wasm `bigint` at the boundary: 107 ns for a `u64` getter on + Node 24 against 98 ns returning the `bigint` as it is. Rejected: `bigint`, which + `ts/README.md` measured 8 to 65% slower on the codec, and which the translator's route + does not share. +- ✅ For this slice, the clock and randomness come from `wasm32-wasip1`'s std, whose imports the binding + implements with `performance.now`, `crypto.getRandomValues`, and the console: 24 KB over + `wasm32-unknown-unknown`'s module on the api fixture (3%), 9.5 KB gzipped. Rejected: + `web-time` or js-sys in the crate, a source change that brings wasm-bindgen back; a + patched std through `-Zbuild-std`; waiting for a web std upstream, which has none. +- ✅ Bytes Rust returns are copied out and freed at once, so no view outlives a growth of + memory. Rejected for now: an object of a pointer and length making its view at each + read, which keeps Rust's buffer alive until a `FinalizationRegistry` frees it. A copy + costs V8's `ArrayBuffer` allocation, 33 ns at 16 bytes but 0.8 µs at 1 KiB, against 0.2 µs + for the registry: measure the crossover on the benchmark's payload rows and lend above + it, as Dart lends past 64 KiB. -- How a 64-bit integer crosses. A wasm `i64` reaches JavaScript as a `bigint`, which - `ts/README.md` measured 8 to 65% slower than the translator's numbers-while-safe form on - the codec, and both routes must share one type for a caller to swap them. Recommended: - the translator's branded `rs.u64`, converted at the boundary, with the conversion's - cost on the benchmark's u64 getter row. +Decided with the maintainer on 2026-11-16, picking +[#847](https://github.com/kixel-ai/rust2/pull/847) to merge: -- How a stock crate's `std::time::Instant::now` becomes `performance.now`. moq-net - reaches it: `Timestamp::now` reads kio's clock, whose fallback is `Instant::now`. std - for `wasm32-unknown-unknown` has no clock and no hook for one, so the call panics - there, and getrandom and uuid refuse that target until a binary picks a backend, whose - browser one is wasm-bindgen's (`ts/README.md`). The ways to a web clock: - - compile against a std that imports its platform, `wasm32-wasip1`'s, and have the - generated binding implement each import the module declares with the web API for it. - The import names are then a detail between the generated `.wasm` and its generated - binding, not a WASI contract, and nothing of WASI ships; - - a web std of rustc's own: none exists. On 2026-11-12 the platform support page on - rust-lang/rust's `master` lists no web target, only the tier-3, `no_std` - `wasm32-none-component`, added on 2026-10-15 and so in no nightly up to the pin; - - the crate calls `web-time` or js-sys itself, a source change AGENTS.md calls a gap, and - one that brings wasm-bindgen back; - - a patched std built with `-Zbuild-std`, which is hand-rolling what upstream maintains. - Recommended: the first, measured for size against `wasm32-unknown-unknown` on the - fixture. Whichever is chosen, what has no web API (the file system, sockets, the - environment, a process) is refused at export, at the span of the call that reaches it, - rather than failing when the module loads or the call runs. That needs every reachable - body's MIR, which rust2-ts reads through its own MIR sysroot (`ts/src/profile.toml`, - `ts/src/cli.rs`) and the exporter does not read at all today: size it before starting, - and split it out if it is most of the work, since [WASI](/quest/m3/wasi.md) needs the - same. -- How a crate that itself imports browser APIs through wasm-bindgen (web-sys) exports. - Recommended: refuse it at the import's span until a consumer needs both. +- ✅ Merge the first slice on `wasm32-wasip1`'s std, its WASI imports implemented with web + APIs. Rejected: retargeting to `wasm32-unknown-unknown` before merging; skipping the + slice. The 2026-11-09 decision, no WASI runtime or polyfill in the web bundle, stands as + the goal, so this quest moves the web target off `wasm32-wasip1`. +- ✅ The copied-or-lent crossover for returned bytes is this quest's, measured on the + benchmark column's payload rows. Rejected: a quest of its own; dropping it. + +Recommended for moving off `wasm32-wasip1`: size it before choosing a route. On +`wasm32-unknown-unknown` the std's `Instant::now` and `SystemTime::now` panic and its +output is discarded, so the route must give std a clock, randomness, and output through +`rust2_*` imports without a source change or a consumer's config. #847's rejected options +(`web-time` or js-sys, a std patched through `-Zbuild-std`, a web std upstream) are the +starting survey; re-measure each against the 24 KB the WASI std costs today. -Public API: the TypeScript binding's shape, and the name of the web target. +Recommended for what remains: split the MIR refusal into a quest of its own shared with +[WASI](/quest/m3/wasi.md) once the exporter's MIR reading is sized, and run the browsers through Playwright's or the dev shell's +headless binaries with a static server of the script's directory, never the user's +signed-in Chrome. diff --git a/ts/rust-toolchain.toml b/ts/rust-toolchain.toml index 1af7bb4cd..84d7fecfc 100644 --- a/ts/rust-toolchain.toml +++ b/ts/rust-toolchain.toml @@ -4,5 +4,6 @@ # flake.nix reads this file for the dev shell's RUST2_TS_TOOLCHAIN. channel = "nightly-2026-11-12" components = ["rustc-dev", "llvm-tools", "rust-src", "rustfmt", "clippy"] -# Translation type-checks for wasm32, whose 32-bit usize is the one a JS number holds. -targets = ["wasm32-unknown-unknown"] +# Translation type-checks for wasm32, whose 32-bit usize is the one a JS number holds, and +# rust2-ffi's web binding runs over a wasm32-wasip1 build, whose std imports its platform. +targets = ["wasm32-unknown-unknown", "wasm32-wasip1"]