diff --git a/Cargo.lock b/Cargo.lock index c1ac1642..451cb3d9 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -389,6 +389,16 @@ dependencies = [ "vstd", ] +[[package]] +name = "clazel-js" +version = "0.0.0" +dependencies = [ + "clazel-js-builtins", + "clazel-js-heap", + "clazel-js-syntax", + "clazel-js-vm", +] + [[package]] name = "clazel-js-builtins" version = "0.0.0" diff --git a/crates/clazel-js-builtins/src/object.rs b/crates/clazel-js-builtins/src/object.rs index 35d2a352..b2c8064b 100644 --- a/crates/clazel-js-builtins/src/object.rs +++ b/crates/clazel-js-builtins/src/object.rs @@ -193,11 +193,15 @@ fn define_properties(vm: &mut Vm, obj: Value, props: Value) -> Result<(), Abrupt /// A property descriptor for a data property (§6.2.6†): each field present or /// absent. #[derive(Clone, Copy, Debug)] -struct Descriptor { - value: Option, - writable: Option, - enumerable: Option, - configurable: Option, +pub struct Descriptor { + /// `[[Value]]`. + pub value: Option, + /// `[[Writable]]`. + pub writable: Option, + /// `[[Enumerable]]`. + pub enumerable: Option, + /// `[[Configurable]]`. + pub configurable: Option, } /// ToPropertyDescriptor ( Obj ), §6.2.6.5†: @@ -272,7 +276,10 @@ fn define_property(vm: &mut Vm, _this: Value, args: &[Value]) -> Result>, } impl Vm { @@ -349,6 +352,7 @@ impl Vm { terminator: Terminator::new(), budget: u64::MAX, atoms, + embedder: None, }) } @@ -359,6 +363,29 @@ impl Vm { self.terminator.clone() } + /// Stores the embedder's own state in the VM, replacing what was there. + /// + /// A [`NativeFn`] is a plain function pointer that gets only `&mut Vm`, so + /// an embedder whose natives are closures (`clazel-js`) keeps the table of + /// closures here and finds it again from inside the native. The VM never + /// looks at it. Dropping the VM drops it. + pub fn set_embedder(&mut self, data: T) { + self.embedder = Some(Box::new(data)); + } + + /// The embedder's state, if it is a `T`. + #[must_use] + pub fn embedder(&self) -> Option<&T> { + self.embedder.as_deref().and_then(|e| e.downcast_ref::()) + } + + /// The embedder's state, mutably, if it is a `T`. + pub fn embedder_mut(&mut self) -> Option<&mut T> { + self.embedder + .as_deref_mut() + .and_then(|e| e.downcast_mut::()) + } + /// Bounds the back-edges and calls the VM may still make; when spent, a /// run ends as [`Abrupt::Terminated`]. pub fn set_budget(&mut self, steps: u64) { diff --git a/crates/clazel-js/Cargo.toml b/crates/clazel-js/Cargo.toml new file mode 100644 index 00000000..b3f22f52 --- /dev/null +++ b/crates/clazel-js/Cargo.toml @@ -0,0 +1,25 @@ +[package] +name = "clazel-js" +version = "0.0.0" +edition.workspace = true +license.workspace = true +publish.workspace = true +description = "The JavaScript engine's embedding API for Clazel (phase-7.md item 7.8): Runtime, realms, scripts and modules, native functions, host objects, rooted handles, the Host trait, limits and the Terminator. This is the contract only; nothing here is implemented yet." + +# Engine crates only (`cargo xtask check` enforces that no engine crate reaches +# a browser crate; see ENGINE in xtask/src/status.rs): the parser and compiler +# for scripts, the interpreter, the built-ins, and the heap's value type. +[dependencies] +clazel-js-builtins = { path = "../clazel-js-builtins" } +clazel-js-heap = { path = "../clazel-js-heap" } +clazel-js-syntax = { path = "../clazel-js-syntax" } +clazel-js-vm = { path = "../clazel-js-vm" } + +# Verification tier (docs/VERIFICATION.md). Tier 0: this crate holds the +# contract and its stubs, and nothing is proven about it. +[package.metadata.clazel] +tier = 0 +target-tier = 0 + +[lints] +workspace = true diff --git a/crates/clazel-js/README.md b/crates/clazel-js/README.md new file mode 100644 index 00000000..a637ba08 --- /dev/null +++ b/crates/clazel-js/README.md @@ -0,0 +1,406 @@ +# clazel-js: the engine's embedding API + +`clazel-js` is the one crate a program names to embed Clazel's JavaScript +engine. The browser embeds it, and so can a command-line runtime, a +Node-style server, or another Rust program. This is phase-7.md item 7.8, and +"The engine as a library" in that file is the plan this README works out. + +**Status: the contract, and its first implementation.** The types and +signatures here are the proposal. The contract was written first, as the plan +says, so that people can review it before `clazel-webidl` and `clazel-web` +build on it; the first part of the implementation is on top of it without +changing a signature, over the interpreter (`clazel-js-vm`) and the built-ins +(`clazel-js-builtins`). What the VM does not have yet still returns +`Error::NotImplemented`; "What is implemented" below lists each item and why. +Tier 0, no proofs. What to review is in "Open questions". + +Read the API in `src/`, one file per topic: `runtime.rs` (Runtime, limits, +Terminator), `value.rs` (the four ways to hold a value), `scope.rs` (all the +operations), `code.rs` (realms, source, scripts, modules), `native.rs` +(native functions, host objects), `host.rs` (the `Host` trait), `error.rs`. +`cargo doc -p clazel-js --no-deps --open` shows the same with the examples. + +## What is implemented + +Works now, with tests that use the public API only (`tests/api.rs`, and +the doctests): `Runtime::new` (VM, built-ins, host), `scope`, `run_jobs`, +`terminator` (the interpreter's own flag), `limits`, `heap_used` (an estimate); +primitives and strings (UTF-16 exact), `kind` and the `as_*`, `to_*` and `is_*` +conversions, `strict_equals`, `same_value`, `instance_of`; `new_object`, `get`, +`set`, `has_property`, `define_property` (data properties), +`get_prototype_of`, `set_prototype_of`, `get_method`, `call`, `construct`; +`function`, `define_method`, `Args`, `new_host_object` with `host_data`, +`get_prototype_from_constructor`, `host_mut`, `check_terminated`; errors, +`new_exception`, `throw_error`, `throw`, `report`, `Error::Thrown`; +`create_realm` (once), `global`, realm and script host data; `compile_script`, +`run_script`, `eval_script`; `Handle`, `Weak`, `Member`; `gc` and +`clear_kept_objects` as no-ops. + +Still `NotImplemented`, each because the VM lacks the feature: arrays +(`new_array*`), promises (`new_promise` and the rest), `iterate` and symbols +(`new_symbol`, `well_known_symbol`), BigInt, ArrayBuffer, `delete_property` +(the heap cannot remove a property), accessor descriptors in `define_property`, +modules and synthetic modules (the compiler's module goal and the runtime's +module records), a second realm and `RealmOptions::global`, `construct` with a +`new_target` other than the constructor, `instance_of` of a bound function, +`ErrorKind::EvalError` and `UriError`. The infallible constructors for the +missing values (`new_symbol`, `well_known_symbol`, `bigint_from_*`) cannot +return an error, so they record it and the next fallible call returns it. + +**Where it deviates, so reviewers see it:** + +- **No completion value.** `run_script` and `eval_script` return `undefined` + because the compiler's script has no completion value. Results go out + through globals or native functions. +- **Re-entrance.** A native closure that JavaScript re-enters while it runs + gets `Error::Busy`, because the closures are stored in the VM they borrow + (the table is where a plain function pointer can find it). Open question 14. +- **Rooting.** There is no collector in this tree (open pull requests), so + nothing is ever freed: `Local`, `Handle`, `Weak` and `Member` are checked + (the runtime they belong to, the arena's generation) but root nothing; + `Weak::upgrade` is always `Some`, `HostObject::trace` and `Host::trace_roots` + are never called, `Scope::nested` releases nothing, and a `Handle` drop does + nothing. The API is written so that a collector can start rooting without a + signature change: every value passes through `Scope`, `Handle` is the only + long-lived root, and `Member` is reported by its owner. +- **The `Host` hooks.** None is called: they are what promises, modules, + `Date`, `eval` of strings and `FinalizationRegistry` call, and the VM has + none of them. The engine's job queue works (`Scope::enqueue_job_internal`, + `run_job`, `run_jobs`) but nothing makes a job yet, so `run_jobs` returns 0. +- **Exotic hooks of `HostObject`** are not called: a host object is an + ordinary object with its data beside it. +- **Limits.** `heap_bytes` and `value_stack_bytes` map to the arena's cell + limit and the frame region's slots (estimates), the heap limit gives + `OutOfMemory` and not a `RangeError`, `native_depth` counts only closures + made by `Scope::function`, the rest are not used (see `Runtime::new`). +- **Stack traces.** `ErrorReport::stack` is empty and `Source::start_line` is + not used: the VM keeps no source positions. + +## The boundary + +- Engine crates depend on no browser crate. `cargo xtask check` enforces it + with the `ENGINE` list in `xtask/src/status.rs`, which holds this crate. +- `clazel-js` depends on the engine's `clazel-js-vm`, `clazel-js-builtins`, + `clazel-js-syntax` and `clazel-js-heap` and no other crate. No type of + theirs is in its public API: a `Local` is private data over the heap's value. +- The browser uses only this public API. A binding that needs something the API + lacks gets it added here, not a private path. +- The Test262 runner (`clazel-js-shell`, a later item) is a second embedder and + builds `$262` from public calls alone. + +## A `Runtime` + +A `Runtime` is one ECMAScript agent: a heap, a job queue, limits and a `Host`. + +- **No global state.** No `static`, no thread-local. A process can hold many + runtimes. +- **`Send`, not `Sync`.** A runtime can move to another thread between calls, and + only one thread uses it at a time. Compile-checked by doctests. For this to + hold the `Host` is `Send` too. The browser runs one runtime per renderer, on + one thread (7.0(e)). +- **Everything goes through a scope.** `Runtime::scope(|scope| ...)` is the only + way in. Inside native functions and `Host` hooks the engine hands over a + `Scope` for that call. +- **Dropping a runtime** frees the heap and drops native closures and host + object data. It runs no JavaScript. + +Configuration is a `Config` of `Limits` and a `JitMode` (only `Off` until jit.md's +crate exists), and a `Host`: + +```rust +use clazel_js::{Config, DefaultHost, Key, Limits, RealmOptions, Runtime, Source}; + +fn main() -> Result<(), clazel_js::Error> { + let mut rt = Runtime::new(Config::new(Limits::unlimited()), DefaultHost::new())?; + let realm = rt.scope(|scope| scope.create_realm(RealmOptions::default()))?; + let sum = rt.scope(|scope| { + // The script's completion value is not produced yet (see "What is + // implemented"), so the result goes out through a global. + scope.eval_script(&realm, Source::new("sum.js", "var sum = 1 + 2;"))?; + let global = scope.global(&realm)?; + let value = scope.get(global, Key::from("sum"))?; + Ok(scope.as_number(value)) + })?; + assert_eq!(sum, Some(3.0)); + rt.run_jobs()?; + Ok(()) +} +``` + +## Realms + +`Scope::create_realm` makes a realm: a global object and its own built-ins. +`$262.createRealm()` is exactly this, and frames would be later. A `Realm` is a +root (cloneable, `Send`, `Sync`) and every call that runs code names its realm. +`Scope::global` reaches the global object, and installing `console` or `window` +is ordinary property definition on it. `RealmOptions::global` lets the +global object be a host object, which the browser's `Window` needs. +`Scope::set_realm_host_defined` attaches the embedder's data to a realm (HTML's +environment settings object). + +## Scripts and modules + +- **Source** is `Source { name, text, start_line, host_defined }`. The text is a + `&str`, a sequence of code points, as ECMA-262 defines source text. The name + is for stack traces and reports, and `host_defined` is the embedder's data + (base URL, fetch options), kept with the compiled code. +- **Scripts.** `eval_script` does `compile_script` then `run_script`, which are + separate so a host can follow HTML's "prepare the script element". A syntax + error is a thrown `SyntaxError`. +- **Modules** follow ECMA-262's phases, one method each: `parse_module`, + `load_requested_modules`, `link`, `evaluate_module`, plus `module_namespace` and + `module_status`. Loading is asynchronous and the host's: the engine calls + `Host::load_imported_module(referrer, request, payload)`, and the host + answers with `Scope::finish_loading_imported_module(payload, result)`, now or + on a later event-loop turn. Dynamic `import()` uses the same hook. The + `Referrer` carries the importing code's `host_defined` data, so the host knows + what to resolve against. `import.meta` goes through two more hooks. A host + can add its own resolver, or CommonJS (through synthetic modules), without + engine changes. +- **Jobs.** The engine queues jobs and runs them only when asked: + `Runtime::run_jobs` is a microtask checkpoint. The event loop is the host's. + HTML's lives in `clazel-web`, and a Node-style runtime would drive the same + calls from its own. + +## Values, and holding them + +Values live in the collector's heap, which does not move them (7.0(f)). Four +types hold a value, from cheapest to most durable: + +| Type | Roots the value? | Lives | Use | +|---|---|---|---| +| `Local<'s>` | yes, until its scope ends | one `Scope` | everything inside a call. `Copy`; cannot escape the closure (compile-checked) | +| `Handle` | yes, until dropped | any time, any thread | what outlives a call: a callback to run later, a promise's resolvers. `Clone`, `Send`, `Sync`; dropping needs no runtime | +| `Weak` | no | any time | side tables from platform objects to wrappers; `upgrade` gives `None` after collection | +| `Member` | only if its owner reports it | owner's choice | JS values inside a host object's data or the host, reported from `trace` so there is no uncollectable cycle | + +- **Stale is an error, never an alias.** Every reference carries the arena's + generation (7.5, 7.6). Using one that no longer names its object gives + `Error::StaleHandle`. A handle from another runtime gives `Error::WrongRuntime`. +- **When the collector runs:** inside an operation that allocates, or on + `Scope::gc()` (`$262.gc()`), at points the engine chooses. Never between two + of the embedder's own Rust statements, and never while tracing, which is given + no `Scope`. +- **Roots** are the value stack, every live `Local`, every `Handle`, the job + queue, and what the host reports from `Host::trace_roots` (for the browser: + the wrapper of every node in a tree) and each host object's `trace`. +- **Strings** are UTF-16 code unit sequences, as in the language. + `Scope::string` takes Rust text; `string_utf16` takes units, including lone + surrogates, which WebIDL's conversions need. `string_to_utf16` reads exactly, + and `string_to_string_lossy` replaces lone surrogates. + +## Native functions and host objects + +- **`Scope::function(name, length, Callable, f)`** makes a JavaScript function + from a Rust closure `Fn(&mut Scope, &Args) -> Result`. It is `Fn`, not + `FnMut`, because a native function can be re-entered through JavaScript it + calls. State it needs lives in a host object, in the `Host`, or behind a lock. + `Callable::Constructor` makes it usable with `new`, with `Args::new_target` + set, and `get_prototype_from_constructor` gives subclasses their prototype. +- **`HostObject`** is a trait for the Rust data of a JavaScript object. It is + typed (`host_data::` checks, `Error::WrongType` otherwise), is dropped when + the collector frees the object, reports the values it refers to from `trace`, + and may have four exotic hooks (`get_own_property`, `define_own_property`, + `delete_property`, `own_property_keys`) for WebIDL's legacy platform objects. + This is how `clazel-webidl` builds DOM wrappers. + +## `Host` + +One trait for everything ECMA-262 leaves to the host, each with a stated +default, so `DefaultHost` works for a program that needs none. Hooks get +`&mut self` and a `Scope`, may re-enter the engine, and may fail with an +`Error`, which the calling operation passes on. + +| Group | Methods (ECMA-262 name) | Default | +|---|---|---| +| Jobs | `enqueue_promise_job`, `enqueue_generic_job`, `enqueue_timeout_job`, `enqueue_finalization_registry_cleanup_job` | the engine's own queue | +| Job callbacks | `make_job_callback`, `call_job_callback` | a plain callback; call it | +| Modules | `load_imported_module`, `supported_import_attributes`, `get_import_meta_properties`, `finalize_import_meta` | refuse with a `TypeError`; none; none; nothing | +| Promises | `promise_rejection_tracker` | nothing | +| Code from strings | `ensure_can_compile_strings`, `has_source_text_available` | allow; yes | +| Objects | `ensure_can_add_private_element`, `resize_array_buffer` | allow; `Unhandled` | +| The world | `now_ms`, `local_tza`, `random_u64`, `default_locale` | system clock; UTC; (required); `en-US` | +| The collector | `trace_roots` | nothing | + +The browser's answers for the world are its own: 7.0(b)'s fixed offset and +`en-US`, in `clazel-web`. The engine fixes none of them. `random_u64` has no +default because the engine has no entropy source and rule 8 forbids adding a +dependency for one. `DefaultHost` implements it from the standard library. + +**`$262`, built from public calls.** The shell's hooks need nothing private: + +| `$262` | Public call | +|---|---| +| `createRealm()` | `Scope::create_realm`, then `global` | +| `evalScript(src)` | `Scope::eval_script` in the realm | +| `gc()` | `Scope::gc` | +| `detachArrayBuffer(buf)` | `Scope::detach_array_buffer` | +| `agent` | none; see the open questions | + +## Errors and exceptions + +`Result` throughout. One variant is a JavaScript value; the rest are the +engine's and cannot be caught by JavaScript: + +- `Thrown(Exception)`: JavaScript threw. An `Exception` holds the value in a + `Handle`, so it can be reported after the call returned. This includes the + `SyntaxError` for bad source and the `RangeError`s the limits raise. + `Scope::report` turns it into an `ErrorReport` (name, message, stack) without + running user code. +- `Terminated`: a `Terminator` ended the evaluation. +- `OutOfMemory`: the heap limit was hit and not even the `RangeError` could be + allocated. Rare. +- `StaleHandle`, `WrongRuntime`, `WrongType`, `Busy`: misuse of the API, + caught and reported, never undefined behaviour. +- `NotImplemented`: something the VM does not have yet; see "What is + implemented". + +A native function returns errors of either kind with `?`. To throw: +`return Err(scope.throw_error(ErrorKind::TypeError, "..."))`, or +`scope.throw(value)` for a value the embedder made (a `DOMException`). + +## Limits and the `Terminator` + +**Limits are the embedder's.** `Limits` has no `Default`, and a struct literal must +name every field, so nothing is fixed in the engine and adding a limit makes +each embedder choose. `Limits::unlimited()` is a named choice for tests. + +| Limit | When passed | +|---|---| +| `heap_bytes` | full collection first, then a `RangeError` | +| `value_stack_bytes` | `RangeError`, "too much recursion" | +| `native_depth` | `RangeError`; counts built-ins that call back into JS | +| `code_bytes` | the JIT stops compiling; not an error | +| `regexp_backtrack_entries` | `RangeError` from the match | +| `nesting_depth` | `SyntaxError` (parser), `RangeError` (`JSON.parse`) | + +Timers and fetches in flight are the host's to bound, not the engine's. + +**`Terminator`** (`Runtime::terminator()`; `Clone`, `Send`, `Sync`) stops a runtime +from another thread. It sets a flag; the interpreter checks it at loop back-edges +and calls, JIT code at the same points, built-ins in their long loops, and native +functions via `Scope::check_terminated`. The evaluation ends with +`Error::Terminated`. JavaScript cannot catch it, and no `finally` runs. The flag +stays set until `Terminator::clear`. The `Terminator` itself is implemented +and tested here, because it is only an atomic flag. The browser keeps 7.0(g)'s +policy (it ends a stuck renderer, on the user's word) and may use this later to +keep the tab. jit.md adds no interaction beyond "JIT code checks the same flag at +the same points". + +**Executable memory** is the embedder's choice (jit.md J.0(b)). `JitMode` gains a +variant that carries a `CodeMapper` when `clazel-jit` exists. Until then it is +interpreter only, which is complete. + +## What the browser's bindings will use + +| Browser need | API | +|---|---| +| Install `window`, `document`, `console` | `create_realm` with a host-object global; `global`; `define_property`, `define_method` | +| Interface objects and prototypes (7.12) | `function` with `Callable::Constructor`; `get_prototype_from_constructor`; `define_property`; `set_prototype_of` | +| Wrappers, one per platform object (7.12, 7.13) | `new_host_object` with typed data; `Weak` for the side table; `Host::trace_roots` for nodes in a tree | +| `NodeList[0]`, `HTMLCollection.name` | `HostObject`'s exotic hooks | +| WebIDL conversions (3.2) | `to_number`, `to_string`, `to_boolean`, `to_object`, `is_callable`, `get_method`, `iterate`, `string_utf16`, `bigint_from_*` | +| `DOMException`, TypeErrors | `throw_error`, `throw` | +| Event listeners calling JS (7.14) | `Handle` or `Member` to the callback; `call`; `report` for uncaught exceptions | +| Promises from `fetch()`, `import()` (7.15, 7.16) | `new_promise`, `resolve_promise`, `reject_promise`, `promise_then`, `promise_state` | +| Script elements (7.15) | `compile_script`, `run_script`, `parse_module`, `load_requested_modules`, `link`, `evaluate_module`, `Host::load_imported_module` | +| Event loop, microtasks, `queueMicrotask` (7.15) | `Runtime::run_jobs`; `Host::enqueue_promise_job`, `make_job_callback`, `call_job_callback`; `clear_kept_objects` after a checkpoint | +| Unhandled rejections | `Host::promise_rejection_tracker` | +| `Date`, `Math.random`, locale | `Host::now_ms`, `local_tza`, `random_u64`, `default_locale` | +| A stuck page (7.0(g)) | `Terminator` | + +## What is deliberately not in the API + +- **A C API** (`clazel-js-capi`): Phase 8, and needs its own decision under rule 1. +- **Stability.** Rust only, unstable, no semver promise until Phase 8 has a second + real user. +- **Node as a drop-in.** A Node-compatible runtime on `clazel-js` is the + realistic path, not V8 API emulation. +- **Threads and shared memory**: `SharedArrayBuffer`, `Atomics`, and so + `$262.agent`; one runtime per thread only (7.0(b), 7.0(e)). +- **`Intl`, Temporal, WebAssembly, a debugger protocol, heap snapshots.** +- **Event loops, timers, `console`, `fetch`, a DOM.** The embedder's. The engine + has none and calls the `Host` instead. +- **Catching panics from native functions.** The lints forbid them here, and an + embedder's panic is its own. +- **Safety against a hostile embedder is not a goal; safety against hostile + JavaScript is.** An embedder that runs untrusted code without the browser's + sandbox relies on the engine's own guarantees: no `unsafe` outside + `clazel-sys`, the arena's generation checks, the validator's theorem for JIT + code, and the limits. + +## Open questions + +Nothing here is a decision the plan marks as the maintainer's. These are what the +plan leaves open and this contract had to settle, or leaves unsettled, so please +look at each. + +1. **After `Terminated`, is the runtime usable?** The proposal: the flag is + sticky, so every call ends `Terminated` until the embedder calls + `Terminator::clear`; after that the heap is consistent and the runtime + usable. It rests on `finally` blocks not running. It makes termination safe + for a runtime that is then dropped, and for the browser, but "usable after" + is a promise to implement and test. +2. **Handle model.** `Local<'s>` scoped to a closure, plus `Handle` (reference + counted, dropped without the runtime) and `Member` (reported from `trace`). + Plan 7.0(f) says "a scoped handle stack, checked on scope exit". The scope + here is a closure with a lifetime the compiler enforces, which is checked + earlier than at exit. The cost is that a value cannot be returned from a + nested scope except as a `Handle`; an `escape` call is possible if that bites. +3. **`Host: Send`.** It keeps `Runtime: Send`. It means the browser's host cannot + hold `Rc`s of DOM state: nodes are arena ids (Phase 4), which should work, + but it is the contract's strictest demand on `clazel-web`. +4. **Exotic hooks.** Four are given; WebIDL §3.9 and §3.10 (legacy platform + objects, named properties) may need `set`/`get` receivers or more. The + set is to be fixed against 7.12's generator, and may grow. +5. **The global's `this` value** (HTML's `WindowProxy`) is not in `RealmOptions`. + ECMA-262 lets a host set it separately from the global object. Needed by + 7.15, and the contract does not yet say how. +6. **Synthetic modules** (`new_synthetic_module`, `set_synthetic_export`) are + reserved in the contract, since "a host can add CommonJS" needs them and + JSON modules do. The plan does not list them as a Phase 7 deliverable. +7. **`$262.agent`.** The plan lists `agent` among the host hooks, and 7.0(b) + leaves out `SharedArrayBuffer` and `Atomics`, which `agent` exists to test. + This API has no agent hook, and the shell skips those tests. If another + host wants agents in Phase 8, a `Runtime` per thread plus shared memory + needs its own design. +8. **Hooks the plan's list lacks.** `HostEnqueueFinalizationRegistryCleanupJob` + (7.6 needs it) and `HostGetSupportedImportAttributes` are in the trait; + the plan's list does not name them. 7.4's check against the pinned edition + decides which stay. +9. **ECMA-262 section numbers** are not cited on the hooks, because 7.1 has not + pinned an edition. They are named by abstract operation instead, which does + not change between editions. Rule 5 asks for sections, so they are added when + 7.1 pins one. Until then the citations are incomplete. +10. **`run_jobs` and a throwing job.** A job that throws stops the run and + returns the exception; later jobs stay queued. A host that wants + "report and continue" overrides the queue hooks and runs jobs itself. + The alternative is one more hook. The plan names none. +11. **`Source` text as `&str`.** Source with a lone surrogate cannot be written. ECMA-262 + source text is code points, and the browser decodes with `clazel-encoding`, + which gives scalar values only, so nothing is lost in practice. Say so if + UTF-16 source is wanted. +12. **Where `CodeMapper` lives.** jit.md names it; this crate cannot depend on a + crate that does not exist. Likely `clazel-jit` defines it and `clazel-js` + re-exports it. +13. **`OutOfMemory` versus `RangeError`.** 7.19 says the heap limit gives a + `RangeError`. This contract keeps `OutOfMemory` for when even that cannot + be allocated. If that case can be avoided by reserving room for one + error object, the variant can go. +14. **Native closures and re-entrance.** `Scope::function` takes `Fn + Send`. + Re-entering a running closure needs it shared with the call that is + running, which for a `Send` runtime means `Fn + Send + Sync` (an `Arc`), + or a runtime that is not `Send`. With `Send` alone the implementation + stores each closure in the VM's embedder slot and takes it out while it + runs, so a re-entrant call is `Error::Busy`. Proposal: add `Sync` to the + bound (the browser's closures hold ids, not `Rc`s, as open question 3 + already asks of the host). +15. **Infallible constructors that cannot work yet.** `bigint_from_*`, + `new_symbol` and `well_known_symbol` return a `Local`, not a `Result`, so + when the VM lacks the type the error is held for the next fallible call. + Proposal: make them return `Result` (they allocate, so `string` and + `string_utf16` could fail the same way, with `OutOfMemory`, which is also + held today). +16. **Script completion value.** `run_script` documents the value of the last + expression statement; the compiler does not produce it yet. No signature + change, but embedders should not rely on it until the compiler does. diff --git a/crates/clazel-js/src/code.rs b/crates/clazel-js/src/code.rs new file mode 100644 index 00000000..962c73cf --- /dev/null +++ b/crates/clazel-js/src/code.rs @@ -0,0 +1,330 @@ +//! Realms, source text, scripts and modules. + +use core::any::Any; +use core::marker::PhantomData; + +use crate::native::HostObject; +use crate::value::Handle; + +/// A realm: a global object and its own copy of every built-in +/// (ECMA-262's Realm Record). +/// +/// - **Why more than one.** `$262.createRealm()` in Test262, and later a +/// frame. A realm's `Array` is not another realm's `Array`, and +/// `instanceof` across them is false, as in a browser. +/// - **Lifetime.** A `Realm` is a root: the realm and everything reachable +/// from its global object live until the last clone is dropped. Like +/// [`Handle`] it is `Send`, `Sync` and `Clone`, and needs a +/// [`Scope`](crate::Scope) to do anything. +/// - **No ambient realm.** Every call that runs code names the realm. Inside a +/// native function, [`Scope::current_realm`](crate::Scope::current_realm) +/// is the realm of the function being called. +/// +/// This stays `no_run`: the VM has one global environment, so a second +/// `create_realm` is `NotImplemented`. +/// +/// ```no_run +/// use clazel_js::{Runtime, RealmOptions, Source}; +/// +/// fn two_realms(rt: &mut Runtime) -> clazel_js::Result<()> { +/// let (a, b) = rt.scope(|scope| { +/// Ok((scope.create_realm(RealmOptions::default())?, +/// scope.create_realm(RealmOptions::default())?)) +/// })?; +/// rt.scope(|scope| { +/// let same = scope.eval_script(&a, Source::new("t.js", "[] instanceof Array"))?; +/// assert_eq!(scope.as_boolean(same), Some(true)); +/// // A realm's own object is not an instance of the other realm's Array. +/// let global_b = scope.global(&b)?; +/// let _ = global_b; +/// Ok(()) +/// }) +/// } +/// ``` +#[derive(Clone, Debug)] +pub struct Realm { + root: Handle, +} + +impl Realm { + pub(crate) fn new(root: Handle) -> Realm { + Realm { root } + } + + /// The root that keeps the realm alive. + pub fn as_handle(&self) -> &Handle { + &self.root + } +} + +/// How to build a realm. The default is an ordinary global object with the +/// standard built-ins. +/// +/// A host-object global is `NotImplemented` yet (the VM's global is an +/// ordinary object), so this only builds the options: +/// +/// ``` +/// use clazel_js::{Exotic, HostObject, RealmOptions}; +/// +/// /// The browser's `Window`: a host object serving as the global object. +/// struct Window; +/// impl HostObject for Window {} +/// +/// let options = RealmOptions { +/// global: Some(Box::new(Window)), +/// }; +/// # let _ = options; +/// ``` +#[derive(Default)] +pub struct RealmOptions { + /// Make the global object a host object with this data, whose prototype is + /// the realm's `Object.prototype`. `None` makes an ordinary object. Its + /// exotic hooks answer for the global's own properties. The global's `this` + /// value (HTML's `WindowProxy`) is an open question in the README. + pub global: Option>, +} + +/// Source text to compile, with where it came from. +/// +/// - **Text** is a `&str`: a sequence of Unicode code points, as ECMA-262 +/// defines source text. The browser decodes bytes to text with +/// `clazel-encoding` before calling. +/// - **Name** is what stack traces and error reports show: a URL for a +/// script from the network, `"inline"` or similar for the rest. +/// - **`start_line`** is the 1-based line number of the text's first line, so +/// an inline script in a page reports page line numbers. +/// - **`host_defined`** is the embedder's data about this code (a base URL, +/// fetch options). It is kept with the compiled [`Script`] or [`Module`] and +/// given back by [`Scope::host_defined`](crate::Scope::host_defined) +/// and to the [`Host`](crate::Host) hooks as part of a [`Referrer`]. +/// +/// ``` +/// use clazel_js::Source; +/// +/// struct BaseUrl(String); +/// +/// let source = Source::new("https://example.test/app.js", "export default 1;") +/// .with_start_line(1) +/// .with_host_defined(Box::new(BaseUrl("https://example.test/".to_owned()))); +/// assert_eq!(source.name(), "https://example.test/app.js"); +/// ``` +pub struct Source<'a> { + name: &'a str, + text: &'a str, + start_line: u32, + host_defined: Option>, +} + +impl<'a> Source<'a> { + /// Source text with a name, starting at line 1, with no host data. + pub fn new(name: &'a str, text: &'a str) -> Source<'a> { + Source { + name, + text, + start_line: 1, + host_defined: None, + } + } + + /// Sets the line number of the first line. + #[must_use] + pub fn with_start_line(mut self, start_line: u32) -> Source<'a> { + self.start_line = start_line; + self + } + + /// Attaches the embedder's data. + #[must_use] + pub fn with_host_defined(mut self, data: Box) -> Source<'a> { + self.host_defined = Some(data); + self + } + + pub(crate) fn into_host_defined(self) -> Option> { + self.host_defined + } + + /// The name. + pub fn name(&self) -> &str { + self.name + } + + /// The text. + pub fn text(&self) -> &str { + self.text + } + + /// The line number of the first line. + pub fn start_line(&self) -> u32 { + self.start_line + } + + /// The embedder's data, if any. + pub fn host_defined(&self) -> Option<&(dyn Any + Send)> { + self.host_defined.as_deref() + } +} + +/// A parsed classic script (ECMA-262's Script Record), not yet run. +/// +/// Parsing and running are separate so a host can follow HTML's "prepare the +/// script element", which fetches and compiles, then runs when the parser +/// or the event loop says. [`Scope::eval_script`](crate::Scope::eval_script) does both at +/// once. A `Script` is a root, `Clone`, `Send` and `Sync`, and may be run +/// more than once; top-level `var`s and functions are created in the realm +/// each time it runs, as for a script run twice. +/// +/// ``` +/// use clazel_js::{Key, Realm, Runtime, Script, Source}; +/// +/// fn compile_then_run(rt: &mut Runtime, realm: &Realm) -> clazel_js::Result<()> { +/// let script: Script = rt.scope(|scope| { +/// scope.compile_script(realm, Source::new("later.js", "globalThis.n = 1")) +/// })?; +/// // ... the parser unblocks ... +/// rt.scope(|scope| { +/// scope.run_script(&script)?; +/// Ok(()) +/// }) +/// } +/// # let mut rt = clazel_js::Runtime::new(clazel_js::Config::new(clazel_js::Limits::unlimited()), clazel_js::DefaultHost::new())?; +/// # let realm = rt.scope(|scope| scope.create_realm(clazel_js::RealmOptions::default()))?; +/// # compile_then_run(&mut rt, &realm)?; +/// # let n = rt.scope(|scope| { +/// # let global = scope.global(&realm)?; +/// # let n = scope.get(global, Key::from("n"))?; +/// # Ok(scope.as_number(n)) +/// # })?; +/// # assert_eq!(n, Some(1.0)); +/// # Ok::<(), clazel_js::Error>(()) +/// ``` +#[derive(Clone, Debug)] +pub struct Script { + root: Handle, + /// The index of the script's code in the VM's table. + main: u32, +} + +impl Script { + pub(crate) fn new(root: Handle, main: u32) -> Script { + Script { root, main } + } + + pub(crate) fn main(&self) -> u32 { + self.main + } + + /// The root that keeps the script alive. + pub fn as_handle(&self) -> &Handle { + &self.root + } +} + +/// A module (ECMA-262's Source Text Module Record or a synthetic one). +/// +/// The life of a module follows ECMA-262 §16.2.1.5, which the methods of +/// [`Scope`](crate::Scope) name: parse, load requested modules (the host +/// supplies each import through [`Host::load_imported_module`](crate::Host::load_imported_module)), +/// link, evaluate. `Module` is a root, `Clone`, `Send` and `Sync`. +/// +/// This stays `no_run`: modules return `NotImplemented` until the VM has +/// them. +/// +/// ```no_run +/// use clazel_js::{ModuleStatus, Realm, Runtime, Source}; +/// +/// /// Loads and runs a module whose imports the host can already resolve. +/// fn run_module(rt: &mut Runtime, realm: &Realm, text: &str) -> clazel_js::Result<()> { +/// let module = rt.scope(|scope| scope.parse_module(realm, Source::new("m.js", text)))?; +/// rt.scope(|scope| { +/// let loaded = scope.load_requested_modules(&module)?; +/// let _ = loaded; // a promise: settled when every import has been finished +/// Ok(()) +/// })?; +/// rt.run_jobs()?; +/// rt.scope(|scope| { +/// if scope.module_status(&module)? == ModuleStatus::Unlinked { +/// scope.link(&module)?; +/// } +/// let _done = scope.evaluate_module(&module)?; // a promise, for top-level await +/// Ok(()) +/// }) +/// } +/// ``` +#[derive(Clone, Debug)] +pub struct Module { + root: Handle, +} + +impl Module { + /// The root that keeps the module alive. + pub fn as_handle(&self) -> &Handle { + &self.root + } +} + +/// A module's state (ECMA-262's Cyclic Module Record `[[Status]]`). +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum ModuleStatus { + /// Just created by `parse_module`. + New, + /// Its requested modules are loaded; not yet linked. + Unlinked, + /// `link` is running. + Linking, + /// Linked, not yet evaluated. + Linked, + /// Evaluation is running. + Evaluating, + /// Evaluation is waiting on top-level `await`. + EvaluatingAsync, + /// Evaluation finished, with a value or an error (kept by the module). + Evaluated, +} + +/// One import attribute: `with { type: "json" }` is `("type", "json")`. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct ImportAttribute { + /// The attribute's key. + pub key: String, + /// Its value. + pub value: String, +} + +/// What a module asks to import: ECMA-262's ModuleRequest Record. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct ModuleRequest { + /// The module specifier, exactly as written in the source. + pub specifier: String, + /// The import attributes, in source order. + pub attributes: Vec, +} + +/// The code that asked for an import: the referrer of +/// [`Host::load_imported_module`](crate::Host::load_imported_module). Its +/// [host data](crate::Scope::host_defined) tells the host where to resolve +/// the specifier against. +#[derive(Clone, Copy, Debug)] +pub enum Referrer<'a> { + /// A classic script (a dynamic `import()` in one). + Script(&'a Script), + /// A module (a static `import` or a dynamic `import()` in one). + Module(&'a Module), + /// Neither: `import()` in `eval` or `Function` code outside any script + /// or module, which has only the realm. + Realm(&'a Realm), +} + +/// The engine's token for one pending import, passed to +/// [`Host::load_imported_module`](crate::Host::load_imported_module) and given +/// back to [`Scope::finish_loading_imported_module`](crate::Scope::finish_loading_imported_module). +/// +/// A host may finish it at once or on a later turn of its event loop, from +/// the same thread as the runtime. It must be finished exactly once; the type +/// is consumed by finishing it. Dropping it without finishing leaves the +/// module graph's load promise pending for ever, which is a bug in the host +/// but not unsafe. +#[derive(Debug)] +pub struct LoadPayload { + _pending: PhantomData<()>, +} diff --git a/crates/clazel-js/src/error.rs b/crates/clazel-js/src/error.rs new file mode 100644 index 00000000..6b70fb3e --- /dev/null +++ b/crates/clazel-js/src/error.rs @@ -0,0 +1,200 @@ +//! Errors and exceptions. + +use core::fmt; + +use crate::value::Handle; + +/// What every fallible call in this crate returns. +pub type Result = core::result::Result; + +/// The kinds of error object the engine can create (ECMA-262's native error +/// types). +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum ErrorKind { + /// `Error`. + Error, + /// `EvalError`. + EvalError, + /// `RangeError`. + RangeError, + /// `ReferenceError`. + ReferenceError, + /// `SyntaxError`. + SyntaxError, + /// `TypeError`. + TypeError, + /// `URIError`. + UriError, +} + +/// A value JavaScript threw, held by a rooted [`Handle`]. +/// +/// An `Exception` is what `catch` would see. It stays alive for as long as it +/// is held, whichever scope it was thrown in, so an embedder can report it +/// after the call that threw it has returned. +/// +/// ``` +/// use clazel_js::{Error, Realm, Scope, Source}; +/// +/// fn report(scope: &mut Scope<'_>, realm: &Realm) -> clazel_js::Result { +/// match scope.eval_script(realm, Source::new("page.js", "null.x")) { +/// Err(Error::Thrown(exception)) => { +/// let report = scope.report(&exception)?; +/// println!("{}: {}", report.name, report.message); +/// Ok(report.name) +/// } +/// other => other.map(|_| String::new()), +/// } +/// } +/// # let mut rt = clazel_js::Runtime::new(clazel_js::Config::new(clazel_js::Limits::unlimited()), clazel_js::DefaultHost::new())?; +/// # let realm = rt.scope(|scope| scope.create_realm(clazel_js::RealmOptions::default()))?; +/// # let name = rt.scope(|scope| report(scope, &realm))?; +/// # assert_eq!(name, "TypeError"); +/// # Ok::<(), clazel_js::Error>(()) +/// ``` +#[derive(Clone, Debug)] +pub struct Exception { + value: Handle, +} + +impl Exception { + /// Wraps a value to be reported as thrown, for example to refuse a module + /// load in [`Scope::finish_loading_imported_module`](crate::Scope::finish_loading_imported_module). + /// The engine builds the ones it returns in [`Error::Thrown`]. + pub fn from_handle(value: Handle) -> Exception { + Exception { value } + } + + /// The thrown value, as a rooted handle. Turn it back into a + /// [`Local`](crate::Local) with [`Scope::local`](crate::Scope::local). + pub fn value(&self) -> &Handle { + &self.value + } +} + +/// A thrown error described in plain Rust types, for logging and for the +/// browser's "report the exception" step (which is HTML's, not the engine's; +/// the engine only supplies these fields). +/// +/// Built by [`Scope::report`](crate::Scope::report). It never runs user code: +/// a getter that throws while the report is built leaves that field empty. +#[derive(Clone, Debug, Default, PartialEq, Eq)] +pub struct ErrorReport { + /// `name` of the thrown object, or `"Error"` if it has none. For a thrown + /// non-object, the type of the value, such as `"string"`. + pub name: String, + /// `message` of the thrown object, or the string conversion of a thrown + /// primitive. + pub message: String, + /// The call stack when the error object was created, innermost first. + /// Empty if the thrown value is not an error object. + pub stack: Vec, +} + +/// One frame of a call stack. +#[derive(Clone, Debug, Default, PartialEq, Eq)] +pub struct StackFrame { + /// The function's name, or `None` for top-level code and anonymous + /// functions. + pub function: Option, + /// The `name` of the [`Source`](crate::Source) the frame's code came from. + pub source: String, + /// 1-based line, counting from the source's `start_line`. + pub line: u32, + /// 1-based column, in UTF-16 code units. + pub column: u32, +} + +/// Why a call failed. +/// +/// Exactly one variant, [`Thrown`](Error::Thrown), is a JavaScript value. +/// Every other variant is the engine's or the embedder's, and JavaScript +/// cannot observe or catch it. A native function passes both kinds back with +/// `?`. +/// +/// This stays `no_run`: the script would loop for ever. +/// +/// ```no_run +/// use clazel_js::{Error, Realm, Scope, Source}; +/// +/// fn run(scope: &mut Scope<'_>, realm: &Realm) { +/// match scope.eval_script(realm, Source::new("a.js", "while (true) {}")) { +/// Ok(_) => {} +/// Err(Error::Thrown(_)) => { /* the script threw; `catch` could have caught it */ } +/// Err(Error::Terminated) => { /* a Terminator stopped it; nothing in JS ran after */ } +/// Err(other) => eprintln!("engine error: {other}"), +/// } +/// } +/// ``` +#[derive(Clone, Debug)] +#[non_exhaustive] +pub enum Error { + /// JavaScript threw this value. Includes the `SyntaxError` for source + /// that does not parse, and the `RangeError`s the limits report + /// (heap, value stack, nested native calls, nesting depth, RegExp + /// backtracking). All of them can be caught by JavaScript. + Thrown(Exception), + /// A [`Terminator`](crate::Terminator) ended the evaluation. JavaScript + /// cannot catch it, and no `finally` block runs while it propagates. + Terminated, + /// The heap limit was reached and the engine could not even allocate the + /// `RangeError` to report it. This is the rare case; the ordinary report + /// of the heap limit is [`Thrown`](Error::Thrown). + OutOfMemory, + /// The handle names something that no longer exists, so using it would + /// have aliased a different object. The generation check caught it. + StaleHandle, + /// The handle, realm, script or module belongs to another + /// [`Runtime`](crate::Runtime). + WrongRuntime, + /// The value was not of the type the call needs. The text names what was + /// wanted, for example `"host object of this type"`. + WrongType(&'static str), + /// The data being asked for is already borrowed by a call further up the + /// stack (a host object's data while one of its own hooks runs). + Busy, + /// The contract is written but the body is not. The text names the call. + /// This variant exists only until item 7.8 builds the implementation. + NotImplemented(&'static str), +} + +impl fmt::Display for Error { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + match self { + Error::Thrown(_) => f.write_str("JavaScript threw a value"), + Error::Terminated => f.write_str("terminated"), + Error::OutOfMemory => f.write_str("out of memory"), + Error::StaleHandle => f.write_str("stale handle"), + Error::WrongRuntime => f.write_str("handle from another runtime"), + Error::WrongType(what) => write!(f, "wrong type: wanted {what}"), + Error::Busy => f.write_str("already borrowed further up the stack"), + Error::NotImplemented(what) => write!(f, "not implemented: {what}"), + } + } +} + +impl std::error::Error for Error {} + +/// The body of every call whose implementation is still to come: names the +/// call, uses its arguments so the contract's parameter names stay as written, +/// and returns [`Error::NotImplemented`]. +macro_rules! not_implemented { + ($what:expr $(, $arg:expr)* $(,)?) => {{ + let _ = ($(&$arg,)*); + ::core::result::Result::Err($crate::Error::NotImplemented($what)) + }}; +} +pub(crate) use not_implemented; + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn display_names_the_unimplemented_call() { + assert_eq!( + Error::NotImplemented("Runtime::new").to_string(), + "not implemented: Runtime::new" + ); + } +} diff --git a/crates/clazel-js/src/host.rs b/crates/clazel-js/src/host.rs new file mode 100644 index 00000000..3564523b --- /dev/null +++ b/crates/clazel-js/src/host.rs @@ -0,0 +1,488 @@ +//! The [`Host`] trait: everything ECMA-262 leaves to the host, and what the +//! engine needs from the world. +//! +//! The ECMA-262 section of each hook is not cited yet. Rule 5 asks for the +//! exact section, and the edition they refer to is pinned in item 7.1, which +//! has not run. Each hook is named by the abstract operation's name, which +//! does not change between editions; section numbers join when 7.1 pins one, +//! and 7.4 checks this list against the pinned edition's list of host hooks. + +use core::any::Any; +use std::hash::{BuildHasher, RandomState}; +use std::time::{SystemTime, UNIX_EPOCH}; + +use crate::code::{LoadPayload, Module, ModuleRequest, Realm, Referrer}; +use crate::error::{ErrorKind, Result}; +use crate::native::Tracer; +use crate::scope::Scope; +use crate::value::{Handle, Local}; + +/// A queued unit of work for the event loop: a promise reaction, a +/// `FinalizationRegistry` cleanup, or a generic job. +/// +/// The engine makes a `Job` and gives it to the host to queue. Running it is +/// [`Scope::run_job`](crate::Scope::run_job), once, on the runtime's thread. A +/// `Job` is a root, so dropping one without running it only loses the work. +/// It is `Send` and `Sync` like a [`Handle`]. +#[derive(Debug)] +pub struct Job { + root: Handle, + realm: Option, +} + +impl Job { + /// The realm the job runs in, if the operation that made it names one. + pub fn realm(&self) -> Option<&Realm> { + self.realm.as_ref() + } + + /// The root that keeps the job's closure alive. + pub fn as_handle(&self) -> &Handle { + &self.root + } +} + +/// A callback and the host's data about it: ECMA-262's JobCallback Record. +/// +/// [`Host::make_job_callback`] makes one when a promise reaction or a +/// `FinalizationRegistry` is created, and [`Host::call_job_callback`] calls it +/// later. HTML uses the data to remember the "incumbent settings object". +#[derive(Debug)] +pub struct JobCallback { + callback: Handle, + host_defined: Option>, +} + +impl JobCallback { + /// A job callback with no host data. + pub fn new(callback: Handle) -> JobCallback { + JobCallback { + callback, + host_defined: None, + } + } + + /// Attaches the host's data. + #[must_use] + pub fn with_host_defined(mut self, data: Box) -> JobCallback { + self.host_defined = Some(data); + self + } + + /// The callback function. + pub fn callback(&self) -> &Handle { + &self.callback + } + + /// The host's data, if any. + pub fn host_defined(&self) -> Option<&(dyn Any + Send)> { + self.host_defined.as_deref() + } +} + +/// What [`Host::promise_rejection_tracker`] is told happened. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum RejectionOperation { + /// A promise with no handler was rejected. + Reject, + /// A handler was added to an already-rejected promise that had none. + Handle, +} + +/// Which dynamic code-from-strings feature is asking +/// [`Host::ensure_can_compile_strings`]. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum DynamicCodeKind { + /// `eval(...)`; `direct` is true for a direct call that sees local scope. + Eval { + /// Whether this was a direct `eval`. + direct: bool, + }, + /// `Function(...)`. + Function, + /// `GeneratorFunction(...)`. + GeneratorFunction, + /// `AsyncFunction(...)`. + AsyncFunction, + /// `AsyncGeneratorFunction(...)`. + AsyncGeneratorFunction, +} + +/// The strings handed to [`Host::ensure_can_compile_strings`]. They are +/// UTF-16 because the program can build them with lone surrogates. +#[derive(Clone, Copy, Debug)] +pub struct CompileStrings<'a> { + /// Which feature is compiling code. + pub kind: DynamicCodeKind, + /// The parameter strings (empty for `eval`). + pub parameters: &'a [Vec], + /// The body, or for `eval` the code. + pub body: &'a [u16], +} + +/// The answer of [`Host::resize_array_buffer`]. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum Resize { + /// The host did the resize. + Handled, + /// The host left it to the engine's default, which allocates. + Unhandled, +} + +/// What the embedder supplies. Every method has a default so a program that +/// needs none of the hooks can use [`DefaultHost`], and an embedder +/// overrides what it needs. +/// +/// - **Reentrancy.** A hook gets `&mut self` and a [`Scope`] and may call +/// back into the engine through that scope, including evaluating code. +/// While a hook runs, the host is lent to it, so [`Scope::host_mut`] from +/// code the hook runs gives [`Error::Busy`](crate::Error::Busy). +/// - **Errors.** A hook that returns `Err` makes the operation that called it +/// fail with that error, as ECMA-262 says for an abrupt completion from a +/// host-defined operation. `Err(Error::Terminated)` is passed on as is. +/// - **Threads.** `Host: Send`, which keeps [`Runtime`](crate::Runtime) +/// `Send`. A host that needs a value that is not `Send` keeps an id or a +/// channel in the host and the value elsewhere. +/// - **The event loop is the host's.** Nothing here runs a job: the hooks +/// queue, and the embedder calls [`Runtime::run_jobs`](crate::Runtime::run_jobs) +/// when its loop says to. +/// +/// The defaults named in each method are the engine's behaviour for a host +/// that says nothing. The browser's answers (HTML's, and 7.0(b)'s fixed +/// time zone offset and `en-US`) are the browser's, in `clazel-web`. +/// +/// None of these hooks is called yet: the VM has no promises, modules or +/// `Date`, which are what call them. The example compiles and runs its type +/// checks: +/// +/// ``` +/// use clazel_js::{ +/// Host, Job, Local, Module, ModuleRequest, LoadPayload, Referrer, RejectionOperation, +/// Result, Scope, +/// }; +/// +/// /// A host with a task queue of its own, rejection reporting, and a fixed clock. +/// struct PageHost { +/// tasks: Vec, +/// unhandled: Vec, +/// } +/// +/// impl Host for PageHost { +/// fn enqueue_promise_job(&mut self, _scope: &mut Scope<'_>, job: Job) -> Result<()> { +/// self.tasks.push(job); +/// Ok(()) +/// } +/// +/// fn promise_rejection_tracker( +/// &mut self, +/// _scope: &mut Scope<'_>, +/// _promise: Local<'_>, +/// operation: RejectionOperation, +/// ) { +/// self.unhandled.push(format!("{operation:?}")); +/// } +/// +/// fn now_ms(&mut self) -> f64 { +/// 1_700_000_000_000.0 +/// } +/// +/// fn random_u64(&mut self) -> u64 { +/// 4 // chosen by fair dice roll +/// } +/// } +/// ``` +pub trait Host: Any + Send { + // ---- Jobs ----------------------------------------------------------- + + /// `HostEnqueuePromiseJob(job, realm)`: queue a promise reaction. + /// + /// Default: append it to the engine's own queue, which + /// [`Runtime::run_jobs`](crate::Runtime::run_jobs) drains in order. A host + /// that overrides this takes over the order and calls + /// [`Scope::run_job`] itself. + fn enqueue_promise_job(&mut self, scope: &mut Scope<'_>, job: Job) -> Result<()> { + scope.enqueue_job_internal(job) + } + + /// `HostEnqueueGenericJob(job, realm)`. Default: as for promise jobs. + fn enqueue_generic_job(&mut self, scope: &mut Scope<'_>, job: Job) -> Result<()> { + scope.enqueue_job_internal(job) + } + + /// `HostEnqueueTimeoutJob(job, realm, milliseconds)`: run `job` after at + /// least `delay_ms`. Only a feature with timers in the language uses it + /// (`Atomics.waitAsync`, which the browser does not ship), so no + /// embedder is required to override it. Default: the engine's own queue, + /// with the delay ignored. + fn enqueue_timeout_job( + &mut self, + scope: &mut Scope<'_>, + job: Job, + delay_ms: f64, + ) -> Result<()> { + let _ = delay_ms; + scope.enqueue_job_internal(job) + } + + /// `HostEnqueueFinalizationRegistryCleanupJob(finalizationRegistry)`: a + /// registry has cells to clean up. The phase plan's list of hooks does not + /// name this one and 7.6 needs it (finalization callbacks are queued as + /// tasks); it is listed under the README's open questions. Default: the + /// engine's own queue. + fn enqueue_finalization_registry_cleanup_job( + &mut self, + scope: &mut Scope<'_>, + job: Job, + ) -> Result<()> { + scope.enqueue_job_internal(job) + } + + /// `HostMakeJobCallback(callback)`. Default: a [`JobCallback`] holding the + /// function and no host data. + fn make_job_callback( + &mut self, + scope: &mut Scope<'_>, + callback: Local<'_>, + ) -> Result { + Ok(JobCallback::new(scope.persist(callback))) + } + + /// `HostCallJobCallback(jobCallback, V, argumentsList)`. Default: call the + /// function with `this` and the arguments. + fn call_job_callback<'s>( + &mut self, + scope: &mut Scope<'s>, + callback: &JobCallback, + this: Local<'_>, + arguments: &[Local<'_>], + ) -> Result> { + let function = scope.local(callback.callback())?; + scope.call(function, this, arguments) + } + + // ---- Modules -------------------------------------------------------- + + /// `HostLoadImportedModule(referrer, moduleRequest, hostDefined, payload)`: + /// find (and fetch, if need be) the module `request` names, then call + /// [`Scope::finish_loading_imported_module`] with it or with the error. + /// It may do so before returning or on a later turn. + /// + /// ECMA-262 requires the same `(referrer, request)` to give the same module + /// every time or fail every time; keeping that is the host's job. + /// + /// Default: finish with a `TypeError` saying this host loads no modules. + fn load_imported_module( + &mut self, + scope: &mut Scope<'_>, + referrer: Referrer<'_>, + request: &ModuleRequest, + payload: LoadPayload, + ) -> Result<()> { + let _ = (referrer, request); + let error = scope.new_exception(ErrorKind::TypeError, "this host does not load modules")?; + scope.finish_loading_imported_module(payload, Err(error)) + } + + /// `HostGetSupportedImportAttributes()`: the attribute keys this host + /// understands (for example `"type"`). The engine refuses an import with + /// any other key with a `SyntaxError`. Default: none. Whether the pinned + /// edition has this hook is checked in 7.4. + fn supported_import_attributes(&self) -> &[&'static str] { + &[] + } + + /// `HostGetImportMetaProperties(moduleRecord)`: the properties of + /// `import.meta` for `module`, as (key, value) pairs. Default: none. + fn get_import_meta_properties<'s>( + &mut self, + scope: &mut Scope<'s>, + module: &Module, + ) -> Result)>> { + let _ = (scope, module); + Ok(Vec::new()) + } + + /// `HostFinalizeImportMeta(importMeta, moduleRecord)`: last chance to change + /// the `import.meta` object. Default: nothing. + fn finalize_import_meta( + &mut self, + scope: &mut Scope<'_>, + import_meta: Local<'_>, + module: &Module, + ) -> Result<()> { + let _ = (scope, import_meta, module); + Ok(()) + } + + // ---- Promises, code from strings, and the like ------------------------ + + /// `HostPromiseRejectionTracker(promise, operation)`: a promise was + /// rejected with no handler, or got its first handler after that. It + /// cannot fail or throw; the host records what it needs. Default: nothing. + fn promise_rejection_tracker( + &mut self, + scope: &mut Scope<'_>, + promise: Local<'_>, + operation: RejectionOperation, + ) { + let _ = (scope, promise, operation); + } + + /// `HostEnsureCanCompileStrings(calleeRealm, ...)`: may `eval` and the + /// `Function` constructors compile this text in `callee`? `Err` refuses, + /// and the error is what the call throws. Default: yes. + fn ensure_can_compile_strings( + &mut self, + scope: &mut Scope<'_>, + callee: &Realm, + strings: &CompileStrings<'_>, + ) -> Result<()> { + let _ = (scope, callee, strings); + Ok(()) + } + + /// `HostHasSourceTextAvailable(func)`: may `Function.prototype.toString` + /// show the source of `function`? Default: yes. + fn has_source_text_available(&mut self, scope: &mut Scope<'_>, function: Local<'_>) -> bool { + let _ = (scope, function); + true + } + + /// `HostEnsureCanAddPrivateElement(O)`: may a private element be added to + /// `object`? `Err` refuses. Default: yes. + fn ensure_can_add_private_element( + &mut self, + scope: &mut Scope<'_>, + object: Local<'_>, + ) -> Result<()> { + let _ = (scope, object); + Ok(()) + } + + /// `HostResizeArrayBuffer(buffer, newByteLength)`. Default: + /// [`Resize::Unhandled`]. + fn resize_array_buffer( + &mut self, + scope: &mut Scope<'_>, + buffer: Local<'_>, + new_byte_length: u64, + ) -> Result { + let _ = (scope, buffer, new_byte_length); + Ok(Resize::Unhandled) + } + + // ---- What the engine needs from the world ----------------------------- + + /// The current time in milliseconds since the Unix epoch, for + /// `Date.now()` and `new Date()`. Default: the system clock. + fn now_ms(&mut self) -> f64 { + match SystemTime::now().duration_since(UNIX_EPOCH) { + Ok(d) => d.as_secs_f64() * 1000.0, + Err(_) => 0.0, + } + } + + /// The local time zone's offset from UTC in milliseconds at `time_ms` + /// (ECMA-262's `LocalTZA`). `is_utc` says whether `time_ms` is a UTC time + /// or a local one to convert back. Default: 0, that is, UTC. + fn local_tza(&mut self, time_ms: f64, is_utc: bool) -> f64 { + let _ = (time_ms, is_utc); + 0.0 + } + + /// Random bits for `Math.random`. Required, because the engine has no + /// source of its own (rule 8: no randomness dependency). It need not be + /// cryptographic. [`DefaultHost`] draws from the standard library's + /// per-process random hash keys. + fn random_u64(&mut self) -> u64; + + /// The default locale, as a BCP 47 tag, for `toLocaleString` and friends. + /// Default: `"en-US"`. + fn default_locale(&self) -> &str { + "en-US" + } + + // ---- The collector ------------------------------------------------------ + + /// Reports the JavaScript values the host keeps alive: for the browser, + /// the wrapper of every node in a document's tree, the task queues and the + /// timers. Called during every collection. See [`Tracer`]. Default: + /// nothing. + fn trace_roots(&mut self, tracer: &mut Tracer<'_>) { + let _ = tracer; + } +} + +/// A host that says nothing: every hook has its default, and the clock and +/// randomness come from the standard library. +/// +/// Test262's runner, small tools and the examples use it. A real embedder +/// supplies its own. +/// +/// ``` +/// use clazel_js::{Config, DefaultHost, Limits, Runtime}; +/// +/// fn main() -> Result<(), clazel_js::Error> { +/// let _rt = Runtime::new(Config::new(Limits::unlimited()), DefaultHost::new())?; +/// Ok(()) +/// } +/// ``` +#[derive(Debug, Default)] +pub struct DefaultHost { + draws: u64, +} + +impl DefaultHost { + /// A default host. + pub fn new() -> DefaultHost { + DefaultHost { draws: 0 } + } +} + +impl Host for DefaultHost { + fn random_u64(&mut self) -> u64 { + // A fresh `RandomState` has per-process random keys; hashing a counter + // gives different bits each call. Good enough for `Math.random`, which + // ECMA-262 does not require to be unpredictable. + self.draws = self.draws.wrapping_add(1); + RandomState::new().hash_one(self.draws) + } +} + +// The engine's own queue is reached through this one call, which the default +// hooks use and an embedder that forwards to it may too. +impl Scope<'_> { + /// Appends `job` to the engine's own job queue, the one + /// [`Runtime::run_jobs`](crate::Runtime::run_jobs) drains. What the default + /// `enqueue_*` hooks do, and what an overriding host may call to forward. + pub fn enqueue_job_internal(&mut self, job: Job) -> Result<()> { + self.push_job(job) + } + + /// Runs a job to completion. A job that throws returns the exception. + pub fn run_job(&mut self, job: Job) -> Result<()> { + // A job's root is the function to run: no arguments, `undefined` for + // `this`. Nothing in the engine makes jobs yet (no promises), so this + // serves hosts that queue their own through `Scope::function`. + let function = self.local(job.as_handle())?; + let this = self.undefined(); + self.call(function, this, &[])?; + Ok(()) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + #[cfg_attr(miri, ignore = "reads the system clock and the OS random source")] + fn default_host_answers_for_the_world() { + let mut host = DefaultHost::new(); + assert_eq!(host.local_tza(0.0, true), 0.0); + assert_eq!(host.default_locale(), "en-US"); + assert!(host.now_ms() > 1.5e12); + assert_ne!(host.random_u64(), host.random_u64()); + assert!(host.supported_import_attributes().is_empty()); + } +} diff --git a/crates/clazel-js/src/lib.rs b/crates/clazel-js/src/lib.rs new file mode 100644 index 00000000..bbf749d3 --- /dev/null +++ b/crates/clazel-js/src/lib.rs @@ -0,0 +1,51 @@ +//! The JavaScript engine's embedding API (phase-7.md item 7.8, "The engine as +//! a library"). +//! +//! **This is the contract, and its first implementation** (phase-7.md item +//! 7.8, first part), over `clazel-js-vm`'s interpreter and +//! `clazel-js-builtins`. Every type and signature is the reviewed contract; +//! what the VM does not have yet (arrays, promises, symbols, BigInt, +//! ArrayBuffer, modules, a second realm, a collector) returns +//! [`Error::NotImplemented`], and the README's "What is implemented" section +//! lists each item with its reason. The README also states the rules in prose +//! (threads, rooting, termination, what is left out) and lists the open +//! questions. The doc comments carry examples that run, except the few that +//! need what is not there yet, which stay `no_run` and say so. +//! +//! The pieces, in the order a program meets them: +//! +//! - [`Runtime`], [`Config`], [`Limits`] and [`Terminator`]: one agent, its +//! limits, and the handle that stops it from another thread. +//! - [`Scope`]: every operation, inside [`Runtime::scope`]. Its values are +//! [`Local`]s; [`Handle`], [`Weak`] and [`Member`] hold them longer. +//! - [`Realm`], [`Source`], [`Script`] and [`Module`]: code to run. +//! - [`Scope::function`], [`Args`] and [`HostObject`]: Rust inside JavaScript. +//! - [`Host`]: what ECMA-262 leaves to the embedder, and [`DefaultHost`]. +//! - [`Error`], [`Exception`] and [`ErrorReport`]: what goes wrong. +//! +//! An embedder names this crate and no other engine crate. + +mod code; +mod error; +mod host; +mod native; +mod runtime; +mod scope; +mod state; +mod value; + +pub use code::{ + ImportAttribute, LoadPayload, Module, ModuleRequest, ModuleStatus, Realm, RealmOptions, + Referrer, Script, Source, +}; +pub use error::{Error, ErrorKind, ErrorReport, Exception, Result, StackFrame}; +pub use host::{ + CompileStrings, DefaultHost, DynamicCodeKind, Host, Job, JobCallback, RejectionOperation, + Resize, +}; +pub use native::{Args, Callable, Exotic, HostObject, NativeFn, Tracer}; +pub use runtime::{Config, JitMode, Limits, Runtime, Terminator}; +pub use scope::{Resolvers, Scope}; +pub use value::{ + Handle, Key, Local, Member, PromiseState, PropertyDescriptor, ValueKind, Weak, WellKnownSymbol, +}; diff --git a/crates/clazel-js/src/native.rs b/crates/clazel-js/src/native.rs new file mode 100644 index 00000000..ca87573e --- /dev/null +++ b/crates/clazel-js/src/native.rs @@ -0,0 +1,267 @@ +//! Native functions and host objects: how Rust code becomes part of a +//! JavaScript program. + +use core::any::Any; +use core::marker::PhantomData; + +use clazel_js_heap::value::Value; + +use crate::error::Result; +use crate::scope::Scope; +use crate::value::{Key, Local, Member, PropertyDescriptor}; + +/// What a native function is called with. +/// +/// `this` and the arguments are [`Local`]s of the call's own scope, so the +/// function can use them freely and cannot keep them. A missing argument is +/// `undefined`, as for any JavaScript function. +/// +/// ``` +/// use clazel_js::{Args, Callable, Key, Local, Result, Scope}; +/// +/// /// `add(a, b)` as JavaScript sees it. +/// fn add<'s>(scope: &mut Scope<'s>, args: &Args<'s>) -> Result> { +/// let a = scope.to_number(args.get(0))?; +/// let b = scope.to_number(args.get(1))?; +/// Ok(scope.number(a + b)) +/// } +/// # let mut rt = clazel_js::Runtime::new(clazel_js::Config::new(clazel_js::Limits::unlimited()), clazel_js::DefaultHost::new())?; +/// # let sum = rt.scope(|scope| { +/// # let function = scope.function("add", 2, Callable::Function, add)?; +/// # let this = scope.undefined(); +/// # let (a, b) = (scope.number(40.0), scope.number(2.0)); +/// # let sum = scope.call(function, this, &[a, b])?; +/// # // A missing argument is `undefined`, which is NaN as a number. +/// # let missing = scope.call(function, this, &[a])?; +/// # assert!(scope.as_number(missing).is_some_and(f64::is_nan)); +/// # let _ = Key::from("unused"); +/// # Ok(scope.as_number(sum)) +/// # })?; +/// # assert_eq!(sum, Some(42.0)); +/// # Ok::<(), clazel_js::Error>(()) +/// ``` +#[derive(Clone, Copy, Debug)] +pub struct Args<'s> { + runtime: usize, + this: Value, + args: &'s [Value], + new_target: Value, +} + +impl<'s> Args<'s> { + pub(crate) fn new(runtime: usize, this: Value, args: &'s [Value], new_target: Value) -> Self { + Args { + runtime, + this, + args, + new_target, + } + } + + /// The `this` value. + pub fn this(&self) -> Local<'s> { + Local::new(self.this, self.runtime) + } + + /// How many arguments the caller passed. + pub fn len(&self) -> usize { + self.args.len() + } + + /// Whether the caller passed no arguments. + pub fn is_empty(&self) -> bool { + self.len() == 0 + } + + /// Argument `index`, or `undefined` if the caller passed fewer. + pub fn get(&self, index: usize) -> Local<'s> { + let value = self.args.get(index).copied().unwrap_or(Value::UNDEFINED); + Local::new(value, self.runtime) + } + + /// `new.target`: `Some` when the function was called with `new` (or by + /// `Reflect.construct`), and the constructor `new` was applied to, which + /// may be a subclass. `None` for an ordinary call. + pub fn new_target(&self) -> Option> { + (self.new_target != Value::UNDEFINED).then(|| Local::new(self.new_target, self.runtime)) + } +} + +/// Whether a native function can be used with `new`. +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] +pub enum Callable { + /// An ordinary function: `new` throws a `TypeError`, and + /// [`Args::new_target`] is always `None`. What WebIDL calls an operation. + #[default] + Function, + /// A constructor: `new` calls it with [`Args::new_target`] set. A call + /// without `new` is the function's own business; it can throw. What + /// WebIDL calls an interface object. + Constructor, +} + +/// A request to run a native function body on behalf of the engine. Boxed +/// closures of this shape are what [`Scope::function`] takes. +/// +/// `Fn`, not `FnMut`: a native function can be re-entered through JavaScript +/// it calls, so mutable state it needs goes in a host object, in the +/// [`Host`](crate::Host), or behind a lock, and not in the closure. `Send` +/// because the [`Runtime`](crate::Runtime) is. +pub type NativeFn = dyn for<'s> Fn(&mut Scope<'s>, &Args<'s>) -> Result> + Send; + +/// An answer from an exotic hook: do what an ordinary object does, or here is +/// the answer. +#[derive(Clone, Copy, Debug)] +pub enum Exotic { + /// No special behaviour for this key: the engine continues as for an + /// ordinary object (looking at the object's own properties, then its + /// prototype). + Ordinary, + /// The embedder's answer. + Handled(T), +} + +/// The data of a host object, and the object's special behaviour. +/// +/// A host object is a JavaScript object that carries a Rust value, which the +/// embedder owns. This is how `clazel-webidl` builds a wrapper for a DOM +/// node: the wrapper is a JavaScript object, and its data says which node. +/// +/// - **Typed.** The data's type is the slot's type. [`Scope::host_data`] and +/// [`Scope::host_data_mut`] check it and give +/// [`Error::WrongType`](crate::Error::WrongType) for any other object, so a +/// method called on the wrong `this` is a defined error and never a +/// reinterpreted pointer. +/// - **Lifetime.** The data is dropped, on the runtime's thread, when the +/// collector frees the object or the runtime is dropped. +/// - **Tracing.** If the data refers to other JavaScript values it reports +/// them from [`trace`](HostObject::trace), using [`Member`]. The default +/// reports nothing. +/// - **Exotic behaviour.** The four hooks let a host object be what WebIDL +/// calls a legacy platform object: `NodeList[0]`, `HTMLCollection.byName`, +/// `localStorage.key`. Each defaults to [`Exotic::Ordinary`], and the +/// engine checks the result against ECMA-262's invariants for the internal +/// method (a non-configurable property cannot be reported missing, and so +/// on), throwing `TypeError` if the hook breaks them. While a hook runs the +/// object's data is lent to it and taken out of the object, so another +/// access to the same data gets [`Error::Busy`](crate::Error::Busy). +/// - **Which hooks exist** is an open question in the README: these four are +/// what WebIDL §3.9 and §3.10 appear to need and the list may grow. +/// +/// The hooks are not called yet (the VM has no exotic dispatch), so this +/// example only compiles and runs its type checks: +/// +/// ``` +/// use clazel_js::{Exotic, HostObject, Key, Local, PropertyDescriptor, Result, Runtime, Scope}; +/// +/// /// The data of a `NodeList` wrapper: the ids of the nodes it holds. +/// struct NodeList { +/// nodes: Vec, +/// } +/// +/// impl HostObject for NodeList { +/// fn get_own_property<'s>( +/// &mut self, +/// scope: &mut Scope<'s>, +/// _this: Local<'s>, +/// key: Key<'_, 's>, +/// ) -> Result>>> { +/// let Key::Index(i) = key else { return Ok(Exotic::Ordinary) }; +/// let Some(id) = self.nodes.get(i as usize) else { +/// return Ok(Exotic::Handled(None)); +/// }; +/// let wrapper = scope.number(*id as f64); // a real binding makes the node's wrapper +/// Ok(Exotic::Handled(Some(PropertyDescriptor { +/// value: Some(wrapper), +/// writable: Some(false), +/// enumerable: Some(true), +/// configurable: Some(true), +/// ..PropertyDescriptor::default() +/// }))) +/// } +/// } +/// +/// fn make(rt: &mut Runtime) -> clazel_js::Result<()> { +/// rt.scope(|scope| { +/// let list = scope.new_host_object(None, NodeList { nodes: vec![1, 2] })?; +/// let n = scope.host_data::(list)?.nodes.len(); +/// assert_eq!(n, 2); +/// Ok(()) +/// }) +/// } +/// ``` +pub trait HostObject: Any + Send { + /// Reports every [`Member`] this data holds. See [`Tracer`]. + fn trace(&self, tracer: &mut Tracer<'_>) { + let _ = tracer; + } + + /// `[[GetOwnProperty]]` for `key`. + fn get_own_property<'s>( + &mut self, + scope: &mut Scope<'s>, + this: Local<'s>, + key: Key<'_, 's>, + ) -> Result>>> { + let _ = (scope, this, key); + Ok(Exotic::Ordinary) + } + + /// `[[DefineOwnProperty]]` for `key`. `Handled(true)` means it succeeded + /// and `Handled(false)` that it was refused. + fn define_own_property<'s>( + &mut self, + scope: &mut Scope<'s>, + this: Local<'s>, + key: Key<'_, 's>, + descriptor: PropertyDescriptor<'s>, + ) -> Result> { + let _ = (scope, this, key, descriptor); + Ok(Exotic::Ordinary) + } + + /// `[[Delete]]` for `key`. + fn delete_property<'s>( + &mut self, + scope: &mut Scope<'s>, + this: Local<'s>, + key: Key<'_, 's>, + ) -> Result> { + let _ = (scope, this, key); + Ok(Exotic::Ordinary) + } + + /// The extra own keys `[[OwnPropertyKeys]]` should list, which the + /// engine puts in front of the object's ordinary keys in the order + /// ECMA-262 fixes (indices first). `Handled` keys that are not strings, + /// symbols or indices are a `TypeError`. + fn own_property_keys<'s>( + &mut self, + scope: &mut Scope<'s>, + this: Local<'s>, + ) -> Result>>> { + let _ = (scope, this); + Ok(Exotic::Ordinary) + } +} + +/// The collector's marker, handed to [`HostObject::trace`] and +/// [`Host::trace_roots`](crate::Host::trace_roots). +/// +/// During a collection the engine calls each live host object's `trace`, and +/// the host's `trace_roots` once. Everything reported is treated as reachable +/// from there. Collection runs only at points the engine chooses (phase-7.md +/// item 7.6), and tracing cannot run JavaScript or allocate: the type gives it +/// no [`Scope`]. +#[derive(Debug)] +pub struct Tracer<'a> { + _collector: PhantomData<&'a mut ()>, +} + +impl Tracer<'_> { + /// Reports that the value is reachable. Reporting one twice is fine, and + /// reporting a stale one is ignored (the generation check). + pub fn mark(&mut self, member: Member) { + let _ = member; + } +} diff --git a/crates/clazel-js/src/runtime.rs b/crates/clazel-js/src/runtime.rs new file mode 100644 index 00000000..4cec6065 --- /dev/null +++ b/crates/clazel-js/src/runtime.rs @@ -0,0 +1,422 @@ +//! [`Runtime`], its [`Config`] and [`Limits`], and the [`Terminator`]. + +use core::cell::Cell; +use core::marker::PhantomData; + +use clazel_js_vm::interp::{Abrupt, Config as VmConfig, Terminator as VmTerminator, Vm}; + +use crate::error::{Error, Result}; +use crate::host::{DefaultHost, Host}; +use crate::scope::{CELL_BYTES, Scope}; +use crate::state::State; + +/// Every limit is the embedder's to set, and the engine has no default for +/// any of them (phase-7.md, "Limits and stopping"). +/// +/// A struct literal must name every field, so adding a limit later makes +/// every embedder choose a value. The numbers the browser picks are not in +/// this crate. Each limit has its own report, listed with the field. +/// +/// ``` +/// use clazel_js::Limits; +/// +/// // A test harness with limits generous enough never to matter, and one +/// // that is not: a small heap that is meant to be hit. +/// let relaxed = Limits::unlimited(); +/// let strict = Limits { +/// heap_bytes: 64 << 20, +/// ..relaxed +/// }; +/// assert_eq!(strict.heap_bytes, 64 << 20); +/// assert_eq!(strict.native_depth, relaxed.native_depth); +/// ``` +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct Limits { + /// Heap size in bytes. An allocation that would pass it first runs a full + /// collection, then throws a `RangeError` if it still would. + pub heap_bytes: u64, + /// Size of the value-stack region in bytes. Passing it throws a + /// `RangeError` ("too much recursion"). + pub value_stack_bytes: u64, + /// How many native functions may be on the call stack at once, counting + /// built-ins that call back into JavaScript such as `Array.prototype.map`. + /// Passing it throws a `RangeError`. + pub native_depth: u32, + /// Bytes of generated machine code the JIT may hold. Passing it stops + /// compiling and leaves functions to the interpreter; it is not an error. + /// Ignored when [`JitMode::Off`]. + pub code_bytes: u64, + /// Entries in the RegExp matcher's backtrack stack. Passing it throws a + /// `RangeError` from the match, rather than hanging on `(a+)+b`. + pub regexp_backtrack_entries: u64, + /// Nesting depth of the parser (source text) and of `JSON.parse`. Passing + /// it throws a `SyntaxError` for source and a `RangeError` for JSON. + pub nesting_depth: u32, +} + +impl Limits { + /// Limits that no ordinary program reaches, for tests and for a runner + /// that wants the engine's behaviour without its limits getting in the + /// way. This is a named choice, not a default: nothing in the engine + /// calls it. + pub const fn unlimited() -> Limits { + Limits { + heap_bytes: u64::MAX, + value_stack_bytes: u64::MAX, + native_depth: u32::MAX, + code_bytes: u64::MAX, + regexp_backtrack_entries: u64::MAX, + nesting_depth: u32::MAX, + } + } +} + +/// Whether the JIT is on. Only [`Off`](JitMode::Off) exists until jit.md's +/// `clazel-jit` does; then a variant carrying a `CodeMapper` is added +/// (jit.md J.0(b)): the embedder's choice of how validated code becomes +/// executable. The interpreter is complete without it. +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] +#[non_exhaustive] +pub enum JitMode { + /// Interpret only. + #[default] + Off, +} + +/// What a [`Runtime`] is built from. +/// +/// ``` +/// use clazel_js::{Config, JitMode, Limits}; +/// +/// let config = Config::new(Limits::unlimited()); +/// assert_eq!(config.jit, JitMode::Off); +/// ``` +#[derive(Clone, Copy, Debug)] +pub struct Config { + /// The limits. See [`Limits`]. + pub limits: Limits, + /// Whether to use the JIT. + pub jit: JitMode, +} + +impl Config { + /// A configuration with the given limits and the JIT off. + pub const fn new(limits: Limits) -> Config { + Config { + limits, + jit: JitMode::Off, + } + } +} + +/// A handle that stops a [`Runtime`] from another thread. +/// +/// - **How it works.** `terminate` sets a flag. The interpreter checks it at +/// loop back-edges and at calls, and JIT code checks it at the same points. +/// An evaluation that sees it ends with +/// [`Error::Terminated`](crate::Error::Terminated). +/// - **JavaScript cannot catch it.** `catch` does not run, and neither does +/// `finally`: running either would run JavaScript after being told to stop. +/// Native frames see `Err(Error::Terminated)` and must pass it on. One that +/// does not still stops at the next check, which raises it again. +/// - **It is sticky.** The flag stays set, so every later call into the same +/// `Runtime` also ends in `Terminated`, until [`Terminator::clear`] (an open +/// question in the README is whether a terminated runtime stays usable). +/// - **Cost.** The check is one relaxed atomic load. It is not a way to +/// interrupt a native function that is itself in a long loop; built-ins +/// check it too, and an embedder's native function should +/// [`Scope::check_terminated`] in a long loop. +/// - **It is the embedder's policy.** The browser still ends a stuck renderer +/// from outside, on the user's word (phase-7.md 7.0(g)), and may use this +/// later to keep the tab. +/// +/// A `Terminator` is `Clone`, `Send` and `Sync`. +/// +/// ``` +/// use std::thread; +/// use std::time::Duration; +/// use clazel_js::{Config, DefaultHost, Limits, Realm, RealmOptions, Runtime}; +/// +/// fn run_until_stopped(rt: &mut Runtime, realm: &Realm) -> bool { +/// let terminator = rt.terminator(); +/// let watchdog = thread::spawn(move || { +/// thread::sleep(Duration::from_millis(20)); +/// terminator.terminate(); +/// }); +/// let result = rt.scope(|scope| { +/// scope.eval_script(realm, clazel_js::Source::new("loop.js", "for (;;) {}"))?; +/// Ok::<(), clazel_js::Error>(()) +/// }); +/// let _ = watchdog.join(); +/// rt.terminator().clear(); +/// matches!(result, Err(clazel_js::Error::Terminated)) +/// } +/// # let mut rt = Runtime::new(Config::new(Limits::unlimited()), DefaultHost::new())?; +/// # let realm = rt.scope(|scope| scope.create_realm(RealmOptions::default()))?; +/// # assert!(run_until_stopped(&mut rt, &realm)); +/// # Ok::<(), clazel_js::Error>(()) +/// ``` +#[derive(Clone, Debug, Default)] +pub struct Terminator { + /// The interpreter's own flag, which its loop reads at back-edges and + /// calls. + flag: VmTerminator, +} + +impl Terminator { + /// Asks the runtime to stop. Safe to call from any thread, any number of + /// times. + pub fn terminate(&self) { + self.flag.terminate(); + } + + /// Whether `terminate` has been called and not cleared. + pub fn is_terminated(&self) -> bool { + self.flag.is_set() + } + + /// Lets the runtime run again. Call it after an evaluation has returned + /// `Terminated`, never while one is running. + pub fn clear(&self) { + self.flag.reset(); + } +} + +/// One ECMAScript agent: a heap, a job queue, limits and a [`Host`]. +/// +/// - **No global state.** Everything the engine knows lives in the `Runtime`, +/// with no `static` and no thread-local, so a process can hold many. +/// - **Threads.** A `Runtime` is `Send` and not `Sync`. It can move to another +/// thread between calls, and only one thread can use it at a time. The +/// browser runs one per renderer, on one thread, as phase-7.md 7.0(e) +/// decided. [`Terminator`] is the one piece usable from other threads. +/// `Host: Send` is what keeps this true, because the host lives inside. +/// - **Calls go through a scope.** [`Runtime::scope`] runs a closure with a +/// [`Scope`], and everything else is a method of that. +/// - **Dropping** frees the whole heap, runs each native closure's and host +/// object's destructor, and does not run any JavaScript (no finalizer). +/// +/// ```compile_fail +/// use clazel_js::Runtime; +/// +/// fn needs_sync() {} +/// +/// // Does not compile: a Runtime is not Sync. +/// fn check() { needs_sync::(); } +/// ``` +/// +/// The compiler gives a script no completion value yet, so `eval_script` +/// returns `undefined` and this example reads its result from a global (see +/// the README): +/// +/// ``` +/// use clazel_js::{Config, DefaultHost, Key, Limits, RealmOptions, Runtime, Source}; +/// +/// fn main() -> Result<(), clazel_js::Error> { +/// let mut rt = Runtime::new(Config::new(Limits::unlimited()), DefaultHost::new())?; +/// let realm = rt.scope(|scope| scope.create_realm(RealmOptions::default()))?; +/// let sum = rt.scope(|scope| { +/// scope.eval_script(&realm, Source::new("sum.js", "var sum = 1 + 2;"))?; +/// let global = scope.global(&realm)?; +/// let value = scope.get(global, Key::from("sum"))?; +/// Ok(scope.as_number(value)) +/// })?; +/// assert_eq!(sum, Some(3.0)); +/// rt.run_jobs()?; +/// Ok(()) +/// } +/// ``` +/// +/// A `Runtime` moves to another thread as a whole: +/// +/// ``` +/// use clazel_js::Runtime; +/// +/// fn assert_send() {} +/// fn check() { assert_send::(); } +/// check(); +/// ``` +pub struct Runtime { + limits: Limits, + terminator: Terminator, + /// The VM, with the runtime's state (and so the host) in its embedder + /// slot, see [`crate::state`]. + vm: Box, + /// What [`Runtime::host_mut`] answers with if the state is ever missing, + /// which it cannot be: the method has no way to fail. + fallback_host: DefaultHost, + // `Cell` is `Send` and not `Sync`, which is the rule. + _not_sync: PhantomData>, +} + +impl Runtime { + /// Builds a runtime. The `host` is taken for the life of the runtime; + /// reach it again with [`Runtime::host_mut`] or, from inside a native + /// function, [`Scope::host_mut`]. + /// + /// The VM and the built-ins are made here, so the one realm the VM has + /// exists at once, and [`Scope::create_realm`] hands it out (the + /// contract's "no realms" is not what a VM with one global can do). The + /// limits that have a counterpart are applied: `heap_bytes` becomes the + /// arena's cell count (an estimate of 64 bytes a cell), `value_stack_bytes` + /// the frame region's slot count (8 bytes a slot), and `native_depth` is + /// checked on every call of a closure made by [`Scope::function`]. + /// `code_bytes` (no JIT), `regexp_backtrack_entries` (no RegExp) and + /// `nesting_depth` (the parser's own fixed bound applies) are accepted + /// and not used yet. The heap limit gives [`Error::OutOfMemory`] rather + /// than a `RangeError`, since the VM cannot allocate an error object + /// when it is full and there is no collector to run first. + pub fn new(config: Config, host: impl Host) -> Result { + let limits = config.limits; + // Limits the VM has a counterpart for: its arena counts cells (an + // estimate of `CELL_BYTES` each) and its frame region counts 8-byte + // slots. The VM clamps both to what it can address. + let heap_cells = usize::try_from(limits.heap_bytes / CELL_BYTES).unwrap_or(usize::MAX); + let region_slots = usize::try_from(limits.value_stack_bytes / 8).unwrap_or(usize::MAX); + let mut vm = Vm::new(VmConfig { + region_slots, + heap_cells, + }) + .map_err(vm_failure)?; + clazel_js_builtins::install(&mut vm).map_err(vm_failure)?; + let terminator = Terminator { + flag: vm.terminator(), + }; + vm.set_embedder(State::new(Box::new(host), limits)); + Ok(Runtime { + limits, + terminator, + vm: Box::new(vm), + fallback_host: DefaultHost::new(), + _not_sync: PhantomData, + }) + } + + /// Runs `f` with a [`Scope`]. Every [`Local`](crate::Local) made inside is + /// rooted until `f` returns, and cannot leave it; what `f` returns must + /// not borrow from the scope. This is the only way in. + /// + /// `f` cannot call `scope` again, because it has no access to the + /// `Runtime`. Code that wants an inner scope uses [`Scope::nested`]. + pub fn scope(&mut self, f: impl for<'s> FnOnce(&mut Scope<'s>) -> R) -> R { + let runtime = self.runtime_id(); + let mut scope = Scope::new(&mut self.vm, runtime); + f(&mut scope) + } + + /// Runs queued jobs (promise reactions, generic jobs, finalization + /// callbacks) until the queue is empty, and returns how many ran. This is + /// a microtask checkpoint; the engine never decides when to run one. + /// + /// The queue is the engine's own unless the [`Host`] diverted it: + /// [`Host::enqueue_promise_job`] and its siblings default to appending to + /// it. A job that throws stops the run: the exception comes back as + /// `Err`, the jobs after it stay queued, and calling `run_jobs` again + /// continues with them. A [`Terminator`] stops it as it stops anything. + /// + /// ``` + /// use clazel_js::Runtime; + /// + /// fn checkpoint(rt: &mut Runtime) -> clazel_js::Result<()> { + /// // After a script returns, with the host's own tasks still to run: + /// let ran = rt.run_jobs()?; + /// println!("{ran} jobs"); + /// Ok(()) + /// } + /// # let mut rt = clazel_js::Runtime::new(clazel_js::Config::new(clazel_js::Limits::unlimited()), clazel_js::DefaultHost::new())?; + /// # checkpoint(&mut rt)?; + /// # Ok::<(), clazel_js::Error>(()) + /// ``` + pub fn run_jobs(&mut self) -> Result { + let runtime = self.runtime_id(); + let mut scope = Scope::new(&mut self.vm, runtime); + scope.check_deferred()?; + let mut ran: u64 = 0; + while let Some(job) = scope.pop_job() { + scope.run_job(job)?; + ran = ran.saturating_add(1); + } + Ok(ran) + } + + /// A handle that stops this runtime from another thread. Every call gives + /// a handle to the same flag. + pub fn terminator(&self) -> Terminator { + self.terminator.clone() + } + + /// The limits this runtime was built with. + pub fn limits(&self) -> Limits { + self.limits + } + + /// The host, between calls. Not available while a hook is running; there + /// the hook's own `&mut self` is the host. + pub fn host_mut(&mut self) -> &mut dyn Host { + match self.vm.embedder_mut::() { + Some(state) => &mut *state.host, + None => &mut self.fallback_host, + } + } + + /// Bytes the heap holds now, live and not yet swept, for the embedder's + /// own accounting and for tests of [`Limits::heap_bytes`]. + pub fn heap_used(&self) -> Result { + // An estimate: live cells at `CELL_BYTES` each. Nothing is swept yet. + let cells = u64::try_from(self.vm.heap().live()).map_err(|_| Error::OutOfMemory)?; + cells.checked_mul(CELL_BYTES).ok_or(Error::OutOfMemory) + } +} + +impl Runtime { + /// The runtime's identity, as `Local`s carry it. + fn runtime_id(&mut self) -> usize { + self.vm.embedder::().map_or(0, |state| state.id) + } +} + +/// A failure of the VM while a runtime is being built, before there is a +/// runtime state to take errors from. +fn vm_failure(abrupt: Abrupt) -> Error { + match abrupt { + Abrupt::OutOfMemory => Error::OutOfMemory, + Abrupt::Terminated => Error::Terminated, + Abrupt::Throw(_) | Abrupt::NotYet(_) | Abrupt::Internal(_) => { + Error::NotImplemented("the VM could not start with these limits") + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn is_send() {} + fn is_send_sync() {} + + #[test] + fn terminator_is_a_shared_sticky_flag() { + is_send_sync::(); + let a = Terminator::default(); + let b = a.clone(); + assert!(!a.is_terminated()); + b.terminate(); + assert!(a.is_terminated()); + b.terminate(); + assert!(a.is_terminated()); + a.clear(); + assert!(!b.is_terminated()); + } + + #[test] + fn runtime_is_send() { + is_send::(); + } + + #[test] + fn unlimited_is_the_largest_of_each() { + let l = Limits::unlimited(); + assert_eq!(l.heap_bytes, u64::MAX); + assert_eq!(l.native_depth, u32::MAX); + } +} diff --git a/crates/clazel-js/src/scope.rs b/crates/clazel-js/src/scope.rs new file mode 100644 index 00000000..6bed37a6 --- /dev/null +++ b/crates/clazel-js/src/scope.rs @@ -0,0 +1,1436 @@ +//! [`Scope`]: every operation on values, realms, code and objects. + +use core::any::Any; +use core::marker::PhantomData; +use std::sync::Arc; + +use clazel_js_builtins::object::{Descriptor, define_property_or_throw}; +use clazel_js_builtins::util; +use clazel_js_heap::shape::Attrs; +use clazel_js_heap::string::{JsString, Key as HeapKey}; +use clazel_js_heap::value::{Decoded, Value}; +use clazel_js_syntax::exec::parse; +use clazel_js_syntax::spec::SourceGoal; +use clazel_js_vm::compile::{CompileError, compile_script}; +use clazel_js_vm::heap::{HeapError, MAX_PROTO_DEPTH, ObjKind}; +use clazel_js_vm::interp::{Abrupt, Intrinsic, Vm}; + +use crate::code::{ + LoadPayload, Module, ModuleStatus, Realm, RealmOptions, Referrer, Script, Source, +}; +use crate::error::{Error, ErrorKind, ErrorReport, Exception, Result, not_implemented}; +use crate::host::Host; +use crate::native::{Args, Callable, HostObject}; +use crate::state::{State, abrupt_to_error, trampoline}; +use crate::value::{ + Handle, Key, Local, Member, PromiseState, PropertyDescriptor, ValueKind, Weak, WellKnownSymbol, +}; + +/// The resolving functions of a promise made by [`Scope::new_promise`]. +/// +/// Held by the embedder until the work the promise stands for is done: a +/// fetch finishes, a timer fires. It is two [`Handle`]s, `Send` and `Sync`, +/// and settling uses [`Scope::resolve_promise`] and [`Scope::reject_promise`] +/// on the runtime's thread. Settling twice is a no-op, as for JavaScript's own +/// resolving functions. +#[derive(Clone, Debug)] +pub struct Resolvers { + resolve: Handle, + reject: Handle, +} + +impl Resolvers { + /// The `resolve` function. + pub fn resolve_function(&self) -> &Handle { + &self.resolve + } + + /// The `reject` function. + pub fn reject_function(&self) -> &Handle { + &self.reject + } +} + +/// Where all work on a [`Runtime`](crate::Runtime) happens, and the owner of +/// the lifetime `'s` that every [`Local`] it makes carries. +/// +/// A `Scope` exists inside [`Runtime::scope`](crate::Runtime::scope), inside +/// each native function and hook (which get one for their call), and inside +/// [`Scope::nested`]. All the engine's operations are methods of it, grouped +/// below. +/// +/// - **Rooting.** Each `Local` is rooted until its scope ends. A loop that +/// makes many temporary values uses `nested` per iteration so they are not +/// all held until the end. +/// - **Collection.** The collector runs only inside an operation that +/// allocates or that the embedder asks for ([`Scope::gc`]), never between +/// two lines of the embedder's own code, so no `Local` is ever seen half +/// moved. The heap does not move objects (phase-7.md 7.0(f)). +/// - **Errors.** Operations that can run JavaScript, and so throw, return +/// `Result`. Operations that cannot (making a number, reading a kind) do not. +/// +/// There are no Arrays in the VM yet, so the list here is an ordinary object: +/// +/// ``` +/// use clazel_js::{Key, Runtime}; +/// +/// fn sum_squares(rt: &mut Runtime, n: u32) -> clazel_js::Result { +/// rt.scope(|scope| { +/// let list = scope.new_object()?; +/// for i in 0..n { +/// // Temporaries die at the end of each pass, not at the end of the call. +/// scope.nested(|inner| { +/// let x = inner.number(f64::from(i) * f64::from(i)); +/// inner.set(list, Key::Index(i), x) +/// })?; +/// } +/// let mut sum = 0.0; +/// for i in 0..n { +/// let x = scope.get(list, Key::Index(i))?; +/// sum += scope.as_number(x).unwrap_or(0.0); +/// } +/// Ok(sum) +/// }) +/// } +/// # let mut rt = clazel_js::Runtime::new(clazel_js::Config::new(clazel_js::Limits::unlimited()), clazel_js::DefaultHost::new())?; +/// # assert_eq!(sum_squares(&mut rt, 4)?, 14.0); +/// # Ok::<(), clazel_js::Error>(()) +/// ``` +#[derive(Debug)] +pub struct Scope<'s> { + /// The runtime's VM. A scope is this borrow and the runtime's identity; + /// everything else is in the VM's embedder slot (see [`crate::state`]). + vm: &'s mut Vm, + runtime: usize, + // Invariant in `'s`, so a `Local<'s>` cannot be coerced to another scope's. + _scope: PhantomData &'s ()>, +} + +/// What the heap's arena stands for in bytes, for `Limits::heap_bytes` and +/// `Runtime::heap_used`. The arena counts cells (a string, an object or an +/// environment), whose size varies, so both are estimates. +pub(crate) const CELL_BYTES: u64 = 64; + +/// A key of the property tables, an `Attrs` for methods and the like. +const METHOD_ATTRS: Attrs = Attrs(Attrs::WRITABLE | Attrs::CONFIGURABLE); + +// The machinery every operation uses. +impl<'s> Scope<'s> { + pub(crate) fn new(vm: &'s mut Vm, runtime: usize) -> Scope<'s> { + Scope { + vm, + runtime, + _scope: PhantomData, + } + } + + /// The runtime's state. + fn state(&self) -> Result<&State> { + self.vm.embedder::().ok_or(Error::WrongRuntime) + } + + /// The runtime's state, mutably. + fn state_mut(&mut self) -> Result<&mut State> { + self.vm.embedder_mut::().ok_or(Error::WrongRuntime) + } + + /// A `Local` of this scope for a value of the VM. + fn lv(&self, value: Value) -> Local<'s> { + Local::new(value, self.runtime) + } + + /// The VM's value of a `Local`, if it is of this runtime. + fn peek(&self, local: Local<'_>) -> Option { + (local.runtime() == self.runtime).then(|| local.value()) + } + + /// The VM's value of a `Local`: [`Error::WrongRuntime`] if it is another + /// runtime's. + fn val(&self, local: Local<'_>) -> Result { + self.peek(local).ok_or(Error::WrongRuntime) + } + + /// A VM operation's failure as this API's error. + fn err(&mut self, abrupt: Abrupt) -> Error { + abrupt_to_error(self.vm, abrupt) + } + + /// A VM operation's result as this API's. + fn run(&mut self, result: core::result::Result) -> Result { + result.map_err(|abrupt| self.err(abrupt)) + } + + /// A heap operation's failure as this API's error. + fn heap(&mut self, result: core::result::Result) -> Result { + result.map_err(|e| match e { + HeapError::Full | HeapError::TooLong => Error::OutOfMemory, + HeapError::Corrupt => Error::StaleHandle, + }) + } + + /// Records the error an infallible constructor could not return, for the + /// next operation that can fail to return instead. + fn defer(&mut self, error: Error) { + if let Ok(state) = self.state_mut() { + state.deferred.get_or_insert(error); + } + } + + /// Returns the error an earlier infallible constructor recorded, once. + pub(crate) fn check_deferred(&mut self) -> Result<()> { + match self.state_mut()?.deferred.take() { + Some(error) => Err(error), + None => Ok(()), + } + } + + /// Whether a reference still names a live cell (the arena's generation + /// check). Values that are not references are always alive. + fn alive(&self, value: Value) -> bool { + value.as_ref().is_none() || self.vm.heap().cell(value).is_some() + } + + fn token(&self) -> Arc<()> { + match self.state() { + Ok(state) => state.token.clone(), + Err(_) => Arc::new(()), + } + } + + /// Whether a handle's token is this runtime's. + fn owns(&self, token: &Arc<()>) -> Result<()> { + if Arc::ptr_eq(token, &self.state()?.token) { + Ok(()) + } else { + Err(Error::WrongRuntime) + } + } + + fn persist_value(&mut self, value: Value) -> Handle { + Handle::new(self.token(), value) + } + + /// An object value, or [`Error::WrongType`]. + fn object(&self, local: Local<'_>) -> Result { + let value = self.val(local)?; + if self.vm.heap().is_object(value) { + Ok(value) + } else { + Err(Error::WrongType("object")) + } + } + + /// A property key as the heap's interned key. A string key is interned, so + /// a long-lived runtime that is given endlessly new names grows its + /// interner (nothing collects it yet). + fn heap_key(&mut self, key: Key<'_, '_>) -> Result { + match key { + Key::Str(text) => { + let interned = self.vm.heap_mut().intern_str(text); + self.heap(interned) + } + Key::Index(index) => { + let interned = self.vm.heap_mut().intern_str(&index.to_string()); + self.heap(interned) + } + Key::Value(local) => { + let value = self.val(local)?; + let key = self.vm.coerce_property_key(value); + self.run(key) + } + } + } + + /// A string value from a conversion that can fail for length. + fn string_value( + &mut self, + text: core::result::Result, + ) -> Local<'s> { + let value = match text { + Ok(text) => self.vm.heap_mut().new_string(text), + Err(_) => Err(HeapError::TooLong), + }; + match value { + Ok(value) => self.lv(value), + Err(_) => { + self.defer(Error::OutOfMemory); + self.lv(Value::UNDEFINED) + } + } + } + + /// An infallible constructor of something this runtime lacks. + fn missing(&mut self, what: &'static str) -> Local<'s> { + self.defer(Error::NotImplemented(what)); + self.lv(Value::UNDEFINED) + } + + /// The realm: the VM's one global environment. + fn realm(&self) -> Realm { + Realm::new(Handle::new(self.token(), self.vm.global())) + } + + /// [`Error::WrongRuntime`] unless the realm is this runtime's. + fn check_realm(&self, realm: &Realm) -> Result<()> { + let handle = realm.as_handle(); + self.owns(handle.token())?; + if handle.value() == self.vm.global() { + Ok(()) + } else { + Err(Error::WrongRuntime) + } + } + + /// Takes the oldest job of the engine's own queue. + pub(crate) fn pop_job(&mut self) -> Option { + self.state_mut().ok()?.jobs.pop_front() + } + + /// Queues a job on the engine's own queue. + pub(crate) fn push_job(&mut self, job: crate::host::Job) -> Result<()> { + self.check_deferred()?; + self.state_mut()?.jobs.push_back(job); + Ok(()) + } +} + +impl<'s> Scope<'s> { + /// Runs `f` with an inner scope. The `Local`s `f` makes are released when + /// it returns, and cannot escape it. What `f` returns must be owned + /// (a [`Handle`], a number, an [`Exception`]); to keep a value, call + /// [`Scope::persist`] inside `f`. + pub fn nested(&mut self, f: impl for<'i> FnOnce(&mut Scope<'i>) -> R) -> R { + let runtime = self.runtime; + let mut inner = Scope::new(&mut *self.vm, runtime); + f(&mut inner) + } + + // ---- Holding values ---------------------------------------------------- + + /// Roots `value` beyond this scope. See [`Handle`]. + pub fn persist(&mut self, value: Local<'_>) -> Handle { + match self.peek(value) { + Some(value) => self.persist_value(value), + None => { + self.defer(Error::WrongRuntime); + self.persist_value(Value::UNDEFINED) + } + } + } + + /// The value a handle names, as a `Local` of this scope. + /// [`Error::WrongRuntime`] if the handle is another runtime's, + /// [`Error::StaleHandle`] if its generation does not match. + pub fn local(&mut self, handle: &Handle) -> Result> { + self.check_deferred()?; + self.owns(handle.token())?; + let value = handle.value(); + if self.alive(value) { + Ok(self.lv(value)) + } else { + Err(Error::StaleHandle) + } + } + + /// A weak reference to `value`. See [`Weak`]. + pub fn downgrade(&mut self, value: Local<'_>) -> Weak { + match self.peek(value) { + Some(value) => Weak::new(self.token(), value), + None => { + self.defer(Error::WrongRuntime); + Weak::new(self.token(), Value::UNDEFINED) + } + } + } + + /// The value, if it is still alive. `Ok(None)` once it has been collected. + pub fn upgrade(&mut self, weak: &Weak) -> Result>> { + self.check_deferred()?; + self.owns(weak.token())?; + let value = weak.value(); + Ok(self.alive(value).then(|| self.lv(value))) + } + + /// A [`Member`] for `value`, to store in a host object's data and report + /// from its `trace`. + pub fn member(&mut self, value: Local<'_>) -> Member { + match self.peek(value) { + Some(value) => Member::new(value, self.runtime), + None => { + self.defer(Error::WrongRuntime); + Member::new(Value::UNDEFINED, self.runtime) + } + } + } + + /// The value a member names. [`Error::StaleHandle`] if the owner did not + /// report it and it has been collected. + pub fn local_from_member(&mut self, member: Member) -> Result> { + self.check_deferred()?; + if member.runtime() != self.runtime { + return Err(Error::WrongRuntime); + } + let value = member.value(); + if self.alive(value) { + Ok(self.lv(value)) + } else { + Err(Error::StaleHandle) + } + } + + // ---- Making and reading primitive values ----------------------------- + + /// `undefined`. + pub fn undefined(&mut self) -> Local<'s> { + self.lv(Value::UNDEFINED) + } + + /// `null`. + pub fn null(&mut self) -> Local<'s> { + self.lv(Value::NULL) + } + + /// A Boolean. + pub fn boolean(&mut self, value: bool) -> Local<'s> { + self.lv(Value::boolean(value)) + } + + /// A Number. NaN is canonicalized, as the value encoding requires. + pub fn number(&mut self, value: f64) -> Local<'s> { + self.lv(util::number(value)) + } + + /// A String from Rust text. + pub fn string(&mut self, value: &str) -> Local<'s> { + self.string_value(JsString::from_rust_str(value)) + } + + /// A String from UTF-16 code units, which may hold lone surrogates that a + /// Rust `&str` cannot. This is the exact form JavaScript strings take, + /// and what WebIDL's `DOMString` and `USVString` conversions start from. + pub fn string_utf16(&mut self, units: &[u16]) -> Local<'s> { + self.string_value(JsString::from_units(units)) + } + + /// A BigInt from an `i64`. + pub fn bigint_from_i64(&mut self, value: i64) -> Local<'s> { + let _ = value; + self.missing("Scope::bigint_from_i64: the VM has no BigInt yet") + } + + /// A BigInt from a `u64`. + pub fn bigint_from_u64(&mut self, value: u64) -> Local<'s> { + let _ = value; + self.missing("Scope::bigint_from_u64: the VM has no BigInt yet") + } + + /// A new unique Symbol with an optional description. + pub fn new_symbol(&mut self, description: Option<&str>) -> Local<'s> { + let _ = description; + self.missing("Scope::new_symbol: the VM has no Symbols yet") + } + + /// A well-known symbol. The same symbol in every call and every realm of + /// this runtime, as ECMA-262 says. + pub fn well_known_symbol(&mut self, symbol: WellKnownSymbol) -> Local<'s> { + let _ = symbol; + self.missing("Scope::well_known_symbol: the VM has no Symbols yet") + } + + /// What kind of value this is. Never throws and never runs JavaScript. + pub fn kind(&self, value: Local<'_>) -> ValueKind { + let Some(v) = self.peek(value) else { + return ValueKind::Undefined; + }; + let heap = self.vm.heap(); + match v.decode() { + Decoded::Null => ValueKind::Null, + Decoded::Bool(_) => ValueKind::Boolean, + Decoded::Int32(_) | Decoded::Double(_) => ValueKind::Number, + Decoded::Ref(_) if heap.is_string(v) => ValueKind::String, + Decoded::Ref(_) if heap.is_callable(v) => ValueKind::Function, + Decoded::Ref(_) if heap.is_object(v) => ValueKind::Object, + _ => ValueKind::Undefined, + } + } + + /// The Boolean, or `None` if the value is not one. + pub fn as_boolean(&self, value: Local<'_>) -> Option { + match self.peek(value)?.decode() { + Decoded::Bool(b) => Some(b), + _ => None, + } + } + + /// The Number, or `None` if the value is not one. + pub fn as_number(&self, value: Local<'_>) -> Option { + util::as_number(self.peek(value)?) + } + + /// A String's UTF-16 code units, exactly. `Err(WrongType)` for a + /// non-string. + pub fn string_to_utf16(&self, value: Local<'_>) -> Result> { + let v = self.val(value)?; + let text = self.vm.heap().string(v).ok_or(Error::WrongType("string"))?; + Ok(text.units().collect()) + } + + /// A String as Rust text, with each lone surrogate replaced by U+FFFD. + /// `Err(WrongType)` for a non-string. + pub fn string_to_string_lossy(&self, value: Local<'_>) -> Result { + let v = self.val(value)?; + let text = self.vm.heap().string(v).ok_or(Error::WrongType("string"))?; + Ok(text.to_string_lossy()) + } + + // ---- Conversions and tests (what WebIDL's conversions are built from) -- + + /// `ToBoolean`. Cannot throw. + pub fn to_boolean(&mut self, value: Local<'_>) -> bool { + match self.peek(value) { + Some(v) => self.vm.to_boolean(v), + None => { + self.defer(Error::WrongRuntime); + false + } + } + } + + /// `ToNumber`. Can throw: a Symbol, a BigInt, or an object whose + /// `valueOf` throws. + pub fn to_number(&mut self, value: Local<'_>) -> Result { + self.check_deferred()?; + let v = self.val(value)?; + let n = self.vm.to_number(v); + self.run(n) + } + + /// `ToString`, as a String value. Can throw. + pub fn to_string(&mut self, value: Local<'_>) -> Result> { + self.check_deferred()?; + let v = self.val(value)?; + if self.vm.heap().is_string(v) { + return Ok(self.lv(v)); + } + let text = self.vm.to_js_string(v); + let text = self.run(text)?; + let made = self.vm.heap_mut().new_string(text); + let made = self.heap(made)?; + Ok(self.lv(made)) + } + + /// `ToObject`. Throws a `TypeError` for `undefined` and `null`. + pub fn to_object(&mut self, value: Local<'_>) -> Result> { + self.check_deferred()?; + let v = self.val(value)?; + let o = self.vm.to_object(v); + let o = self.run(o)?; + Ok(self.lv(o)) + } + + /// `IsCallable`. + pub fn is_callable(&self, value: Local<'_>) -> bool { + self.peek(value) + .is_some_and(|v| self.vm.heap().is_callable(v)) + } + + /// `IsConstructor`. + pub fn is_constructor(&self, value: Local<'_>) -> bool { + self.peek(value).is_some_and(|v| self.vm.is_constructor(v)) + } + + /// `IsArray`. Throws for a revoked proxy. + pub fn is_array(&mut self, value: Local<'_>) -> Result { + // The VM has no Array objects yet, so no value is one. + self.check_deferred()?; + self.val(value)?; + Ok(false) + } + + /// `IsStrictlyEqual` (`===`). + pub fn strict_equals(&self, a: Local<'_>, b: Local<'_>) -> bool { + let (Some(x), Some(y)) = (self.peek(a), self.peek(b)) else { + return false; + }; + if let (Some(x), Some(y)) = (util::as_number(x), util::as_number(y)) { + return x == y; + } + let heap = self.vm.heap(); + if let (Some(x), Some(y)) = (heap.string(x), heap.string(y)) { + return x == y; + } + x == y + } + + /// `SameValue` (`Object.is`). + pub fn same_value(&self, a: Local<'_>, b: Local<'_>) -> bool { + match (self.peek(a), self.peek(b)) { + (Some(x), Some(y)) => util::same_value(self.vm, x, y), + _ => false, + } + } + + /// `InstanceofOperator` (`value instanceof constructor`). Can throw. + pub fn instance_of(&mut self, value: Local<'_>, constructor: Local<'_>) -> Result { + // InstanceofOperator (§13.10.2) without step 2 (`@@hasInstance`, there + // are no Symbols yet): step 3 is IsCallable, step 4 OrdinaryHasInstance. + self.check_deferred()?; + let v = self.val(value)?; + let c = self.val(constructor)?; + if !self.vm.heap().is_object(c) { + let e = self + .vm + .type_error("Right-hand side of 'instanceof' is not an object"); + return Err(self.err(e)); + } + if !self.vm.heap().is_callable(c) { + let e = self + .vm + .type_error("Right-hand side of 'instanceof' is not callable"); + return Err(self.err(e)); + } + if matches!( + self.vm.heap().obj(c).map(|o| o.kind), + Some(ObjKind::Bound(_)) + ) { + return Err(Error::NotImplemented( + "Scope::instance_of with a bound function: its target is not readable yet", + )); + } + if !self.vm.heap().is_object(v) { + return Ok(false); + } + let key = self.heap_key(Key::Str("prototype"))?; + let proto = self.vm.get_value(c, key); + let proto = self.run(proto)?; + if !self.vm.heap().is_object(proto) { + let e = self + .vm + .type_error("Function has non-object prototype in instanceof check"); + return Err(self.err(e)); + } + let mut current = v; + for _ in 0..MAX_PROTO_DEPTH { + current = self.vm.heap().proto_of(current).unwrap_or(Value::NULL); + if current == Value::NULL || !self.vm.heap().is_object(current) { + return Ok(false); + } + if current == proto { + return Ok(true); + } + } + Err(Error::StaleHandle) + } + + // ---- Objects ------------------------------------------------------------ + + /// A new ordinary object, as `{}` in the current realm. + pub fn new_object(&mut self) -> Result> { + self.check_deferred()?; + let o = self.vm.new_object(); + let o = self.run(o)?; + Ok(self.lv(o)) + } + + /// A new Array of the given length, as `new Array(length)`. + pub fn new_array(&mut self, length: u32) -> Result> { + let _ = length; + not_implemented!("Scope::new_array: the VM has no Array objects yet") + } + + /// A new Array holding these values. + pub fn new_array_from(&mut self, elements: &[Local<'_>]) -> Result> { + let _ = elements; + not_implemented!("Scope::new_array_from: the VM has no Array objects yet") + } + + /// `Get(object, key)`. Runs getters and proxy traps, so can throw. + pub fn get(&mut self, object: Local<'_>, key: Key<'_, '_>) -> Result> { + self.check_deferred()?; + let o = self.val(object)?; + let k = self.heap_key(key)?; + let v = self.vm.get_value(o, k); + let v = self.run(v)?; + Ok(self.lv(v)) + } + + /// `Set(object, key, value, true)`: throws in the cases strict-mode + /// assignment throws (a read-only property, a frozen object). + pub fn set(&mut self, object: Local<'_>, key: Key<'_, '_>, value: Local<'_>) -> Result<()> { + self.check_deferred()?; + let o = self.object(object)?; + let v = self.val(value)?; + let k = self.heap_key(key)?; + let done = self.vm.put_value(o, k, v, true); + self.run(done) + } + + /// `HasProperty` (`key in object`). + pub fn has_property(&mut self, object: Local<'_>, key: Key<'_, '_>) -> Result { + self.check_deferred()?; + let o = self.object(object)?; + let k = self.heap_key(key)?; + let found = util::has_property(self.vm, o, k); + let found = self.run(found)?; + Ok(found) + } + + /// `DeletePropertyOrThrow`, but returning `false` for a refusal instead of + /// throwing, as sloppy-mode `delete` does. + pub fn delete_property(&mut self, object: Local<'_>, key: Key<'_, '_>) -> Result { + let _ = (object, key); + not_implemented!("Scope::delete_property: the heap cannot remove a property yet") + } + + /// `DefinePropertyOrThrow`: `Object.defineProperty`. + pub fn define_property( + &mut self, + object: Local<'_>, + key: Key<'_, '_>, + descriptor: PropertyDescriptor<'_>, + ) -> Result<()> { + self.check_deferred()?; + let o = self.object(object)?; + if descriptor.get.is_some() || descriptor.set.is_some() { + return Err(Error::NotImplemented( + "Scope::define_property with an accessor: the heap has no accessor properties yet", + )); + } + let k = self.heap_key(key)?; + let value = match descriptor.value { + Some(v) => Some(self.val(v)?), + None => None, + }; + let desc = Descriptor { + value, + writable: descriptor.writable, + enumerable: descriptor.enumerable, + configurable: descriptor.configurable, + }; + let done = define_property_or_throw(self.vm, o, k, &desc); + self.run(done) + } + + /// `GetPrototypeOf`. `null` is returned as the `null` value. + pub fn get_prototype_of(&mut self, object: Local<'_>) -> Result> { + self.check_deferred()?; + let o = self.object(object)?; + let proto = self.vm.heap().proto_of(o).unwrap_or(Value::NULL); + Ok(self.lv(proto)) + } + + /// `SetPrototypeOf`: throws if the object refuses (not extensible, or a + /// cycle). + pub fn set_prototype_of(&mut self, object: Local<'_>, prototype: Local<'_>) -> Result<()> { + // OrdinarySetPrototypeOf (§10.1.2.1): an object is always extensible + // here, so only the cycle check (step 8) can refuse. + self.check_deferred()?; + let o = self.object(object)?; + let p = self.val(prototype)?; + if p != Value::NULL && !self.vm.heap().is_object(p) { + let e = self + .vm + .type_error("Object prototype may only be an Object or null"); + return Err(self.err(e)); + } + let mut walk = p; + for _ in 0..MAX_PROTO_DEPTH { + if walk == Value::NULL { + let done = self.vm.heap_mut().set_proto(o, p); + return self.heap(done); + } + if walk == o { + let e = self.vm.type_error("Cyclic prototype value"); + return Err(self.err(e)); + } + walk = self.vm.heap().proto_of(walk).unwrap_or(Value::NULL); + } + Err(Error::StaleHandle) + } + + /// `GetMethod(value, key)`: `Ok(None)` if the property is `undefined` or + /// `null`, a `TypeError` if it is anything else but callable. + pub fn get_method(&mut self, value: Local<'_>, key: Key<'_, '_>) -> Result>> { + let f = self.get(value, key)?; + let v = self.val(f)?; + if v == Value::UNDEFINED || v == Value::NULL { + return Ok(None); + } + if self.vm.heap().is_callable(v) { + return Ok(Some(f)); + } + let e = self.vm.type_error("property is not a function"); + Err(self.err(e)) + } + + /// `Call(function, this, arguments)`. + pub fn call( + &mut self, + function: Local<'_>, + this: Local<'_>, + arguments: &[Local<'_>], + ) -> Result> { + self.check_deferred()?; + let f = self.val(function)?; + let t = self.val(this)?; + let mut args = Vec::with_capacity(arguments.len()); + for a in arguments { + args.push(self.val(*a)?); + } + let r = self.vm.call(f, t, &args); + let r = self.run(r)?; + Ok(self.lv(r)) + } + + /// `Construct(constructor, arguments, newTarget)`; `new_target` of `None` + /// is the constructor itself. + pub fn construct( + &mut self, + constructor: Local<'_>, + arguments: &[Local<'_>], + new_target: Option>, + ) -> Result> { + self.check_deferred()?; + let c = self.val(constructor)?; + if let Some(nt) = new_target + && self.val(nt)? != c + { + return Err(Error::NotImplemented( + "Scope::construct with a new_target other than the constructor", + )); + } + let mut args = Vec::with_capacity(arguments.len()); + for a in arguments { + args.push(self.val(*a)?); + } + let r = self.vm.construct_value(c, &args); + let r = self.run(r)?; + Ok(self.lv(r)) + } + + /// Runs the iterator protocol over `iterable`, calling `f` with each value + /// until it returns `Ok(false)` or the iterator ends. If `f` returns `Err`, + /// or `Ok(false)`, the iterator is closed (`IteratorClose`) first. This is + /// the operation WebIDL's `sequence` and `iterable` conversions need. + /// + /// This stays `no_run`: `iterate` returns `NotImplemented` until the VM + /// has Symbols and iterators. + /// + /// ```no_run + /// use clazel_js::Runtime; + /// + /// fn count(rt: &mut Runtime, iterable: &clazel_js::Handle) -> clazel_js::Result { + /// rt.scope(|scope| { + /// let iterable = scope.local(iterable)?; + /// let mut n = 0; + /// scope.iterate(iterable, |_scope, _item| { + /// n += 1; + /// Ok(true) + /// })?; + /// Ok(n) + /// }) + /// } + /// ``` + pub fn iterate( + &mut self, + iterable: Local<'_>, + f: impl for<'i> FnMut(&mut Scope<'i>, Local<'i>) -> Result, + ) -> Result<()> { + let _ = (iterable, f); + not_implemented!("Scope::iterate: the VM has no iteration protocol or Symbols yet") + } + + // ---- Native functions and host objects ------------------------------------ + + /// A JavaScript function that runs `f`. + /// + /// `name` and `length` are the function's `name` and `length`. `callable` + /// says whether `new` works on it. `f` gets a fresh scope for the call, + /// the arguments, and returns the result or an [`Error`]. Panics in `f` + /// are not caught: the lints forbid them in this repository, and an + /// embedder that panics gets its own panic. + /// + /// **Re-entrance, not yet:** `f` is `Fn` so that JavaScript can call it + /// again while it runs, but the closures live inside the VM that `f` + /// borrows, so the running closure is out of its table: a call that + /// reaches the same function again gets [`Error::Busy`] (which JavaScript + /// cannot catch). Different functions nest freely. Supporting the same + /// one needs `f: Sync`, see the README's open questions. + /// + /// ``` + /// use clazel_js::{Args, Callable, Key, Local, Result, Runtime, Scope, Source}; + /// + /// fn install(rt: &mut Runtime, realm: &clazel_js::Realm) -> Result<()> { + /// rt.scope(|scope| { + /// let global = scope.global(realm)?; + /// let greet = scope.function("greet", 1, Callable::Function, |scope, args| { + /// let who = scope.to_string(args.get(0))?; + /// let who = scope.string_to_string_lossy(who)?; + /// Ok(scope.string(&format!("hello, {who}"))) + /// })?; + /// scope.set(global, Key::from("greet"), greet) + /// }) + /// } + /// # let mut rt = clazel_js::Runtime::new(clazel_js::Config::new(clazel_js::Limits::unlimited()), clazel_js::DefaultHost::new())?; + /// # let realm = rt.scope(|scope| scope.create_realm(clazel_js::RealmOptions::default()))?; + /// # install(&mut rt, &realm)?; + /// # let text = rt.scope(|scope| { + /// # scope.eval_script(&realm, Source::new("g.js", "var said = greet('world');"))?; + /// # let global = scope.global(&realm)?; + /// # let said = scope.get(global, Key::from("said"))?; + /// # scope.string_to_string_lossy(said) + /// # })?; + /// # assert_eq!(text, "hello, world"); + /// # Ok::<(), clazel_js::Error>(()) + /// ``` + pub fn function( + &mut self, + name: &str, + length: u32, + callable: Callable, + f: impl for<'a> Fn(&mut Scope<'a>, &Args<'a>) -> Result> + Send + 'static, + ) -> Result> { + self.check_deferred()?; + let length = i32::try_from(length).unwrap_or(i32::MAX); + let made = match callable { + Callable::Function => self.vm.new_native(name, length, trampoline), + Callable::Constructor => self.vm.new_native_constructor(name, length, trampoline), + }; + let function = self.run(made)?; + let boxed: Box = Box::new(f); + self.state_mut()? + .natives + .insert(function.bits(), Some(boxed)); + Ok(self.lv(function)) + } + + /// Makes a function with [`Scope::function`] and defines it as a method + /// of `object`: writable, non-enumerable, configurable, as WebIDL + /// operations and built-in methods are. + pub fn define_method( + &mut self, + object: Local<'_>, + name: &str, + length: u32, + f: impl for<'a> Fn(&mut Scope<'a>, &Args<'a>) -> Result> + Send + 'static, + ) -> Result<()> { + self.check_deferred()?; + let o = self.object(object)?; + let function = self.function(name, length, Callable::Function, f)?; + let k = self.heap_key(Key::Str(name))?; + let v = self.val(function)?; + let done = self.vm.heap_mut().define(o, k, v, METHOD_ATTRS); + self.heap(done) + } + + /// A new host object carrying `data`, with this prototype (`None` is + /// `null`). See [`HostObject`]. + pub fn new_host_object( + &mut self, + prototype: Option>, + data: impl HostObject, + ) -> Result> { + self.check_deferred()?; + let proto = match prototype { + Some(p) => { + let p = self.val(p)?; + if p != Value::NULL && !self.vm.heap().is_object(p) { + return Err(Error::WrongType("object or null")); + } + p + } + None => Value::NULL, + }; + let made = self.vm.heap_mut().new_object(proto, ObjKind::Plain); + let object = self.heap(made)?; + self.state_mut()? + .host_objects + .insert(object.bits(), Box::new(data)); + Ok(self.lv(object)) + } + + /// The data of a host object of type `T`. [`Error::WrongType`] if the + /// value is anything else (another type of host object included), and + /// [`Error::Busy`] if one of its own hooks is running. + pub fn host_data(&self, object: Local<'_>) -> Result<&T> { + let o = self.val(object)?; + let data = self + .state()? + .host_objects + .get(&o.bits()) + .ok_or(Error::WrongType("a host object"))?; + let data: &dyn Any = &**data; + data.downcast_ref::() + .ok_or(Error::WrongType("a host object of the requested type")) + } + + /// As [`Scope::host_data`], mutably. + pub fn host_data_mut(&mut self, object: Local<'_>) -> Result<&mut T> { + let o = self.val(object)?; + let data = self + .state_mut()? + .host_objects + .get_mut(&o.bits()) + .ok_or(Error::WrongType("a host object"))?; + let data: &mut dyn Any = &mut **data; + data.downcast_mut::() + .ok_or(Error::WrongType("a host object of the requested type")) + } + + /// `GetPrototypeFromConstructor(newTarget, ...)`: the `prototype` of + /// `new_target` if it is an object, else `fallback`. A constructor that + /// makes a host object calls this with its [`Args::new_target`] so that a + /// subclass (`class X extends Node`) gets its own prototype. + pub fn get_prototype_from_constructor( + &mut self, + new_target: Local<'_>, + fallback: Local<'_>, + ) -> Result> { + self.check_deferred()?; + let nt = self.val(new_target)?; + let fb = self.val(fallback)?; + if self.vm.heap().is_object(nt) { + let key = self.heap_key(Key::Str("prototype"))?; + let proto = self.vm.get_value(nt, key); + let proto = self.run(proto)?; + if self.vm.heap().is_object(proto) { + return Ok(self.lv(proto)); + } + } + Ok(self.lv(fb)) + } + + /// The embedder's [`Host`] as its own type. [`Error::WrongType`] if the + /// host is another type, and [`Error::Busy`] while a hook of the host is + /// running (the hook already has the host as `&mut self`). + pub fn host_mut(&mut self) -> Result<&mut H> { + let host: &mut dyn Any = &mut *self.state_mut()?.host; + host.downcast_mut::() + .ok_or(Error::WrongType("the host's type")) + } + + /// For a native function: ends the call with [`Error::Terminated`] if a + /// [`Terminator`](crate::Terminator) has been used. Call it in any native + /// loop that can run long. + pub fn check_terminated(&self) -> Result<()> { + if self.vm.terminator().is_set() { + Err(Error::Terminated) + } else { + Ok(()) + } + } + + // ---- Errors --------------------------------------------------------------- + + /// A new error object of `kind` with `message`, as an [`Exception`] ready to + /// throw or to refuse a module load with. + pub fn new_exception(&mut self, kind: ErrorKind, message: &str) -> Result { + self.check_deferred()?; + let which = match kind { + ErrorKind::Error => Intrinsic::ErrorPrototype, + ErrorKind::RangeError => Intrinsic::RangeErrorPrototype, + ErrorKind::ReferenceError => Intrinsic::ReferenceErrorPrototype, + ErrorKind::SyntaxError => Intrinsic::SyntaxErrorPrototype, + ErrorKind::TypeError => Intrinsic::TypeErrorPrototype, + ErrorKind::EvalError | ErrorKind::UriError => { + return Err(Error::NotImplemented( + "Scope::new_exception for EvalError and URIError: the built-ins have no such constructor yet", + )); + } + }; + // §20.5.6.1.1 NativeError ( message ), steps 2 to 4: `[[ErrorData]]`, + // the intrinsic prototype and an own, non-enumerable `message`. + let proto = self.vm.intrinsic(which); + let made = self.vm.heap_mut().new_object(proto, ObjKind::Error); + let object = self.heap(made)?; + let text = JsString::from_rust_str(message).map_err(|_| Error::OutOfMemory)?; + let text = self.vm.heap_mut().new_string(text); + let text = self.heap(text)?; + let k = self.heap_key(Key::Str("message"))?; + let done = self.vm.heap_mut().define(object, k, text, METHOD_ATTRS); + self.heap(done)?; + Ok(Exception::from_handle(self.persist_value(object))) + } + + /// The `Err` for throwing a new error: `return Err(scope.throw_error(...))`. + /// If creating the error object itself fails, that failure is returned. + pub fn throw_error(&mut self, kind: ErrorKind, message: &str) -> Error { + match self.new_exception(kind, message) { + Ok(exception) => Error::Thrown(exception), + Err(other) => other, + } + } + + /// The `Err` for throwing any value, for example a `DOMException` the + /// embedder made. + pub fn throw(&mut self, value: Local<'_>) -> Error { + Error::Thrown(Exception::from_handle(self.persist(value))) + } + + /// The value inside an exception, as a `Local` of this scope. + pub fn exception_value(&mut self, exception: &Exception) -> Result> { + self.local(exception.value()) + } + + /// Describes a thrown value. See [`ErrorReport`]. Reads `name`, `message` + /// and `stack` as data properties and does not call getters, so it cannot + /// run JavaScript or throw. + pub fn report(&mut self, exception: &Exception) -> Result { + let value = self.exception_value(exception)?; + let v = self.val(value)?; + if self.vm.heap().is_object(v) { + // Data properties only: there are no accessors to run, and + // `get_named` runs no JavaScript. + let name = self.vm.get_named(v, "name"); + let name = self.run(name)?; + let message = self.vm.get_named(v, "message"); + let message = self.run(message)?; + return Ok(ErrorReport { + name: self.vm.string_text(name).unwrap_or_default(), + message: self.vm.string_text(message).unwrap_or_default(), + // The VM keeps no stack of source positions yet. + stack: Vec::new(), + }); + } + // A primitive (a Symbol is the only one ToString can throw on, and + // there are none). + let text = self.vm.to_js_string(v); + let text = self.run(text)?; + Ok(ErrorReport { + name: String::new(), + message: text.to_string_lossy(), + stack: Vec::new(), + }) + } + + // ---- Promises --------------------------------------------------------------- + + /// A new pending promise and its resolving functions. For an API that + /// returns a promise and settles it later (`fetch`). + /// + /// This stays `no_run`: promises return `NotImplemented` until the VM has + /// them. + /// + /// ```no_run + /// use clazel_js::{Handle, Resolvers, Runtime}; + /// + /// // `fetch()` returns the promise now and keeps the resolvers for later. + /// fn start_fetch(rt: &mut Runtime) -> clazel_js::Result<(Handle, Resolvers)> { + /// rt.scope(|scope| { + /// let (promise, resolvers) = scope.new_promise()?; + /// Ok((scope.persist(promise), resolvers)) + /// }) + /// } + /// + /// // The kernel answered; settle it, then let the reactions run. + /// fn finish_fetch(rt: &mut Runtime, resolvers: &Resolvers) -> clazel_js::Result<()> { + /// rt.scope(|scope| { + /// let response = scope.new_object()?; + /// scope.resolve_promise(resolvers, response) + /// })?; + /// rt.run_jobs()?; + /// Ok(()) + /// } + /// ``` + pub fn new_promise(&mut self) -> Result<(Local<'s>, Resolvers)> { + not_implemented!("Scope::new_promise: the VM has no Promise objects yet") + } + + /// Calls the promise's `resolve` with `value`. If the value is a thenable + /// the promise follows it, as for any resolve. + pub fn resolve_promise(&mut self, resolvers: &Resolvers, value: Local<'_>) -> Result<()> { + let _ = (resolvers, value); + not_implemented!("Scope::resolve_promise: the VM has no Promise objects yet") + } + + /// Calls the promise's `reject` with `reason`. + pub fn reject_promise(&mut self, resolvers: &Resolvers, reason: Local<'_>) -> Result<()> { + let _ = (resolvers, reason); + not_implemented!("Scope::reject_promise: the VM has no Promise objects yet") + } + + /// `Promise.resolve(value)` in the current realm. + pub fn promise_resolve(&mut self, value: Local<'_>) -> Result> { + let _ = value; + not_implemented!("Scope::promise_resolve: the VM has no Promise objects yet") + } + + /// `PerformPromiseThen` on `promise` with these reactions (each a function + /// or `None`), returning the derived promise. This is how the embedder + /// continues after a promise it did not make, such as the one + /// [`Scope::evaluate_module`] returns. + pub fn promise_then( + &mut self, + promise: Local<'_>, + on_fulfilled: Option>, + on_rejected: Option>, + ) -> Result> { + let _ = (promise, on_fulfilled, on_rejected); + not_implemented!("Scope::promise_then: the VM has no Promise objects yet") + } + + /// A promise's state now. Reading it never marks a rejection handled. + pub fn promise_state(&self, promise: Local<'_>) -> Result> { + let _ = promise; + not_implemented!("Scope::promise_state: the VM has no Promise objects yet") + } + + // ---- ArrayBuffers ------------------------------------------------------------ + + /// A new `ArrayBuffer` that owns `bytes`. + pub fn new_array_buffer(&mut self, bytes: Vec) -> Result> { + let _ = bytes; + not_implemented!("Scope::new_array_buffer: the VM has no ArrayBuffer yet") + } + + /// An `ArrayBuffer`'s bytes. Empty for a detached one. The borrow ends + /// before any call that can run JavaScript, which could detach or resize it. + pub fn array_buffer_bytes(&self, buffer: Local<'_>) -> Result<&[u8]> { + let _ = buffer; + not_implemented!("Scope::array_buffer_bytes: the VM has no ArrayBuffer yet") + } + + /// `DetachArrayBuffer(buffer, key)`: after it the buffer has length 0. + /// `key` must be the `ArrayBuffer`'s detach key if it has one, else a + /// `TypeError`. This is Test262's `$262.detachArrayBuffer`, and what + /// `postMessage` transfers and `structuredClone` use later. + pub fn detach_array_buffer(&mut self, buffer: Local<'_>, key: Option>) -> Result<()> { + let _ = (buffer, key); + not_implemented!("Scope::detach_array_buffer: the VM has no ArrayBuffer yet") + } + + // ---- Realms --------------------------------------------------------------------- + + /// `CreateRealm` plus `SetDefaultGlobalBindings`: a new realm with its own + /// built-ins. This is `$262.createRealm`. + /// + /// **Not yet:** the VM has one global environment, and + /// [`Runtime::new`](crate::Runtime::new) has already installed the + /// built-ins in it. The first call returns that realm and a second is + /// [`Error::NotImplemented`]; so is `RealmOptions::global`. + pub fn create_realm(&mut self, options: RealmOptions) -> Result { + self.check_deferred()?; + if options.global.is_some() { + return Err(Error::NotImplemented( + "Scope::create_realm with RealmOptions::global: the VM's global is an ordinary object", + )); + } + let state = self.state_mut()?; + if state.realm_made { + return Err(Error::NotImplemented( + "a second realm: a VM has one global environment", + )); + } + state.realm_made = true; + Ok(self.realm()) + } + + /// The realm of the function being run. Inside a native function, the + /// function's own realm; inside a hook, the realm of the code that + /// triggered it, if there is one. + pub fn current_realm(&mut self) -> Result { + self.check_deferred()?; + Ok(self.realm()) + } + + /// The realm's global object. Add properties to it with [`Scope::set`] and + /// [`Scope::define_property`]; that is how an embedder installs `console` + /// or `window`. + pub fn global(&mut self, realm: &Realm) -> Result> { + self.check_deferred()?; + self.check_realm(realm)?; + Ok(self.lv(self.vm.global())) + } + + /// Attaches the embedder's data to a realm (HTML's environment settings + /// object), replacing what was there. + pub fn set_realm_host_defined( + &mut self, + realm: &Realm, + data: Box, + ) -> Result<()> { + self.check_realm(realm)?; + self.state_mut()?.realm_host_defined = Some(data); + Ok(()) + } + + /// The data attached with [`Scope::set_realm_host_defined`]. + pub fn realm_host_defined(&self, realm: &Realm) -> Result> { + self.check_realm(realm)?; + Ok(self.state()?.realm_host_defined.as_deref()) + } + + // ---- Scripts and modules ------------------------------------------------------------ + + /// `ParseScript`: compiles `source`. A syntax error is + /// [`Error::Thrown`] holding a `SyntaxError` of `realm`. + pub fn compile_script(&mut self, realm: &Realm, source: Source<'_>) -> Result