Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
425 changes: 208 additions & 217 deletions Cargo.standalone.lock

Large diffs are not rendered by default.

11 changes: 10 additions & 1 deletion Cargo.standalone.toml
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,12 @@ edition = "2024"
license = "MIT"
resolver = "2"

[package.metadata.napi]
# The pinned public Wasmer SDK predates LinearMemory::do_wait_interruptible.
# build.rs uses this marker so the compatibility path cannot be changed by
# --no-default-features or --all-features.
standalone_legacy_wait = true

[features]
js = [
"dep:js-sys",
Expand Down Expand Up @@ -33,7 +39,9 @@ cli = [
anyhow = "1"
# Standalone builds use one immutable Wasmer source revision. The N-API
# instantiation hook and shared-memory bridge are developed together on the SDK
# branch, so mixing this source with crates.io lacks required APIs.
# branch, so mixing this source with crates.io lacks required APIs. This public
# revision also carries the APIs needed by the wasm32+js backend. Edge's WASIX
# child-reap integration uses its separately reviewed Wasmer source.
wasmer = { git = "https://github.com/wasmerio/wasmer.git", rev = "c83ba6d315d051739339636da7080ed5987845de", default-features = false }

# This dependencies are ONLY needed for testing napi in Wasm locally
Expand All @@ -46,6 +54,7 @@ virtual-fs = { git = "https://github.com/wasmerio/wasmer.git", rev = "c83ba6d315
tokio = { version = "1", features = ["rt-multi-thread"], optional = true }
enum-iterator = "2.3.0"
offset-allocator = "0.2.0"
parking_lot = "0.12"

[target.'cfg(target_arch = "wasm32")'.dependencies]
js-sys = { version = "0.3", optional = true }
Expand Down
1 change: 1 addition & 0 deletions Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,7 @@ virtual-fs = { version = "=0.705.0", path = "../virtual-fs", optional = true }
tokio = { version = "1", features = ["rt-multi-thread"], optional = true }
enum-iterator = "2.3.0"
offset-allocator = "0.2.0"
parking_lot = "0.12"

[target.'cfg(target_arch = "wasm32")'.dependencies]
js-sys = { version = "0.3", optional = true }
Expand Down
67 changes: 67 additions & 0 deletions FROZEN_EDGEJS_ABI.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
# Released EdgeJS 0.0.1 N-API compatibility

The frozen guest is the `edgejs` atom from `wasmer/edgejs@0.0.1`, SHA-256
`ca6467e67c8503474cb4204cd2dbbae387c8fa19cad6f6c23131844143e27ccc`.
`tests/fixtures/edgejs-0.0.1-imports.txt` records its import section;
`tests/fixtures/edgejs-0.0.1-napi-signatures.txt` records all 186 `napi`
function types. Linking rejects a changed signature. The legacy names use the
same provider environment, resource budget, lane admission, and sticky stop as
the versioned extension.

## Verified paths

- The exact atom prints `v24.13.2-pre` for `--version` and runs
`-e "console.log('LEGACY_NAPI_BOOT_OK')"`.
- Its default V8 flag string is validated and inert. Unexpected flags fail
before creating a V8 environment.
- Legacy serialized message handles retain their app budget until explicit
release. Deserialization may read the same handle repeatedly. Release,
stale-handle access, double release, and host-stop cleanup are covered by
`tests/legacy_manifest.rs`; host stop removes the native holder and charge.
- The legacy module creation and state queries use the provider's bounded
module handles. Its old heap-statistics layout is translated from one
provider observation. Structured clone uses the existing transient budget.
- The old contextify cache entry compiles source without executing it and
returns an empty guest-owned Buffer. It retains no code cache. The released
guest reports `cachedDataProduced` as true when requested even though the
buffer is empty; this legacy ABI does not pass that request to the host.

The exact atom probes require a local copy and are intentionally opt in:

```sh
NAPI_EDGEJS_0_0_1_ATOM=/path/to/edgejs \
./cargo-standalone.sh test --quiet --features cli --test legacy_manifest
```

## Current limits

- Dynamic `import('data:text/javascript,export default 7')` starts from a
running `-e` script, then rejects in the released guest's ESM translator:
`internalBinding('cjs_lexer')` is undefined. The probe does not reach a
`module_wrap_create` host call. The ESM test is ignored until the released
guest's binding path and the remaining legacy module-wrap operations are
resolved.
- The frozen worker probe now creates a worker, receives its posted message,
and exits cleanly. The regression test runs whenever
`NAPI_EDGEJS_0_0_1_ATOM` points to the exact released atom. Native environment
IDs are allocated across all sessions of the instance, including WASIX
workers; this prevents one worker's environment from resolving to another
worker's native V8 environment. The earlier owning-thread assertion has not
recurred in this probe.
- The frozen serdes binding, profiler/snapshot operations, and several stack
introspection calls fail explicitly. Their existing native implementations
retain buffers or samples without a workload budget, or have no equivalent
in the current provider. Calling `node:v8` serialization therefore needs a
metered implementation before it can be supported.
- Both module-wrap `create_cached_data` imports fail before entering V8.
`CreateCodeCache` allocates native `CachedData` before reporting its size;
the provider needs an enforced allocation limit before this path can be
charged to a workload. This is separate from the legacy contextify cache
entry described above.
- A V8 fatal or out-of-memory callback records a workload stop if control
returns to the N-API import boundary. V8 can terminate the host process
before returning from a native fatal error; the callback alone cannot
provide process-level fault containment.

These limitations are recorded so a successful import-only link or zero exit
from an ESM flag probe is not mistaken for application compatibility.
69 changes: 68 additions & 1 deletion build.rs
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
use std::{
env,
env, fs,
io::Read,
path::{Path, PathBuf},
};
Expand Down Expand Up @@ -37,6 +37,12 @@ enum ExtraLink {
}

fn main() {
println!("cargo:rustc-check-cfg=cfg(napi_standalone_legacy_wait)");
println!("cargo:rerun-if-changed=Cargo.toml");
if standalone_legacy_wait() {
println!("cargo:rustc-cfg=napi_standalone_legacy_wait");
}

let target_arch = env::var("CARGO_CFG_TARGET_ARCH").unwrap_or_default();
if target_arch == "wasm32" {
if env::var_os("CARGO_FEATURE_JS").is_none() {
Expand Down Expand Up @@ -85,6 +91,24 @@ fn main() {

let v8_defines = read_env_value("V8_DEFINES", &["NAPI_V8_DEFINES", "NAPI_V8_V8_DEFINES"])
.unwrap_or_else(|| "V8_COMPRESS_POINTERS".to_string());
let sandbox_define = v8_defines
.split(&[';', ',', ' '][..])
.any(|define| matches!(define, "V8_ENABLE_SANDBOX" | "V8_ENABLE_SANDBOX=1"));
if sandbox_define {
panic!(
"V8_ENABLE_SANDBOX is unsupported: N-API backing stores can reside outside the V8 sandbox"
);
}
// The bridge exposes Wasmer linear memory and other embedder-owned
// allocations as V8 ArrayBuffer backing stores. V8's sandbox requires
// every such store to reside inside its sandbox address range. Until the
// bridge has a sandbox-resident backing-store implementation, accepting
// this archive would make ordinary guest code abort the host process.
if read_sandbox_build_flag(&v8.library_path) == Some(true) {
panic!(
"sandbox-enabled V8 archives are unsupported: N-API backing stores can reside outside the V8 sandbox"
);
}

let mut build = cc::Build::new();
build
Expand Down Expand Up @@ -225,6 +249,49 @@ fn main() {
}
}

fn standalone_legacy_wait() -> bool {
let manifest_dir =
PathBuf::from(env::var("CARGO_MANIFEST_DIR").expect("CARGO_MANIFEST_DIR is not set"));
let manifest = fs::read_to_string(manifest_dir.join("Cargo.toml"))
.expect("failed to read N-API Cargo.toml");
let mut in_napi_metadata = false;
for line in manifest.lines() {
let line = line.trim();
if line.starts_with('[') {
in_napi_metadata = line == "[package.metadata.napi]";
} else if in_napi_metadata {
let declaration = line.split('#').next().unwrap_or("").trim();
if let Some((key, value)) = declaration.split_once('=')
&& key.trim() == "standalone_legacy_wait"
{
return value.trim() == "true";
}
}
}
false
}

fn read_sandbox_build_flag(library_path: &Path) -> Option<bool> {
let config_path = library_path.parent()?.parent()?.join("build-config.txt");
println!("cargo:rerun-if-changed={}", config_path.display());
let config = match std::fs::read_to_string(&config_path) {
Ok(config) => config,
Err(err) if err.kind() == std::io::ErrorKind::NotFound => return None,
Err(err) => panic!("failed to read {}: {err}", config_path.display()),
};
match config
.lines()
.find_map(|line| line.strip_prefix("v8_enable_sandbox="))
{
Some("true") => Some(true),
Some("false") => Some(false),
_ => panic!(
"{} lacks a valid v8_enable_sandbox flag",
config_path.display()
),
}
}

fn resolve_v8_config() -> Result<V8Config, String> {
let include_override = read_env_value(
"NAPI_V8_INCLUDE_DIR",
Expand Down
1 change: 1 addition & 0 deletions cargo-standalone.sh
Original file line number Diff line number Diff line change
Expand Up @@ -71,4 +71,5 @@ for entry in build.rs include lib src tests v8; do
ln -s "$repo_root/$entry" "$standalone_work_dir/$entry"
done

export NAPI_SOURCE_ROOT="$repo_root"
"${cargo_cmd[@]}" "$subcommand" --manifest-path "$standalone_work_dir/Cargo.toml" "$@"
28 changes: 28 additions & 0 deletions include/unofficial_napi.h
Original file line number Diff line number Diff line change
Expand Up @@ -261,6 +261,34 @@ NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_configure_near_heap_lim
unofficial_napi_near_heap_limit_callback callback_or_null,
void* data,
size_t restored_heap_limit);

// Committed bytes of the environment's old generation: every heap space the
// engine's hard heap limit governs (everything but the young generation and
// read-only space). Intended for near-heap-limit callbacks, which must return
// a limit that covers this figure; the engine admits the first large young
// object without consulting the limit and aborts the process after the next
// collection if the limit still does not cover the promoted object. Engines
// that do not expose the figure report zero.
NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_get_heap_committed_old_generation(
napi_env env,
size_t* result);

// Runs a full collection if the environment's heap holds committed memory
// beyond its hard limit that no collection has examined yet. The engine admits
// the first large young object without consulting the heap limit, so after a
// script returns the heap may exceed the limit with no near-heap-limit
// callback having run; an idle environment would keep that memory
// unaccounted for indefinitely. Call from the environment's thread after
// running JavaScript. `old_generation_limit` is the engine's current hard
// old-generation limit as the embedder last set or answered it (the figure the
// engine's own post-collection check uses); zero means unknown, in which case
// the engine's reported total heap limit is used instead, which under-triggers
// by the young-generation allowance. `*collected` reports whether a collection
// ran. Engines without the behaviour report `false`.
NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_collect_garbage_if_over_heap_limit(
napi_env env,
size_t old_generation_limit,
bool* collected);
Comment on lines +265 to +291

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe we may get by with only having one function

// Unofficial helpers used by util/options parity work in edge.
// These expose engine-specific data that is not available in the public N-API.
NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_get_promise_details(napi_env env,
Expand Down
15 changes: 15 additions & 0 deletions lib/src/napi_resource_limits.h
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
#ifndef NAPI_PRIVATE_RESOURCE_LIMITS_H_
#define NAPI_PRIVATE_RESOURCE_LIMITS_H_

#include "js_native_api.h"

// Host-only configuration, not a guest import or public module API.
#ifdef __cplusplus
extern "C" {
#endif
napi_status NAPI_CDECL snapi_private_set_resource_limits(napi_env env, int enabled);
#ifdef __cplusplus
}
#endif

#endif
56 changes: 56 additions & 0 deletions quickjs/src/internal/napi_module_wrap.cc
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@
#include <new>
#include <sstream>
#include <string>
#include <unordered_set>
#include <utility>
#include <vector>

Expand Down Expand Up @@ -217,6 +218,19 @@ void napi_module_wrap__::free_record(record *entry)
if (entry == nullptr)
return;

// Links store record pointers for duplicate-request checks. Clear incoming
// links before freeing a record so a parent cannot instantiate through a
// destroyed dependency or mistake a later allocation for the old record.
for (record *dependent : records_)
{
if (dependent == entry)
continue;
for (record *&linked : dependent->linked_records)
{
if (linked == entry)
linked = nullptr;
}
}
remove(entry);
for (auto &request : entry->requests)
JS_FreeValue(ctx_, request.attributes);
Expand Down Expand Up @@ -689,11 +703,44 @@ napi_status napi_module_wrap__::link(unofficial_napi_module module,
return napi_ok;
}

napi_status napi_module_wrap__::validate_linked_graph(record *root)
{
// QuickJS can link implicitly while evaluating a module or a require()
// facade. Verify the whole reachable, not-yet-linked graph before any of
// those entry points follow request pointers. Keep already-linked modules
// usable after their wrapper handles have been destroyed.
std::unordered_set<record *> live(records_.begin(), records_.end());
std::unordered_set<record *> visited;
std::vector<record *> pending{root};
while (!pending.empty())
{
record *entry = pending.back();
pending.pop_back();
if (!live.contains(entry))
return throw_error("ERR_VM_MODULE_LINK_FAILURE", "Linked module is invalid");
if (!visited.insert(entry).second ||
JS_GetModuleStatus(ctx_, entry->module) != JS_MODULE_STATUS_UNLINKED)
continue;
if (entry->linked_records.size() != entry->requests.size())
return throw_error("ERR_VM_MODULE_LINK_FAILURE", "Linked module is incomplete");
for (record *linked : entry->linked_records)
{
if (!live.contains(linked))
return throw_error("ERR_VM_MODULE_LINK_FAILURE", "Linked module is invalid");
pending.push_back(linked);
}
}
return napi_ok;
}

napi_status napi_module_wrap__::instantiate(unofficial_napi_module module)
{
record *entry = find(module);
if (entry == nullptr)
return napi_util__::invalid_arg(env_);
napi_status validation = validate_linked_graph(entry);
if (validation != napi_ok)
return validation;
if (JS_LinkModule(ctx_, entry->module) < 0)
return return_pending_exception("Module linking failed");
return napi_ok;
Expand All @@ -709,6 +756,9 @@ napi_status napi_module_wrap__::evaluate(unofficial_napi_module module,
record *entry = find(module);
if (entry == nullptr || result_out == nullptr)
return napi_util__::invalid_arg(env_);
napi_status validation = validate_linked_graph(entry);
if (validation != napi_ok)
return validation;
JSValue promise = JS_EvaluateModule(ctx_, entry->module);
if (JS_IsException(promise))
return return_pending_exception("Failed to evaluate module");
Expand All @@ -725,6 +775,9 @@ napi_status napi_module_wrap__::evaluate_sync(unofficial_napi_module module,
record *entry = find(module);
if (entry == nullptr || result_out == nullptr)
return napi_util__::invalid_arg(env_);
napi_status validation = validate_linked_graph(entry);
if (validation != napi_ok)
return validation;

JSValue promise = JS_EvaluateModule(ctx_, entry->module);
if (JS_IsException(promise))
Expand Down Expand Up @@ -1013,6 +1066,9 @@ napi_status napi_module_wrap__::create_required_module_facade(unofficial_napi_mo
record *entry = find(module);
if (entry == nullptr || result_out == nullptr)
return napi_util__::invalid_arg(env_);
napi_status validation = validate_linked_graph(entry);
if (validation != napi_ok)
return validation;

std::string filename = "<required-module-facade:" +
std::to_string(++facade_counter_) + ">";
Expand Down
1 change: 1 addition & 0 deletions quickjs/src/internal/napi_module_wrap.h
Original file line number Diff line number Diff line change
Expand Up @@ -104,6 +104,7 @@ class napi_module_wrap__
record *find_by_wrapper(JSValueConst wrapper) const;
void remove(record *entry);
void free_record(record *entry);
napi_status validate_linked_graph(record *root);

JSValue get_host_defined_option_symbol() const;
JSValue get_symbols_binding_property(const char *name) const;
Expand Down
Loading
Loading