Skip to content

feat(napi): consolidate managed Edge V8 and metered WebAssembly - #84

Closed
theduke wants to merge 12 commits into
mainfrom
feat/napi-webassembly-metered
Closed

theduke wants to merge 12 commits into
mainfrom
feat/napi-webassembly-metered

Conversation

@theduke

@theduke theduke commented Oct 5, 2026 •

Copy link
Copy Markdown
Contributor

This PR consolidates the managed Edge V8 provider, metered nested WebAssembly, guest isolation, and host-safe heap-limit handling on main. It also restores normal standalone EdgeJS behavior: WebAssembly is enabled and application resource quotas are opt-in. Managed Edge contexts and contexts with an explicit memory budget retain their restrictions.

  • Managed per-instance lanes, accounting, callback boundaries, and frozen EdgeJS ABI compatibility.
  • Disable asm.js validation to keep it from bypassing WebAssembly policy.
  • Embedder-controlled WebAssembly policy, per-context V8 page accounting, and metered WebAssembly memory and compiled-code limits.
  • Host-safe V8 heap-limit handling and bounded foreground checkpoints.
  • Unrestricted standalone defaults: restore serdes, profiling, heap snapshots, and module cache creation without a budget; apply serializer, guest-copy, property, and VM metadata quotas only to budgeted or managed execution.
  • Keep guest memory range checks, overflow checks, ownership checks, stack protection, and engine/ABI bounds in every mode. Retained standalone worker messages can exceed the initial accounting reservation.
  • Add --restricted-webassembly as an explicit opt-out; retain --unmetered-webassembly compatibility.

The alternative nine-PR stack (#93, #94, #95, #96, #97, #98, #99, #100, #101) is superseded by this PR. The environment lookup optimization in #79 is excluded.

Public Wasmer integration is tracked in wasmerio/wasmer#7065; internal Edge already includes the earlier compatible provider through wasmerio/wasmer-internal#53. This standalone-defaults follow-up needs no EdgeJS or Wasmer source changes. No Prometheus registration is added here.

Standalone defaults and EdgeJS validation

Against EdgeJS 18b0ce9ef6484feb796445567787a113a682a9d5, using its existing wasm artifact and the standalone CLI's pinned public Wasmer SDK:

  • All 16 previously confirmed Node serialization regressions pass with default runner settings.
  • node:v8 serialize/deserialize, node:test, WebAssembly compilation, and an 8 MiB structured clone pass.
  • A 40 MiB worker-message round trip and the finalizer test reclaiming across 6 GiB of cumulative buffer allocations pass.
  • Real Astro SSR, Next.js SSR, and Etherpad /health return HTTP 200.
  • VM operations pass above the former caps: 20,000 sandbox properties, 5 MiB function source, 1,100 parameters/context extensions/synthetic exports, 2,100 live modules, and 5,000 imports.
  • Boundary tests verify standalone WebAssembly, serdes, 70,000-byte auto-length strings, and 5,000 property descriptors, and verify the explicit-budget restrictions remain enforced.
  • Rebased Rust library/CLI and expanded targeted integration checks: 146 passed, one failed, one ignored. The failure is v8_host_control::guest_messages_remain_charged_until_instance_shutdown; it reproduces on unchanged split-PR head daff275, while the same guest succeeds through the unrestricted CLI.
  • wasm32-unknown-unknown with js, formatting, and git diff --check pass.

The rebase preserves main's 0.705.0 standalone package version and aligns the wasm-bindgen test dependencies with js-sys/wasm-bindgen; the rebased Cargo checks use --locked. The full 1,676-case Node suite preceded this follow-up and was not rerun. Native Release V8 CTest was rerun after the CI fixes: all 115 tests passed locally. The earlier PR84 RawReplTabCompleteBufferFromNodeTest embedding double-free has not been revalidated against these edits and is not claimed fixed.

Rebase verification

Rebased all nine original PR commits onto main at bb3434d2ade539fe05e18a28673b23e798f9ec11, preserving upstream unsigned guest pointers/IDs, the count-only native callback optimization, and host-JS performance, lifecycle, and new.target support. Independent subagent review found no actionable conflict-resolution issues. Two follow-up commits align the standalone test lockfile and guard a native-only managed-lane test assertion.

  • Native release tests: 146 passed, one ignored; the same previously reported budgeted-message test fails.
  • Actual Wasm-host tests: 15 passed, covering callbacks, constructor targets, lifecycle, guest memory growth, encodings, numbers, and ID maps.
  • Host-JS context tests: 15 passed.
  • Eight ABI probes passed: guest pointers above 2 GiB, handles with bit 31 set, callbacks, constructors, classes, handle scopes, and callback arities 0/5/70.
  • All 16 EdgeJS serialization regression cases passed; Astro SSR, real Next.js SSR, and Etherpad /health returned HTTP 200 through the rebased default runner.
  • Locked browser-hosted build, formatting, and whitespace checks passed.

Dashboard GC latency fix

The consolidated work now includes 91a95bd: V8's fallback foreground queue processes one ready task per checkpoint and reports admitted/pending work, giving the guest an event-loop turn before running a self-posted successor. The previous drain-until-empty loop could monopolize a streamed dashboard response during major GC. Promise microtask and finalizer ordering is preserved.

Release Edge + LLVM guest, production-style systemd user cgroups, default 512 MiB workload limit, backend stubbed with zero delay, unchanged guest and identical 209,094-byte response. After fresh host starts and five warmup requests, matched 145-request A/B/A windows measured full response time:

Provider Median p95 Maximum >300 ms
Original 1,024.08 ms 1,109.36 ms 1,156.92 ms 98/145
Bounded foreground pump 77.09 ms 84.35 ms 91.32 ms 0/145
Original restored 1,025.39 ms 1,097.58 ms 1,203.23 ms 98/145

Matched p95 fell 92.4%. A further 1,000 consecutive requests (995 after warmup) retained median 76.70 ms, p95 83.27 ms and maximum 157.98 ms, with HTTP 200 throughout. Cgroup counters showed no CPU throttling. GC CPU work remains; the fix prevents queued foreground work from monopolizing a checkpoint.

Validation: deterministic standalone V8 self-reposting-task regression fails the original pump and passes the fix; all eight existing native promise tests pass, both on main and the managed Edge integration source. The standalone test owns V8 initialization/disposal in a separate process to preserve the shared test environments.

cmake --build build --target napi_v8_foreground_checkpoint_test napi_v8_test_35_promise
ctest --test-dir build -R 'foreground_checkpoint_fairness|test_35_promise' --output-on-failure

CI verification

All 10 GitHub checks passed on 490a382: V8 and QuickJS on Linux/macOS, Node 20/22/24/26, Bun, and Wasm callback lifetime. Local Release V8 CTest also passed all 115 tests.

Quota rejection tests explicitly enable native resource limits, and a new 5 MiB clone/message test covers unrestricted defaults. Nonempty null module-link arrays are rejected in every mode. Existing rejection assertions and workflow exclusions were preserved.

@theduke
theduke force-pushed the feat/napi-webassembly-metered branch from 8cd862c to f0446df Compare October 5, 2026 12:09
@theduke theduke changed the title feat(napi): opt-in metered V8 WebAssembly feat(napi): consolidate managed Edge V8 and metered WebAssembly Oct 5, 2026
@theduke
theduke changed the base branch from codex/edge-instance-lane-rebased to main October 5, 2026 12:09
theduke added a commit that referenced this pull request Oct 6, 2026
Merge the consolidated NAPI PR #84 head including the validated bounded foreground checkpoint fix. Keep the maintained Edge integration manifests at Wasmer 7.4 and NAPI/WASIX 0.704; the provider code is identical to the consolidated PR, which targets the 7.5 main release.

@syrusakbary syrusakbary left a comment •

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 don't love the current API, I believe we can get better with one function (or none) API surface in the unofficial napi

Comment thread include/unofficial_napi.h
Comment on lines +265 to +291
// 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);

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

Consolidate the managed lane lifecycle, guest boundary accounting, callback handling, frozen EdgeJS ABI compatibility, and corresponding regression coverage used by Edge. Includes provider changes from PR #78 and existing Wasmer 7.5 manifest alignment.
V8 validates "use asm" modules, translates them to WebAssembly and
compiles them with its wasm pipeline. That path never consults the
embedder's wasm code-generation callback (only the WebAssembly JS API
and module deserialization do), so a guest-heap context that has no
WebAssembly global and refuses wasm code generation could still make V8
reserve wasm code space and map new executable memory by running an
asm.js module. Those allocations are outside the guest heap and outside
any embedder resource limit.

Pass --no-validate-asm with the provider's default V8 flags. asm.js
then runs as ordinary JavaScript: correct programs produce the same
results, and the code is compiled by the regular JS tiers inside the
isolate's code range.

The new regression test runs an asm.js module whose function calls a
foreign function that inspects the caller's stack frame. In sloppy-mode
JavaScript CallSite.getFunction() returns the running function itself;
for translated asm.js the frame is a wasm frame and does not. The test
fails without this change.

Measured with the CLI harness and an asm.js script: before, running the
module added a new anonymous rwx mapping outside every earlier
reservation; with the flag, the process maps are unchanged.
Guest environments allocate V8 array buffers in the guest's linear
memory, where they count against the context's memory budget. V8 does not
allocate WebAssembly memories and compiled wasm code that way, so the
provider removes WebAssembly from guest-heap environments and refuses
wasm code generation in them. That decision was hard-coded at three
sites (root context, its code-generation slot, and the flag `vm`
contexts inherit).

Make it an embedder choice:

* `NapiCtxBuilder::webassembly(WasmPolicy)` with `WasmPolicy::Restricted`
  (the default, current behaviour) and `WasmPolicy::EnabledUnmetered`.
  The opt-in is named and documented as unmetered and unsupported for
  untrusted code: wasm memory reservations and commits, compiled code
  and background compilation are not charged to `total_memory_bytes`,
  a `NapiMemoryAccountant` or any other limit. The enum is
  non-exhaustive so a metered variant can be added once those
  allocations are accounted for.
* The policy is stored per context, copied into every store's
  environment (including WASIX worker threads) and passed to the native
  bridge on env creation. The bridge calls a new provider-private entry,
  snapi_private_create_env, which takes the policy as a separate
  argument: unofficial_napi_env_create_options doubles as the guest's
  wasm32 wire ABI, so the policy cannot be an option there, and guests
  can neither set nor observe it. unofficial_napi_create_env keeps its
  signature and forwards the restrictive policy.
* The three restriction sites derive from the policy; with the default
  the result is identical to before (restricted iff the env has a guest
  heap). Unknown policy values are rejected with napi_invalid_arg after
  the guest heap has been released, like other invalid arguments.
* With the opt-in, `vm` contexts still honour codeGeneration.wasm, and
  realms the provider did not create still refuse wasm code generation.
* napi_wasmer gains `--unmetered-webassembly` for manual evaluation.

Tests:

* v8_host_control: an explicitly disabled policy keeps WebAssembly out
  of the root context, a fresh realm and `vm` contexts; the unmetered
  policy compiles, instantiates and grows memory in the root context
  and a `vm` context, a `vm` context with wasm code generation disabled
  refuses to compile, and a following default context in the same
  process is restricted again.
* test_21 (native): guest-heap environments refuse wasm code generation
  through the V8 API (which does not need the WebAssembly global) under
  the default policy and allow it with the opt-in; environments without
  a guest heap are unchanged; an unknown policy is rejected and releases
  the guest heap exactly once.
* Unit tests: the policy reaches the store environment, and the bridge
  rejects an unknown policy and releases the guest-heap context.
Enable WebAssembly for the standalone runner and unbudgeted contexts.
Apply resource quotas only to explicitly budgeted or managed execution,
and restore native serdes, profiling, snapshots and code cache support
for unrestricted standalone guests. Preserve pointer, overflow and
ownership checks while allowing larger valid operations and messages.

Add boundary coverage for default versus budgeted behavior and retain
an explicit --restricted-webassembly CLI opt-out.
@theduke
theduke force-pushed the feat/napi-webassembly-metered branch from 78b4757 to 918a62e Compare October 23, 2026 16:47
@syrusakbary

Copy link
Copy Markdown
Member

This PR is closed in favor of #160 and #161

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants