From 05bdff5e5b85071a4f5c257bf7ecaa6198e1efdf Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Fri, 23 Oct 2026 16:20:55 +0200 Subject: [PATCH 001/150] Give each V8 isolate an agent next to its env State that belongs to the isolate rather than to one realm lived in eight process-wide maps keyed by isolate or env, each read under g_runtime_mu: g_env_by_isolate, g_hash_seeds, g_tracking_allocators, g_fatal_error_callbacks, g_near_heap_limit_callbacks, g_profiler_states, g_promise_reject_callbacks and g_promise_hooks. They are gone. napi_agent__ (internal/napi_v8_agent.h) is created with the isolate, owned by the env owner handle, and found from an isolate through data slot 0. It holds the hash seed, the array buffer allocator, the profiler sessions, the near-heap-limit slot, the embedder hooks (fatal, OOM, context tokens, foreground task) and the wrap, buffer and type-tag private keys. It also sets the microtask policy and the default dynamic-import hook, which the env constructor used to reset. The promise reject callback and promise hooks are realm state and move to the env. Dispatch goes isolate -> agent -> principal env; resolving context -> env is left to a later phase. GetModuleWrapEnvForIsolate is an agent lookup instead of a scan. Shutting the agent down now also removes the near-heap-limit trampoline, which used to stay registered with the freed env as its data. Each isolate still has one env; there is no ABI change. Co-Authored-By: Claude Opus 5.5 --- v8/src/internal/napi_v8_agent.h | 73 ++++ v8/src/internal/napi_v8_env.h | 22 +- v8/src/js_native_api_v8.cc | 82 +++-- v8/src/unofficial_napi.cc | 477 ++++++++------------------- v8/src/unofficial_napi_contextify.cc | 21 +- 5 files changed, 299 insertions(+), 376 deletions(-) create mode 100644 v8/src/internal/napi_v8_agent.h diff --git a/v8/src/internal/napi_v8_agent.h b/v8/src/internal/napi_v8_agent.h new file mode 100644 index 0000000000..9980781a78 --- /dev/null +++ b/v8/src/internal/napi_v8_agent.h @@ -0,0 +1,73 @@ +#ifndef NAPI_V8_AGENT_H_ +#define NAPI_V8_AGENT_H_ + +#include +#include +#include + +#include + +#include "js_native_api.h" +#include "unofficial_napi.h" + +namespace v8 { +class CpuProfiler; +} // namespace v8 + +// One engine instance: a V8 isolate and the state that belongs to it rather +// than to a realm. Every env points at its agent. Today an agent has one env, +// its principal env; envs for other realms of the isolate will share it. +// +// Only the isolate's own thread reads or writes these fields, except +// `allocator` and `hash_seed`, which are fixed once the agent is set up. +struct napi_agent__ { + explicit napi_agent__(v8::Isolate* isolate); + ~napi_agent__(); + + napi_agent__(const napi_agent__&) = delete; + napi_agent__& operator=(const napi_agent__&) = delete; + + // The agent installed on `isolate`, or null. + static napi_agent__* From(v8::Isolate* isolate); + + // Turns off the agent's V8 hooks and profilers. Runs before the principal + // env is torn down. + void Shutdown(); + + v8::Isolate* const isolate; + napi_env principal_env = nullptr; + + // Backs the isolate's ArrayBuffers. Null when the isolate was not created + // by unofficial_napi_create_env. + std::shared_ptr allocator; + // Provider-generated seed; zero means "ask the isolate". + uint64_t hash_seed = 0; + + // Isolate-wide keys for wraps, buffer records and type tags. + v8::Global wrap_private_key; + v8::Global buffer_private_key; + v8::Global type_tag_private_key; + + // Embedder hooks from unofficial_napi_attach_env, attached once. + bool embedder_hooks_attached = false; + unofficial_napi_fatal_error_callback fatal_error_callback = nullptr; + unofficial_napi_oom_error_callback oom_error_callback = nullptr; + unofficial_napi_context_token_callback context_token_assign_callback = nullptr; + unofficial_napi_context_token_callback context_token_unassign_callback = nullptr; + void* context_token_callback_data = nullptr; + unofficial_napi_enqueue_foreground_task_callback enqueue_foreground_task_callback = + nullptr; + void* enqueue_foreground_task_target = nullptr; + + // The one near-heap-limit slot. `near_heap_limit_installed` is true while + // the provider's trampoline is registered with V8. + unofficial_napi_near_heap_limit_callback near_heap_limit_callback = nullptr; + void* near_heap_limit_data = nullptr; + bool near_heap_limit_installed = false; + + // Profiler sessions. V8's CPU and sampling heap profilers are per isolate. + v8::CpuProfiler* cpu_profiler = nullptr; + std::vector active_profiles; +}; + +#endif // NAPI_V8_AGENT_H_ diff --git a/v8/src/internal/napi_v8_env.h b/v8/src/internal/napi_v8_env.h index 0c7a5f110e..ba585fa779 100644 --- a/v8/src/internal/napi_v8_env.h +++ b/v8/src/internal/napi_v8_env.h @@ -1,8 +1,10 @@ #ifndef NAPI_V8_ENV_H_ #define NAPI_V8_ENV_H_ +#include #include #include +#include #include #include #include @@ -16,6 +18,7 @@ #include "internal/napi_factory.h" #include "internal/napi_lifetime_tracker.h" #include "internal/napi_ref_tracker.h" +#include "internal/napi_v8_agent.h" #include "unofficial_napi.h" typedef void(NAPI_CDECL* napi_cleanup_hook)(void* arg); @@ -82,6 +85,12 @@ struct napi_env__ { #endif v8::Isolate* isolate = nullptr; + // The agent this env belongs to. Set at creation and never changed. + napi_agent__* agent = nullptr; + // Set only when the env had to create its own agent (an isolate the + // provider did not set up). + std::unique_ptr owned_agent; + // The env's realm. Never changes. v8::Global context_ref; napi::error_state__ error_state; std::vector open_handle_scope_stack; @@ -89,9 +98,6 @@ struct napi_env__ { v8::Global last_exception_message; std::string last_exception_source_line; std::string last_exception_thrown_at; - v8::Global wrap_private_key; - v8::Global buffer_private_key; - v8::Global type_tag_private_key; void* instance_data = nullptr; napi_finalize instance_data_finalize_cb = nullptr; void* instance_data_finalize_hint = nullptr; @@ -104,12 +110,10 @@ struct napi_env__ { std::unordered_set pending_finalizers; std::unordered_set pending_buffer_finalizers; bool finalization_scheduled = false; - unofficial_napi_context_token_callback context_token_assign_callback = nullptr; - unofficial_napi_context_token_callback context_token_unassign_callback = nullptr; - void* context_token_callback_data = nullptr; - unofficial_napi_enqueue_foreground_task_callback enqueue_foreground_task_callback = nullptr; - void* enqueue_foreground_task_target = nullptr; - bool embedder_hooks_attached = false; + // Realm hooks: unofficial_napi_set_promise_reject_callback and + // unofficial_napi_set_promise_hooks (init, before, after, resolve). + v8::Global promise_reject_callback; + std::array, 4> promise_hooks; #if defined(NAPI_ENABLE_LIFETIME_TRACKER) && defined(NAPI_ENABLE_LIFETIME_PERIODIC_STATS) napi::periodic_gate__ lifetime_stats_gate_{2000}; diff --git a/v8/src/js_native_api_v8.cc b/v8/src/js_native_api_v8.cc index f25e0272a1..60a0e17c5a 100644 --- a/v8/src/js_native_api_v8.cc +++ b/v8/src/js_native_api_v8.cc @@ -41,9 +41,10 @@ void ScheduleFinalizerQueueDrain(napi_env env) { if (env == nullptr || env->finalization_scheduled) return; env->finalization_scheduled = true; - if (env->enqueue_foreground_task_callback != nullptr) { - napi_status status = env->enqueue_foreground_task_callback( - env->enqueue_foreground_task_target, + napi_agent__* agent = env->agent; + if (agent != nullptr && agent->enqueue_foreground_task_callback != nullptr) { + napi_status status = agent->enqueue_foreground_task_callback( + agent->enqueue_foreground_task_target, DrainFinalizerQueueForegroundTask, env, nullptr, @@ -558,21 +559,57 @@ void napi_env__::DrainFinalizerQueue() { } } +namespace { + +// Isolate data slot that points at the isolate's napi_agent__. +constexpr uint32_t kNapiAgentDataSlot = 0; + +} // namespace + +napi_agent__::napi_agent__(v8::Isolate* isolate_in) : isolate(isolate_in) { + isolate->SetData(kNapiAgentDataSlot, this); + isolate->SetMicrotasksPolicy(v8::MicrotasksPolicy::kExplicit); + isolate->SetHostImportModuleDynamicallyCallback(NapiHostImportModuleDynamically); + v8::HandleScope handle_scope(isolate); + wrap_private_key.Reset( + isolate, + v8::Private::ForApi(isolate, v8::String::NewFromUtf8Literal(isolate, "__napi_wrap"))); + buffer_private_key.Reset( + isolate, + v8::Private::ForApi( + isolate, v8::String::NewFromUtf8Literal(isolate, "__napi_buffer_record"))); + type_tag_private_key.Reset( + isolate, + v8::Private::ForApi(isolate, v8::String::NewFromUtf8Literal(isolate, "__napi_type_tag"))); +} + +napi_agent__::~napi_agent__() { + wrap_private_key.Reset(); + buffer_private_key.Reset(); + type_tag_private_key.Reset(); + if (From(isolate) == this) { + isolate->SetData(kNapiAgentDataSlot, nullptr); + } +} + +napi_agent__* napi_agent__::From(v8::Isolate* isolate) { + if (isolate == nullptr) return nullptr; + return static_cast(isolate->GetData(kNapiAgentDataSlot)); +} + napi_env__::napi_env__(v8::Local context, int32_t module_api_version) : isolate(v8::Isolate::GetCurrent()), + agent(napi_agent__::From(isolate)), context_ref(isolate, context), factory_(this) { (void)module_api_version; - isolate->SetHostImportModuleDynamicallyCallback(NapiHostImportModuleDynamically); - v8::Local wrapKey = v8::Private::ForApi( - isolate, v8::String::NewFromUtf8Literal(isolate, "__napi_wrap")); - wrap_private_key.Reset(isolate, wrapKey); - v8::Local bufferKey = v8::Private::ForApi( - isolate, v8::String::NewFromUtf8Literal(isolate, "__napi_buffer_record")); - buffer_private_key.Reset(isolate, bufferKey); - v8::Local typeTagKey = v8::Private::ForApi( - isolate, v8::String::NewFromUtf8Literal(isolate, "__napi_type_tag")); - type_tag_private_key.Reset(isolate, typeTagKey); + if (agent == nullptr) { + owned_agent = std::make_unique(isolate); + agent = owned_agent.get(); + } + if (agent->principal_env == nullptr) { + agent->principal_env = this; + } napi_v8_clear_last_error(this); } @@ -590,6 +627,9 @@ napi_env__::~napi_env__() { if (instance_data_finalize_cb != nullptr) { instance_data_finalize_cb(this, instance_data, instance_data_finalize_hint); } + if (agent != nullptr && agent->principal_env == this) { + agent->principal_env = nullptr; + } NAPI_V8_LIFETIME_DUMP(this, "napi_env__ teardown end"); } @@ -2573,7 +2613,7 @@ napi_status NAPI_CDECL napi_wrap(napi_env env, v8::Local value = napi_v8_unwrap_value(js_object); if (!value->IsObject()) return napi_object_expected; v8::Local object = value.As(); - v8::Local wrapKey = env->wrap_private_key.Get(env->isolate); + v8::Local wrapKey = env->agent->wrap_private_key.Get(env->isolate); if (object->HasPrivate(env->context(), wrapKey).FromMaybe(false)) { return napi_v8_set_last_error(env, napi_invalid_arg, "Invalid argument"); } @@ -2624,7 +2664,7 @@ napi_status NAPI_CDECL napi_unwrap(napi_env env, napi_value js_object, void** re v8::Local value = napi_v8_unwrap_value(js_object); if (!value->IsObject()) return napi_object_expected; v8::Local object = value.As(); - v8::Local wrapKey = env->wrap_private_key.Get(env->isolate); + v8::Local wrapKey = env->agent->wrap_private_key.Get(env->isolate); v8::Local wrapped; if (!object->GetPrivate(env->context(), wrapKey).ToLocal(&wrapped) || !wrapped->IsExternal()) { @@ -2642,7 +2682,7 @@ napi_status NAPI_CDECL napi_remove_wrap(napi_env env, napi_value js_object, void napi_status status = napi_unwrap(env, js_object, &out); if (status != napi_ok) return status; v8::Local object = napi_v8_unwrap_value(js_object).As(); - v8::Local wrapKey = env->wrap_private_key.Get(env->isolate); + v8::Local wrapKey = env->agent->wrap_private_key.Get(env->isolate); v8::Local wrapped; if (!object->GetPrivate(env->context(), wrapKey).ToLocal(&wrapped) || !wrapped->IsExternal()) { @@ -2988,7 +3028,7 @@ napi_status NAPI_CDECL napi_create_buffer(napi_env env, v8::Local buffer_obj = CreateBufferObject(env, record->backing_store, 0, length); record->holder.Reset(env->isolate, buffer_obj); record->holder.SetWeak(record, BufferWeakCallback, v8::WeakCallbackType::kParameter); - v8::Local key = env->buffer_private_key.Get(env->isolate); + v8::Local key = env->agent->buffer_private_key.Get(env->isolate); buffer_obj ->SetPrivate(env->context(), key, v8::External::New(env->isolate, record)) .FromJust(); @@ -3050,7 +3090,7 @@ napi_status NAPI_CDECL napi_create_external_buffer(napi_env env, v8::Local buffer_obj = CreateBufferObject(env, record->backing_store, 0, length); record->holder.Reset(env->isolate, buffer_obj); record->holder.SetWeak(record, BufferWeakCallback, v8::WeakCallbackType::kParameter); - v8::Local key = env->buffer_private_key.Get(env->isolate); + v8::Local key = env->agent->buffer_private_key.Get(env->isolate); buffer_obj ->SetPrivate(env->context(), key, v8::External::New(env->isolate, record)) .FromJust(); @@ -3101,7 +3141,7 @@ napi_status NAPI_CDECL node_api_create_buffer_from_arraybuffer( CreateBufferObject(env, record->backing_store, byte_offset, byte_length); record->holder.Reset(env->isolate, buffer_obj); record->holder.SetWeak(record, BufferWeakCallback, v8::WeakCallbackType::kParameter); - v8::Local key = env->buffer_private_key.Get(env->isolate); + v8::Local key = env->agent->buffer_private_key.Get(env->isolate); buffer_obj ->SetPrivate(env->context(), key, v8::External::New(env->isolate, record)) .FromJust(); @@ -3193,7 +3233,7 @@ napi_status NAPI_CDECL napi_type_tag_object( if (!target->IsObject()) return napi_invalid_arg; v8::Local object = target.As(); - v8::Local key = env->type_tag_private_key.Get(env->isolate); + v8::Local key = env->agent->type_tag_private_key.Get(env->isolate); if (object->HasPrivate(env->context(), key).FromMaybe(false)) { return napi_v8_set_last_error(env, napi_invalid_arg, "Invalid argument"); } @@ -3226,7 +3266,7 @@ napi_status NAPI_CDECL napi_check_object_type_tag(napi_env env, } v8::Local object = target.As(); - v8::Local key = env->type_tag_private_key.Get(env->isolate); + v8::Local key = env->agent->type_tag_private_key.Get(env->isolate); v8::Local tag_value; *result = false; if (!object->GetPrivate(env->context(), key).ToLocal(&tag_value) || diff --git a/v8/src/unofficial_napi.cc b/v8/src/unofficial_napi.cc index 7b4763896d..00123dc5a0 100644 --- a/v8/src/unofficial_napi.cc +++ b/v8/src/unofficial_napi.cc @@ -46,11 +46,14 @@ struct SharedRuntime { class TrackingArrayBufferAllocator; +// The owner handle (unofficial_napi_env_owner): the isolate, its agent and +// the scopes that keep the principal context entered. struct UnofficialEnvScope { v8::Isolate* isolate = nullptr; std::shared_ptr allocator; std::optional isolate_scope; std::optional handle_scope; + std::unique_ptr agent; std::optional> context; std::optional context_scope; napi_env env = nullptr; @@ -64,6 +67,7 @@ struct UnofficialEnvScope { } ~UnofficialEnvScope() { + agent.reset(); if (context.has_value()) { context->Reset(); } @@ -91,35 +95,8 @@ std::mutex g_runtime_mu; // for the teardown thread (Isolate::Delete touches the platform's page // allocator and tracing controller). The OS reclaims everything at _exit. SharedRuntime& g_runtime = *new SharedRuntime(); -std::unordered_map& g_env_by_isolate = - *new std::unordered_map(); -std::unordered_map& g_hash_seeds = - *new std::unordered_map(); -std::unordered_map>& g_promise_reject_callbacks = - *new std::unordered_map>(); -std::unordered_map, 4>>& g_promise_hooks = - *new std::unordered_map, 4>>(); std::unordered_map& g_prepare_stack_trace_callbacks = *new std::unordered_map(); -std::unordered_map>& - g_tracking_allocators = *new std::unordered_map>(); - -struct FatalErrorCallbacks { - unofficial_napi_fatal_error_callback fatal = nullptr; - unofficial_napi_oom_error_callback oom = nullptr; -}; - -std::unordered_map& g_fatal_error_callbacks = - *new std::unordered_map(); - -struct NearHeapLimitCallbackState { - unofficial_napi_near_heap_limit_callback callback = nullptr; - void* data = nullptr; -}; - -std::unordered_map& g_near_heap_limit_callbacks = - *new std::unordered_map(); struct InterruptRequest { napi_env env = nullptr; @@ -127,14 +104,6 @@ struct InterruptRequest { void* data = nullptr; }; -struct ProfilerState { - v8::CpuProfiler* cpu_profiler = nullptr; - std::vector active_profiles; -}; - -std::unordered_map& g_profiler_states = - *new std::unordered_map(); - class StringOutputStream final : public v8::OutputStream { public: WriteResult WriteAsciiChunk(char* data, int size) override { @@ -182,15 +151,15 @@ napi_status CreateExternalUtf8Bytes(napi_env env, env, napi_uint8_array, owner->size(), arraybuffer, 0, result); } -void DisposeProfilerState(napi_env env, ProfilerState* state) { - if (env == nullptr || env->isolate == nullptr || state == nullptr) return; +void DisposeProfilers(napi_agent__* agent) { + if (agent == nullptr || agent->isolate == nullptr) return; bool heap_profile_started = false; - for (unofficial_napi_profile profile_session : state->active_profiles) { + for (unofficial_napi_profile profile_session : agent->active_profiles) { if (profile_session == nullptr) continue; if (profile_session->kind == unofficial_napi_profile_cpu && - state->cpu_profiler != nullptr) { + agent->cpu_profiler != nullptr) { if (v8::CpuProfile* profile = - state->cpu_profiler->Stop(profile_session->provider_id)) { + agent->cpu_profiler->Stop(profile_session->provider_id)) { profile->Delete(); } } else if (profile_session->kind == unofficial_napi_profile_heap) { @@ -198,20 +167,16 @@ void DisposeProfilerState(napi_env env, ProfilerState* state) { } delete profile_session; } - state->active_profiles.clear(); + agent->active_profiles.clear(); if (heap_profile_started) { - env->isolate->GetHeapProfiler()->StopSamplingHeapProfiler(); + agent->isolate->GetHeapProfiler()->StopSamplingHeapProfiler(); } - if (state->cpu_profiler != nullptr) { - state->cpu_profiler->Dispose(); - state->cpu_profiler = nullptr; + if (agent->cpu_profiler != nullptr) { + agent->cpu_profiler->Dispose(); + agent->cpu_profiler = nullptr; } } -ProfilerState& EnsureProfilerState(napi_env env) { - return g_profiler_states[env]; -} - uint64_t GenerateHashSeed() { try { std::random_device random_device; @@ -382,15 +347,8 @@ v8::Local LookupPrepareStackTraceCallback(napi_env env, v8::MaybeLocal NapiPrepareStackTraceCallback(v8::Local context, v8::Local exception, v8::Local trace) { - napi_env env = nullptr; - { - std::lock_guard lock(g_runtime_mu); - auto env_it = g_env_by_isolate.find(context->GetIsolate()); - if (env_it != g_env_by_isolate.end()) { - env = env_it->second; - } - } - + napi_agent__* agent = napi_agent__::From(context->GetIsolate()); + napi_env env = agent != nullptr ? agent->principal_env : nullptr; if (env == nullptr) { return exception->ToString(context); } @@ -423,26 +381,17 @@ bool IsEnvThreadEntered(napi_env env) { return env != nullptr && env->isolate != nullptr && v8::Isolate::GetCurrent() == env->isolate; } -size_t NearHeapLimitCallback(void* raw_env, +size_t NearHeapLimitCallback(void* raw_agent, size_t current_heap_limit, size_t initial_heap_limit) { - napi_env env = static_cast(raw_env); - v8::Isolate* isolate = env != nullptr ? env->isolate : nullptr; - if (isolate == nullptr) { + auto* agent = static_cast(raw_agent); + if (agent == nullptr || agent->near_heap_limit_callback == nullptr) { return current_heap_limit; } - NearHeapLimitCallbackState state; - { - std::lock_guard lock(g_runtime_mu); - auto callback_it = g_near_heap_limit_callbacks.find(isolate); - if (callback_it != g_near_heap_limit_callbacks.end()) { - state = callback_it->second; - } - } - if (state.callback == nullptr) { - return current_heap_limit; - } - return state.callback(env, state.data, current_heap_limit, initial_heap_limit); + return agent->near_heap_limit_callback(agent->principal_env, + agent->near_heap_limit_data, + current_heap_limit, + initial_heap_limit); } // Rust-exported guest-heap hooks (see guest_heap.rs). When a guest-heap @@ -646,47 +595,16 @@ void ApplyDefaultV8Flags() { } void FatalErrorCallback(const char* location, const char* message) { - v8::Isolate* isolate = v8::Isolate::TryGetCurrent(); - if (isolate == nullptr) return; - - unofficial_napi_fatal_error_callback callback = nullptr; - napi_env env = nullptr; - { - std::lock_guard lock(g_runtime_mu); - auto callback_it = g_fatal_error_callbacks.find(isolate); - if (callback_it != g_fatal_error_callbacks.end()) { - callback = callback_it->second.fatal; - } - auto env_it = g_env_by_isolate.find(isolate); - if (env_it != g_env_by_isolate.end()) { - env = env_it->second; - } - } - if (callback != nullptr) { - callback(env, location, message); - } + napi_agent__* agent = napi_agent__::From(v8::Isolate::TryGetCurrent()); + if (agent == nullptr || agent->fatal_error_callback == nullptr) return; + agent->fatal_error_callback(agent->principal_env, location, message); } void OOMErrorCallback(const char* location, const v8::OOMDetails& details) { - v8::Isolate* isolate = v8::Isolate::TryGetCurrent(); - if (isolate == nullptr) return; - - unofficial_napi_oom_error_callback callback = nullptr; - napi_env env = nullptr; - { - std::lock_guard lock(g_runtime_mu); - auto callback_it = g_fatal_error_callbacks.find(isolate); - if (callback_it != g_fatal_error_callbacks.end()) { - callback = callback_it->second.oom; - } - auto env_it = g_env_by_isolate.find(isolate); - if (env_it != g_env_by_isolate.end()) { - env = env_it->second; - } - } - if (callback != nullptr) { - callback(env, location, details.is_heap_oom, details.detail); - } + napi_agent__* agent = napi_agent__::From(v8::Isolate::TryGetCurrent()); + if (agent == nullptr || agent->oom_error_callback == nullptr) return; + agent->oom_error_callback( + agent->principal_env, location, details.is_heap_oom, details.detail); } napi_status ConfigureRuntime(const char* engine_flags, @@ -743,18 +661,10 @@ void PromiseRejectCallback(v8::PromiseRejectMessage message) { if (promise.IsEmpty()) return; v8::Isolate* isolate = promise->GetIsolate(); - napi_env env = nullptr; - v8::Local callback; - { - std::lock_guard lock(g_runtime_mu); - const auto env_it = g_env_by_isolate.find(isolate); - if (env_it == g_env_by_isolate.end() || env_it->second == nullptr) return; - env = env_it->second; - const auto cb_it = g_promise_reject_callbacks.find(isolate); - if (cb_it == g_promise_reject_callbacks.end() || cb_it->second.IsEmpty()) return; - callback = cb_it->second.Get(isolate); - } - if (env == nullptr || callback.IsEmpty()) return; + napi_agent__* agent = napi_agent__::From(isolate); + napi_env env = agent != nullptr ? agent->principal_env : nullptr; + if (env == nullptr || env->promise_reject_callback.IsEmpty()) return; + v8::Local callback = env->promise_reject_callback.Get(isolate); v8::PromiseRejectEvent event = message.GetEvent(); v8::Local value; @@ -826,6 +736,7 @@ bool GetPromiseHookFunction(napi_env env, return true; } +#ifndef V8_ENABLE_JAVASCRIPT_PROMISE_HOOKS bool HasPromiseHooks(const std::array, 4>& hooks) { for (const auto& hook : hooks) { if (!hook.IsEmpty()) return true; @@ -833,7 +744,6 @@ bool HasPromiseHooks(const std::array, 4>& hooks) { return false; } -#ifndef V8_ENABLE_JAVASCRIPT_PROMISE_HOOKS size_t PromiseHookIndex(v8::PromiseHookType type) { switch (type) { case v8::PromiseHookType::kInit: @@ -853,22 +763,12 @@ void PromiseHookCallback(v8::PromiseHookType type, v8::Local promise, v8::Local parent) { v8::Isolate* isolate = promise->GetIsolate(); - napi_env env = nullptr; - v8::Local callback; - { - std::lock_guard lock(g_runtime_mu); - const auto env_it = g_env_by_isolate.find(isolate); - if (env_it == g_env_by_isolate.end() || env_it->second == nullptr) return; - env = env_it->second; - - const auto hooks_it = g_promise_hooks.find(isolate); - if (hooks_it == g_promise_hooks.end()) return; - - const size_t index = PromiseHookIndex(type); - if (index >= hooks_it->second.size() || hooks_it->second[index].IsEmpty()) return; - callback = hooks_it->second[index].Get(isolate); - } - if (env == nullptr || callback.IsEmpty()) return; + napi_agent__* agent = napi_agent__::From(isolate); + napi_env env = agent != nullptr ? agent->principal_env : nullptr; + if (env == nullptr) return; + const size_t index = PromiseHookIndex(type); + if (index >= env->promise_hooks.size() || env->promise_hooks[index].IsEmpty()) return; + v8::Local callback = env->promise_hooks[index].Get(isolate); v8::HandleScope handle_scope(isolate); v8::Local context = @@ -898,13 +798,9 @@ std::array, 4> LookupPromiseHooksForContext(napi_env env std::array, 4> hooks; if (env == nullptr || isolate == nullptr) return hooks; - std::lock_guard lock(g_runtime_mu); - auto hooks_it = g_promise_hooks.find(isolate); - if (hooks_it == g_promise_hooks.end()) return hooks; - for (size_t i = 0; i < hooks.size(); ++i) { - if (!hooks_it->second[i].IsEmpty()) { - hooks[i] = hooks_it->second[i].Get(isolate); + if (!env->promise_hooks[i].IsEmpty()) { + hooks[i] = env->promise_hooks[i].Get(isolate); } } return hooks; @@ -1691,6 +1587,23 @@ napi_status StructuredCloneImpl( } // namespace +void napi_agent__::Shutdown() { + DisposeProfilers(this); + if (near_heap_limit_installed) { + near_heap_limit_installed = false; + isolate->RemoveNearHeapLimitCallback(NearHeapLimitCallback, 0); + } + near_heap_limit_callback = nullptr; + near_heap_limit_data = nullptr; + fatal_error_callback = nullptr; + oom_error_callback = nullptr; + isolate->CancelTerminateExecution(); + isolate->SetPromiseHook(nullptr); + isolate->SetPromiseRejectCallback(nullptr); + isolate->SetFatalErrorHandler(nullptr); + isolate->SetOOMErrorHandler(nullptr); +} + void NapiV8ApplyPromiseHooksToContext(napi_env env, v8::Local context) { if (env == nullptr || env->isolate == nullptr || context.IsEmpty()) return; @@ -1745,11 +1658,11 @@ napi_status NAPI_CDECL unofficial_napi_attach_env( napi_env env, const unofficial_napi_env_hooks* hooks, uint64_t* accepted_hooks_out) { - if (env == nullptr || env->isolate == nullptr || hooks == nullptr || - accepted_hooks_out == nullptr || + if (env == nullptr || env->isolate == nullptr || env->agent == nullptr || + hooks == nullptr || accepted_hooks_out == nullptr || hooks->size < sizeof(unofficial_napi_env_hooks) || hooks->version != UNOFFICIAL_NAPI_ENV_HOOKS_VERSION || - env->embedder_hooks_attached) { + env->agent->embedder_hooks_attached) { return napi_invalid_arg; } { @@ -1762,17 +1675,17 @@ napi_status NAPI_CDECL unofficial_napi_attach_env( hooks->data)) { return napi_generic_failure; } - auto& fatal = g_fatal_error_callbacks[env->isolate]; - fatal.fatal = hooks->fatal_error_callback; - fatal.oom = hooks->oom_error_callback; } - env->context_token_assign_callback = hooks->context_token_assign_callback; - env->context_token_unassign_callback = hooks->context_token_unassign_callback; - env->context_token_callback_data = hooks->data; - env->enqueue_foreground_task_callback = hooks->enqueue_foreground_task_callback; - env->enqueue_foreground_task_target = hooks->data; - env->embedder_hooks_attached = true; + napi_agent__* agent = env->agent; + agent->fatal_error_callback = hooks->fatal_error_callback; + agent->oom_error_callback = hooks->oom_error_callback; + agent->context_token_assign_callback = hooks->context_token_assign_callback; + agent->context_token_unassign_callback = hooks->context_token_unassign_callback; + agent->context_token_callback_data = hooks->data; + agent->enqueue_foreground_task_callback = hooks->enqueue_foreground_task_callback; + agent->enqueue_foreground_task_target = hooks->data; + agent->embedder_hooks_attached = true; env->isolate->SetFatalErrorHandler( hooks->fatal_error_callback != nullptr ? FatalErrorCallback : nullptr); @@ -1785,67 +1698,33 @@ napi_status NAPI_CDECL unofficial_napi_attach_env( napi_status NAPI_CDECL unofficial_napi_create_env_from_context( v8::Local context, int32_t module_api_version, napi_env* result) { if (result == nullptr || context.IsEmpty()) return napi_invalid_arg; - context->GetIsolate()->SetMicrotasksPolicy(v8::MicrotasksPolicy::kExplicit); auto* env = new (std::nothrow) napi_env__(context, module_api_version); if (env == nullptr) return napi_generic_failure; - { - std::lock_guard lock(g_runtime_mu); - g_env_by_isolate[env->isolate] = env; - } *result = env; return napi_ok; } static napi_status DestroyEnvInstance(napi_env env) { if (env == nullptr) return napi_invalid_arg; - ProfilerState profiler_state; - bool has_profiler_state = false; { std::lock_guard lock(g_runtime_mu); if (g_runtime.platform != nullptr) { g_runtime.platform->ClearForegroundTaskTarget(env->isolate, env); } - auto env_it = g_env_by_isolate.find(env->isolate); - if (env_it != g_env_by_isolate.end() && env_it->second == env) { - g_env_by_isolate.erase(env_it); - } - g_hash_seeds.erase(env->isolate); - auto cb_it = g_promise_reject_callbacks.find(env->isolate); - if (cb_it != g_promise_reject_callbacks.end()) { - cb_it->second.Reset(); - g_promise_reject_callbacks.erase(cb_it); - } - auto hooks_it = g_promise_hooks.find(env->isolate); - if (hooks_it != g_promise_hooks.end()) { - for (auto& hook : hooks_it->second) { - hook.Reset(); - } - g_promise_hooks.erase(hooks_it); - } auto prepare_it = g_prepare_stack_trace_callbacks.find(env); if (prepare_it != g_prepare_stack_trace_callbacks.end()) { ResetPrepareStackTraceState(&prepare_it->second); g_prepare_stack_trace_callbacks.erase(prepare_it); } unofficial_napi_internal::ResetErrorFormattingState(env); - g_fatal_error_callbacks.erase(env->isolate); - g_near_heap_limit_callbacks.erase(env->isolate); - auto profiler_it = g_profiler_states.find(env); - if (profiler_it != g_profiler_states.end()) { - profiler_state = std::move(profiler_it->second); - g_profiler_states.erase(profiler_it); - has_profiler_state = true; - } } - if (env->isolate != nullptr) { - if (has_profiler_state) { - DisposeProfilerState(env, &profiler_state); - } - env->isolate->CancelTerminateExecution(); - env->isolate->SetPromiseHook(nullptr); - env->isolate->SetPromiseRejectCallback(nullptr); - env->isolate->SetFatalErrorHandler(nullptr); - env->isolate->SetOOMErrorHandler(nullptr); + env->promise_reject_callback.Reset(); + for (auto& hook : env->promise_hooks) { + hook.Reset(); + } + // The principal env takes the agent's hooks down with it. + if (env->agent != nullptr && env->agent->principal_env == env) { + env->agent->Shutdown(); } delete env; return napi_ok; @@ -1856,35 +1735,27 @@ napi_status NAPI_CDECL unofficial_napi_configure_near_heap_limit_callback( unofficial_napi_near_heap_limit_callback callback_or_null, void* data, size_t restored_heap_limit) { - if (env == nullptr || env->isolate == nullptr || + if (env == nullptr || env->isolate == nullptr || env->agent == nullptr || (callback_or_null != nullptr && restored_heap_limit != 0) || (callback_or_null == nullptr && data != nullptr)) { return napi_invalid_arg; } + napi_agent__* agent = env->agent; if (callback_or_null != nullptr) { - bool install_provider_callback = false; - { - std::lock_guard lock(g_runtime_mu); - auto [it, inserted] = - g_near_heap_limit_callbacks.try_emplace(env->isolate); - it->second.callback = callback_or_null; - it->second.data = data; - install_provider_callback = inserted; - } - if (install_provider_callback) { - env->isolate->AddNearHeapLimitCallback(NearHeapLimitCallback, env); + agent->near_heap_limit_callback = callback_or_null; + agent->near_heap_limit_data = data; + if (!agent->near_heap_limit_installed) { + agent->near_heap_limit_installed = true; + env->isolate->AddNearHeapLimitCallback(NearHeapLimitCallback, agent); } return napi_ok; } - bool remove_provider_callback = false; - { - std::lock_guard lock(g_runtime_mu); - remove_provider_callback = - g_near_heap_limit_callbacks.erase(env->isolate) != 0; - } - if (remove_provider_callback) { + agent->near_heap_limit_callback = nullptr; + agent->near_heap_limit_data = nullptr; + if (agent->near_heap_limit_installed) { + agent->near_heap_limit_installed = false; env->isolate->RemoveNearHeapLimitCallback( NearHeapLimitCallback, restored_heap_limit); } @@ -1965,22 +1836,15 @@ napi_status NAPI_CDECL unofficial_napi_create_env( ReleaseRuntime(); return napi_generic_failure; } - { - std::lock_guard lock(g_runtime_mu); - g_hash_seeds[isolate] = GenerateHashSeed(); - g_tracking_allocators[allocator.get()] = allocator; - } - auto* scope = new (std::nothrow) UnofficialEnvScope(isolate, allocator); if (scope == nullptr) { DisposeIsolateAndWait(platform, isolate); - { - std::lock_guard lock(g_runtime_mu); - g_tracking_allocators.erase(allocator.get()); - } ReleaseRuntime(); return napi_generic_failure; } + scope->agent = std::make_unique(isolate); + scope->agent->allocator = allocator; + scope->agent->hash_seed = GenerateHashSeed(); v8::Local context = v8::Context::New(isolate); scope->context.emplace(isolate, context); @@ -1989,10 +1853,6 @@ napi_status NAPI_CDECL unofficial_napi_create_env( if (status != napi_ok || scope->env == nullptr) { delete scope; DisposeIsolateAndWait(platform, isolate); - { - std::lock_guard lock(g_runtime_mu); - g_tracking_allocators.erase(allocator.get()); - } ReleaseRuntime(); return (status == napi_ok) ? napi_generic_failure : status; } @@ -2014,6 +1874,7 @@ napi_status ReleaseEnvScope(unofficial_napi_env_owner owner, } v8::Isolate* isolate = scope->isolate; + // Keeps the allocator alive until the isolate is disposed. std::shared_ptr allocator = scope->allocator; delete scope; @@ -2025,12 +1886,7 @@ napi_status ReleaseEnvScope(unofficial_napi_env_owner owner, } DisposeIsolateAndWait(platform, isolate, shutdown_pump_handle); } - if (allocator != nullptr) { - { - std::lock_guard lock(g_runtime_mu); - g_tracking_allocators.erase(allocator.get()); - } - } + allocator.reset(); ReleaseRuntime(); return status; } @@ -2336,13 +2192,7 @@ napi_status NAPI_CDECL unofficial_napi_set_promise_reject_callback(napi_env env, if (env == nullptr || env->isolate == nullptr || callback == nullptr) return napi_invalid_arg; v8::Local raw = napi_v8_unwrap_value(callback); if (!raw->IsFunction()) return napi_function_expected; - { - std::lock_guard lock(g_runtime_mu); - g_env_by_isolate[env->isolate] = env; - auto& slot = g_promise_reject_callbacks[env->isolate]; - slot.Reset(); - slot.Reset(env->isolate, raw.As()); - } + env->promise_reject_callback.Reset(env->isolate, raw.As()); env->isolate->SetPromiseRejectCallback(PromiseRejectCallback); return napi_ok; } @@ -2362,31 +2212,15 @@ napi_status NAPI_CDECL unofficial_napi_set_promise_hooks(napi_env env, return napi_function_expected; } - std::array, 4> persistent_hooks; for (size_t i = 0; i < hooks.size(); ++i) { + env->promise_hooks[i].Reset(); if (!hooks[i].IsEmpty()) { - persistent_hooks[i].Reset(env->isolate, hooks[i]); - } - } - const bool has_hooks = HasPromiseHooks(persistent_hooks); - - { - std::lock_guard lock(g_runtime_mu); - g_env_by_isolate[env->isolate] = env; - - auto existing = g_promise_hooks.find(env->isolate); - if (existing != g_promise_hooks.end()) { - for (auto& hook : existing->second) { - hook.Reset(); - } - } - - if (has_hooks) { - g_promise_hooks[env->isolate] = std::move(persistent_hooks); - } else if (existing != g_promise_hooks.end()) { - g_promise_hooks.erase(existing); + env->promise_hooks[i].Reset(env->isolate, hooks[i]); } } +#ifndef V8_ENABLE_JAVASCRIPT_PROMISE_HOOKS + const bool has_hooks = HasPromiseHooks(env->promise_hooks); +#endif #ifdef V8_ENABLE_JAVASCRIPT_PROMISE_HOOKS NapiV8ApplyPromiseHooksToContext(env, env->context()); @@ -2462,16 +2296,14 @@ napi_status NAPI_CDECL unofficial_napi_mark_promise_as_handled( return napi_ok; } - v8::Local callback; - { - std::lock_guard lock(g_runtime_mu); - const auto cb_it = g_promise_reject_callbacks.find(isolate); - if (cb_it == g_promise_reject_callbacks.end() || cb_it->second.IsEmpty()) { - return napi_ok; - } - callback = cb_it->second.Get(isolate); + // The reject callback is dispatched by the agent's principal env, as in + // PromiseRejectCallback. + napi_agent__* agent = env->agent; + napi_env reject_env = agent != nullptr ? agent->principal_env : nullptr; + if (reject_env == nullptr || reject_env->promise_reject_callback.IsEmpty()) { + return napi_ok; } - if (callback.IsEmpty()) return napi_ok; + v8::Local callback = reject_env->promise_reject_callback.Get(isolate); v8::Local args[3] = { v8::Integer::New( @@ -2701,13 +2533,9 @@ napi_status NAPI_CDECL unofficial_napi_get_hash_seed(napi_env env, if (env == nullptr || env->isolate == nullptr || hash_seed_out == nullptr) { return napi_invalid_arg; } - { - std::lock_guard lock(g_runtime_mu); - auto it = g_hash_seeds.find(env->isolate); - if (it != g_hash_seeds.end()) { - *hash_seed_out = it->second; - return napi_ok; - } + if (env->agent != nullptr && env->agent->hash_seed != 0) { + *hash_seed_out = env->agent->hash_seed; + return napi_ok; } *hash_seed_out = env->isolate->GetHashSeed(); return napi_ok; @@ -2745,12 +2573,10 @@ napi_status NAPI_CDECL unofficial_napi_get_heap_statistics( stats_out->used_global_handles_size = stats.used_global_handles_size(); stats_out->external_memory = stats.external_memory(); stats_out->array_buffer_memory = 0; - { - std::lock_guard lock(g_runtime_mu); - auto it = g_tracking_allocators.find(env->isolate->GetArrayBufferAllocator()); - if (it != g_tracking_allocators.end() && it->second) { - stats_out->array_buffer_memory = it->second->total_mem_usage(); - } + if (env->agent != nullptr && env->agent->allocator != nullptr) { + stats_out->array_buffer_memory = + static_cast(env->agent->allocator.get()) + ->total_mem_usage(); } return napi_ok; } @@ -2817,21 +2643,18 @@ napi_status NAPI_CDECL unofficial_napi_profile_start( *result_out = unofficial_napi_profile_start_ok; *profile_out = nullptr; if (!IsEnvThreadEntered(env)) return napi_cannot_run_js; + napi_agent__* agent = env->agent; + if (agent == nullptr) return napi_invalid_arg; if (kind == unofficial_napi_profile_heap) { - { - std::lock_guard lock(g_runtime_mu); - auto it = g_profiler_states.find(env); - if (it != g_profiler_states.end() && - std::any_of(it->second.active_profiles.begin(), - it->second.active_profiles.end(), - [](unofficial_napi_profile profile) { - return profile != nullptr && - profile->kind == unofficial_napi_profile_heap; - })) { - *result_out = unofficial_napi_profile_start_busy; - return napi_ok; - } + if (std::any_of(agent->active_profiles.begin(), + agent->active_profiles.end(), + [](unofficial_napi_profile profile) { + return profile != nullptr && + profile->kind == unofficial_napi_profile_heap; + })) { + *result_out = unofficial_napi_profile_start_busy; + return napi_ok; } if (!env->isolate->GetHeapProfiler()->StartSamplingHeapProfiler()) { *result_out = unofficial_napi_profile_start_busy; @@ -2843,24 +2666,16 @@ napi_status NAPI_CDECL unofficial_napi_profile_start( return napi_generic_failure; } profile->kind = kind; - { - std::lock_guard lock(g_runtime_mu); - EnsureProfilerState(env).active_profiles.push_back(profile); - } + agent->active_profiles.push_back(profile); *profile_out = profile; return napi_ok; } - v8::CpuProfiler* cpu_profiler = nullptr; - { - std::lock_guard lock(g_runtime_mu); - ProfilerState& state = EnsureProfilerState(env); - if (state.cpu_profiler == nullptr) { - state.cpu_profiler = v8::CpuProfiler::New(env->isolate); - if (state.cpu_profiler == nullptr) return napi_generic_failure; - } - cpu_profiler = state.cpu_profiler; + if (agent->cpu_profiler == nullptr) { + agent->cpu_profiler = v8::CpuProfiler::New(env->isolate); + if (agent->cpu_profiler == nullptr) return napi_generic_failure; } + v8::CpuProfiler* cpu_profiler = agent->cpu_profiler; v8::CpuProfilingResult result = cpu_profiler->Start( v8::CpuProfilingOptions{v8::CpuProfilingMode::kLeafNodeLineNumbers, @@ -2882,13 +2697,7 @@ napi_status NAPI_CDECL unofficial_napi_profile_start( } profile->kind = kind; profile->provider_id = static_cast(result.id); - { - std::lock_guard lock(g_runtime_mu); - auto it = g_profiler_states.find(env); - if (it != g_profiler_states.end()) { - it->second.active_profiles.push_back(profile); - } - } + agent->active_profiles.push_back(profile); *profile_out = profile; return napi_ok; } @@ -2904,21 +2713,15 @@ napi_status NAPI_CDECL unofficial_napi_profile_stop( *json_out = nullptr; if (!IsEnvThreadEntered(env)) return napi_cannot_run_js; - v8::CpuProfiler* cpu_profiler = nullptr; - unofficial_napi_profile_kind kind = unofficial_napi_profile_cpu; - uint32_t provider_id = 0; - { - std::lock_guard lock(g_runtime_mu); - auto it = g_profiler_states.find(env); - if (it == g_profiler_states.end()) return napi_invalid_arg; - auto active_it = std::find(it->second.active_profiles.begin(), - it->second.active_profiles.end(), profile); - if (active_it == it->second.active_profiles.end()) return napi_invalid_arg; - kind = profile->kind; - provider_id = profile->provider_id; - it->second.active_profiles.erase(active_it); - cpu_profiler = it->second.cpu_profiler; - } + napi_agent__* agent = env->agent; + if (agent == nullptr) return napi_invalid_arg; + auto active_it = std::find(agent->active_profiles.begin(), + agent->active_profiles.end(), profile); + if (active_it == agent->active_profiles.end()) return napi_invalid_arg; + const unofficial_napi_profile_kind kind = profile->kind; + const uint32_t provider_id = profile->provider_id; + agent->active_profiles.erase(active_it); + v8::CpuProfiler* cpu_profiler = agent->cpu_profiler; if (kind == unofficial_napi_profile_heap) { std::string json; diff --git a/v8/src/unofficial_napi_contextify.cc b/v8/src/unofficial_napi_contextify.cc index ed23b40675..0ded77d73d 100644 --- a/v8/src/unofficial_napi_contextify.cc +++ b/v8/src/unofficial_napi_contextify.cc @@ -592,12 +592,13 @@ std::string SerializeModuleRequestKey(const std::string& specifier, return key; } +// The isolate's principal env, if it has module_wrap state. napi_env GetModuleWrapEnvForIsolate(v8::Isolate* isolate) { + napi_agent__* agent = napi_agent__::From(isolate); + napi_env env = agent != nullptr ? agent->principal_env : nullptr; + if (env == nullptr) return nullptr; std::lock_guard lock(g_module_wrap_mu); - for (auto& entry : g_module_wrap_states) { - if (entry.first != nullptr && entry.first->isolate == isolate) return entry.first; - } - return nullptr; + return g_module_wrap_states.count(env) != 0 ? env : nullptr; } ModuleWrapBindingState* GetModuleWrapState(napi_env env) { @@ -789,9 +790,10 @@ void CleanupContextRecords(void* arg) { auto it = g_context_records.find(env); if (it == g_context_records.end()) return; for (auto& rec : it->second) { - if (rec.key_ref != nullptr && env->context_token_unassign_callback != nullptr) { - env->context_token_unassign_callback( - env, rec.key_ref, env->context_token_callback_data); + if (rec.key_ref != nullptr && env->agent != nullptr && + env->agent->context_token_unassign_callback != nullptr) { + env->agent->context_token_unassign_callback( + env, rec.key_ref, env->agent->context_token_callback_data); } if (rec.key_ref != nullptr) { napi_delete_reference(env, rec.key_ref); @@ -1323,8 +1325,9 @@ bool StoreRecord(napi_env env, } record.context.Reset(env->isolate, context); record.own_microtask_queue = std::move(own_microtask_queue); - if (env->context_token_assign_callback != nullptr) { - env->context_token_assign_callback(env, record.key_ref, env->context_token_callback_data); + if (env->agent != nullptr && env->agent->context_token_assign_callback != nullptr) { + env->agent->context_token_assign_callback( + env, record.key_ref, env->agent->context_token_callback_data); } g_context_records[env].push_back(std::move(record)); return true; From 2ff2331bd21e95012012571d3d2a8bee36c3b7b6 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Fri, 23 Oct 2026 16:21:04 +0200 Subject: [PATCH 002/150] Give each QuickJS runtime an agent and fix the callback realm napi_env__ carried the runtime-level state of its JSRuntime and a switchable current_context_ that vm contexts swapped in and out at 16 napi_env_context_scope__ sites. Every napi_value, ref and deferred also remembered the context it was made in, so a value could be tagged with the wrong realm when a subsystem wrapped it. napi_agent__ (internal/napi_agent.{h,cc}) now owns the runtime-level state: the handle-scope stack, the pending exception (freed with the runtime, so last_exception_context_ is gone), external memory, the embedder hooks, continuation data and promise context frames. It also owns the runtime-wide promise, rejection, import.meta and dynamic-import hooks, installed with the agent as opaque and dispatched to the env. The env keeps one JSContext that never changes. current_context_, main_context(), current_context() and napi_env_context_scope__ are deleted, and values hold only their runtime. QuickJS does not switch realms for C-function-data calls, so the trampoline got the caller's context and took the env from its opaque. A native function made in the main realm and called from a vm script then saw the vm global and created objects there. The trampoline now takes the env from the function's own data and runs in that env's context, as V8 and Node do. Native callbacks are refused once env teardown starts; before, only calls from the main context were. Each runtime still has one env; there is no ABI change. Co-Authored-By: Claude Opus 5.5 --- quickjs/CMakeLists.txt | 1 + quickjs/src/internal/napi_agent.cc | 396 +++++++++++++++++++++++ quickjs/src/internal/napi_agent.h | 132 ++++++++ quickjs/src/internal/napi_contextify.cc | 12 +- quickjs/src/internal/napi_deferred.cc | 24 +- quickjs/src/internal/napi_deferred.h | 6 +- quickjs/src/internal/napi_env.cc | 182 ++++------- quickjs/src/internal/napi_env.h | 68 ++-- quickjs/src/internal/napi_external.cc | 9 + quickjs/src/internal/napi_external.h | 2 + quickjs/src/internal/napi_function.cc | 13 +- quickjs/src/internal/napi_module_wrap.cc | 33 -- quickjs/src/internal/napi_module_wrap.h | 11 - quickjs/src/internal/napi_promises.cc | 229 ++----------- quickjs/src/internal/napi_promises.h | 36 +-- quickjs/src/internal/napi_ref.cc | 37 +-- quickjs/src/internal/napi_ref.h | 1 - quickjs/src/internal/napi_scope.cc | 17 +- quickjs/src/internal/napi_scope.h | 1 - quickjs/src/internal/napi_util.cc | 1 - quickjs/src/internal/napi_value.cc | 43 +-- quickjs/src/internal/napi_value.h | 9 +- quickjs/src/js_native_api_quickjs.cc | 33 +- quickjs/src/unofficial_napi.cc | 99 ++++-- 24 files changed, 779 insertions(+), 616 deletions(-) create mode 100644 quickjs/src/internal/napi_agent.cc create mode 100644 quickjs/src/internal/napi_agent.h diff --git a/quickjs/CMakeLists.txt b/quickjs/CMakeLists.txt index 7faa1cd554..c1f1e2dd35 100644 --- a/quickjs/CMakeLists.txt +++ b/quickjs/CMakeLists.txt @@ -62,6 +62,7 @@ add_library(napi_quickjs STATIC ../lib/src/napi_text.cc ../lib/src/napi_typedarray_metadata.cc src/js_native_api_quickjs.cc + src/internal/napi_agent.cc src/internal/napi_callback_info.cc src/internal/napi_buffer.cc src/internal/napi_callsite.cc diff --git a/quickjs/src/internal/napi_agent.cc b/quickjs/src/internal/napi_agent.cc new file mode 100644 index 0000000000..92a5dd066f --- /dev/null +++ b/quickjs/src/internal/napi_agent.cc @@ -0,0 +1,396 @@ +#include "internal/napi_agent.h" + +#include "internal/napi_env.h" +#include "internal/napi_module_wrap.h" +#include "internal/napi_promises.h" +#include "internal/napi_util.h" + +#include +#include + +namespace +{ +void *js_identity(JSValueConst value) +{ + return JS_IsObject(value) ? JS_VALUE_GET_PTR(value) : nullptr; +} +} // namespace + +napi_agent__::napi_agent__(JSRuntime *runtime) + : runtime_{runtime}, + scopes_{this} +{ +} + +// JSValues are released by clear_values() during env teardown, while the +// runtime is still alive. +napi_agent__::~napi_agent__() = default; + +JSRuntime *napi_agent__::runtime() const +{ + return runtime_; +} + +napi_env napi_agent__::principal_env() const +{ + return principal_env_; +} + +void napi_agent__::set_principal_env(napi_env env) +{ + principal_env_ = env; +} + +napi_env napi_agent__::env_for_context(JSContext *ctx) const +{ + if (ctx != nullptr) + { + auto *env = static_cast(JS_GetContextOpaque(ctx)); + if (env != nullptr && env->agent() == this) + return env; + } + return principal_env_; +} + +bool napi_agent__::open_root_scope(napi_env env) +{ + if (root_scope_ == nullptr) + { + root_scope_ = create_scope(env, nullptr); + current_scope_ = root_scope_; + } + return root_scope_ != nullptr; +} + +void napi_agent__::close_root_scope() +{ + napi_scope__ *root = scope_from_handle(root_scope_); + if (root != nullptr) + root->close(); +} + +void napi_agent__::close_scopes() +{ + scopes_.close(); + current_scope_ = nullptr; + root_scope_ = nullptr; +} + +napi_handle_scope napi_agent__::root_scope() const +{ + return root_scope_; +} + +napi_handle_scope napi_agent__::current_scope() const +{ + return current_scope_; +} + +void napi_agent__::set_current_scope(napi_handle_scope scope) +{ + current_scope_ = scope; +} + +bool napi_agent__::is_current_scope(napi_handle_scope scope) const +{ + return current_scope_ == scope; +} + +napi_handle_scope napi_agent__::create_scope(napi_env env, napi_handle_scope parent) +{ + auto *handle = scopes_.allocate(env, parent); + return reinterpret_cast(handle); +} + +void napi_agent__::destroy_scope(napi_handle_scope scope) +{ + scopes_.destroy(reinterpret_cast(scope)); +} + +napi_scope__ *napi_agent__::scope_from_handle(napi_handle_scope scope_handle) const +{ + auto scope = reinterpret_cast(scope_handle); +#ifndef NDEBUG + if (scope != nullptr) + assert(scopes_.owns(scope)); +#endif + return scope; +} + +bool napi_agent__::owns_scope(napi_scope__ *scope) const +{ + return scopes_.owns(scope); +} + +size_t napi_agent__::scope_storage_slot_count() const +{ + return scopes_.storage_slot_count(); +} + +size_t napi_agent__::active_scope_count() const +{ + return scopes_.count_active(); +} + +bool napi_agent__::has_pending_exception() const +{ + return has_pending_exception_; +} + +void napi_agent__::set_pending_exception(JSValue exception) +{ + clear_pending_exception(); + pending_exception_ = exception; + has_pending_exception_ = true; +} + +JSValue napi_agent__::take_pending_exception() +{ + if (!has_pending_exception_) + return JS_UNDEFINED; + + JSValue exception = pending_exception_; + pending_exception_ = JS_UNDEFINED; + has_pending_exception_ = false; + return exception; +} + +void napi_agent__::clear_pending_exception() +{ + if (!has_pending_exception_) + return; + + JS_FreeValueRT(runtime_, pending_exception_); + pending_exception_ = JS_UNDEFINED; + has_pending_exception_ = false; +} + +int64_t napi_agent__::adjust_external_memory(int64_t change_in_bytes) +{ + if (change_in_bytes > 0 && + external_memory_ > std::numeric_limits::max() - change_in_bytes) + { + external_memory_ = std::numeric_limits::max(); + } + else if (change_in_bytes < 0 && + external_memory_ < std::numeric_limits::min() - change_in_bytes) + { + external_memory_ = std::numeric_limits::min(); + } + else + { + external_memory_ += change_in_bytes; + } + return external_memory_; +} + +bool napi_agent__::attach_embedder_hooks(const unofficial_napi_env_hooks &hooks) +{ + if (embedder_hooks_attached_) + return false; + embedder_hooks_ = hooks; + embedder_hooks_attached_ = true; + return true; +} + +void napi_agent__::attach_promise_hook() +{ + JS_SetPromiseHook(runtime_, napi_agent__::promise_hook, this); +} + +void napi_agent__::set_rejection_tracking(bool enabled) +{ + JS_SetHostPromiseRejectionTracker( + runtime_, enabled ? napi_agent__::rejection_tracker : nullptr, this); +} + +void napi_agent__::clear_promise_hooks() +{ + JS_SetPromiseHook(runtime_, nullptr, nullptr); + JS_SetHostPromiseRejectionTracker(runtime_, nullptr, nullptr); +} + +void napi_agent__::attach_module_hooks() +{ + JS_SetModuleImportMetaInitFunc(runtime_, napi_agent__::import_meta_init, this); + JS_SetModuleDynamicImportFunc(runtime_, napi_agent__::dynamic_import, this); +} + +void napi_agent__::clear_module_hooks() +{ + JS_SetModuleImportMetaInitFunc(runtime_, nullptr, nullptr); + JS_SetModuleDynamicImportFunc(runtime_, nullptr, nullptr); +} + +JSValueConst napi_agent__::continuation_preserved_embedder_data() const +{ + return continuation_preserved_embedder_data_; +} + +void napi_agent__::set_continuation_preserved_embedder_data(JSValueConst value) +{ + replace_stored_value(&continuation_preserved_embedder_data_, value); +} + +void napi_agent__::capture_context_frame(JSValueConst promise) +{ + void *identity = js_identity(promise); + if (identity == nullptr || JS_IsUndefined(continuation_preserved_embedder_data_)) + return; + + JSValue frame = JS_DupValueRT(runtime_, continuation_preserved_embedder_data_); + auto it = promise_context_frames_.find(identity); + if (it != promise_context_frames_.end()) + { + JS_FreeValueRT(runtime_, it->second); + it->second = frame; + return; + } + promise_context_frames_.emplace(identity, frame); +} + +void napi_agent__::enter_context_frame(JSValueConst promise) +{ + promise_context_frame_stack_.push_back( + JS_DupValueRT(runtime_, continuation_preserved_embedder_data_)); + + JSValueConst frame = JS_UNDEFINED; + void *identity = js_identity(promise); + if (identity != nullptr) + { + auto it = promise_context_frames_.find(identity); + if (it != promise_context_frames_.end()) + frame = it->second; + } + replace_stored_value(&continuation_preserved_embedder_data_, frame); +} + +void napi_agent__::leave_context_frame(JSValueConst promise) +{ + if (!promise_context_frame_stack_.empty()) + { + JSValue previous = promise_context_frame_stack_.back(); + promise_context_frame_stack_.pop_back(); + JS_FreeValueRT(runtime_, continuation_preserved_embedder_data_); + continuation_preserved_embedder_data_ = previous; + } + + (void)promise; +} + +void napi_agent__::release_context_frame(JSValueConst promise) +{ + void *identity = js_identity(promise); + if (identity == nullptr) + return; + + auto it = promise_context_frames_.find(identity); + if (it != promise_context_frames_.end()) + { + JS_FreeValueRT(runtime_, it->second); + promise_context_frames_.erase(it); + } +} + +void napi_agent__::clear_values() +{ + clear_pending_exception(); + + JS_FreeValueRT(runtime_, continuation_preserved_embedder_data_); + continuation_preserved_embedder_data_ = JS_UNDEFINED; + + for (auto &entry : promise_context_frames_) + JS_FreeValueRT(runtime_, entry.second); + promise_context_frames_.clear(); + + for (auto &frame : promise_context_frame_stack_) + JS_FreeValueRT(runtime_, frame); + promise_context_frame_stack_.clear(); +} + +void napi_agent__::replace_stored_value(JSValue *target, JSValueConst value) +{ + JS_FreeValueRT(runtime_, *target); + *target = JS_DupValueRT(runtime_, value); +} + +void napi_agent__::promise_hook(JSContext *ctx, + JSPromiseHookType type, + JSValueConst promise, + JSValueConst parent_promise, + void *opaque) +{ + auto *agent = static_cast(opaque); + if (agent == nullptr || ctx == nullptr || JS_GetRuntime(ctx) != agent->runtime_) + return; + + if (type == JS_PROMISE_HOOK_INIT) + agent->capture_context_frame(promise); + else if (type == JS_PROMISE_HOOK_BEFORE) + agent->enter_context_frame(promise); + + napi_env env = agent->env_for_context(ctx); + if (napi_util__::check_env(env)) + { + if (type == JS_PROMISE_HOOK_INIT) + { + JSValueConst argv[] = {promise, parent_promise}; + env->promises().call_hook(static_cast(type), 2, argv); + } + else + { + JSValueConst argv[] = {promise}; + env->promises().call_hook(static_cast(type), 1, argv); + } + } + + if (type == JS_PROMISE_HOOK_AFTER) + agent->leave_context_frame(promise); + else if (type == JS_PROMISE_HOOK_RESOLVE) + agent->release_context_frame(promise); +} + +void napi_agent__::rejection_tracker(JSContext *ctx, + JSValueConst promise, + JSValueConst reason, + bool is_handled, + void *opaque) +{ + auto *agent = static_cast(opaque); + if (agent == nullptr || ctx == nullptr || JS_GetRuntime(ctx) != agent->runtime_) + return; + + agent->release_context_frame(promise); + + napi_env env = agent->env_for_context(ctx); + if (napi_util__::check_env(env)) + env->promises().call_reject_callback(promise, reason, is_handled); +} + +int napi_agent__::import_meta_init(JSContext *ctx, + JSModuleDef *module, + JSValueConst meta, + void *opaque) +{ + auto *agent = static_cast(opaque); + napi_env env = agent == nullptr ? nullptr : agent->env_for_context(ctx); + if (!napi_util__::check_env(env)) + return 0; + return env->module_wrap().initialize_import_meta(module, meta); +} + +JSValue napi_agent__::dynamic_import(JSContext *ctx, + JSModuleDef *referrer, + JSValueConst referrer_name, + JSValueConst specifier, + JSValueConst attributes, + JSModuleImportPhaseEnum phase, + void *opaque) +{ + auto *agent = static_cast(opaque); + napi_env env = agent == nullptr ? nullptr : agent->env_for_context(ctx); + if (!napi_util__::check_env(env)) + return JS_ThrowTypeError(ctx, "Dynamic import callback is not registered"); + return env->module_wrap().import_module_dynamically(referrer, referrer_name, specifier, + attributes, phase); +} diff --git a/quickjs/src/internal/napi_agent.h b/quickjs/src/internal/napi_agent.h new file mode 100644 index 0000000000..ae144ca84d --- /dev/null +++ b/quickjs/src/internal/napi_agent.h @@ -0,0 +1,132 @@ +#ifndef NAPI_QUICKJS_AGENT_H_ +#define NAPI_QUICKJS_AGENT_H_ + +#include "../../../include/js_native_api.h" +#include "../../../include/unofficial_napi.h" +#include "napi_allocator.h" +#include "napi_scope.h" + +#include +#include +#include +#include + +// State of one QuickJS runtime, shared by every env made on it: handle +// scopes, the pending exception, runtime-wide engine hooks and async context +// frames. An env's realm (its JSContext) lives on the env. +struct napi_agent__ +{ + explicit napi_agent__(JSRuntime *runtime); + ~napi_agent__(); + + napi_agent__(const napi_agent__ &) = delete; + napi_agent__ &operator=(const napi_agent__ &) = delete; + + JSRuntime *runtime() const; + + napi_env principal_env() const; + void set_principal_env(napi_env env); + // The env of the realm `ctx` belongs to, or the principal env. + napi_env env_for_context(JSContext *ctx) const; + + // Handle scopes. Values in them are usable with every env of this agent. + bool open_root_scope(napi_env env); + void close_root_scope(); + void close_scopes(); + napi_handle_scope root_scope() const; + napi_handle_scope current_scope() const; + void set_current_scope(napi_handle_scope scope); + bool is_current_scope(napi_handle_scope scope) const; + napi_handle_scope create_scope(napi_env env, napi_handle_scope parent); + void destroy_scope(napi_handle_scope scope); + napi_scope__ *scope_from_handle(napi_handle_scope scope) const; + bool owns_scope(napi_scope__ *scope) const; + size_t scope_storage_slot_count() const; + size_t active_scope_count() const; + + template + void for_each_active_scope(Fn fn) const + { + for (const auto &scope : scopes_) + fn(scope); + } + + // Pending exception, kept until N-API hands it back to JavaScript. + bool has_pending_exception() const; + void set_pending_exception(JSValue exception); + JSValue take_pending_exception(); + void clear_pending_exception(); + + int64_t adjust_external_memory(int64_t change_in_bytes); + bool attach_embedder_hooks(const unofficial_napi_env_hooks &hooks); + + // Runtime-wide engine hooks. They dispatch to the env of the realm the + // engine reports. + void attach_promise_hook(); + void set_rejection_tracking(bool enabled); + void clear_promise_hooks(); + void attach_module_hooks(); + void clear_module_hooks(); + + // Continuation-preserved embedder data and the frame captured per promise. + JSValueConst continuation_preserved_embedder_data() const; + void set_continuation_preserved_embedder_data(JSValueConst value); + void capture_context_frame(JSValueConst promise); + void enter_context_frame(JSValueConst promise); + void leave_context_frame(JSValueConst promise); + void release_context_frame(JSValueConst promise); + + // Frees every JSValue the agent holds. Must run before the runtime is freed. + void clear_values(); + +private: + static void promise_hook(JSContext *ctx, + JSPromiseHookType type, + JSValueConst promise, + JSValueConst parent_promise, + void *opaque); + static void rejection_tracker(JSContext *ctx, + JSValueConst promise, + JSValueConst reason, + bool is_handled, + void *opaque); + static int import_meta_init(JSContext *ctx, + JSModuleDef *module, + JSValueConst meta, + void *opaque); + static JSValue dynamic_import(JSContext *ctx, + JSModuleDef *referrer, + JSValueConst referrer_name, + JSValueConst specifier, + JSValueConst attributes, + JSModuleImportPhaseEnum phase, + void *opaque); + + void replace_stored_value(JSValue *target, JSValueConst value); + + JSRuntime *runtime_ = nullptr; + napi_env principal_env_ = nullptr; + + // Handle scope stack. + napi_allocator__ scopes_; + napi_handle_scope root_scope_ = nullptr; + napi_handle_scope current_scope_ = nullptr; + + // Pending exception. + JSValue pending_exception_ = JS_UNDEFINED; + bool has_pending_exception_ = false; + + // Declared external memory. + int64_t external_memory_ = 0; + + // Embedder hooks, attached once. + bool embedder_hooks_attached_ = false; + unofficial_napi_env_hooks embedder_hooks_{}; + + // Async context tracking. + JSValue continuation_preserved_embedder_data_ = JS_UNDEFINED; + std::unordered_map promise_context_frames_; + std::vector promise_context_frame_stack_; +}; + +#endif // NAPI_QUICKJS_AGENT_H_ diff --git a/quickjs/src/internal/napi_contextify.cc b/quickjs/src/internal/napi_contextify.cc index 7db6b3b42d..49aa28203c 100644 --- a/quickjs/src/internal/napi_contextify.cc +++ b/quickjs/src/internal/napi_contextify.cc @@ -216,7 +216,6 @@ namespace quickjs::detail if (rc < 0) { JS_FreePropertyEnum(source_ctx, props, prop_count); - napi_env_context_scope__ target_scope{env, target_ctx}; return napi_util__::return_pending_if_caught(env, "Failed to define context property"); } } @@ -235,7 +234,6 @@ namespace quickjs::detail record->global, JS_GPN_STRING_MASK | JS_GPN_SYMBOL_MASK) < 0) { - napi_env_context_scope__ child_scope{record->env, record->ctx}; return napi_util__::return_pending_if_caught(record->env, "Failed to enumerate context baseline"); } @@ -267,7 +265,6 @@ namespace quickjs::detail record->global, JS_GPN_STRING_MASK | JS_GPN_SYMBOL_MASK) < 0) { - napi_env_context_scope__ child_scope{record->env, record->ctx}; return napi_util__::return_pending_if_caught(record->env, "Failed to enumerate context globals"); } @@ -281,7 +278,6 @@ namespace quickjs::detail if (sandbox_has < 0) { JS_FreePropertyEnum(record->ctx, props, prop_count); - napi_env_context_scope__ parent_scope{record->env, record->parent_ctx}; return napi_util__::return_pending_if_caught(record->env, "Failed to inspect sandbox property"); } @@ -293,7 +289,6 @@ namespace quickjs::detail if (has < 0) { JS_FreePropertyEnum(record->ctx, props, prop_count); - napi_env_context_scope__ child_scope{record->env, record->ctx}; return napi_util__::return_pending_if_caught(record->env, "Failed to read context global"); } if (has == 0) @@ -310,7 +305,6 @@ namespace quickjs::detail if (rc < 0) { JS_FreePropertyEnum(record->ctx, props, prop_count); - napi_env_context_scope__ parent_scope{record->env, record->parent_ctx}; return napi_util__::return_pending_if_caught(record->env, "Failed to write sandbox property"); } } @@ -799,7 +793,6 @@ namespace quickjs::detail env_->module_wrap().unregister_dynamic_import_referrer(filename, host_defined_option_id); return sync_status; } - napi_env_context_scope__ child_scope{env_, record->ctx}; JSEvalOptions options{ .version = JS_EVAL_OPTIONS_VERSION, .eval_flags = JS_EVAL_TYPE_GLOBAL, @@ -822,7 +815,7 @@ namespace quickjs::detail return sync_status; } env_->module_wrap().unregister_dynamic_import_referrer(filename, host_defined_option_id); - *result_out = env_->wrap_value_in_current_scope(record->ctx, result, true); + *result_out = env_->wrap_value_in_current_scope(result, true); return (*result_out == nullptr) ? napi_generic_failure : napi_ok; } @@ -910,7 +903,6 @@ namespace quickjs::detail } JSContext *compile_ctx = record == nullptr ? ctx_ : record->ctx; - napi_env_context_scope__ compile_scope{env_, compile_ctx}; JSValue fn = JS_UNDEFINED; bool have_fn = false; @@ -949,7 +941,7 @@ namespace quickjs::detail if (!source_url.empty()) napi_util__::set_string_property(compile_ctx, out, "sourceURL", source_url); JS_SetPropertyStr(compile_ctx, out, "sourceMapURL", JS_UNDEFINED); - *result_out = env_->wrap_value_in_current_scope(compile_ctx, out, true); + *result_out = env_->wrap_value_in_current_scope(out, true); return (*result_out == nullptr) ? napi_generic_failure : napi_ok; } diff --git a/quickjs/src/internal/napi_deferred.cc b/quickjs/src/internal/napi_deferred.cc index 2931a26bc1..f5a6a7cb44 100644 --- a/quickjs/src/internal/napi_deferred.cc +++ b/quickjs/src/internal/napi_deferred.cc @@ -3,9 +3,8 @@ #include "internal/napi_env.h" #include "internal/napi_value.h" -napi_deferred__::napi_deferred__(napi_env env, JSContext *context, JSValue resolve, JSValue reject) +napi_deferred__::napi_deferred__(napi_env env, JSValue resolve, JSValue reject) : env_{env}, - context_{context}, resolve_{resolve}, reject_{reject} { @@ -16,16 +15,14 @@ napi_deferred__::~napi_deferred__() if (env_ == nullptr) return; - napi_env env = env_; - JSContext *context = context_; + JSContext *context = env_->context(); JSValue resolve = resolve_; JSValue reject = reject_; env_ = nullptr; - context_ = nullptr; resolve_ = JS_UNDEFINED; reject_ = JS_UNDEFINED; - if (env != nullptr && context != nullptr) + if (context != nullptr) { JS_FreeValue(context, resolve); JS_FreeValue(context, reject); @@ -37,16 +34,11 @@ napi_env napi_deferred__::env() const return env_; } -JSContext *napi_deferred__::context() const +napi_deferred__ *napi_deferred__::create(napi_env env, JSValue resolve, JSValue reject) { - return context_; -} - -napi_deferred__ *napi_deferred__::create(napi_env env, JSContext *context, JSValue resolve, JSValue reject) -{ - if (env == nullptr || context == nullptr) + if (env == nullptr) return nullptr; - return env->create_deferred(context, resolve, reject); + return env->create_deferred(resolve, reject); } void napi_deferred__::destroy(napi_deferred__ *deferred) @@ -62,11 +54,11 @@ void napi_deferred__::destroy(napi_deferred__ *deferred) JSValue napi_deferred__::call_resolve(napi_value resolution) { JSValue arg = napi_quickjs_value_inner(env_, resolution); - return JS_Call(context_, resolve_, JS_UNDEFINED, 1, &arg); + return JS_Call(env_->context(), resolve_, JS_UNDEFINED, 1, &arg); } JSValue napi_deferred__::call_reject(napi_value rejection) { JSValue arg = napi_quickjs_value_inner(env_, rejection); - return JS_Call(context_, reject_, JS_UNDEFINED, 1, &arg); + return JS_Call(env_->context(), reject_, JS_UNDEFINED, 1, &arg); } diff --git a/quickjs/src/internal/napi_deferred.h b/quickjs/src/internal/napi_deferred.h index 5e7f6fe733..d354833b18 100644 --- a/quickjs/src/internal/napi_deferred.h +++ b/quickjs/src/internal/napi_deferred.h @@ -7,8 +7,8 @@ struct napi_deferred__ { - napi_deferred__(napi_env env, JSContext *context, JSValue resolve, JSValue reject); - static napi_deferred__ *create(napi_env env, JSContext *context, JSValue resolve, JSValue reject); + napi_deferred__(napi_env env, JSValue resolve, JSValue reject); + static napi_deferred__ *create(napi_env env, JSValue resolve, JSValue reject); static void destroy(napi_deferred__ *deferred); ~napi_deferred__(); @@ -18,14 +18,12 @@ struct napi_deferred__ napi_deferred__ &operator=(napi_deferred__ &&other) = delete; napi_env env() const; - JSContext *context() const; JSValue call_resolve(napi_value resolution); JSValue call_reject(napi_value rejection); private: // Owning environment and stored promise callbacks. napi_env env_ = nullptr; - JSContext *context_ = nullptr; JSValue resolve_ = JS_UNDEFINED; JSValue reject_ = JS_UNDEFINED; }; diff --git a/quickjs/src/internal/napi_env.cc b/quickjs/src/internal/napi_env.cc index db21073a9a..3302a61902 100644 --- a/quickjs/src/internal/napi_env.cc +++ b/quickjs/src/internal/napi_env.cc @@ -5,15 +5,12 @@ #include #include -#include #include -napi_env__::napi_env__(JSContext *context, int32_t module_api_version) - : main_context_{context}, - current_context_{context}, +napi_env__::napi_env__(napi_agent__ *agent, JSContext *context, int32_t module_api_version) + : agent_{agent}, + context_{context}, module_api_version_{module_api_version}, - last_exception_{JS_UNDEFINED}, - scopes_{this}, refs_{this}, cleanup_hooks_{this}, deferreds_{this}, @@ -23,8 +20,10 @@ napi_env__::napi_env__(JSContext *context, int32_t module_api_version) contextify_{this, context}, module_wrap_{this, context} { - root_scope_ = create_scope(nullptr); - current_scope_ = root_scope_; + if (agent_->principal_env() == nullptr) + agent_->set_principal_env(this); + if (context_ != nullptr) + agent_->open_root_scope(this); clear_last_error(); } @@ -39,6 +38,7 @@ void napi_env__::prepare_teardown() if (torn_down_) return; + closing_ = true; NAPI_QUICKJS_LIFETIME_DUMP(this, "napi_env__ teardown begin"); while (!env_cleanup_hooks_.empty()) { @@ -56,20 +56,25 @@ void napi_env__::prepare_teardown() clear_last_exception(); clear_refs_for_teardown(); - napi_scope__ *root_scope = scope_from_handle(root_scope_); - if (root_scope != nullptr) + const bool principal = is_principal(); + if (principal) { - root_scope->close(); - if (main_context_ != nullptr) - JS_RunGC(JS_GetRuntime(main_context_)); + if (agent_->root_scope() != nullptr) + { + agent_->close_root_scope(); + JS_RunGC(agent_->runtime()); + } + agent_->close_scopes(); + agent_->clear_module_hooks(); } - scopes_.close(); - current_scope_ = nullptr; - root_scope_ = nullptr; module_wrap_.teardown(); contextify_.teardown(); buffers_.teardown(); + if (principal) + agent_->clear_promise_hooks(); promises_.teardown(); + if (principal) + agent_->clear_values(); NAPI_QUICKJS_LIFETIME_DUMP(this, "napi_env__ teardown end"); torn_down_ = true; } @@ -96,24 +101,29 @@ void napi_env__::finalize_instance_data() finalize_cb(this, data, finalize_hint); } -JSContext *napi_env__::context() const +bool napi_env__::is_closing() const { - return current_context_; + return closing_; } -JSContext *napi_env__::main_context() const +napi_agent__ *napi_env__::agent() const { - return main_context_; + return agent_; } -JSContext *napi_env__::current_context() const +void napi_env__::adopt_agent(std::unique_ptr agent) { - return current_context_; + owned_agent_ = std::move(agent); } -void napi_env__::set_current_context(JSContext *context) +bool napi_env__::is_principal() const { - current_context_ = context == nullptr ? main_context_ : context; + return agent_->principal_env() == this; +} + +JSContext *napi_env__::context() const +{ + return context_; } int32_t napi_env__::module_api_version() const @@ -123,40 +133,29 @@ int32_t napi_env__::module_api_version() const napi_handle_scope napi_env__::root_scope() const { - return root_scope_; + return agent_->root_scope(); } napi_handle_scope napi_env__::current_scope() const { - return current_scope_; + return agent_->current_scope(); } napi_handle_scope napi_env__::create_scope(napi_handle_scope parent) { - if (current_context_ == nullptr) + if (context_ == nullptr) return nullptr; - auto *handle = scopes_.allocate(this, parent); - return reinterpret_cast(handle); + return agent_->create_scope(this, parent); } void napi_env__::destroy_scope(napi_handle_scope scope) { - scopes_.destroy(reinterpret_cast(scope)); + agent_->destroy_scope(scope); } napi_scope__ *napi_env__::scope_from_handle(napi_handle_scope scope_handle) const { - using Alloc = decltype(scopes_); -#ifdef NDEBUG - auto scope = reinterpret_cast(scope_handle); -#else - auto scope = reinterpret_cast(scope_handle); - assert(scopes_.owns(scope)); - auto owner = Alloc::unsafe_owner(scope); - assert(owner == this); -#endif - - return scope; + return agent_->scope_from_handle(scope_handle); } JSValue napi_env__::wrap_external_data(void *data) @@ -168,7 +167,7 @@ JSValue napi_env__::wrap_external_data(void *data, node_api_basic_finalize finalize_cb, void *finalize_hint) { - JSContext *ctx = current_context_; + JSContext *ctx = context_; if (ctx == nullptr) return JS_EXCEPTION; @@ -190,40 +189,30 @@ JSValue napi_env__::wrap_external_data(void *data, napi_value napi_env__::wrap_value_in_current_scope(JSValue value, bool owned) { - napi_scope__ *scope = scope_from_handle(current_scope_); + napi_scope__ *scope = agent_->scope_from_handle(agent_->current_scope()); return scope == nullptr ? nullptr : scope->wrap_value(value, owned); } -napi_value napi_env__::wrap_value_in_current_scope(JSContext *context, JSValue value, bool owned) -{ - napi_scope__ *scope = scope_from_handle(current_scope_); - return scope == nullptr ? nullptr : scope->wrap_value(context, value, owned); -} - void napi_env__::delete_value_from_current_scope(napi_value value) { - napi_scope__ *scope = scope_from_handle(current_scope_); + napi_scope__ *scope = agent_->scope_from_handle(agent_->current_scope()); if (scope != nullptr) scope->delete_value(value); } napi_value__ *napi_env__::value_from_handle(napi_value value_handle) { - using Alloc = decltype(scopes_); -#ifdef NDEBUG - auto value = value_handle; -#else - auto value = value_handle; +#ifndef NDEBUG auto owner = napi_scope__::ValuesAllocator::unsafe_owner(value_handle); - assert(scopes_.owns(owner)); + assert(agent_->owns_scope(owner)); #endif - return value; + return value_handle; } napi_ref napi_env__::wrap_ref_in_root_scope(JSValueConst value, uint32_t initial_ref_count) { - if (current_context_ == nullptr) + if (context_ == nullptr) return nullptr; napi_ref wrapped = refs_.allocate(this, value, initial_ref_count); @@ -269,22 +258,22 @@ size_t napi_env__::active_ref_count() const bool napi_env__::is_current_scope(napi_handle_scope scope) const { - return current_scope_ == scope; + return agent_->is_current_scope(scope); } void napi_env__::set_current_scope(napi_handle_scope scope) { - current_scope_ = scope; + agent_->set_current_scope(scope); } size_t napi_env__::scope_storage_slot_count() const { - return scopes_.storage_slot_count(); + return agent_->scope_storage_slot_count(); } size_t napi_env__::active_scope_count() const { - return scopes_.count_active(); + return agent_->active_scope_count(); } #if defined(NAPI_ENABLE_LIFETIME_TRACKER) && defined(NAPI_ENABLE_LIFETIME_PERIODIC_STATS) @@ -316,38 +305,22 @@ napi_status napi_env__::clear_last_error() bool napi_env__::has_last_exception() const { - return has_last_exception_; + return agent_->has_pending_exception(); } void napi_env__::clear_last_exception() { - if (!has_last_exception_) - return; - - JS_FreeValue(last_exception_context_ == nullptr ? main_context_ : last_exception_context_, last_exception_); - last_exception_context_ = nullptr; - last_exception_ = JS_UNDEFINED; - has_last_exception_ = false; + agent_->clear_pending_exception(); } void napi_env__::set_last_exception(JSValue exception) { - clear_last_exception(); - last_exception_context_ = current_context_; - last_exception_ = exception; - has_last_exception_ = true; + agent_->set_pending_exception(exception); } JSValue napi_env__::take_last_exception() { - if (!has_last_exception_) - return JS_UNDEFINED; - - JSValue exception = last_exception_; - last_exception_context_ = nullptr; - last_exception_ = JS_UNDEFINED; - has_last_exception_ = false; - return exception; + return agent_->take_pending_exception(); } void *napi_env__::instance_data() const @@ -400,7 +373,7 @@ napi_status napi_env__::remove_cleanup_hook(napi_cleanup_hook hook, void *arg) napi_env_cleanup_hook__ *napi_env__::create_cleanup_hook(napi_cleanup_hook hook, void *arg) { - if (main_context_ == nullptr || hook == nullptr) + if (context_ == nullptr || hook == nullptr) return nullptr; return cleanup_hooks_.allocate(this, hook, arg); } @@ -410,11 +383,11 @@ void napi_env__::destroy_cleanup_hook(napi_env_cleanup_hook__ *entry) cleanup_hooks_.destroy(entry); } -napi_deferred__ *napi_env__::create_deferred(JSContext *context, JSValue resolve, JSValue reject) +napi_deferred__ *napi_env__::create_deferred(JSValue resolve, JSValue reject) { - if (context == nullptr) + if (context_ == nullptr) return nullptr; - return deferreds_.allocate(this, context, resolve, reject); + return deferreds_.allocate(this, resolve, reject); } void napi_env__::destroy_deferred(napi_deferred__ *deferred) @@ -427,25 +400,11 @@ napi_external_backing_store_hint__ *napi_env__::create_external_backing_store( node_api_basic_finalize finalize_cb, void *finalize_hint) { - if (main_context_ == nullptr) + if (context_ == nullptr) return nullptr; return external_backing_stores_.allocate(this, external_data, finalize_cb, finalize_hint); } -napi_env_context_scope__::napi_env_context_scope__(napi_env env, JSContext *context) - : env_{env}, - previous_{env == nullptr ? nullptr : env->current_context()} -{ - if (env_ != nullptr && context != nullptr) - env_->set_current_context(context); -} - -napi_env_context_scope__::~napi_env_context_scope__() -{ - if (env_ != nullptr) - env_->set_current_context(previous_); -} - void napi_env__::destroy_external_backing_store(napi_external_backing_store_hint__ *hint) { external_backing_stores_.destroy(hint); @@ -453,21 +412,12 @@ void napi_env__::destroy_external_backing_store(napi_external_backing_store_hint int64_t napi_env__::adjust_external_memory(int64_t change_in_bytes) { - if (change_in_bytes > 0 && - external_memory_ > std::numeric_limits::max() - change_in_bytes) - { - external_memory_ = std::numeric_limits::max(); - } - else if (change_in_bytes < 0 && - external_memory_ < std::numeric_limits::min() - change_in_bytes) - { - external_memory_ = std::numeric_limits::min(); - } - else - { - external_memory_ += change_in_bytes; - } - return external_memory_; + return agent_->adjust_external_memory(change_in_bytes); +} + +bool napi_env__::attach_embedder_hooks(const unofficial_napi_env_hooks &hooks) +{ + return agent_->attach_embedder_hooks(hooks); } napi_promises__ &napi_env__::promises() diff --git a/quickjs/src/internal/napi_env.h b/quickjs/src/internal/napi_env.h index de2912bbe5..9360c033b8 100644 --- a/quickjs/src/internal/napi_env.h +++ b/quickjs/src/internal/napi_env.h @@ -4,6 +4,7 @@ #include "../../../include/js_native_api.h" #include "../../../include/node_api_types.h" #include "../../../include/unofficial_napi.h" +#include "napi_agent.h" #include "napi_callback_info.h" #include "napi_buffer.h" #include "napi_contextify.h" @@ -19,6 +20,7 @@ #include "napi_periodic_gate.h" #include +#include #include #include #include @@ -26,18 +28,22 @@ struct napi_external_backing_store_hint__; +// One realm (JSContext) of an agent. The context never changes. struct napi_env__ { - explicit napi_env__(JSContext *context, int32_t module_api_version); + napi_env__(napi_agent__ *agent, JSContext *context, int32_t module_api_version); ~napi_env__(); void prepare_teardown(); void finalize_instance_data(); + // Native callbacks are refused once teardown has started. + bool is_closing() const; + napi_agent__ *agent() const; + // Makes this env own its agent (an env made from an embedder's context). + void adopt_agent(std::unique_ptr agent); + bool is_principal() const; JSContext *context() const; - JSContext *main_context() const; - JSContext *current_context() const; - void set_current_context(JSContext *context); int32_t module_api_version() const; napi_handle_scope root_scope() const; @@ -46,7 +52,6 @@ struct napi_env__ void destroy_scope(napi_handle_scope scope); napi_scope__ *scope_from_handle(napi_handle_scope scope) const; napi_value wrap_value_in_current_scope(JSValue value, bool owned); - napi_value wrap_value_in_current_scope(JSContext *context, JSValue value, bool owned); JSValue wrap_external_data(void *data); JSValue wrap_external_data(void *data, node_api_basic_finalize finalize_cb, void *finalize_hint); napi_value__ *value_from_handle(napi_value value); @@ -64,8 +69,7 @@ struct napi_env__ template void for_each_active_scope(Fn fn) const { - for (const auto &scope : scopes_) - fn(scope); + agent_->for_each_active_scope(fn); } template @@ -96,7 +100,7 @@ struct napi_env__ napi_status remove_cleanup_hook(napi_cleanup_hook hook, void *arg); napi_env_cleanup_hook__ *create_cleanup_hook(napi_cleanup_hook hook, void *arg); void destroy_cleanup_hook(napi_env_cleanup_hook__ *entry); - napi_deferred__ *create_deferred(JSContext *context, JSValue resolve, JSValue reject); + napi_deferred__ *create_deferred(JSValue resolve, JSValue reject); void destroy_deferred(napi_deferred__ *deferred); napi_external_backing_store_hint__ *create_external_backing_store( void *external_data, @@ -114,28 +118,21 @@ struct napi_env__ quickjs::detail::napi_module_wrap__ &module_wrap(); const quickjs::detail::napi_module_wrap__ &module_wrap() const; - bool attach_embedder_hooks(const unofficial_napi_env_hooks &hooks) - { - if (embedder_hooks_attached_) - return false; - embedder_hooks_ = hooks; - embedder_hooks_attached_ = true; - return true; - } + bool attach_embedder_hooks(const unofficial_napi_env_hooks &hooks); private: void clear_refs_for_teardown(); - // QuickJS contexts and API version. - JSContext *main_context_; - JSContext *current_context_; + // Set only when this env owns its agent; destroyed last. + std::unique_ptr owned_agent_; + + // Agent, realm and API version. + napi_agent__ *agent_; + JSContext *context_; int32_t module_api_version_ = 8; - // Last native/JS error state. + // Last native error state. napi::error_state__ error_state_; - JSContext *last_exception_context_ = nullptr; - JSValue last_exception_; - bool has_last_exception_ = false; // Instance data finalizer. void *instance_data_ = nullptr; @@ -145,12 +142,7 @@ struct napi_env__ // Cleanup hooks in registration order. std::vector env_cleanup_hooks_; - // Scope stack. - napi_handle_scope root_scope_ = nullptr; - napi_handle_scope current_scope_ = nullptr; - // Env-owned slot allocators. - napi_allocator__ scopes_; napi_allocator__ refs_; napi_allocator__ cleanup_hooks_; napi_allocator__ deferreds_; @@ -162,9 +154,6 @@ struct napi_env__ napi::periodic_gate__ lifetime_string_symbol_values_gate_{10000}; #endif - // External memory accounting. - int64_t external_memory_ = 0; - // Env-owned subsystems. napi_buffer__ buffers_; napi_promises__ promises_; @@ -172,24 +161,9 @@ struct napi_env__ quickjs::detail::napi_module_wrap__ module_wrap_; // Env teardown state. + bool closing_ = false; bool torn_down_ = false; bool clearing_refs_for_teardown_ = false; - bool embedder_hooks_attached_ = false; - unofficial_napi_env_hooks embedder_hooks_{}; -}; - -class napi_env_context_scope__ -{ -public: - napi_env_context_scope__(napi_env env, JSContext *context); - ~napi_env_context_scope__(); - - napi_env_context_scope__(const napi_env_context_scope__ &) = delete; - napi_env_context_scope__ &operator=(const napi_env_context_scope__ &) = delete; - -private: - napi_env env_ = nullptr; - JSContext *previous_ = nullptr; }; napi_status napi_quickjs_set_last_error(napi_env env, diff --git a/quickjs/src/internal/napi_external.cc b/quickjs/src/internal/napi_external.cc index 996395a1bd..ed7ec7b0c9 100644 --- a/quickjs/src/internal/napi_external.cc +++ b/quickjs/src/internal/napi_external.cc @@ -54,6 +54,15 @@ void *napi_external__::get_value(JSValueConst value) return hint == nullptr ? nullptr : hint->external_data(); } +napi_env napi_external__::get_env(JSValueConst value) +{ + if (!is_external(value)) + return nullptr; + auto *hint = static_cast( + JS_GetOpaque(value, external_class_id)); + return hint == nullptr ? nullptr : hint->env(); +} + napi_external_backing_store_hint__ *napi_external__::get_wrap_record(JSContext *ctx, JSValueConst object) { auto *wrap = static_cast( diff --git a/quickjs/src/internal/napi_external.h b/quickjs/src/internal/napi_external.h index ed39b9db1b..084ac12368 100644 --- a/quickjs/src/internal/napi_external.h +++ b/quickjs/src/internal/napi_external.h @@ -15,6 +15,8 @@ class napi_external__ static JSClassID record_class_id(); static bool is_external(JSValueConst value); static void *get_value(JSValueConst value); + // The env that created the external. + static napi_env get_env(JSValueConst value); static napi_external_backing_store_hint__ *get_wrap_record(JSContext *ctx, JSValueConst object); static const char *type_tag_property(); diff --git a/quickjs/src/internal/napi_function.cc b/quickjs/src/internal/napi_function.cc index c929779031..1b8b09183a 100644 --- a/quickjs/src/internal/napi_function.cc +++ b/quickjs/src/internal/napi_function.cc @@ -57,16 +57,20 @@ JSValue napi_function__::create_internal(napi_env env, return JS_DupValue(env->context(), napi_quickjs_value_inner(env, fn_val)); } -JSValue napi_function__::trampoline(JSContext *ctx, +// QuickJS passes the caller's realm as `ctx` for C function data (it does not +// switch realms). The callback runs in the realm of the env that created the +// function instead, as in V8 and Node. +JSValue napi_function__::trampoline(JSContext *caller_ctx, JSValueConst this_val, int argc, JSValueConst *argv, int magic, JSValue *func_data) { - auto env = static_cast(JS_GetContextOpaque(ctx)); - if (!napi_util__::check_env(env)) - return JS_ThrowReferenceError(ctx, "Null NAPI env"); + auto env = napi_external__::get_env(func_data[0]); + if (!napi_util__::check_env(env) || env->is_closing()) + return JS_ThrowReferenceError(caller_ctx, "Null NAPI env"); + JSContext *ctx = env->context(); auto cb_ptr = napi_external__::get_value(func_data[0]); if (cb_ptr == nullptr) @@ -74,7 +78,6 @@ JSValue napi_function__::trampoline(JSContext *ctx, auto cb = reinterpret_cast(cb_ptr); auto user_data = napi_external__::get_value(func_data[1]); - napi_env_context_scope__ context_scope{env, ctx}; quickjs_callback_handle_scope__ callback_scope{env}; if (!callback_scope.is_open()) return JS_ThrowOutOfMemory(ctx); diff --git a/quickjs/src/internal/napi_module_wrap.cc b/quickjs/src/internal/napi_module_wrap.cc index f9c38bdedd..61a5dabaa5 100644 --- a/quickjs/src/internal/napi_module_wrap.cc +++ b/quickjs/src/internal/napi_module_wrap.cc @@ -135,9 +135,6 @@ napi_module_wrap__::napi_module_wrap__(napi_env env, JSContext *context) import_module_dynamically_callback_{JS_UNDEFINED}, initialize_import_meta_callback_{JS_UNDEFINED} { - JSRuntime *rt = JS_GetRuntime(ctx_); - JS_SetModuleImportMetaInitFunc(rt, host_import_meta_init, this); - JS_SetModuleDynamicImportFunc(rt, host_dynamic_import, this); } napi_module_wrap__::~napi_module_wrap__() @@ -150,10 +147,6 @@ void napi_module_wrap__::teardown() if (torn_down_) return; - JSRuntime *rt = JS_GetRuntime(ctx_); - JS_SetModuleImportMetaInitFunc(rt, nullptr, nullptr); - JS_SetModuleDynamicImportFunc(rt, nullptr, nullptr); - while (!records_.empty()) free_record(records_.back()); for (auto &referrer : script_referrers_) @@ -1233,30 +1226,4 @@ int napi_module_wrap__::synthetic_init(JSContext *ctx, JSModuleDef *module) return env->module_wrap().initialize_synthetic_module(module); } -int napi_module_wrap__::host_import_meta_init(JSContext *ctx, - JSModuleDef *module, - JSValueConst meta, - void *opaque) -{ - auto *self = static_cast(opaque); - if (self == nullptr) - return 0; - return self->initialize_import_meta(module, meta); -} - -JSValue napi_module_wrap__::host_dynamic_import(JSContext *ctx, - JSModuleDef *referrer, - JSValueConst referrer_name, - JSValueConst specifier, - JSValueConst attributes, - JSModuleImportPhaseEnum phase, - void *opaque) -{ - auto *self = static_cast(opaque); - if (self == nullptr) - return JS_ThrowTypeError(ctx, "Dynamic import callback is not registered"); - return self->import_module_dynamically(referrer, referrer_name, specifier, - attributes, phase); -} - } // namespace quickjs::detail diff --git a/quickjs/src/internal/napi_module_wrap.h b/quickjs/src/internal/napi_module_wrap.h index 81ebe5e5b4..ffcd7f1834 100644 --- a/quickjs/src/internal/napi_module_wrap.h +++ b/quickjs/src/internal/napi_module_wrap.h @@ -122,17 +122,6 @@ class napi_module_wrap__ napi_status cache_module_requests(record *entry); static int synthetic_init(JSContext *ctx, JSModuleDef *module); - static int host_import_meta_init(JSContext *ctx, - JSModuleDef *module, - JSValueConst meta, - void *opaque); - static JSValue host_dynamic_import(JSContext *ctx, - JSModuleDef *referrer, - JSValueConst referrer_name, - JSValueConst specifier, - JSValueConst attributes, - JSModuleImportPhaseEnum phase, - void *opaque); // Owning environment and QuickJS context. napi_env env_; diff --git a/quickjs/src/internal/napi_promises.cc b/quickjs/src/internal/napi_promises.cc index 9e95ac9f21..ccc1666f9f 100644 --- a/quickjs/src/internal/napi_promises.cc +++ b/quickjs/src/internal/napi_promises.cc @@ -3,28 +3,11 @@ #include "internal/napi_env.h" #include "internal/napi_value.h" -namespace -{ -void *js_identity(JSValueConst value) -{ - return JS_IsObject(value) ? JS_VALUE_GET_PTR(value) : nullptr; -} - -bool is_same_runtime(napi_env env, JSContext *ctx) -{ - return env != nullptr && - ctx != nullptr && - env->main_context() != nullptr && - JS_GetRuntime(ctx) == JS_GetRuntime(env->main_context()); -} -} - napi_promises__::napi_promises__(napi_env env, JSContext *context) : env_{env}, context_{context}, promise_reject_callback_{JS_UNDEFINED}, - promise_hooks_{JS_UNDEFINED, JS_UNDEFINED, JS_UNDEFINED, JS_UNDEFINED}, - continuation_preserved_embedder_data_{JS_UNDEFINED} + promise_hooks_{JS_UNDEFINED, JS_UNDEFINED, JS_UNDEFINED, JS_UNDEFINED} { } @@ -37,7 +20,6 @@ void napi_promises__::teardown() { if (torn_down_) return; - clear_runtime_hooks(); clear_stored_values(); torn_down_ = true; } @@ -47,33 +29,6 @@ bool napi_promises__::is_active() const return !torn_down_ && env_ != nullptr && context_ != nullptr; } -void napi_promises__::attach_runtime_hooks() -{ - if (!is_active()) - return; - JSRuntime *runtime = JS_GetRuntime(context_); - JS_SetPromiseHook(runtime, napi_promises__::promise_hook, env_); -} - -void napi_promises__::clear_runtime_hooks() -{ - if (context_ == nullptr) - return; - JSRuntime *runtime = JS_GetRuntime(context_); - JS_SetPromiseHook(runtime, nullptr, nullptr); - JS_SetHostPromiseRejectionTracker(runtime, nullptr, nullptr); -} - -void napi_promises__::update_rejection_tracker() -{ - if (!is_active()) - return; - JS_SetHostPromiseRejectionTracker( - JS_GetRuntime(context_), - has_reject_callback() ? napi_promises__::rejection_tracker : nullptr, - env_); -} - napi_status napi_promises__::set_optional_function(napi_value value, JSValue *target) { if (target == nullptr) @@ -100,12 +55,6 @@ napi_status napi_promises__::set_optional_function(napi_value value, JSValue *ta return napi_ok; } -void napi_promises__::replace_stored_value(JSValue *target, JSValueConst value) -{ - JS_FreeValue(context_, *target); - *target = JS_DupValue(context_, value); -} - void napi_promises__::clear_stored_values() { JS_FreeValue(context_, promise_reject_callback_); @@ -116,17 +65,6 @@ void napi_promises__::clear_stored_values() JS_FreeValue(context_, hook); hook = JS_UNDEFINED; } - - JS_FreeValue(context_, continuation_preserved_embedder_data_); - continuation_preserved_embedder_data_ = JS_UNDEFINED; - - for (auto &entry : promise_context_frames_) - JS_FreeValue(context_, entry.second); - promise_context_frames_.clear(); - - for (auto &frame : promise_context_frame_stack_) - JS_FreeValue(context_, frame); - promise_context_frame_stack_.clear(); } void napi_promises__::clear_pending_exception_if_any() @@ -137,13 +75,13 @@ void napi_promises__::clear_pending_exception_if_any() JS_FreeValue(context_, exception); } -void napi_promises__::call_hook(JSValueConst hook, int argc, JSValueConst *argv) +void napi_promises__::call_function(JSValueConst function, int argc, JSValueConst *argv) { - if (context_ == nullptr || !JS_IsFunction(context_, hook)) + if (context_ == nullptr || !JS_IsFunction(context_, function)) return; JSValue global = JS_GetGlobalObject(context_); - JSValue ret = JS_Call(context_, hook, global, argc, argv); + JSValue ret = JS_Call(context_, function, global, argc, argv); JS_FreeValue(context_, global); if (JS_IsException(ret)) { @@ -163,13 +101,6 @@ bool napi_promises__::has_reject_callback() const return JS_IsFunction(context_, promise_reject_callback_); } -JSValue napi_promises__::dup_reject_callback() const -{ - if (!has_reject_callback()) - return JS_UNDEFINED; - return JS_DupValue(context_, promise_reject_callback_); -} - napi_status napi_promises__::set_hooks(napi_value init, napi_value before, napi_value after, @@ -204,81 +135,32 @@ napi_status napi_promises__::set_hooks(napi_value init, return napi_ok; } -JSValue napi_promises__::dup_hook(size_t index) const +void napi_promises__::call_hook(size_t index, int argc, JSValueConst *argv) { - if (index >= promise_hooks_.size() || !JS_IsFunction(context_, promise_hooks_[index])) - return JS_UNDEFINED; - return JS_DupValue(context_, promise_hooks_[index]); -} - -JSValueConst napi_promises__::continuation_preserved_embedder_data() const -{ - return continuation_preserved_embedder_data_; -} - -void napi_promises__::set_continuation_preserved_embedder_data(JSValueConst value) -{ - replace_stored_value(&continuation_preserved_embedder_data_, value); -} - -void napi_promises__::capture_context_frame(JSValueConst promise) -{ - void *identity = js_identity(promise); - if (identity == nullptr || JS_IsUndefined(continuation_preserved_embedder_data_)) + if (!is_active() || index >= promise_hooks_.size() || + !JS_IsFunction(context_, promise_hooks_[index])) return; - JSValue frame = JS_DupValue(context_, continuation_preserved_embedder_data_); - auto it = promise_context_frames_.find(identity); - if (it != promise_context_frames_.end()) - { - JS_FreeValue(context_, it->second); - it->second = frame; - return; - } - promise_context_frames_.emplace(identity, frame); + // The hook may replace itself while it runs. + JSValue hook = JS_DupValue(context_, promise_hooks_[index]); + call_function(hook, argc, argv); + JS_FreeValue(context_, hook); } -void napi_promises__::enter_context_frame(JSValueConst promise) +void napi_promises__::call_reject_callback(JSValueConst promise, + JSValueConst reason, + bool is_handled) { - promise_context_frame_stack_.push_back( - JS_DupValue(context_, continuation_preserved_embedder_data_)); - - JSValueConst frame = JS_UNDEFINED; - void *identity = js_identity(promise); - if (identity != nullptr) - { - auto it = promise_context_frames_.find(identity); - if (it != promise_context_frames_.end()) - frame = it->second; - } - replace_stored_value(&continuation_preserved_embedder_data_, frame); -} - -void napi_promises__::leave_context_frame(JSValueConst promise) -{ - if (!promise_context_frame_stack_.empty()) - { - JSValue previous = promise_context_frame_stack_.back(); - promise_context_frame_stack_.pop_back(); - JS_FreeValue(context_, continuation_preserved_embedder_data_); - continuation_preserved_embedder_data_ = previous; - } - - (void)promise; -} - -void napi_promises__::release_context_frame(JSValueConst promise) -{ - void *identity = js_identity(promise); - if (identity == nullptr) + if (!is_active() || !has_reject_callback()) return; - auto it = promise_context_frames_.find(identity); - if (it != promise_context_frames_.end()) - { - JS_FreeValue(context_, it->second); - promise_context_frames_.erase(it); - } + JSValue callback = JS_DupValue(context_, promise_reject_callback_); + JSValue event_type = JS_NewInt32(context_, is_handled ? 1 : 0); + JSValueConst rejection_value = is_handled ? JS_UNDEFINED : reason; + JSValueConst argv[] = {event_type, promise, rejection_value}; + call_function(callback, 3, argv); + JS_FreeValue(context_, event_type); + JS_FreeValue(context_, callback); } JSValue napi_promises__::microtask_job(JSContext *ctx, int argc, JSValueConst *argv) @@ -287,70 +169,3 @@ JSValue napi_promises__::microtask_job(JSContext *ctx, int argc, JSValueConst *a return JS_UNDEFINED; return JS_Call(ctx, argv[0], JS_UNDEFINED, 0, nullptr); } - -void napi_promises__::promise_hook(JSContext *ctx, - JSPromiseHookType type, - JSValueConst promise, - JSValueConst parent_promise, - void *opaque) -{ - napi_env env = static_cast(opaque); - if (!is_same_runtime(env, ctx)) - return; - - napi_promises__ &promises = env->promises(); - if (type == JS_PROMISE_HOOK_INIT) - promises.capture_context_frame(promise); - else if (type == JS_PROMISE_HOOK_BEFORE) - promises.enter_context_frame(promise); - - size_t hook_index = static_cast(type); - JSValue hook = promises.dup_hook(hook_index); - if (JS_IsFunction(promises.context_, hook)) - { - if (type == JS_PROMISE_HOOK_INIT) - { - JSValueConst argv[] = {promise, parent_promise}; - promises.call_hook(hook, 2, argv); - } - else - { - JSValueConst argv[] = {promise}; - promises.call_hook(hook, 1, argv); - } - } - JS_FreeValue(promises.context_, hook); - - if (type == JS_PROMISE_HOOK_AFTER) - promises.leave_context_frame(promise); - else if (type == JS_PROMISE_HOOK_RESOLVE) - promises.release_context_frame(promise); -} - -void napi_promises__::rejection_tracker(JSContext *ctx, - JSValueConst promise, - JSValueConst reason, - bool is_handled, - void *opaque) -{ - napi_env env = static_cast(opaque); - if (!is_same_runtime(env, ctx)) - return; - - napi_promises__ &promises = env->promises(); - promises.release_context_frame(promise); - - JSValue callback = promises.dup_reject_callback(); - if (!JS_IsFunction(promises.context_, callback)) - { - JS_FreeValue(promises.context_, callback); - return; - } - - JSValue event_type = JS_NewInt32(promises.context_, is_handled ? 1 : 0); - JSValueConst rejection_value = is_handled ? JS_UNDEFINED : reason; - JSValueConst argv[] = {event_type, promise, rejection_value}; - promises.call_hook(callback, 3, argv); - JS_FreeValue(promises.context_, event_type); - JS_FreeValue(promises.context_, callback); -} diff --git a/quickjs/src/internal/napi_promises.h b/quickjs/src/internal/napi_promises.h index 8cf1cc049a..9f075747f7 100644 --- a/quickjs/src/internal/napi_promises.h +++ b/quickjs/src/internal/napi_promises.h @@ -7,9 +7,9 @@ #include #include -#include -#include +// The env's promise reject callback and lifecycle hooks. The agent installs +// the runtime-wide engine hooks and dispatches to these. class napi_promises__ { public: @@ -18,44 +18,23 @@ class napi_promises__ void teardown(); - void attach_runtime_hooks(); - void clear_runtime_hooks(); - void update_rejection_tracker(); - napi_status set_reject_callback(napi_value callback); bool has_reject_callback() const; - JSValue dup_reject_callback() const; napi_status set_hooks(napi_value init, napi_value before, napi_value after, napi_value resolve); - JSValue dup_hook(size_t index) const; - JSValueConst continuation_preserved_embedder_data() const; - void set_continuation_preserved_embedder_data(JSValueConst value); - void capture_context_frame(JSValueConst promise); - void enter_context_frame(JSValueConst promise); - void leave_context_frame(JSValueConst promise); - void release_context_frame(JSValueConst promise); + void call_hook(size_t index, int argc, JSValueConst *argv); + void call_reject_callback(JSValueConst promise, JSValueConst reason, bool is_handled); static JSValue microtask_job(JSContext *ctx, int argc, JSValueConst *argv); - static void promise_hook(JSContext *ctx, - JSPromiseHookType type, - JSValueConst promise, - JSValueConst parent_promise, - void *opaque); - static void rejection_tracker(JSContext *ctx, - JSValueConst promise, - JSValueConst reason, - bool is_handled, - void *opaque); private: napi_status set_optional_function(napi_value value, JSValue *target); - void replace_stored_value(JSValue *target, JSValueConst value); void clear_stored_values(); - void call_hook(JSValueConst hook, int argc, JSValueConst *argv); + void call_function(JSValueConst function, int argc, JSValueConst *argv); void clear_pending_exception_if_any(); bool is_active() const; @@ -67,11 +46,6 @@ class napi_promises__ JSValue promise_reject_callback_; std::array promise_hooks_; - // Continuation and async context tracking. - JSValue continuation_preserved_embedder_data_; - std::unordered_map promise_context_frames_; - std::vector promise_context_frame_stack_; - // Subsystem lifecycle. bool torn_down_ = false; }; diff --git a/quickjs/src/internal/napi_ref.cc b/quickjs/src/internal/napi_ref.cc index 2b1b25d9be..ae8c927c7d 100644 --- a/quickjs/src/internal/napi_ref.cc +++ b/quickjs/src/internal/napi_ref.cc @@ -17,14 +17,13 @@ napi_ref__::napi_ref__(napi_env env, JSValueConst value, uint32_t initial_ref_count) : env_{env}, - context_{env == nullptr ? nullptr : env->context()}, value_{value}, ref_count_{initial_ref_count} { if (ref_count_ > 0) - JS_DupValue(context_, value_); + JS_DupValue(context(), value_); else if (!make_weak() && JS_VALUE_HAS_REF_COUNT(value_)) - JS_DupValue(context_, value_); + JS_DupValue(context(), value_); } napi_ref__::~napi_ref__() @@ -37,19 +36,17 @@ void napi_ref__::clear_for_teardown() if (env_ == nullptr) return; - napi_env env = env_; - JSContext *context = context_; + JSContext *context = this->context(); JSValue value = value_; const bool owns_strong_value = JS_GetNativeWeakRefFromLink(&weak_link_) == nullptr && !IsEmptyValue(value) && JS_VALUE_HAS_REF_COUNT(value); delete_weak_handle(); env_ = nullptr; - context_ = nullptr; value_ = JS_UNDEFINED; ref_count_ = 0; - if (env != nullptr && context != nullptr && owns_strong_value) + if (context != nullptr && owns_strong_value) JS_FreeValue(context, value); } @@ -70,7 +67,7 @@ uint32_t napi_ref__::add_ref() if (is_empty()) return ref_count_; if (was_weak) - JS_DupValue(context_, value_); + JS_DupValue(context(), value_); } ++ref_count_; return ref_count_; @@ -85,11 +82,10 @@ uint32_t napi_ref__::rem_ref() uint32_t ref_count = ref_count_; if (ref_count == 0) { - napi_env env = env_; - JSContext *context = context_; + JSContext *context = this->context(); JSValue value = value_; const bool became_weak = make_weak(); - if (became_weak && env != nullptr && context != nullptr) + if (became_weak && context != nullptr) JS_FreeValue(context, value); } return ref_count; @@ -117,7 +113,7 @@ napi_env napi_ref__::env() const JSContext *napi_ref__::context() const { - return context_; + return env_ == nullptr ? nullptr : env_->context(); } JSValueConst napi_ref__::get_inner() const @@ -127,7 +123,7 @@ JSValueConst napi_ref__::get_inner() const JSValue napi_ref__::dup_inner() const { - return JS_DupValue(context_, value_); + return JS_DupValue(context(), value_); } void napi_ref__::weak_target_finalized(JSRuntime *rt, void *opaque) @@ -147,26 +143,27 @@ void napi_ref__::clear_weak_target() void napi_ref__::delete_weak_handle() { JSNativeWeakRef *owner = JS_GetNativeWeakRefFromLink(&weak_link_); - if (owner == nullptr || env_ == nullptr || context_ == nullptr) + if (owner == nullptr || context() == nullptr) return; #ifndef NDEBUG assert(owner != reinterpret_cast(&weak_link_)); assert(weak_link_.next != &weak_link_); #endif - JS_DeleteNativeWeakRefLink(JS_GetRuntime(context_), &weak_link_); + JS_DeleteNativeWeakRefLink(JS_GetRuntime(context()), &weak_link_); } bool napi_ref__::make_weak() { delete_weak_handle(); - if (env_ == nullptr || context_ == nullptr || is_empty()) + JSContext *ctx = context(); + if (ctx == nullptr || is_empty()) return false; const int rc = - JS_AddNativeWeakRefLink(context_, value_, &weak_link_, weak_target_finalized, this); - if (rc < 0 && JS_HasException(context_)) + JS_AddNativeWeakRefLink(ctx, value_, &weak_link_, weak_target_finalized, this); + if (rc < 0 && JS_HasException(ctx)) { - JSValue exception = JS_GetException(context_); - JS_FreeValue(context_, exception); + JSValue exception = JS_GetException(ctx); + JS_FreeValue(ctx, exception); } return JS_GetNativeWeakRefFromLink(&weak_link_) != nullptr; } diff --git a/quickjs/src/internal/napi_ref.h b/quickjs/src/internal/napi_ref.h index 93648e854e..ff8b6bbdfc 100644 --- a/quickjs/src/internal/napi_ref.h +++ b/quickjs/src/internal/napi_ref.h @@ -38,7 +38,6 @@ struct napi_ref__ // Owning environment and referenced QuickJS value. napi_env env_ = nullptr; - JSContext *context_ = nullptr; JSValue value_ = JS_UNDEFINED; JSNativeWeakRefLink weak_link_{}; diff --git a/quickjs/src/internal/napi_scope.cc b/quickjs/src/internal/napi_scope.cc index 8d8d46c1ad..6c98f4ad14 100644 --- a/quickjs/src/internal/napi_scope.cc +++ b/quickjs/src/internal/napi_scope.cc @@ -26,24 +26,19 @@ size_t napi_scope__::level() const } napi_value napi_scope__::wrap_value(JSValue value, bool owned) -{ - return wrap_value(env_ == nullptr ? nullptr : env_->context(), value, owned); -} - -napi_value napi_scope__::wrap_value(JSContext *context, JSValue value, bool owned) { if (closed_) { - if (owned && env_ != nullptr && context != nullptr) - JS_FreeValue(context, value); + if (owned && env_ != nullptr) + JS_FreeValueRT(env_->agent()->runtime(), value); return nullptr; } - napi_value wrapped = values_.allocate(env_, context, value, owned); + napi_value wrapped = values_.allocate(env_, value, owned); if (wrapped == nullptr) { - if (owned && env_ != nullptr && context != nullptr) - JS_FreeValue(context, value); + if (owned && env_ != nullptr) + JS_FreeValueRT(env_->agent()->runtime(), value); return nullptr; } @@ -68,7 +63,7 @@ napi_value napi_scope__::escape_value(napi_value value) return record_escape(nullptr); napi_scope__ *parent_scope = parent(); - return record_escape(parent_scope == nullptr ? nullptr : parent_scope->wrap_value(value->context(), value->get_inner(), false)); + return record_escape(parent_scope == nullptr ? nullptr : parent_scope->wrap_value(value->get_inner(), false)); } void napi_scope__::delete_value(napi_value value) diff --git a/quickjs/src/internal/napi_scope.h b/quickjs/src/internal/napi_scope.h index 2892281b3d..c56754eec5 100644 --- a/quickjs/src/internal/napi_scope.h +++ b/quickjs/src/internal/napi_scope.h @@ -19,7 +19,6 @@ struct napi_scope__ size_t level() const; napi_value wrap_value(JSValue value, bool owned); - napi_value wrap_value(JSContext *context, JSValue value, bool owned); napi_value escape_value(napi_value value); void delete_value(napi_value value); diff --git a/quickjs/src/internal/napi_util.cc b/quickjs/src/internal/napi_util.cc index 852df682c0..2483c8286a 100644 --- a/quickjs/src/internal/napi_util.cc +++ b/quickjs/src/internal/napi_util.cc @@ -138,7 +138,6 @@ napi_status napi_util__::return_pending_if_caught(napi_env env, JSContext *ctx, if (ctx != nullptr && JS_HasException(ctx)) { auto exc = JS_GetException(ctx); - napi_env_context_scope__ context_scope{env, ctx}; set_last_exception(env, exc); return napi_quickjs_set_last_error(env, napi_pending_exception, message); } diff --git a/quickjs/src/internal/napi_value.cc b/quickjs/src/internal/napi_value.cc index 66561859f9..eb5c59d38f 100644 --- a/quickjs/src/internal/napi_value.cc +++ b/quickjs/src/internal/napi_value.cc @@ -4,46 +4,26 @@ #include "internal/napi_scope.h" napi_value__::napi_value__(napi_env env, JSValue value, bool owned) - : napi_value__{env, env == nullptr ? nullptr : env->context(), value, owned} -{ -} - -napi_value__::napi_value__(napi_env env, JSContext *context, JSValue value, bool owned) - : env_{env}, - context_{context}, - value_{owned ? value : JS_DupValue(context, value)} + : runtime_{env == nullptr ? nullptr : env->agent()->runtime()}, + value_{owned ? value : JS_DupValueRT(runtime_, value)} { } napi_value__::~napi_value__() { - if (env_ == nullptr) + if (runtime_ == nullptr) return; - napi_env env = env_; - JSContext *context = context_; + JSRuntime *runtime = runtime_; JSValue value = value_; - env_ = nullptr; - context_ = nullptr; + runtime_ = nullptr; value_ = JS_UNDEFINED; - - if (env != nullptr && context != nullptr) - JS_FreeValue(context, value); + JS_FreeValueRT(runtime, value); } bool napi_value__::is_active() const { - return env_ != nullptr; -} - -napi_env napi_value__::env() const -{ - return env_; -} - -JSContext *napi_value__::context() const -{ - return context_; + return runtime_ != nullptr; } JSValueConst napi_value__::get_inner() const @@ -59,12 +39,3 @@ JSValueConst napi_quickjs_value_inner(napi_env env, napi_value value) napi_value__ *data = env->value_from_handle(value); return data->get_inner(); } - -JSContext *napi_quickjs_value_context(napi_env env, napi_value value) -{ - assert(env != nullptr); - assert(value != nullptr); - - napi_value__ *data = env->value_from_handle(value); - return data->context(); -} diff --git a/quickjs/src/internal/napi_value.h b/quickjs/src/internal/napi_value.h index 16799c696d..c622ce3e16 100644 --- a/quickjs/src/internal/napi_value.h +++ b/quickjs/src/internal/napi_value.h @@ -9,7 +9,6 @@ struct napi_value__ { napi_value__(napi_env env, JSValue value, bool owned); - napi_value__(napi_env env, JSContext *context, JSValue value, bool owned); ~napi_value__(); napi_value__(const napi_value__ &) = delete; @@ -18,18 +17,14 @@ struct napi_value__ napi_value__ &operator=(napi_value__ &&other) = delete; bool is_active() const; - napi_env env() const; - JSContext *context() const; JSValueConst get_inner() const; private: - // Owning environment and wrapped QuickJS value. - napi_env env_ = nullptr; - JSContext *context_ = nullptr; + // A value only needs its runtime: it is usable from every realm of it. + JSRuntime *runtime_ = nullptr; JSValue value_ = JS_UNDEFINED; }; JSValueConst napi_quickjs_value_inner(napi_env env, napi_value value); -JSContext *napi_quickjs_value_context(napi_env env, napi_value value); #endif // NAPI_QUICKJS_VALUE_H_ diff --git a/quickjs/src/js_native_api_quickjs.cc b/quickjs/src/js_native_api_quickjs.cc index ec82831b55..05984cfd86 100644 --- a/quickjs/src/js_native_api_quickjs.cc +++ b/quickjs/src/js_native_api_quickjs.cc @@ -1947,12 +1947,11 @@ extern "C" return napi_invalid_arg; } - JSContext *ctx = napi_quickjs_value_context(env, constructor); + JSContext *ctx = env->context(); if (ctx == nullptr) { return napi_invalid_arg; } - napi_env_context_scope__ context_scope{env, ctx}; // 2. Unwrap the constructor JSValue // Assuming 'unwrap_value' is your helper to get the JSValue from napi_value @@ -1980,7 +1979,7 @@ extern "C" // 6. Wrap and return // 'wrap_value' converts the JSValue back into the napi_value handle - *result = env->wrap_value_in_current_scope(ctx, instance, true); + *result = env->wrap_value_in_current_scope(instance, true); return napi_ok; } @@ -2002,12 +2001,7 @@ extern "C" return napi_util__::invalid_arg(env); } - JSContext *ctx = napi_quickjs_value_context(env, func); - if (ctx == nullptr) - { - return napi_util__::invalid_arg(env); - } - napi_env_context_scope__ context_scope{env, ctx}; + JSContext *ctx = env->context(); JSValue js_func = napi_quickjs_value_inner(env, func); @@ -2041,7 +2035,7 @@ extern "C" if (result != nullptr) { // wrap the result; the current handle scope now owns the returned JSValue - *result = env->wrap_value_in_current_scope(ctx, js_result, true); + *result = env->wrap_value_in_current_scope(js_result, true); } else { @@ -2198,7 +2192,7 @@ extern "C" if (JS_IsException(p)) return napi_util__::return_pending_if_caught(env, ctx, "Failed to create Promise"); - auto *d = napi_deferred__::create(env, ctx, resolving_funcs[0], resolving_funcs[1]); + auto *d = napi_deferred__::create(env, resolving_funcs[0], resolving_funcs[1]); if (d == nullptr) { JS_FreeValue(ctx, resolving_funcs[0]); @@ -2208,7 +2202,7 @@ extern "C" } *deferred = d; - *promise = env->wrap_value_in_current_scope(ctx, p, true); + *promise = env->wrap_value_in_current_scope(p, true); return (*promise == nullptr) ? napi_generic_failure : napi_ok; } @@ -2219,11 +2213,7 @@ extern "C" if (!napi_util__::check_env(env) || deferred == nullptr || resolution == nullptr) return napi_invalid_arg; - JSContext *ctx = deferred->context(); - if (ctx == nullptr) - return napi_invalid_arg; - - napi_env_context_scope__ context_scope{env, ctx}; + JSContext *ctx = env->context(); JSValue ret = deferred->call_resolve(resolution); napi_deferred__::destroy(deferred); @@ -2241,11 +2231,7 @@ extern "C" if (!napi_util__::check_env(env) || deferred == nullptr || rejection == nullptr) return napi_invalid_arg; - JSContext *ctx = deferred->context(); - if (ctx == nullptr) - return napi_invalid_arg; - - napi_env_context_scope__ context_scope{env, ctx}; + JSContext *ctx = env->context(); JSValue ret = deferred->call_reject(rejection); napi_deferred__::destroy(deferred); @@ -2799,7 +2785,6 @@ extern "C" if (!napi_util__::check_value(env, value) || result == nullptr) return napi_invalid_arg; - napi_env_context_scope__ context_scope{env, napi_quickjs_value_context(env, value)}; *result = env->wrap_ref_in_root_scope(napi_quickjs_value_inner(env, value), initial_ref_count); if (*result == nullptr) return napi_generic_failure; @@ -2884,7 +2869,7 @@ extern "C" *result = nullptr; return napi_ok; } - *result = env->wrap_value_in_current_scope(slot->context(), slot->dup_inner(), true); + *result = env->wrap_value_in_current_scope(slot->dup_inner(), true); return (*result == nullptr) ? napi_generic_failure : napi_ok; } diff --git a/quickjs/src/unofficial_napi.cc b/quickjs/src/unofficial_napi.cc index ba1ab2a1d0..89770dab23 100644 --- a/quickjs/src/unofficial_napi.cc +++ b/quickjs/src/unofficial_napi.cc @@ -35,10 +35,13 @@ namespace bool g_runtime_configured = false; std::string g_runtime_engine_flags; + // The owner handle: the runtime, its main context, the agent and the + // principal env. struct UnofficialEnvScope { JSRuntime *rt = nullptr; JSContext *ctx = nullptr; + std::unique_ptr agent; napi_env env = nullptr; }; @@ -48,7 +51,7 @@ namespace return napi_invalid_arg; JSContext *ctx = env->context(); - env->promises().clear_runtime_hooks(); + env->agent()->clear_promise_hooks(); JS_SetContextOpaque(ctx, nullptr); env->prepare_teardown(); return napi_ok; @@ -137,6 +140,36 @@ namespace JS_FreeValue(ctx, symbol_ctor); return ok; } + + // Makes the env for `context` on `agent`; the first env becomes the + // agent's principal env. + napi_status CreateEnvOnAgent(napi_agent__ *agent, + JSContext *context, + int32_t module_api_version, + napi_env *result) + { + auto rt = JS_GetRuntime(context); + if (0 != napi_external__::register_class(rt)) + return napi_generic_failure; + if (!EnsureNodeWellKnownSymbols(context)) + return JS_HasException(context) ? napi_pending_exception : napi_generic_failure; + + auto env = new (std::nothrow) napi_env__{agent, context, module_api_version}; + if (env == nullptr) + return napi_generic_failure; + if (env->root_scope() == nullptr) + { + delete env; + return napi_generic_failure; + } + + JS_SetContextOpaque(context, env); + agent->attach_promise_hook(); + agent->attach_module_hooks(); + + *result = env; + return napi_ok; + } } extern "C" @@ -207,24 +240,15 @@ extern "C" if (result == nullptr || context == nullptr) return napi_invalid_arg; - auto rt = JS_GetRuntime(context); - if (0 != napi_external__::register_class(rt)) + // No owner handle exists on this path, so the env owns its agent. + std::unique_ptr agent{new (std::nothrow) napi_agent__{JS_GetRuntime(context)}}; + if (agent == nullptr) return napi_generic_failure; - if (!EnsureNodeWellKnownSymbols(context)) - return JS_HasException(context) ? napi_pending_exception : napi_generic_failure; - - auto env = new (std::nothrow) napi_env__{context, module_api_version}; - if (env == nullptr) - return napi_generic_failure; - if (env->root_scope() == nullptr) - { - delete env; - return napi_generic_failure; - } - - JS_SetContextOpaque(context, env); - env->promises().attach_runtime_hooks(); - + napi_env env = nullptr; + napi_status status = CreateEnvOnAgent(agent.get(), context, module_api_version, &env); + if (status != napi_ok) + return status; + env->adopt_agent(std::move(agent)); *result = env; return napi_ok; } @@ -286,6 +310,15 @@ extern "C" } auto scope = new (std::nothrow) UnofficialEnvScope{.rt = rt, .ctx = ctx}; + if (scope != nullptr) + { + scope->agent.reset(new (std::nothrow) napi_agent__{rt}); + if (scope->agent == nullptr) + { + delete scope; + scope = nullptr; + } + } if (scope == nullptr) { JS_FreeContext(ctx); @@ -293,7 +326,7 @@ extern "C" return napi_generic_failure; } - auto status = unofficial_napi_create_env_from_context(ctx, module_api_version, &scope->env); + auto status = CreateEnvOnAgent(scope->agent.get(), ctx, module_api_version, &scope->env); if (status != napi_ok || scope->env == nullptr) { delete scope; @@ -439,7 +472,7 @@ extern "C" napi_status status = env->promises().set_reject_callback(callback); if (status != napi_ok) return status; - env->promises().update_rejection_tracker(); + env->agent()->set_rejection_tracking(env->promises().has_reject_callback()); return napi_ok; } @@ -454,7 +487,7 @@ extern "C" napi_status status = env->promises().set_hooks(init, before, after, resolve); if (status != napi_ok) return status; - env->promises().attach_runtime_hooks(); + env->agent()->attach_promise_hook(); return napi_ok; } @@ -530,7 +563,7 @@ extern "C" JSValueConst raw = napi_quickjs_value_inner(env, promise); if (!JS_IsPromise(raw)) return napi_invalid_arg; - JS_PromiseMarkAsHandled(napi_quickjs_value_context(env, promise), raw); + JS_PromiseMarkAsHandled(env->context(), raw); return napi_ok; } @@ -544,22 +577,18 @@ extern "C" *target_out = nullptr; *handler_out = nullptr; - JSContext *ctx = napi_quickjs_value_context(env, proxy); - if (ctx == nullptr) - return napi_invalid_arg; - + JSContext *ctx = env->context(); JSValueConst raw = napi_quickjs_value_inner(env, proxy); if (!JS_IsProxy(raw)) return napi_invalid_arg; - napi_env_context_scope__ context_scope{env, ctx}; JSValue target = JS_GetProxyTarget(ctx, raw); if (JS_IsException(target)) { JSValue exception = JS_GetException(ctx); JS_FreeValue(ctx, exception); - *target_out = env->wrap_value_in_current_scope(ctx, JS_NULL, true); - *handler_out = env->wrap_value_in_current_scope(ctx, JS_NULL, true); + *target_out = env->wrap_value_in_current_scope(JS_NULL, true); + *handler_out = env->wrap_value_in_current_scope(JS_NULL, true); return (*target_out == nullptr || *handler_out == nullptr) ? napi_generic_failure : napi_ok; } @@ -569,13 +598,13 @@ extern "C" JS_FreeValue(ctx, target); JSValue exception = JS_GetException(ctx); JS_FreeValue(ctx, exception); - *target_out = env->wrap_value_in_current_scope(ctx, JS_NULL, true); - *handler_out = env->wrap_value_in_current_scope(ctx, JS_NULL, true); + *target_out = env->wrap_value_in_current_scope(JS_NULL, true); + *handler_out = env->wrap_value_in_current_scope(JS_NULL, true); return (*target_out == nullptr || *handler_out == nullptr) ? napi_generic_failure : napi_ok; } - *target_out = env->wrap_value_in_current_scope(ctx, target, true); - *handler_out = env->wrap_value_in_current_scope(ctx, handler, true); + *target_out = env->wrap_value_in_current_scope(target, true); + *handler_out = env->wrap_value_in_current_scope(handler, true); return (*target_out == nullptr || *handler_out == nullptr) ? napi_generic_failure : napi_ok; } @@ -994,7 +1023,7 @@ extern "C" { if (!napi_util__::check_env(env) || result_out == nullptr) return napi_invalid_arg; - JSValueConst value = env->promises().continuation_preserved_embedder_data(); + JSValueConst value = env->agent()->continuation_preserved_embedder_data(); if (JS_IsUndefined(value)) return napi_util__::create_undefined(env, result_out); return napi_util__::wrap_dup(env, value, result_out); @@ -1006,7 +1035,7 @@ extern "C" { if (!napi_util__::check_env(env) || value == nullptr) return napi_invalid_arg; - env->promises().set_continuation_preserved_embedder_data(napi_quickjs_value_inner(env, value)); + env->agent()->set_continuation_preserved_embedder_data(napi_quickjs_value_inner(env, value)); return napi_ok; } From 6e2ebd3d46db16f9a41a7c90e200e387198f9947 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Fri, 23 Oct 2026 16:21:13 +0200 Subject: [PATCH 003/150] Split the bridge's env state into agent and env SnapiEnvState held everything the bridge keeps for an env, including tables that belong to the engine instance: guest value slots, scope frames, refs, deferreds, the module_wrap, bytecode, profile and buffer lease handle tables, callback invocations, active_callback_ctx and the value limit. Once several realm envs share an isolate, a guest value id minted through one env has to stay valid with the others. SnapiAgentState now owns those tables, the provider owner and the list of its envs. SnapiEnvState keeps the agent pointer, the napi_env and the callback registry and bindings, which record the guest env id their callbacks are invoked with. The table helpers keep their signatures and work on the env's agent, so call sites are unchanged. Scope frames remember the env that opened them and close their napi scope through it. The value limit counts callback registrations and bindings across the agent's envs. Disposing an env tears down its whole agent, in the same order as before. Each agent has one env; g_mu, g_envs and the Rust-facing signatures are unchanged. Co-Authored-By: Claude Opus 5.5 --- src/napi_bridge_init.cc | 399 ++++++++++++++++++++++++---------------- 1 file changed, 236 insertions(+), 163 deletions(-) diff --git a/src/napi_bridge_init.cc b/src/napi_bridge_init.cc index cdfd4124ed..7c0dacd833 100644 --- a/src/napi_bridge_init.cc +++ b/src/napi_bridge_init.cc @@ -110,15 +110,26 @@ struct ValueSlot { struct ScopeFrame { napi_handle_scope scope = nullptr; napi_escapable_handle_scope esc_scope = nullptr; + // The env that opened the napi scope, which must also close it. Frames are + // shared by every env of an agent, so the env popping a frame may differ. + napi_env env = nullptr; std::vector owned_slots; // Guest-visible id (0 for the root frame and for implicit per-callback // frames, which the guest cannot close). uint32_t id = 0; }; -struct SnapiEnvState { - napi_env env = nullptr; +struct SnapiEnvState; + +// One engine instance (isolate) and the thread driving it. Value ids, scope +// frames, refs and handle tables live here rather than on an env, so an id +// minted through one env stays valid with every other env of the same agent. +// Today each agent has exactly one env. +struct SnapiAgentState { + // Provider owner; releasing it tears down the isolate and all its envs. unofficial_napi_env_owner owner = nullptr; + // Envs on this agent; the first is the principal env. + std::vector envs; // Value slot table: maps generation-tagged u32 IDs to scope-bound raw // napi_values. A value id is valid until the scope frame that owns its slot @@ -156,14 +167,11 @@ struct SnapiEnvState { // handle-scope closure and retain their JavaScript values until released. HandleTable buffer_lease_handles; - // Current guest invocation driving this env. This is only valid while the + // Current guest invocation driving this agent. This is only valid while the // driving host import remains on the stack. std::atomic active_callback_ctx{nullptr}; std::unordered_map callback_invocations; uint32_t next_callback_invocation_id = 1; - std::unordered_map cb_registry; - uint32_t next_cb_reg_id = 1; - std::vector> callback_bindings; // Cap on live per-value host handles / callback registrations, bounding the // host-side bookkeeping RSS that the byte budget pools do not otherwise see. @@ -171,11 +179,39 @@ struct SnapiEnvState { size_t value_limit = 0; }; +// One N-API env. The guest's env id resolves to this; everything it shares +// with the other envs of its engine instance is on `agent`. +struct SnapiEnvState { + SnapiAgentState* agent = nullptr; + napi_env env = nullptr; + + // Guest callbacks registered through this env. Each entry records the guest + // env id the callback is invoked with, so they belong to the env. + std::unordered_map cb_registry; + uint32_t next_cb_reg_id = 1; + std::vector> callback_bindings; +}; + struct CallbackBinding { SnapiEnvState* state = nullptr; uint32_t reg_id = 0; }; +// The value limit is per agent, so registrations count across its envs. +size_t AgentCallbackRegistrations(const SnapiAgentState& agent) { + size_t count = 0; + for (const SnapiEnvState* env_state : agent.envs) count += env_state->cb_registry.size(); + return count; +} + +size_t AgentCallbackBindings(const SnapiAgentState& agent) { + size_t count = 0; + for (const SnapiEnvState* env_state : agent.envs) { + count += env_state->callback_bindings.size(); + } + return count; +} + // Never destroyed: static destructors race concurrent env teardown at process // exit (see the runtime-globals comment in unofficial_napi.cc). std::unordered_set& g_envs = *new std::unordered_set(); @@ -186,8 +222,9 @@ HandleTable& g_message_handles = *new HandleTable(); CallbackBinding* RegisterCallbackBinding(SnapiEnvState* state, uint32_t reg_id) { if (state == nullptr || reg_id == 0) return nullptr; - if (state->value_limit != 0 && - state->callback_bindings.size() >= state->value_limit) { + const SnapiAgentState& agent = *state->agent; + if (agent.value_limit != 0 && + AgentCallbackBindings(agent) >= agent.value_limit) { return nullptr; } state->callback_bindings.push_back( @@ -208,18 +245,29 @@ SnapiEnvState* LookupEnvState(SnapiEnvState* env_state) { uint32_t RegisterCallbackInvocation(SnapiEnvState* state, napi_callback_info info) { if (state == nullptr || info == nullptr) return 0; - uint32_t id = state->next_callback_invocation_id++; - if (id == 0) id = state->next_callback_invocation_id++; - state->callback_invocations[id] = CallbackInvocation{info}; + SnapiAgentState& agent = *state->agent; + uint32_t id = agent.next_callback_invocation_id++; + if (id == 0) id = agent.next_callback_invocation_id++; + agent.callback_invocations[id] = CallbackInvocation{info}; return id; } +// The helpers below take the env the guest called through and work on that +// env's agent, which owns the value, scope, ref and handle tables. + // Innermost open frame, creating the root frame on first use. ScopeFrame& CurrentFrame(SnapiEnvState& state) { - if (state.scope_frames.empty()) { - state.scope_frames.emplace_back(); + SnapiAgentState& agent = *state.agent; + if (agent.scope_frames.empty()) { + agent.scope_frames.emplace_back(); } - return state.scope_frames.back(); + return agent.scope_frames.back(); +} + +// Pushes a frame for a napi scope `state` just opened. +void PushFrame(SnapiEnvState& state, ScopeFrame frame) { + frame.env = state.env; + state.agent->scope_frames.push_back(std::move(frame)); } // Mints an id for `val` owned by `frame`. The common path stores into the @@ -227,24 +275,26 @@ ScopeFrame& CurrentFrame(SnapiEnvState& state) { uint32_t StoreValueInFrame(SnapiEnvState& state, napi_value val, ScopeFrame& frame) { if (val == nullptr) return 0; if (state.env == nullptr) return 0; - // Refuse once the per-env handle cap is reached: returning 0 surfaces as an - // N-API failure the guest can handle, instead of leaking host RSS unbounded. - if (state.value_limit != 0 && state.live_value_count >= state.value_limit) { + SnapiAgentState& agent = *state.agent; + // Refuse once the per-agent handle cap is reached: returning 0 surfaces as + // an N-API failure the guest can handle, instead of leaking host RSS + // unbounded. + if (agent.value_limit != 0 && agent.live_value_count >= agent.value_limit) { return 0; } uint32_t index; - if (!state.value_free_slots.empty()) { - index = state.value_free_slots.back(); - state.value_free_slots.pop_back(); + if (!agent.value_free_slots.empty()) { + index = agent.value_free_slots.back(); + agent.value_free_slots.pop_back(); } else { - if (state.value_slots.size() >= kValueIdMaxSlots) return 0; - index = static_cast(state.value_slots.size()); - state.value_slots.emplace_back(); + if (agent.value_slots.size() >= kValueIdMaxSlots) return 0; + index = static_cast(agent.value_slots.size()); + agent.value_slots.emplace_back(); } - ValueSlot& slot = state.value_slots[index]; + ValueSlot& slot = agent.value_slots[index]; slot.value = val; slot.in_use = true; - ++state.live_value_count; + ++agent.live_value_count; frame.owned_slots.push_back(index); return ((index + 1) << kValueIdGenBits) | slot.generation; } @@ -256,11 +306,12 @@ uint32_t StoreValue(SnapiEnvState& state, napi_value val) { napi_value LoadValue(SnapiEnvState& state, uint32_t id) { if (id == 0) return nullptr; if (state.env == nullptr) return nullptr; + SnapiAgentState& agent = *state.agent; const uint32_t index_plus_one = id >> kValueIdGenBits; - if (index_plus_one == 0 || index_plus_one > state.value_slots.size()) { + if (index_plus_one == 0 || index_plus_one > agent.value_slots.size()) { return nullptr; } - ValueSlot& slot = state.value_slots[index_plus_one - 1]; + ValueSlot& slot = agent.value_slots[index_plus_one - 1]; if (!slot.in_use || slot.generation != (id & kValueIdGenMask) || slot.value == nullptr) { return nullptr; @@ -271,31 +322,32 @@ napi_value LoadValue(SnapiEnvState& state, uint32_t id) { // Releases a slot and bumps its generation so any id minted for the old // occupant is rejected by LoadValue. The Local itself dies when the owning // napi scope closes; this only retires the id. -void FreeValueSlot(SnapiEnvState& state, uint32_t index) { - ValueSlot& slot = state.value_slots[index]; +void FreeValueSlot(SnapiAgentState& agent, uint32_t index) { + ValueSlot& slot = agent.value_slots[index]; if (!slot.in_use) return; slot.value = nullptr; slot.in_use = false; slot.generation = static_cast((slot.generation + 1) & kValueIdGenMask); - state.value_free_slots.push_back(index); - --state.live_value_count; + agent.value_free_slots.push_back(index); + --agent.live_value_count; } // Frees every slot the innermost frame owns and pops it. Closes the frame's // napi scope (which kills the backing Locals) unless `close_napi_scope` is // false (env-teardown drain, where release_env reclaims the whole env). void PopCurrentFrame(SnapiEnvState& state, bool close_napi_scope) { - if (state.scope_frames.empty()) return; - ScopeFrame frame = std::move(state.scope_frames.back()); - state.scope_frames.pop_back(); + SnapiAgentState& agent = *state.agent; + if (agent.scope_frames.empty()) return; + ScopeFrame frame = std::move(agent.scope_frames.back()); + agent.scope_frames.pop_back(); for (uint32_t index : frame.owned_slots) { - FreeValueSlot(state, index); + FreeValueSlot(agent, index); } - if (close_napi_scope && state.env != nullptr) { + if (close_napi_scope && state.env != nullptr && frame.env != nullptr) { if (frame.esc_scope != nullptr) { - (void)napi_close_escapable_handle_scope(state.env, frame.esc_scope); + (void)napi_close_escapable_handle_scope(frame.env, frame.esc_scope); } else if (frame.scope != nullptr) { - (void)napi_close_handle_scope(state.env, frame.scope); + (void)napi_close_handle_scope(frame.env, frame.scope); } } } @@ -349,69 +401,74 @@ size_t TypedArrayElementSize(napi_typedarray_type type) { uint32_t StoreRef(SnapiEnvState& state, napi_ref ref) { if (ref == nullptr) return 0; - uint32_t id = state.next_ref_id++; - state.refs[id] = ref; + SnapiAgentState& agent = *state.agent; + uint32_t id = agent.next_ref_id++; + agent.refs[id] = ref; return id; } napi_ref LoadRef(SnapiEnvState& state, uint32_t id) { if (id == 0) return nullptr; - auto it = state.refs.find(id); - return it != state.refs.end() ? it->second : nullptr; + const SnapiAgentState& agent = *state.agent; + auto it = agent.refs.find(id); + return it != agent.refs.end() ? it->second : nullptr; } void RemoveRef(SnapiEnvState& state, uint32_t id) { - state.refs.erase(id); + state.agent->refs.erase(id); } uint32_t StoreDeferred(SnapiEnvState& state, napi_deferred d) { if (d == nullptr) return 0; - uint32_t id = state.next_deferred_id++; - state.deferreds[id] = d; + SnapiAgentState& agent = *state.agent; + uint32_t id = agent.next_deferred_id++; + agent.deferreds[id] = d; return id; } napi_deferred LoadDeferred(SnapiEnvState& state, uint32_t id) { if (id == 0) return nullptr; - auto it = state.deferreds.find(id); - return it != state.deferreds.end() ? it->second : nullptr; + const SnapiAgentState& agent = *state.agent; + auto it = agent.deferreds.find(id); + return it != agent.deferreds.end() ? it->second : nullptr; } void RemoveDeferred(SnapiEnvState& state, uint32_t id) { - state.deferreds.erase(id); + state.agent->deferreds.erase(id); } // Finds the open frame with the given guest-visible id (innermost first). int FindFrameById(SnapiEnvState& state, uint32_t scope_id) { if (scope_id == 0) return -1; - for (int i = static_cast(state.scope_frames.size()) - 1; i >= 0; --i) { - if (state.scope_frames[i].id == scope_id) return i; + const std::vector& frames = state.agent->scope_frames; + for (int i = static_cast(frames.size()) - 1; i >= 0; --i) { + if (frames[i].id == scope_id) return i; } return -1; } uint32_t StoreModuleWrapHandle(SnapiEnvState& state, unofficial_napi_module module) { - return state.module_wrap_handles.Store(reinterpret_cast(module)); + return state.agent->module_wrap_handles.Store(reinterpret_cast(module)); } unofficial_napi_module LoadModuleWrapHandle(SnapiEnvState& state, uint32_t id) { - return reinterpret_cast(state.module_wrap_handles.Load(id)); + return reinterpret_cast(state.agent->module_wrap_handles.Load(id)); } void RemoveModuleWrapHandle(SnapiEnvState& state, uint32_t id) { - state.module_wrap_handles.Remove(id); + state.agent->module_wrap_handles.Remove(id); } uint32_t StoreBytecodeHandle(SnapiEnvState& state, unofficial_napi_bytecode handle) { - return state.bytecode_handles.Store(reinterpret_cast(handle)); + return state.agent->bytecode_handles.Store(reinterpret_cast(handle)); } unofficial_napi_bytecode LoadBytecodeHandle(SnapiEnvState& state, uint32_t id) { - return reinterpret_cast(state.bytecode_handles.Load(id)); + return reinterpret_cast(state.agent->bytecode_handles.Load(id)); } void RemoveBytecodeHandle(SnapiEnvState& state, uint32_t id) { - state.bytecode_handles.Remove(id); + state.agent->bytecode_handles.Remove(id); } SnapiEnvState* RequireEnvState(SnapiEnvState* env_state) { @@ -422,57 +479,82 @@ SnapiEnvState* RequireEnvState(SnapiEnvState* env_state) { return bridge_state; } +// Tears down the agent `state` belongs to, with every env on it: release_env +// takes the provider owner, which disposes the whole isolate. napi_status DisposeBridgeStateLocked(SnapiEnvState* state) { if (state == nullptr) return napi_ok; - for (const auto& entry : state->buffer_lease_handles.handles) { + SnapiAgentState* agent = state->agent; + napi_env env = state->env; + for (const auto& entry : agent->buffer_lease_handles.handles) { (void)unofficial_napi_release_buffer_lease( - state->env, static_cast(entry.second), false); + env, static_cast(entry.second), false); } - state->buffer_lease_handles.Reset(); + agent->buffer_lease_handles.Reset(); // Slots hold raw Locals; they die with the env's scopes when release_env // tears everything down, so draining the frames is pure bookkeeping. - while (!state->scope_frames.empty()) { + while (!agent->scope_frames.empty()) { PopCurrentFrame(*state, /*close_napi_scope=*/true); } - state->value_slots.clear(); - state->value_free_slots.clear(); - state->live_value_count = 0; - state->next_scope_id = 1; - state->refs.clear(); - state->next_ref_id = 1; - state->deferreds.clear(); - state->next_deferred_id = 1; - state->module_wrap_handles.Reset(); + agent->value_slots.clear(); + agent->value_free_slots.clear(); + agent->live_value_count = 0; + agent->next_scope_id = 1; + agent->refs.clear(); + agent->next_ref_id = 1; + agent->deferreds.clear(); + agent->next_deferred_id = 1; + agent->module_wrap_handles.Reset(); // Bytecode handles own engine resources outside any napi scope (V8 // Globals / QuickJS JSValue refcounts), so they must be released // explicitly — env teardown does not reclaim them. - for (auto& entry : state->bytecode_handles.handles) { + for (auto& entry : agent->bytecode_handles.handles) { if (entry.second != nullptr) { (void)unofficial_napi_bytecode_release( - state->env, reinterpret_cast(entry.second)); + env, reinterpret_cast(entry.second)); } } - state->bytecode_handles.Reset(); - state->profile_handles.Reset(); - state->callback_invocations.clear(); - state->next_callback_invocation_id = 1; - state->cb_registry.clear(); - state->next_cb_reg_id = 1; - state->callback_bindings.clear(); - if (state->owner != nullptr) { - napi_status s = unofficial_napi_release_env(state->owner, nullptr); - state->active_callback_ctx.store(nullptr, std::memory_order_release); - state->owner = nullptr; - state->env = nullptr; - g_envs.erase(state); + agent->bytecode_handles.Reset(); + agent->profile_handles.Reset(); + agent->callback_invocations.clear(); + agent->next_callback_invocation_id = 1; + for (SnapiEnvState* env_state : agent->envs) { + env_state->cb_registry.clear(); + env_state->next_cb_reg_id = 1; + env_state->callback_bindings.clear(); + } + napi_status s = napi_ok; + if (agent->owner != nullptr) { + s = unofficial_napi_release_env(agent->owner, nullptr); + agent->owner = nullptr; + } + agent->active_callback_ctx.store(nullptr, std::memory_order_release); + for (SnapiEnvState* env_state : agent->envs) { + env_state->env = nullptr; + g_envs.erase(env_state); + delete env_state; + } + delete agent; + return s; +} + +// Creates an agent for a freshly created provider env and registers that env +// as its principal env. On failure the provider env is released. +SnapiEnvState* NewAgentWithPrincipalEnvLocked(napi_env env, + unofficial_napi_env_owner owner) { + auto* agent = new (std::nothrow) SnapiAgentState(); + auto* state = new (std::nothrow) SnapiEnvState(); + if (agent == nullptr || state == nullptr) { + delete agent; delete state; - return s; + (void)unofficial_napi_release_env(owner, nullptr); + return nullptr; } - state->active_callback_ctx.store(nullptr, std::memory_order_release); - state->env = nullptr; - g_envs.erase(state); - delete state; - return napi_ok; + agent->owner = owner; + agent->envs.push_back(state); + state->agent = agent; + state->env = env; + g_envs.insert(state); + return state; } } // namespace @@ -1483,13 +1565,14 @@ void GuestFinalizerTrampoline(node_api_basic_env /*env*/, void* /*data*/, auto* bridge_state = LookupEnvState(record->state); void* callback_ctx = bridge_state != nullptr - ? bridge_state->active_callback_ctx.load(std::memory_order_acquire) + ? bridge_state->agent->active_callback_ctx.load(std::memory_order_acquire) : nullptr; if (callback_ctx != nullptr) { // Own any value ids the guest mints while running its finalizer; there is // no return value to escape, so a plain handle scope suffices (mirrors // WasmInterruptCallback). napi_env env = bridge_state->env; + std::vector& frames = bridge_state->agent->scope_frames; napi_handle_scope fin_scope = nullptr; if (env != nullptr && napi_open_handle_scope(env, &fin_scope) == napi_ok && @@ -1497,18 +1580,16 @@ void GuestFinalizerTrampoline(node_api_basic_env /*env*/, void* /*data*/, (void)CurrentFrame(*bridge_state); ScopeFrame frame; frame.scope = fin_scope; - bridge_state->scope_frames.push_back(std::move(frame)); + PushFrame(*bridge_state, std::move(frame)); } snapi_host_invoke_wasm_finalizer(callback_ctx, record->guest_env, record->wasm_fn_ptr, record->data, record->hint); if (fin_scope != nullptr) { - while (bridge_state->scope_frames.size() > 1 && - bridge_state->scope_frames.back().scope != fin_scope) { + while (frames.size() > 1 && frames.back().scope != fin_scope) { PopCurrentFrame(*bridge_state, /*close_napi_scope=*/true); } - if (!bridge_state->scope_frames.empty() && - bridge_state->scope_frames.back().scope == fin_scope) { + if (!frames.empty() && frames.back().scope == fin_scope) { PopCurrentFrame(*bridge_state, /*close_napi_scope=*/true); } } @@ -1980,12 +2061,13 @@ extern "C" int snapi_bridge_open_handle_scope(SnapiEnvState* env_state, uint32_t napi_handle_scope scope = nullptr; napi_status s = napi_open_handle_scope(env, &scope); if (s != napi_ok) return s; + SnapiAgentState& agent = *bridge_state->agent; ScopeFrame frame; frame.scope = scope; - frame.id = bridge_state->next_scope_id++; - if (frame.id == 0) frame.id = bridge_state->next_scope_id++; - bridge_state->scope_frames.push_back(std::move(frame)); - *scope_out = bridge_state->scope_frames.back().id; + frame.id = agent.next_scope_id++; + if (frame.id == 0) frame.id = agent.next_scope_id++; + PushFrame(*bridge_state, std::move(frame)); + *scope_out = agent.scope_frames.back().id; return napi_ok; } @@ -1993,12 +2075,13 @@ extern "C" int snapi_bridge_close_handle_scope(SnapiEnvState* env_state, uint32_ auto* bridge_state = RequireEnvState(env_state); if (bridge_state == nullptr) return napi_invalid_arg; const int idx = FindFrameById(*bridge_state, scope_id); - if (idx < 0 || bridge_state->scope_frames[idx].scope == nullptr) { + const std::vector& frames = bridge_state->agent->scope_frames; + if (idx < 0 || frames[idx].scope == nullptr) { return napi_invalid_arg; } // LIFO discipline: only the innermost frame may close. Implicit callback // frames have id 0 and can never match, so a guest cannot close past them. - if (static_cast(idx) != bridge_state->scope_frames.size() - 1) { + if (static_cast(idx) != frames.size() - 1) { return napi_handle_scope_mismatch; } PopCurrentFrame(*bridge_state, /*close_napi_scope=*/true); @@ -2013,12 +2096,13 @@ extern "C" int snapi_bridge_open_escapable_handle_scope(SnapiEnvState* env_state napi_escapable_handle_scope scope = nullptr; napi_status s = napi_open_escapable_handle_scope(env, &scope); if (s != napi_ok) return s; + SnapiAgentState& agent = *bridge_state->agent; ScopeFrame frame; frame.esc_scope = scope; - frame.id = bridge_state->next_scope_id++; - if (frame.id == 0) frame.id = bridge_state->next_scope_id++; - bridge_state->scope_frames.push_back(std::move(frame)); - *scope_out = bridge_state->scope_frames.back().id; + frame.id = agent.next_scope_id++; + if (frame.id == 0) frame.id = agent.next_scope_id++; + PushFrame(*bridge_state, std::move(frame)); + *scope_out = agent.scope_frames.back().id; return napi_ok; } @@ -2026,10 +2110,11 @@ extern "C" int snapi_bridge_close_escapable_handle_scope(SnapiEnvState* env_stat auto* bridge_state = RequireEnvState(env_state); if (bridge_state == nullptr) return napi_invalid_arg; const int idx = FindFrameById(*bridge_state, scope_id); - if (idx < 0 || bridge_state->scope_frames[idx].esc_scope == nullptr) { + const std::vector& frames = bridge_state->agent->scope_frames; + if (idx < 0 || frames[idx].esc_scope == nullptr) { return napi_invalid_arg; } - if (static_cast(idx) != bridge_state->scope_frames.size() - 1) { + if (static_cast(idx) != frames.size() - 1) { return napi_handle_scope_mismatch; } PopCurrentFrame(*bridge_state, /*close_napi_scope=*/true); @@ -2043,18 +2128,19 @@ extern "C" int snapi_bridge_escape_handle(SnapiEnvState* env_state, uint32_t sco if (bridge_state == nullptr) return napi_invalid_arg; napi_env env = bridge_state->env; const int idx = FindFrameById(*bridge_state, scope_id); + std::vector& frames = bridge_state->agent->scope_frames; // The escaped Local is created in the scope enclosing the escapable one, so // its id must be owned by the parent frame; require one to exist. - if (idx <= 0 || bridge_state->scope_frames[idx].esc_scope == nullptr) { + if (idx <= 0 || frames[idx].esc_scope == nullptr) { return napi_invalid_arg; } napi_value escapee = LoadValue(*bridge_state, escapee_id); if (!escapee) return napi_invalid_arg; napi_value result = nullptr; napi_status s = - napi_escape_handle(env, bridge_state->scope_frames[idx].esc_scope, escapee, &result); + napi_escape_handle(env, frames[idx].esc_scope, escapee, &result); if (s != napi_ok) return s; - *out_id = StoreValueInFrame(*bridge_state, result, bridge_state->scope_frames[idx - 1]); + *out_id = StoreValueInFrame(*bridge_state, result, frames[idx - 1]); return napi_ok; } @@ -2320,7 +2406,7 @@ extern "C" int snapi_bridge_unofficial_acquire_buffer_lease( bridge_state->env, value, byte_offset, byte_length, static_cast(mode), &lease, &data); if (status != napi_ok) return status; - const uint32_t lease_id = bridge_state->buffer_lease_handles.Store(lease); + const uint32_t lease_id = bridge_state->agent->buffer_lease_handles.Store(lease); if (lease_id == 0) { (void)unofficial_napi_release_buffer_lease(bridge_state->env, lease, false); return napi_generic_failure; @@ -2335,11 +2421,11 @@ extern "C" int snapi_bridge_unofficial_release_buffer_lease( auto* bridge_state = RequireEnvState(env_state); if (bridge_state == nullptr) return napi_invalid_arg; auto lease = static_cast( - bridge_state->buffer_lease_handles.Load(lease_id)); + bridge_state->agent->buffer_lease_handles.Load(lease_id)); if (lease == nullptr) return napi_invalid_arg; napi_status status = unofficial_napi_release_buffer_lease( bridge_state->env, lease, modified != 0); - bridge_state->buffer_lease_handles.Remove(lease_id); + bridge_state->agent->buffer_lease_handles.Remove(lease_id); return status; } @@ -2656,7 +2742,8 @@ extern "C" int snapi_bridge_define_class(SnapiEnvState* env_state, extern "C" void* snapi_bridge_swap_active_callback_ctx(SnapiEnvState* env_state, void* callback_ctx) { auto* bridge_state = LookupEnvState(env_state); if (bridge_state == nullptr) return nullptr; - return bridge_state->active_callback_ctx.exchange(callback_ctx, std::memory_order_acq_rel); + return bridge_state->agent->active_callback_ctx.exchange(callback_ctx, + std::memory_order_acq_rel); } extern "C" int snapi_bridge_get_cb_info(SnapiEnvState* env_state, uint32_t cbinfo_id, @@ -2666,8 +2753,9 @@ extern "C" int snapi_bridge_get_cb_info(SnapiEnvState* env_state, uint32_t cbinf auto* bridge_state = RequireEnvState(env_state); if (bridge_state == nullptr) return napi_invalid_arg; napi_env env = bridge_state->env; - auto it = bridge_state->callback_invocations.find(cbinfo_id); - if (it == bridge_state->callback_invocations.end()) return napi_generic_failure; + const auto& invocations = bridge_state->agent->callback_invocations; + auto it = invocations.find(cbinfo_id); + if (it == invocations.end()) return napi_generic_failure; size_t wanted = argc_ptr != nullptr ? static_cast(*argc_ptr) : 0; size_t actual = wanted; @@ -2707,8 +2795,9 @@ extern "C" int snapi_bridge_get_new_target(SnapiEnvState* env_state, uint32_t cb auto* bridge_state = RequireEnvState(env_state); if (bridge_state == nullptr) return napi_invalid_arg; napi_env env = bridge_state->env; - auto it = bridge_state->callback_invocations.find(cbinfo_id); - if (it == bridge_state->callback_invocations.end()) return napi_generic_failure; + const auto& invocations = bridge_state->agent->callback_invocations; + auto it = invocations.find(cbinfo_id); + if (it == invocations.end()) return napi_generic_failure; napi_value result; napi_status s = napi_get_new_target(env, it->second.info, &result); if (s != napi_ok) return s; @@ -2735,11 +2824,12 @@ void WasmInterruptCallback(napi_env env, void* raw) { auto* bridge_state = LookupEnvState(request->state); void* callback_ctx = bridge_state != nullptr - ? bridge_state->active_callback_ctx.load(std::memory_order_acquire) + ? bridge_state->agent->active_callback_ctx.load(std::memory_order_acquire) : nullptr; if (callback_ctx != nullptr) { // Own the ids the guest mints while servicing the interrupt (no return // value to escape, so a plain frame suffices). + std::vector& frames = bridge_state->agent->scope_frames; napi_handle_scope interrupt_scope = nullptr; if (env != nullptr && napi_open_handle_scope(env, &interrupt_scope) == napi_ok && @@ -2747,17 +2837,15 @@ void WasmInterruptCallback(napi_env env, void* raw) { (void)CurrentFrame(*bridge_state); ScopeFrame frame; frame.scope = interrupt_scope; - bridge_state->scope_frames.push_back(std::move(frame)); + PushFrame(*bridge_state, std::move(frame)); } snapi_host_invoke_wasm_callback( callback_ctx, request->guest_env, request->wasm_fn_ptr, request->callback_arg); if (interrupt_scope != nullptr) { - while (bridge_state->scope_frames.size() > 1 && - bridge_state->scope_frames.back().scope != interrupt_scope) { + while (frames.size() > 1 && frames.back().scope != interrupt_scope) { PopCurrentFrame(*bridge_state, /*close_napi_scope=*/true); } - if (!bridge_state->scope_frames.empty() && - bridge_state->scope_frames.back().scope == interrupt_scope) { + if (!frames.empty() && frames.back().scope == interrupt_scope) { PopCurrentFrame(*bridge_state, /*close_napi_scope=*/true); } } @@ -2787,8 +2875,8 @@ static napi_value generic_wasm_callback(napi_env env, napi_callback_info info) { napi_get_undefined(env, &undef); return undef; } - void* callback_ctx = - bridge_state->active_callback_ctx.load(std::memory_order_acquire); + SnapiAgentState& agent = *bridge_state->agent; + void* callback_ctx = agent.active_callback_ctx.load(std::memory_order_acquire); if (callback_ctx == nullptr) { napi_value undef; napi_get_undefined(env, &undef); @@ -2816,7 +2904,7 @@ static napi_value generic_wasm_callback(napi_env env, napi_callback_info info) { if (napi_open_escapable_handle_scope(env, &cb_scope) == napi_ok && cb_scope != nullptr) { ScopeFrame frame; frame.esc_scope = cb_scope; - bridge_state->scope_frames.push_back(std::move(frame)); + PushFrame(*bridge_state, std::move(frame)); } // Call Rust trampoline → WASM callback @@ -2828,18 +2916,17 @@ static napi_value generic_wasm_callback(napi_env env, napi_callback_info info) { uint32_t result_id = snapi_host_invoke_wasm_callback( callback_ctx, it->second.guest_env, wasm_fn_ptr, cbinfo_id); - bridge_state->callback_invocations.erase(cbinfo_id); + agent.callback_invocations.erase(cbinfo_id); napi_value result = LoadValue(*bridge_state, result_id); if (cb_scope != nullptr) { // Force-close any scopes the guest left unbalanced so LIFO holds, then // escape the return value into the enclosing scope and pop our frame. - while (bridge_state->scope_frames.size() > 1 && - bridge_state->scope_frames.back().esc_scope != cb_scope) { + std::vector& frames = agent.scope_frames; + while (frames.size() > 1 && frames.back().esc_scope != cb_scope) { PopCurrentFrame(*bridge_state, /*close_napi_scope=*/true); } - if (!bridge_state->scope_frames.empty() && - bridge_state->scope_frames.back().esc_scope == cb_scope) { + if (!frames.empty() && frames.back().esc_scope == cb_scope) { if (result != nullptr) { napi_value escaped = nullptr; if (napi_escape_handle(env, cb_scope, result, &escaped) == napi_ok && @@ -2863,8 +2950,9 @@ extern "C" uint32_t snapi_bridge_alloc_cb_reg_id(SnapiEnvState* env_state) { if (env_state == nullptr) return 0; // Cap callback registrations alongside value handles: 0 signals failure so // the registration chain aborts instead of growing cb_registry unbounded. - if (env_state->value_limit != 0 && - env_state->cb_registry.size() >= env_state->value_limit) { + const SnapiAgentState& agent = *env_state->agent; + if (agent.value_limit != 0 && + AgentCallbackRegistrations(agent) >= agent.value_limit) { return 0; } return env_state->next_cb_reg_id++; @@ -2930,14 +3018,8 @@ extern "C" int snapi_bridge_unofficial_create_env(int32_t module_api_version, } if (s != napi_ok) return s; - auto* state = new (std::nothrow) SnapiEnvState(); - if (state == nullptr) { - (void)unofficial_napi_release_env(owner, nullptr); - return napi_generic_failure; - } - state->env = env; - state->owner = owner; - g_envs.insert(state); + SnapiEnvState* state = NewAgentWithPrincipalEnvLocked(env, owner); + if (state == nullptr) return napi_generic_failure; if (env_out != nullptr) *env_out = state; return napi_ok; @@ -2993,14 +3075,8 @@ extern "C" int snapi_bridge_unofficial_create_env_with_options( module_api_version, has_options ? &options : nullptr, &env, &owner); if (s != napi_ok) return s; - auto* state = new (std::nothrow) SnapiEnvState(); - if (state == nullptr) { - (void)unofficial_napi_release_env(owner, nullptr); - return napi_generic_failure; - } - state->env = env; - state->owner = owner; - g_envs.insert(state); + SnapiEnvState* state = NewAgentWithPrincipalEnvLocked(env, owner); + if (state == nullptr) return napi_generic_failure; if (env_out != nullptr) *env_out = state; return napi_ok; @@ -3039,7 +3115,7 @@ extern "C" int snapi_bridge_unofficial_set_host_near_heap_limit_callback( extern "C" uint64_t snapi_bridge_unofficial_get_live_value_count(SnapiEnvState* env_state) { auto* bridge_state = LookupEnvState(env_state); return bridge_state != nullptr - ? static_cast(bridge_state->live_value_count) + ? static_cast(bridge_state->agent->live_value_count) : 0; } @@ -3057,7 +3133,7 @@ extern "C" int snapi_bridge_unofficial_set_value_limit(SnapiEnvState* env_state, if (env_state == nullptr) { return napi_invalid_arg; } - env_state->value_limit = static_cast(limit); + env_state->agent->value_limit = static_cast(limit); return napi_ok; } @@ -3537,7 +3613,7 @@ extern "C" int snapi_bridge_unofficial_profile_start(SnapiEnvState* env_state, env, static_cast(kind), &result, &profile); if (s != napi_ok) return s; *result_out = static_cast(result); - *profile_out = bridge_state->profile_handles.Store( + *profile_out = bridge_state->agent->profile_handles.Store( reinterpret_cast(profile)); return napi_ok; } @@ -3551,12 +3627,12 @@ extern "C" int snapi_bridge_unofficial_profile_stop(SnapiEnvState* env_state, std::lock_guard lock(g_mu); if (json_out == nullptr) return napi_invalid_arg; auto profile = reinterpret_cast( - bridge_state->profile_handles.Load(profile_id)); + bridge_state->agent->profile_handles.Load(profile_id)); if (profile == nullptr) return napi_invalid_arg; napi_value json = nullptr; napi_status s = unofficial_napi_profile_stop(env, profile, &json); if (s != napi_cannot_run_js && s != napi_invalid_arg) { - (void)bridge_state->profile_handles.Take(profile_id); + (void)bridge_state->agent->profile_handles.Take(profile_id); } if (s != napi_ok) return s; *json_out = json != nullptr ? StoreValue(*bridge_state, json) : 0; @@ -4304,13 +4380,10 @@ extern "C" int snapi_bridge_unofficial_module_wrap_create_required_module_facade extern "C" void snapi_bridge_dispose() { std::lock_guard lock(g_mu); - std::vector env_states; - env_states.reserve(g_envs.size()); - for (auto* env_state : g_envs) { - env_states.push_back(env_state); - } - for (auto* env_state : env_states) { - (void)DisposeBridgeStateLocked(env_state); + // Disposing an env disposes its agent and every env on it, so take one + // live env at a time instead of iterating a snapshot. + while (!g_envs.empty()) { + (void)DisposeBridgeStateLocked(*g_envs.begin()); } for (void* handle : g_message_handles.TakeAll()) { unofficial_napi_message_drop( From f2eb4e1631c4290c9dd904b6b639c93fa99b2bdb Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Fri, 23 Oct 2026 16:21:20 +0200 Subject: [PATCH 004/150] Split host-JS env state into agent and env, drop the active context HostJsEnv held the handle space every napi_value and napi_ref resolves against. It also depended on a module-global active context: env_mut switched wasmerNapiActiveGlobalContext whenever the thread moved to another env, and context_eval, is_buffer and buffer_view read it. So which global a call used depended on which env had run last. HostJsAgent now owns the handle tables and frames, object_ids, wraps, references, deferreds, finalizers, pending callbacks and active_callback_ctx. HostJsEnv keeps its global context, last exception, callbacks, closures, instance data and modules; each env creates its own agent. The JS helpers take the env's context explicitly. A null sandbox, the host global or the context's own global all mean that context. wasmerNapiActiveGlobalContext, activate() and the ACTIVE_HOST_JS_ENV thread-local are deleted, and env_mut is a plain cast. This fixes create_bytes_value and create_guest_buffer_view, which built their Buffer view before looking up the env and so used the last active env's Buffer. vm sandbox behaviour is unchanged. The node context tests are updated for the new helper signatures in the tests commit that follows. Co-Authored-By: Claude Opus 5.5 --- src/snapi_js.rs | 681 +++++++++++++++++++++++++++--------------------- 1 file changed, 379 insertions(+), 302 deletions(-) diff --git a/src/snapi_js.rs b/src/snapi_js.rs index 01e5c57785..62e779cf27 100644 --- a/src/snapi_js.rs +++ b/src/snapi_js.rs @@ -93,7 +93,6 @@ export function wasmer_napi_number(value) { export function wasmer_napi_console_error(message) { console.error(message); } -let wasmerNapiActiveGlobalContext; const wasmerNapiBuffers = new WeakSet(); const wasmerNapiHostSetTimeout = globalThis.setTimeout.bind(globalThis); const wasmerNapiHostQueueMicrotask = globalThis.queueMicrotask.bind(globalThis); @@ -517,21 +516,16 @@ export function wasmer_napi_create_global_context() { export function wasmer_napi_global_context_scope(context) { return context.scope; } -export function wasmer_napi_activate_global_context(context) { - wasmerNapiActiveGlobalContext = context; -} export function wasmer_napi_release_global_context(context) { // Retained JS wrappers must stop calling Rust before its closures are dropped. context.callbacks.dispatches = undefined; - if (wasmerNapiActiveGlobalContext === context) wasmerNapiActiveGlobalContext = undefined; } -export function wasmer_napi_context_eval(sandbox, source) { - if (wasmerNapiActiveGlobalContext !== undefined && - (sandbox == null || sandbox === globalThis || - sandbox === wasmerNapiActiveGlobalContext.scope)) { - sandbox = wasmerNapiActiveGlobalContext.scope; +// Evaluates `source` for the environment that owns `context`. A null sandbox, +// the host global and the context's own global all mean that context. +export function wasmer_napi_context_eval(context, sandbox, source) { + if (sandbox == null || sandbox === globalThis || sandbox === context.scope) { + sandbox = context.scope; } - if (sandbox == null) return (0, eval)(source); // A VM's global facade exposes the same builtins as bare identifiers while // preserving the caller's sandbox bindings. Keep its defaults context-local // so writes to process and Error hooks cannot reach the worker global. @@ -904,20 +898,21 @@ export function wasmer_napi_is_dataview(value) { return false; } } -export function wasmer_napi_is_buffer(value) { +// `context` is the calling environment's global context. +export function wasmer_napi_is_buffer(context, value) { if (wasmerNapiBuffers.has(value)) return true; - const activeBuffer = wasmerNapiActiveGlobalContext?.scopeTarget?.Buffer; - if (typeof activeBuffer?.isBuffer === 'function' && activeBuffer.isBuffer(value)) { + const contextBuffer = context.scopeTarget.Buffer; + if (typeof contextBuffer?.isBuffer === 'function' && contextBuffer.isBuffer(value)) { return true; } const hostBuffer = globalThis.Buffer; - return hostBuffer !== activeBuffer && + return hostBuffer !== contextBuffer && typeof hostBuffer?.isBuffer === 'function' && hostBuffer.isBuffer(value); } -export function wasmer_napi_buffer_view(buffer, offset, length) { +export function wasmer_napi_buffer_view(context, buffer, offset, length) { const view = new Uint8Array(buffer, offset, length); wasmerNapiBuffers.add(view); - const BufferCtor = wasmerNapiActiveGlobalContext?.scopeTarget?.Buffer ?? globalThis.Buffer; + const BufferCtor = context.scopeTarget.Buffer ?? globalThis.Buffer; if (typeof BufferCtor === 'function' && BufferCtor.prototype != null) { Object.setPrototypeOf(view, BufferCtor.prototype); } @@ -1139,10 +1134,13 @@ extern "C" { fn wasmer_napi_console_error(message: &str); fn wasmer_napi_create_global_context() -> JsValue; fn wasmer_napi_global_context_scope(context: &JsValue) -> JsValue; - fn wasmer_napi_activate_global_context(context: &JsValue); fn wasmer_napi_release_global_context(context: &JsValue); #[wasm_bindgen(catch)] - fn wasmer_napi_context_eval(sandbox: &JsValue, source: &str) -> Result; + fn wasmer_napi_context_eval( + context: &JsValue, + sandbox: &JsValue, + source: &str, + ) -> Result; #[wasm_bindgen(catch)] fn wasmer_napi_compile_function( scope: &JsValue, @@ -1182,8 +1180,13 @@ extern "C" { fn wasmer_napi_typed_array_kind(value: &JsValue) -> i32; fn wasmer_napi_is_arraybuffer(value: &JsValue) -> bool; fn wasmer_napi_is_dataview(value: &JsValue) -> bool; - fn wasmer_napi_is_buffer(value: &JsValue) -> bool; - fn wasmer_napi_buffer_view(buffer: &JsValue, offset: u32, length: u32) -> JsValue; + fn wasmer_napi_is_buffer(context: &JsValue, value: &JsValue) -> bool; + fn wasmer_napi_buffer_view( + context: &JsValue, + buffer: &JsValue, + offset: u32, + length: u32, + ) -> JsValue; #[wasm_bindgen(catch)] fn wasmer_napi_get_all_property_names( value: &JsValue, @@ -1341,7 +1344,11 @@ struct SourceTextModule { evaluation: Option, } -struct HostJsEnv { +/// State shared by every environment of one host JavaScript agent (a worker +/// or page): the handle space that gives napi_value, napi_ref and the other +/// per-handle records their meaning, plus agent-wide callback and finalizer +/// bookkeeping. Today each environment owns its own agent. +struct HostJsAgent { values: Vec>, value_live: Vec, value_free_slots: Vec, @@ -1354,33 +1361,44 @@ struct HostJsEnv { next_wrap_id: u32, backing_store_ids: WeakMap, next_backing_store_id: u32, - global_context: JsValue, - live_env_addr: Rc>, - last_exception: Option, + /// The Wasmer store a guest callback runs in; one per agent thread. active_callback_ctx: *mut c_void, next_deferred: u32, deferreds: IdHashMap, next_reference: u32, references: IdHashMap, - next_callback: u32, - callback_regs: IdHashMap, next_cbinfo: u32, callback_infos: IdHashMap, + /// JS-to-guest calls deferred while JSPI is suspended. pending_callbacks: VecDeque, - closures: Vec, - instance_data: u64, wraps: IdHashMap, guest_finalizers: Vec, guest_buffer_finalizers: Vec, externals: IdHashMap, backing_tokens: IdHashMap, type_tags: IdHashMap, + /// Embedder hooks are attached once per agent. + embedder_hooks_attached: bool, +} + +/// One N-API environment: its realm (the virtual global context, fixed for +/// the environment's life), the callbacks and modules created through it, +/// and addon state. +struct HostJsEnv { + agent: Box, + global_context: JsValue, + live_env_addr: Rc>, + /// Pending exception of calls made through this environment. + last_exception: Option, + next_callback: u32, + callback_regs: IdHashMap, + closures: Vec, + instance_data: u64, next_module: u32, next_bytecode: u32, bytecodes: IdHashMap, synthetic_modules: IdHashMap, source_text_modules: IdHashMap, - embedder_hooks_attached: bool, } struct HostJsBytecode { @@ -1396,6 +1414,7 @@ fn host_js_source_for_shape( ) -> Result { if source_text_id != 0 { return state + .agent .get(source_text_id) .and_then(JsValue::as_string) .ok_or(NAPI_STRING_EXPECTED); @@ -1411,6 +1430,26 @@ fn host_js_source_for_shape( } impl HostJsEnv { + fn new() -> Self { + Self { + agent: Box::new(HostJsAgent::new()), + global_context: wasmer_napi_create_global_context(), + live_env_addr: Rc::new(Cell::new(0)), + last_exception: None, + next_callback: 1, + callback_regs: IdHashMap::default(), + closures: Vec::new(), + instance_data: 0, + next_module: 1, + next_bytecode: 1, + bytecodes: IdHashMap::default(), + synthetic_modules: IdHashMap::default(), + source_text_modules: IdHashMap::default(), + } + } +} + +impl HostJsAgent { fn new() -> Self { // Handle zero is N-API's null pointer sentinel, never a JS value. Self { @@ -1431,32 +1470,20 @@ impl HostJsEnv { next_wrap_id: 1, backing_store_ids: WeakMap::new(), next_backing_store_id: 1, - global_context: wasmer_napi_create_global_context(), - live_env_addr: Rc::new(Cell::new(0)), - last_exception: None, active_callback_ctx: ptr::null_mut(), next_deferred: 1, deferreds: IdHashMap::default(), next_reference: 1, references: IdHashMap::default(), - next_callback: 1, - callback_regs: IdHashMap::default(), next_cbinfo: 1, callback_infos: IdHashMap::default(), pending_callbacks: VecDeque::new(), - closures: Vec::new(), - instance_data: 0, wraps: IdHashMap::default(), guest_finalizers: Vec::new(), guest_buffer_finalizers: Vec::new(), externals: IdHashMap::default(), backing_tokens: IdHashMap::default(), type_tags: IdHashMap::default(), - next_module: 1, - next_bytecode: 1, - bytecodes: IdHashMap::default(), - synthetic_modules: IdHashMap::default(), - source_text_modules: IdHashMap::default(), embedder_hooks_attached: false, } } @@ -1645,10 +1672,6 @@ impl HostJsEnv { Some(unsafe { &*value.get() }) } - fn activate(&self) { - wasmer_napi_activate_global_context(&self.global_context); - } - fn open_value_frame(&mut self) -> u32 { let id = self.next_value_frame.max(1); self.next_value_frame = id.saturating_add(1); @@ -1711,11 +1734,6 @@ impl HostJsEnv { thread_local! { static BUFFER_ALLOCS: RefCell>> = RefCell::new(IdHashMap::default()); - // N-API calls normally arrive in long runs from one guest environment. - // Realm activation is only a context switch; repeating its wasm-bindgen - // call before every operation doubles the host boundary crossings on the - // hottest path without changing observable state. - static ACTIVE_HOST_JS_ENV: Cell = const { Cell::new(0) }; } #[unsafe(no_mangle)] @@ -1750,22 +1768,14 @@ unsafe fn env_mut<'a>(env: SnapiEnv) -> Result<&'a mut HostJsEnv, i32> { if env.is_null() { return Err(NAPI_INVALID_ARG); } - let state = unsafe { &mut *env.cast::() }; - let env_addr = env as usize; - ACTIVE_HOST_JS_ENV.with(|active| { - if active.get() != env_addr { - state.activate(); - active.set(env_addr); - } - }); - Ok(state) + Ok(unsafe { &mut *env.cast::() }) } fn evaluation_scope(state: &HostJsEnv, context_id: u32) -> Result { if context_id == 0 { return Ok(wasmer_napi_global_context_scope(&state.global_context)); } - let Some(context) = state.get(context_id) else { + let Some(context) = state.agent.get(context_id) else { return Err(NAPI_INVALID_ARG); }; if context.is_null() || context.is_undefined() { @@ -1850,9 +1860,9 @@ fn value_bytes(value: &JsValue) -> Option> { pub(crate) fn get_value_byte_length_and_token(env: SnapiEnv, id: u32) -> Result<(u32, u64), i32> { let state = unsafe { env_mut(env) }?; - let value = state.get(id).ok_or(NAPI_INVALID_ARG)?; + let value = state.agent.get(id).ok_or(NAPI_INVALID_ARG)?; let byte_len = value_byte_view(value).ok_or(NAPI_INVALID_ARG)?.length(); - let token = state.backing_store_token(id).unwrap_or(id as u64); + let token = state.agent.backing_store_token(id).unwrap_or(id as u64); Ok((byte_len, token)) } @@ -1866,7 +1876,7 @@ pub(crate) fn copy_value_bytes_to_memory( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(value) = state.get(id) else { + let Some(value) = state.agent.get(id) else { return NAPI_INVALID_ARG; }; let Some(source) = value_byte_view(value) else { @@ -1892,7 +1902,7 @@ pub(crate) fn copy_value_range_to_memory( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(value) = state.get(id) else { + let Some(value) = state.agent.get(id) else { return NAPI_INVALID_ARG; }; let Some(source) = value_byte_view(value) else { @@ -1920,7 +1930,7 @@ pub(crate) fn copy_memory_bytes_to_reference( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(reference) = state.references.get(&reference_id) else { + let Some(reference) = state.agent.references.get(&reference_id) else { return NAPI_INVALID_ARG; }; let Some(value) = reference.strong.clone().or_else(|| { @@ -1953,7 +1963,7 @@ pub(crate) fn copy_reference_bytes_to_memory( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(reference) = state.references.get(&reference_id) else { + let Some(reference) = state.agent.references.get(&reference_id) else { return NAPI_INVALID_ARG; }; let Some(value) = reference.strong.clone().or_else(|| { @@ -1988,7 +1998,7 @@ pub(crate) fn copy_memory_range_to_reference( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(reference) = state.references.get(&reference_id) else { + let Some(reference) = state.agent.references.get(&reference_id) else { return NAPI_INVALID_ARG; }; let Some(value) = reference.strong.as_ref() else { @@ -2012,7 +2022,7 @@ unsafe fn put_value(env: SnapiEnv, out: *mut u32, value: JsValue) -> i32 { let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let id = state.insert(value); + let id = state.agent.insert(value); unsafe { write(out, id) }.map_or_else(|e| e, |_| NAPI_OK) } @@ -2021,7 +2031,7 @@ unsafe fn put_primitive(env: SnapiEnv, out: *mut u32, value: JsValue) -> i32 { let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let id = state.insert_primitive(value); + let id = state.agent.insert_primitive(value); unsafe { write(out, id) }.map_or_else(|e| e, |_| NAPI_OK) } @@ -2031,7 +2041,7 @@ unsafe fn put_primitive(env: SnapiEnv, out: *mut u32, value: JsValue) -> i32 { pub(crate) unsafe fn host_js_value(env: SnapiEnv, id: u32) -> Result { let state = unsafe { env_mut(env) }?; - state.get(id).cloned().ok_or(NAPI_INVALID_ARG) + state.agent.get(id).cloned().ok_or(NAPI_INVALID_ARG) } pub(crate) unsafe fn host_js_put_primitive(env: SnapiEnv, value: JsValue, out: *mut u32) -> i32 { @@ -2047,7 +2057,7 @@ pub(crate) unsafe fn host_js_set_named_property( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let (Some(obj), Some(value)) = (state.get(obj), state.get(value)) else { + let (Some(obj), Some(value)) = (state.agent.get(obj), state.agent.get(value)) else { return NAPI_INVALID_ARG; }; match Reflect::set(obj, key, value) { @@ -2068,7 +2078,7 @@ pub(crate) unsafe fn host_js_get_named_property( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(value) = state.get(obj) else { + let Some(value) = state.agent.get(obj) else { return NAPI_INVALID_ARG; }; if !wasmer_napi_is_object_like(value) { @@ -2076,7 +2086,7 @@ pub(crate) unsafe fn host_js_get_named_property( } unsafe { reflect_op(env, out, |s| { - Reflect::get(s.get(obj).ok_or(JsValue::NULL)?, key) + Reflect::get(s.agent.get(obj).ok_or(JsValue::NULL)?, key) }) } } @@ -2090,7 +2100,7 @@ pub(crate) unsafe fn host_js_has_named_property( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(object) = state.get(obj_id) else { + let Some(object) = state.agent.get(obj_id) else { return NAPI_INVALID_ARG; }; match Reflect::has(object, key) { @@ -2171,12 +2181,6 @@ pub unsafe extern "C" fn snapi_bridge_unofficial_release_env(env: SnapiEnv) -> i return NAPI_INVALID_ARG; } let state = unsafe { Box::from_raw(env.cast::()) }; - let env_addr = env as usize; - ACTIVE_HOST_JS_ENV.with(|active| { - if active.get() == env_addr { - active.set(0); - } - }); state.live_env_addr.set(0); wasmer_napi_release_global_context(&state.global_context); // JS dispatch slots are now empty, so dropping the environment can free all @@ -2223,7 +2227,7 @@ pub unsafe extern "C" fn snapi_bridge_get_global(env: SnapiEnv, out: *mut u32) - return NAPI_INVALID_ARG; }; let global = wasmer_napi_global_context_scope(&state.global_context); - let id = state.insert(global); + let id = state.agent.insert(global); unsafe { write(out, id) }.map_or_else(|error| error, |()| NAPI_OK) } @@ -2293,7 +2297,7 @@ unsafe fn read_string_bytes( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(value) = state.get(id) else { + let Some(value) = state.agent.get(id) else { return NAPI_INVALID_ARG; }; let Some(text) = value.as_string() else { @@ -2351,7 +2355,7 @@ pub unsafe extern "C" fn snapi_bridge_get_value_string_utf16( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(text) = state.get(id).and_then(JsValue::as_string) else { + let Some(text) = state.agent.get(id).and_then(JsValue::as_string) else { return NAPI_STRING_EXPECTED; }; let encoded: Vec = text.encode_utf16().collect(); @@ -2415,7 +2419,7 @@ macro_rules! read_number { let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(value) = state.get(id) else { + let Some(value) = state.agent.get(id) else { return NAPI_INVALID_ARG; }; let Some(value) = value.as_f64() else { @@ -2435,7 +2439,7 @@ pub unsafe extern "C" fn snapi_bridge_get_value_bool(env: SnapiEnv, id: u32, out let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(value) = state.get(id).and_then(JsValue::as_bool) else { + let Some(value) = state.agent.get(id).and_then(JsValue::as_bool) else { return NAPI_INVALID_ARG; }; unsafe { write(out, i32::from(value)) }.map_or_else(|e| e, |_| NAPI_OK) @@ -2465,10 +2469,10 @@ pub unsafe extern "C" fn snapi_bridge_typeof(env: SnapiEnv, id: u32, out: *mut i let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(value) = state.get(id) else { + let Some(value) = state.agent.get(id) else { return NAPI_INVALID_ARG; }; - let typ = if state.externals.contains_key(&id) { + let typ = if state.agent.externals.contains_key(&id) { 8 // napi_external } else { napi_typeof(value) @@ -2483,7 +2487,7 @@ macro_rules! type_test { let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(value) = state.get(id) else { + let Some(value) = state.agent.get(id) else { return NAPI_INVALID_ARG; }; unsafe { write(out, i32::from(($test)(value))) }.map_or_else(|e| e, |_| NAPI_OK) @@ -2507,9 +2511,19 @@ type_test!(snapi_bridge_is_date, |v: &JsValue| v .is_instance_of::()); type_test!(snapi_bridge_is_promise, |v: &JsValue| v .is_instance_of::()); -type_test!(snapi_bridge_is_buffer, |v: &JsValue| { - wasmer_napi_is_buffer(v) -}); +// A Buffer is recognised through the calling environment's Buffer, so this +// test needs the environment's context and cannot use `type_test!`. +#[unsafe(no_mangle)] +pub unsafe extern "C" fn snapi_bridge_is_buffer(env: SnapiEnv, id: u32, out: *mut i32) -> i32 { + let Ok(state) = (unsafe { env_mut(env) }) else { + return NAPI_INVALID_ARG; + }; + let Some(value) = state.agent.get(id) else { + return NAPI_INVALID_ARG; + }; + let is_buffer = wasmer_napi_is_buffer(&state.global_context, value); + unsafe { write(out, i32::from(is_buffer)) }.map_or_else(|e| e, |_| NAPI_OK) +} unsafe fn reflect_op( env: SnapiEnv, @@ -2521,7 +2535,7 @@ unsafe fn reflect_op( }; match f(state) { Ok(value) => { - let id = state.insert(value); + let id = state.agent.insert(value); unsafe { write(out, id) }.map_or_else(|e| e, |_| NAPI_OK) } Err(err) => { @@ -2541,8 +2555,11 @@ pub unsafe extern "C" fn snapi_bridge_set_property( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let (Some(obj), Some(key), Some(value)) = (state.get(obj), state.get(key), state.get(value)) - else { + let (Some(obj), Some(key), Some(value)) = ( + state.agent.get(obj), + state.agent.get(key), + state.agent.get(value), + ) else { return NAPI_INVALID_ARG; }; match Reflect::set(obj, key, value) { @@ -2564,8 +2581,8 @@ pub unsafe extern "C" fn snapi_bridge_get_property( unsafe { reflect_op(env, out, |s| { Reflect::get( - s.get(obj).ok_or(JsValue::NULL)?, - s.get(key).ok_or(JsValue::NULL)?, + s.agent.get(obj).ok_or(JsValue::NULL)?, + s.agent.get(key).ok_or(JsValue::NULL)?, ) }) } @@ -2607,7 +2624,7 @@ pub unsafe extern "C" fn snapi_bridge_set_element( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let (Some(obj), Some(value)) = (state.get(obj), state.get(value)) else { + let (Some(obj), Some(value)) = (state.agent.get(obj), state.agent.get(value)) else { return NAPI_INVALID_ARG; }; match Reflect::set(obj, &JsValue::from_f64(index as f64), value) { @@ -2629,7 +2646,7 @@ pub unsafe extern "C" fn snapi_bridge_get_element( unsafe { reflect_op(env, out, |s| { Reflect::get( - s.get(obj).ok_or(JsValue::NULL)?, + s.agent.get(obj).ok_or(JsValue::NULL)?, &JsValue::from_f64(index as f64), ) }) @@ -2645,7 +2662,7 @@ pub unsafe extern "C" fn snapi_bridge_get_array_length( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(value) = state.get(id) else { + let Some(value) = state.agent.get(id) else { return NAPI_INVALID_ARG; }; if !Array::is_array(value) { @@ -2662,7 +2679,7 @@ pub unsafe extern "C" fn snapi_bridge_get_property_names( ) -> i32 { unsafe { reflect_op(env, out, |s| { - Ok(Object::keys(&Object::from(s.get(id).ok_or(JsValue::NULL)?.clone())).into()) + Ok(Object::keys(&Object::from(s.agent.get(id).ok_or(JsValue::NULL)?.clone())).into()) }) } } @@ -2677,7 +2694,7 @@ pub unsafe extern "C" fn snapi_bridge_strict_equals( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let (Some(a), Some(b)) = (state.get(a), state.get(b)) else { + let (Some(a), Some(b)) = (state.agent.get(a), state.agent.get(b)) else { return NAPI_INVALID_ARG; }; unsafe { write(out, i32::from(a == b)) }.map_or_else(|e| e, |_| NAPI_OK) @@ -2688,6 +2705,7 @@ unsafe fn create_error(env: SnapiEnv, code: u32, message: u32, out: *mut u32, ki return NAPI_INVALID_ARG; }; let message = state + .agent .get(message) .and_then(|value| js_string(value).ok()) .unwrap_or_default(); @@ -2697,11 +2715,11 @@ unsafe fn create_error(env: SnapiEnv, code: u32, message: u32, out: *mut u32, ki _ => Error::new(&message).into(), }; if code != 0 - && let Some(code) = state.get(code) + && let Some(code) = state.agent.get(code) { let _ = Reflect::set(&value, &JsValue::from_str("code"), code); } - let id = state.insert(value); + let id = state.agent.insert(value); unsafe { write(out, id) }.map_or_else(|e| e, |_| NAPI_OK) } @@ -2738,7 +2756,7 @@ pub unsafe extern "C" fn snapi_bridge_throw(env: SnapiEnv, id: u32) -> i32 { let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(value) = state.get(id).cloned() else { + let Some(value) = state.agent.get(id).cloned() else { return NAPI_INVALID_ARG; }; state.last_exception = Some(value); @@ -2762,7 +2780,7 @@ pub unsafe extern "C" fn snapi_bridge_get_and_clear_last_exception( return NAPI_INVALID_ARG; }; let value = state.last_exception.take().unwrap_or(JsValue::UNDEFINED); - let id = state.insert(value); + let id = state.agent.insert(value); unsafe { write(out, id) }.map_or_else(|e| e, |_| NAPI_OK) } @@ -2779,13 +2797,14 @@ pub unsafe extern "C" fn snapi_bridge_call_function( return NAPI_INVALID_ARG; }; let Some(function) = state + .agent .get(func) .and_then(|v| v.dyn_ref::()) .cloned() else { return NAPI_FUNCTION_EXPECTED; }; - let this = state.get(recv).cloned().unwrap_or(JsValue::UNDEFINED); + let this = state.agent.get(recv).cloned().unwrap_or(JsValue::UNDEFINED); let ids = if argv.is_null() && argc != 0 { return NAPI_INVALID_ARG; } else if argc == 0 { @@ -2795,14 +2814,14 @@ pub unsafe extern "C" fn snapi_bridge_call_function( }; let args = Array::new(); for id in ids { - let Some(value) = state.get(*id) else { + let Some(value) = state.agent.get(*id) else { return NAPI_INVALID_ARG; }; args.push(value); } match function.apply(&this, &args) { Ok(value) => { - let id = state.insert(value); + let id = state.agent.insert(value); unsafe { write(out, id) }.map_or_else(|e| e, |_| NAPI_OK) } Err(error) => { @@ -2824,6 +2843,7 @@ pub unsafe extern "C" fn snapi_bridge_new_instance( return NAPI_INVALID_ARG; }; let Some(ctor) = state + .agent .get(ctor) .and_then(|v| v.dyn_ref::()) .cloned() @@ -2839,13 +2859,13 @@ pub unsafe extern "C" fn snapi_bridge_new_instance( }; let args = Array::new(); for id in ids { - let Some(v) = state.get(*id) else { + let Some(v) = state.agent.get(*id) else { return NAPI_INVALID_ARG; }; args.push(v); } let value = wasmer_napi_new(&ctor, &args); - let id = state.insert(value); + let id = state.agent.insert(value); unsafe { write(out, id) }.map_or_else(|e| e, |_| NAPI_OK) } @@ -2854,7 +2874,7 @@ pub unsafe extern "C" fn snapi_bridge_run_script(env: SnapiEnv, script: u32, out let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(source) = state.get(script).and_then(JsValue::as_string) else { + let Some(source) = state.agent.get(script).and_then(JsValue::as_string) else { return NAPI_STRING_EXPECTED; }; // napi_run_script executes in the environment's context. Evaluating with @@ -2862,10 +2882,9 @@ pub unsafe extern "C" fn snapi_bridge_run_script(env: SnapiEnv, script: u32, out // realm, allowing Node bootstrap code from one N-API environment to mutate // the SDK scheduler and leak state into every other environment hosted by // that worker. - let global = wasmer_napi_global_context_scope(&state.global_context); - match wasmer_napi_context_eval(&global, &source) { + match wasmer_napi_context_eval(&state.global_context, &JsValue::NULL, &source) { Ok(value) => { - let id = state.insert(value); + let id = state.agent.insert(value); unsafe { write(out, id) }.map_or_else(|e| e, |_| NAPI_OK) } Err(e) => { @@ -2892,16 +2911,16 @@ pub unsafe extern "C" fn snapi_bridge_create_promise( *rs.borrow_mut() = Some(resolve); *rj.borrow_mut() = Some(reject); }); - let deferred = state.next_deferred; - state.next_deferred = deferred.saturating_add(1); - state.deferreds.insert( + let deferred = state.agent.next_deferred; + state.agent.next_deferred = deferred.saturating_add(1); + state.agent.deferreds.insert( deferred, Deferred { resolve: resolve_slot.borrow_mut().take().unwrap(), reject: reject_slot.borrow_mut().take().unwrap(), }, ); - let id = state.insert(promise.into()); + let id = state.agent.insert(promise.into()); if unsafe { write(deferred_out, deferred) }.is_err() || unsafe { write(out, id) }.is_err() { NAPI_INVALID_ARG } else { @@ -2913,10 +2932,10 @@ unsafe fn settle(env: SnapiEnv, deferred: u32, value: u32, reject: bool) -> i32 let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(d) = state.deferreds.remove(&deferred) else { + let Some(d) = state.agent.deferreds.remove(&deferred) else { return NAPI_INVALID_ARG; }; - let Some(v) = state.get(value) else { + let Some(v) = state.agent.get(value) else { return NAPI_INVALID_ARG; }; let result = if reject { @@ -2947,13 +2966,17 @@ unsafe fn create_bytes_value( out: *mut u32, data_out: *mut u64, ) -> i32 { + let Ok(state) = (unsafe { env_mut(env) }) else { + return NAPI_INVALID_ARG; + }; let array = Uint8Array::from(bytes.as_slice()); - let value = wasmer_napi_buffer_view(&array.buffer(), 0, array.length()); + let value = wasmer_napi_buffer_view(&state.global_context, &array.buffer(), 0, array.length()); if !data_out.is_null() { let host = store_bytes(bytes); unsafe { data_out.write(host) } } - unsafe { put_value(env, out, value) } + let id = state.agent.insert(value); + unsafe { write(out, id) }.map_or_else(|e| e, |_| NAPI_OK) } pub(crate) fn create_guest_buffer_view( @@ -2963,8 +2986,17 @@ pub(crate) fn create_guest_buffer_view( byte_length: u32, out: *mut u32, ) -> i32 { - let view = wasmer_napi_buffer_view(memory_buffer, byte_offset, byte_length); - unsafe { put_value(env, out, view) } + let Ok(state) = (unsafe { env_mut(env) }) else { + return NAPI_INVALID_ARG; + }; + let view = wasmer_napi_buffer_view( + &state.global_context, + memory_buffer, + byte_offset, + byte_length, + ); + let id = state.agent.insert(view); + unsafe { write(out, id) }.map_or_else(|e| e, |_| NAPI_OK) } pub(crate) fn create_guest_typedarray_view( @@ -3024,7 +3056,7 @@ pub unsafe extern "C" fn snapi_bridge_snapshot_value_bytes( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(value) = state.get(id) else { + let Some(value) = state.agent.get(id) else { return NAPI_INVALID_ARG; }; let Some(bytes) = value_bytes(value) else { @@ -3048,7 +3080,7 @@ pub unsafe extern "C" fn snapi_bridge_overwrite_value_bytes( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(value) = state.get(id) else { + let Some(value) = state.agent.get(id) else { return NAPI_INVALID_ARG; }; let Ok(bytes) = (unsafe { bytes(data.cast(), len as usize) }) else { @@ -3076,7 +3108,7 @@ pub unsafe extern "C" fn snapi_bridge_get_buffer_info( if status == NAPI_OK && !t.is_null() { let token = unsafe { env_mut(e) } .ok() - .and_then(|state| state.backing_store_token(id)) + .and_then(|state| state.agent.backing_store_token(id)) .unwrap_or(id as u64); unsafe { t.write(token) } } @@ -3092,7 +3124,7 @@ pub unsafe extern "C" fn snapi_bridge_get_backing_store_token( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(token) = state.backing_store_token(id) else { + let Some(token) = state.agent.backing_store_token(id) else { return NAPI_INVALID_ARG; }; unsafe { write(token_out, token) }.map_or_else(|err| err, |()| NAPI_OK) @@ -3118,7 +3150,7 @@ pub unsafe extern "C" fn snapi_bridge_create_reference( let Ok(s) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(value) = s.get(value).cloned() else { + let Some(value) = s.agent.get(value).cloned() else { return NAPI_INVALID_ARG; }; let (strong, weak) = if count == 0 && (value.is_object() || value.is_function()) { @@ -3127,9 +3159,9 @@ pub unsafe extern "C" fn snapi_bridge_create_reference( } else { (Some(value), None) }; - let id = s.next_reference; - s.next_reference = id.saturating_add(1); - s.references.insert( + let id = s.agent.next_reference; + s.agent.next_reference = id.saturating_add(1); + s.agent.references.insert( id, Reference { strong, @@ -3144,7 +3176,7 @@ pub unsafe extern "C" fn snapi_bridge_delete_reference(e: SnapiEnv, id: u32) -> let Ok(s) = (unsafe { env_mut(e) }) else { return NAPI_INVALID_ARG; }; - if s.references.remove(&id).is_some() { + if s.agent.references.remove(&id).is_some() { NAPI_OK } else { NAPI_INVALID_ARG @@ -3155,7 +3187,7 @@ pub unsafe extern "C" fn snapi_bridge_reference_ref(e: SnapiEnv, id: u32, o: *mu let Ok(s) = (unsafe { env_mut(e) }) else { return NAPI_INVALID_ARG; }; - let Some(r) = s.references.get_mut(&id) else { + let Some(r) = s.agent.references.get_mut(&id) else { return NAPI_INVALID_ARG; }; if r.count == 0 && r.strong.is_none() { @@ -3170,7 +3202,7 @@ pub unsafe extern "C" fn snapi_bridge_reference_unref(e: SnapiEnv, id: u32, o: * let Ok(s) = (unsafe { env_mut(e) }) else { return NAPI_INVALID_ARG; }; - let Some(r) = s.references.get_mut(&id) else { + let Some(r) = s.agent.references.get_mut(&id) else { return NAPI_INVALID_ARG; }; r.count = r.count.saturating_sub(1); @@ -3197,14 +3229,14 @@ pub unsafe extern "C" fn snapi_bridge_get_reference_value( let Ok(s) = (unsafe { env_mut(e) }) else { return NAPI_INVALID_ARG; }; - let Some(r) = s.references.get(&id) else { + let Some(r) = s.agent.references.get(&id) else { return NAPI_INVALID_ARG; }; let value = r .strong .clone() .or_else(|| r.weak.as_ref().and_then(WeakRef::deref).map(Into::into)); - let value_id = value.map(|value| s.insert(value)).unwrap_or(0); + let value_id = value.map(|value| s.agent.insert(value)).unwrap_or(0); unsafe { write(o, value_id) }.map_or_else(|e| e, |_| NAPI_OK) } @@ -3218,7 +3250,7 @@ pub unsafe extern "C" fn snapi_bridge_overwrite_reference_bytes( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(reference) = state.references.get(&reference_id) else { + let Some(reference) = state.agent.references.get(&reference_id) else { return NAPI_INVALID_ARG; }; let Some(value) = reference.strong.clone().or_else(|| { @@ -3265,11 +3297,11 @@ unsafe fn drain_guest_finalizers(env: SnapiEnv, force: bool) -> i32 { let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(record) = state.take_ready_guest_finalizer(force) else { + let Some(record) = state.agent.take_ready_guest_finalizer(force) else { return NAPI_OK; }; - let value_frame = state.open_value_frame(); - (record, state.active_callback_ctx, value_frame) + let value_frame = state.agent.open_value_frame(); + (record, state.agent.active_callback_ctx, value_frame) }; let result = unsafe { snapi_host_invoke_wasm_finalizer( @@ -3283,13 +3315,13 @@ unsafe fn drain_guest_finalizers(env: SnapiEnv, force: bool) -> i32 { let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - state.close_value_frame(value_frame); + state.agent.close_value_frame(value_frame); if result == CALLBACK_DEFERRED { - state.guest_finalizers.push(record); + state.agent.guest_finalizers.push(record); return NAPI_OK; } if let Some(wrap_id) = record.wrap_id { - state.wraps.remove(&wrap_id); + state.agent.wraps.remove(&wrap_id); } } } @@ -3330,7 +3362,7 @@ pub unsafe extern "C" fn snapi_bridge_swap_active_callback_ctx( let Ok(s) = (unsafe { env_mut(e) }) else { return ptr::null_mut(); }; - std::mem::replace(&mut s.active_callback_ctx, c) + std::mem::replace(&mut s.agent.active_callback_ctx, c) } #[unsafe(no_mangle)] @@ -3375,20 +3407,20 @@ pub unsafe extern "C" fn snapi_bridge_create_function( )); return JsValue::UNDEFINED; }; - let value_frame = state.open_value_frame(); + let value_frame = state.agent.open_value_frame(); let mut ids = Vec::with_capacity(args.length() as usize); for v in args.iter() { - ids.push(state.insert(v)); + ids.push(state.agent.insert(v)); } - let this_value = state.insert(this); + let this_value = state.agent.insert(this); let new_target = if new_target.is_undefined() { 0 } else { - state.insert(new_target) + state.agent.insert(new_target) }; - let cb = state.next_cbinfo; - state.next_cbinfo = cb.saturating_add(1); - state.callback_infos.insert( + let cb = state.agent.next_cbinfo; + state.agent.next_cbinfo = cb.saturating_add(1); + state.agent.callback_infos.insert( cb, CallbackInfo { args: ids, @@ -3397,7 +3429,7 @@ pub unsafe extern "C" fn snapi_bridge_create_function( data: registration.data, }, ); - (value_frame, cb, state.active_callback_ctx) + (value_frame, cb, state.agent.active_callback_ctx) }; if callback_ctx.is_null() { wasmer_napi_console_error(&format!( @@ -3424,7 +3456,7 @@ pub unsafe extern "C" fn snapi_bridge_create_function( let Ok(state) = (unsafe { env_mut(env) }) else { return JsValue::UNDEFINED; }; - state.pending_callbacks.push_back(PendingCallback { + state.agent.pending_callbacks.push_back(PendingCallback { registration, cbinfo: cb, value_frame, @@ -3437,20 +3469,20 @@ pub unsafe extern "C" fn snapi_bridge_create_function( return JsValue::UNDEFINED; }; let error = state.last_exception.take(); - let result_value = state.get(result).cloned(); + let result_value = state.agent.get(result).cloned(); if result_value.is_none() && result != 0 { wasmer_napi_console_error(&format!( "[wasmer-napi-callback] invalid result callback={callback_name} handle={result} guest_env={} wasm_fn={} value_slots={} free_slots={} scope_depth={}", registration.guest_env, registration.wasm_fn_ptr, - state.values.len(), - state.value_free_slots.len(), - state.value_frames.len(), + state.agent.values.len(), + state.agent.value_free_slots.len(), + state.agent.value_frames.len(), )); } let result = result_value.unwrap_or(JsValue::UNDEFINED); - state.callback_infos.remove(&cb); - state.close_value_frame(value_frame); + state.agent.callback_infos.remove(&cb); + state.agent.close_value_frame(value_frame); if let Some(error) = error { wasm_bindgen::throw_val(error); } @@ -3466,7 +3498,7 @@ pub unsafe extern "C" fn snapi_bridge_create_function( ); } s.closures.push(closure); - let id = s.insert(function.into()); + let id = s.agent.insert(function.into()); unsafe { write(out, id) }.map_or_else(|e| e, |_| NAPI_OK) } @@ -3477,10 +3509,10 @@ pub unsafe extern "C" fn snapi_bridge_drain_pending_callbacks(env: SnapiEnv) -> let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(pending) = state.pending_callbacks.pop_front() else { + let Some(pending) = state.agent.pending_callbacks.pop_front() else { return unsafe { drain_guest_finalizers(env, false) }; }; - (pending, state.active_callback_ctx) + (pending, state.agent.active_callback_ctx) }; let result = unsafe { @@ -3495,7 +3527,7 @@ pub unsafe extern "C" fn snapi_bridge_drain_pending_callbacks(env: SnapiEnv) -> let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - state.pending_callbacks.push_front(pending); + state.agent.pending_callbacks.push_front(pending); return NAPI_OK; } @@ -3504,9 +3536,13 @@ pub unsafe extern "C" fn snapi_bridge_drain_pending_callbacks(env: SnapiEnv) -> return NAPI_INVALID_ARG; }; let error = state.last_exception.take(); - let result = state.get(result).cloned().unwrap_or(JsValue::UNDEFINED); - state.callback_infos.remove(&pending.cbinfo); - state.close_value_frame(pending.value_frame); + let result = state + .agent + .get(result) + .cloned() + .unwrap_or(JsValue::UNDEFINED); + state.agent.callback_infos.remove(&pending.cbinfo); + state.agent.close_value_frame(pending.value_frame); (error, result) }; let settled = if let Some(error) = error { @@ -3539,18 +3575,21 @@ pub unsafe extern "C" fn snapi_bridge_register_guest_buffer_finalizer( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(value) = state.get(value_id).cloned() else { + let Some(value) = state.agent.get(value_id).cloned() else { return NAPI_INVALID_ARG; }; if !value.is_object() && !value.is_function() { return NAPI_INVALID_ARG; } - state.guest_buffer_finalizers.push(GuestBufferFinalizer { - target: WeakRef::new(&value.unchecked_into::()), - handle_id: value_id, - guest_ptr, - recyclable: recyclable != 0, - }); + state + .agent + .guest_buffer_finalizers + .push(GuestBufferFinalizer { + target: WeakRef::new(&value.unchecked_into::()), + handle_id: value_id, + guest_ptr, + recyclable: recyclable != 0, + }); NAPI_OK } @@ -3565,7 +3604,7 @@ pub unsafe extern "C" fn snapi_bridge_take_ready_guest_buffer_finalizer( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(record) = state.take_ready_guest_buffer_finalizer(force != 0) else { + let Some(record) = state.agent.take_ready_guest_buffer_finalizer(force != 0) else { return 1; }; if unsafe { write(handle_id_out, record.handle_id) }.is_err() @@ -3590,7 +3629,7 @@ pub unsafe extern "C" fn snapi_bridge_get_cb_info( let Ok(s) = (unsafe { env_mut(e) }) else { return NAPI_INVALID_ARG; }; - let Some(info) = s.callback_infos.get(&id) else { + let Some(info) = s.agent.callback_infos.get(&id) else { return NAPI_INVALID_ARG; }; let requested = if argc.is_null() { @@ -3634,10 +3673,10 @@ pub unsafe extern "C" fn snapi_bridge_wrap(e: SnapiEnv, o: u32, d: u64, r: *mut let Ok(s) = (unsafe { env_mut(e) }) else { return NAPI_INVALID_ARG; }; - let Some(wrap_id) = s.wrap_id(o, true) else { + let Some(wrap_id) = s.agent.wrap_id(o, true) else { return NAPI_INVALID_ARG; }; - s.wraps.insert(wrap_id, d); + s.agent.wraps.insert(wrap_id, d); if r.is_null() { NAPI_OK } else { @@ -3649,10 +3688,10 @@ pub unsafe extern "C" fn snapi_bridge_unwrap(e: SnapiEnv, o: u32, d: *mut u64) - let Ok(s) = (unsafe { env_mut(e) }) else { return NAPI_INVALID_ARG; }; - let Some(wrap_id) = s.wrap_id(o, false) else { + let Some(wrap_id) = s.agent.wrap_id(o, false) else { return NAPI_INVALID_ARG; }; - let Some(v) = s.wraps.get(&wrap_id).copied() else { + let Some(v) = s.agent.wraps.get(&wrap_id).copied() else { return NAPI_INVALID_ARG; }; unsafe { write(d, v) }.map_or_else(|e| e, |_| NAPI_OK) @@ -3662,13 +3701,14 @@ pub unsafe extern "C" fn snapi_bridge_remove_wrap(e: SnapiEnv, o: u32, d: *mut u let Ok(s) = (unsafe { env_mut(e) }) else { return NAPI_INVALID_ARG; }; - let Some(wrap_id) = s.wrap_id(o, false) else { + let Some(wrap_id) = s.agent.wrap_id(o, false) else { return NAPI_INVALID_ARG; }; - let Some(v) = s.wraps.remove(&wrap_id) else { + let Some(v) = s.agent.wraps.remove(&wrap_id) else { return NAPI_INVALID_ARG; }; - s.guest_finalizers + s.agent + .guest_finalizers .retain(|record| record.wrap_id != Some(wrap_id)); unsafe { write(d, v) }.map_or_else(|e| e, |_| NAPI_OK) } @@ -3677,7 +3717,7 @@ pub unsafe extern "C" fn snapi_bridge_type_tag_object(e: SnapiEnv, o: u32, l: u6 let Ok(s) = (unsafe { env_mut(e) }) else { return NAPI_INVALID_ARG; }; - s.type_tags.insert(o, (l, u)); + s.agent.type_tags.insert(o, (l, u)); NAPI_OK } #[unsafe(no_mangle)] @@ -3691,7 +3731,7 @@ pub unsafe extern "C" fn snapi_bridge_check_object_type_tag( let Ok(s) = (unsafe { env_mut(e) }) else { return NAPI_INVALID_ARG; }; - unsafe { write(r, i32::from(s.type_tags.get(&o) == Some(&(l, u)))) } + unsafe { write(r, i32::from(s.agent.type_tags.get(&o) == Some(&(l, u)))) } .map_or_else(|e| e, |_| NAPI_OK) } @@ -3773,7 +3813,7 @@ pub unsafe extern "C" fn snapi_bridge_unofficial_get_promise_details( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(promise) = state.get(promise_id).cloned() else { + let Some(promise) = state.agent.get(promise_id).cloned() else { return NAPI_INVALID_ARG; }; if !promise.is_instance_of::() { @@ -3790,7 +3830,7 @@ pub unsafe extern "C" fn snapi_bridge_unofficial_get_promise_details( return NAPI_INVALID_ARG; } if has_result && !result_out.is_null() { - let result_id = state.insert(details.get(1)); + let result_id = state.agent.insert(details.get(1)); if unsafe { write(result_out, result_id) }.is_err() { return NAPI_INVALID_ARG; } @@ -3887,7 +3927,7 @@ pub unsafe extern "C" fn snapi_bridge_unofficial_attach_env( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - if state.embedder_hooks_attached || accepted_hooks_out.is_null() { + if state.agent.embedder_hooks_attached || accepted_hooks_out.is_null() { return NAPI_INVALID_ARG; } let _ = (fatal_callback_id, oom_callback_id); @@ -3895,7 +3935,7 @@ pub unsafe extern "C" fn snapi_bridge_unofficial_attach_env( // browser/Node host owns fatal JavaScript and OOM handling. Accept the same // single attachment transition while reporting that no guest callback can // be invoked as a native provider function pointer. - state.embedder_hooks_attached = true; + state.agent.embedder_hooks_attached = true; unsafe { accepted_hooks_out.write(0) }; NAPI_OK } @@ -3913,6 +3953,7 @@ pub unsafe extern "C" fn snapi_bridge_unofficial_enqueue_microtask( return NAPI_INVALID_ARG; }; let Some(callback) = state + .agent .get(callback_id) .and_then(|value| value.dyn_ref::()) .cloned() @@ -3940,7 +3981,7 @@ pub unsafe extern "C" fn snapi_bridge_unofficial_get_own_non_index_properties( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(value) = state.get(value_id).cloned() else { + let Some(value) = state.agent.get(value_id).cloned() else { return NAPI_INVALID_ARG; }; if !value.is_object() && !value.is_function() { @@ -4004,7 +4045,7 @@ pub unsafe extern "C" fn snapi_bridge_unofficial_get_own_non_index_properties( filtered.push(&key); } - let id = state.insert(filtered.into()); + let id = state.agent.insert(filtered.into()); unsafe { write(out_id, id) }.map_or_else(|error| error, |()| NAPI_OK) } #[unsafe(no_mangle)] @@ -4246,19 +4287,19 @@ pub unsafe extern "C" fn snapi_bridge_unofficial_structured_clone( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(value) = state.get(value_id).cloned() else { + let Some(value) = state.agent.get(value_id).cloned() else { return NAPI_INVALID_ARG; }; let transfer_list = if transfer_list_id == 0 { JsValue::UNDEFINED - } else if let Some(value) = state.get(transfer_list_id).cloned() { + } else if let Some(value) = state.agent.get(transfer_list_id).cloned() { value } else { return NAPI_INVALID_ARG; }; match wasmer_napi_structured_clone(&value, &transfer_list) { Ok(cloned) => { - let id = state.insert(cloned); + let id = state.agent.insert(cloned); unsafe { write(out_id, id) }.map_or_else(|error| error, |()| NAPI_OK) } Err(error) => { @@ -4277,7 +4318,7 @@ pub unsafe extern "C" fn snapi_bridge_unofficial_message_create( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(value) = state.get(value_id).cloned() else { + let Some(value) = state.agent.get(value_id).cloned() else { return NAPI_INVALID_ARG; }; let Some(payload) = next_serialized_message(wasmer_napi_message_scope()) else { @@ -4313,7 +4354,7 @@ pub unsafe extern "C" fn snapi_bridge_unofficial_message_take( wasmer_napi_release_message(payload); match obtained { Ok(value) => { - let id = state.insert(value); + let id = state.agent.insert(value); unsafe { write(value_out, id) }.map_or_else(|error| error, |()| NAPI_OK) } Err(error) => { @@ -4344,7 +4385,7 @@ pub unsafe extern "C" fn snapi_bridge_unofficial_create_serdes_binding( }; match wasmer_napi_create_serdes_binding() { Ok(binding) => { - let id = state.insert(binding); + let id = state.agent.insert(binding); unsafe { write(out_id, id) }.map_or_else(|error| error, |()| NAPI_OK) } Err(error) => { @@ -4366,7 +4407,7 @@ pub unsafe extern "C" fn snapi_bridge_unofficial_contextify_contains_module_synt let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(source) = state.get(code_id).and_then(JsValue::as_string) else { + let Some(source) = state.agent.get(code_id).and_then(JsValue::as_string) else { return NAPI_STRING_EXPECTED; }; let params = Array::new(); @@ -4415,13 +4456,14 @@ pub unsafe extern "C" fn snapi_bridge_unofficial_contextify_make_context( Object::new().into() } else { state + .agent .get(sandbox_or_symbol_id) .cloned() .unwrap_or_else(|| Object::new().into()) }; let _ = Reflect::set(&sandbox, &JsValue::from_str("global"), &sandbox); let _ = Reflect::set(&sandbox, &JsValue::from_str("globalThis"), &sandbox); - let id = state.insert(sandbox); + let id = state.agent.insert(sandbox); unsafe { write(result_out, id) }.map_or_else(|err| err, |()| NAPI_OK) } #[unsafe(no_mangle)] @@ -4459,12 +4501,13 @@ pub unsafe extern "C" fn snapi_bridge_unofficial_contextify_run_script( Err(status) => return status, }; let sandbox = state + .agent .get(sandbox_or_null_id) .cloned() .unwrap_or(JsValue::NULL); - match wasmer_napi_context_eval(&sandbox, &source) { + match wasmer_napi_context_eval(&state.global_context, &sandbox, &source) { Ok(value) => { - let id = state.insert(value); + let id = state.agent.insert(value); unsafe { write(result_out, id) }.map_or_else(|err| err, |()| NAPI_OK) } Err(error) => { @@ -4496,7 +4539,11 @@ pub unsafe extern "C" fn snapi_bridge_unofficial_contextify_compile_function( Err(status) => return status, }; let params = Array::new(); - if let Some(values) = state.get(params_id).filter(|value| Array::is_array(value)) { + if let Some(values) = state + .agent + .get(params_id) + .filter(|value| Array::is_array(value)) + { for value in Array::from(values).iter() { match js_string(&value) { Ok(value) => { @@ -4510,6 +4557,7 @@ pub unsafe extern "C" fn snapi_bridge_unofficial_contextify_compile_function( } } let filename = state + .agent .get(filename_id) .and_then(JsValue::as_string) .unwrap_or_default(); @@ -4519,7 +4567,7 @@ pub unsafe extern "C" fn snapi_bridge_unofficial_contextify_compile_function( }; let context_extensions = if context_extensions_id == 0 { Array::new() - } else if let Some(value) = state.get(context_extensions_id) { + } else if let Some(value) = state.agent.get(context_extensions_id) { if value.is_null() || value.is_undefined() { Array::new() } else if Array::is_array(value) { @@ -4549,12 +4597,13 @@ pub unsafe extern "C" fn snapi_bridge_unofficial_contextify_compile_function( &JsValue::UNDEFINED, ); let source_url = state + .agent .get(filename_id) .cloned() .unwrap_or(JsValue::UNDEFINED); let _ = Reflect::set(&result, &JsValue::from_str("sourceURL"), &source_url); let _ = Reflect::set(&result, &JsValue::from_str("function"), function.as_ref()); - let id = state.insert(result.into()); + let id = state.agent.insert(result.into()); unsafe { write(result_out, id) }.map_or_else(|err| err, |()| NAPI_OK) } Err(error) => { @@ -4586,7 +4635,7 @@ pub unsafe extern "C" fn snapi_bridge_unofficial_bytecode_open( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(source_value) = state.get(source_text_id).cloned() else { + let Some(source_value) = state.agent.get(source_text_id).cloned() else { return NAPI_INVALID_ARG; }; let Some(source) = source_value.as_string() else { @@ -4602,12 +4651,17 @@ pub unsafe extern "C" fn snapi_bridge_unofficial_bytecode_open( return NAPI_OK; } let filename = state + .agent .get(filename_id) .and_then(JsValue::as_string) .unwrap_or_default(); let params = Array::new(); if params_id != 0 { - let Some(values) = state.get(params_id).filter(|value| Array::is_array(value)) else { + let Some(values) = state + .agent + .get(params_id) + .filter(|value| Array::is_array(value)) + else { return NAPI_ARRAY_EXPECTED; }; for value in Array::from(values).iter() { @@ -4675,7 +4729,7 @@ pub unsafe extern "C" fn snapi_bridge_unofficial_bytecode_serialize( if !state.bytecodes.contains_key(&bytecode_id) { return NAPI_INVALID_ARG; } - let id = state.insert(Uint8Array::new_with_length(0).into()); + let id = state.agent.insert(Uint8Array::new_with_length(0).into()); unsafe { write(buffer_out, id) }.map_or_else(|error| error, |()| NAPI_OK) } #[unsafe(no_mangle)] @@ -4710,10 +4764,10 @@ unsafe fn host_js_create_source_text_module( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - if state.get(wrapper_id).is_none() { + if state.agent.get(wrapper_id).is_none() { return NAPI_INVALID_ARG; } - let Some(url) = state.get(url_id).and_then(JsValue::as_string) else { + let Some(url) = state.agent.get(url_id).and_then(JsValue::as_string) else { return NAPI_STRING_EXPECTED; }; let source = match host_js_source_for_shape(state, source_text_id, source_bytecode_id, 2) { @@ -4768,7 +4822,7 @@ unsafe fn host_js_create_source_text_module( let handle = state.next_module; state.next_module = state.next_module.wrapping_add(1).max(1); - let requests_id = state.insert(requests.clone().into()); + let requests_id = state.agent.insert(requests.clone().into()); state.source_text_modules.insert( handle, SourceTextModule { @@ -4809,10 +4863,11 @@ unsafe fn host_js_create_synthetic_module( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(wrapper) = state.get(wrapper_id).cloned() else { + let Some(wrapper) = state.agent.get(wrapper_id).cloned() else { return NAPI_INVALID_ARG; }; let Some(export_names_value) = state + .agent .get(export_names_id) .filter(|value| Array::is_array(value)) .cloned() @@ -4820,6 +4875,7 @@ unsafe fn host_js_create_synthetic_module( return NAPI_INVALID_ARG; }; let Some(evaluate) = state + .agent .get(synthetic_eval_steps_id) .and_then(|value| value.dyn_ref::()) .cloned() @@ -4854,7 +4910,7 @@ unsafe fn host_js_create_synthetic_module( evaluation: None, }, ); - let requests_id = state.insert(Array::new().into()); + let requests_id = state.agent.insert(Array::new().into()); for result in [ unsafe { write(handle_out, handle) }, unsafe { write(requests_out, requests_id) }, @@ -5303,7 +5359,7 @@ pub unsafe extern "C" fn snapi_bridge_unofficial_module_wrap_evaluate( }; match start_module_evaluation(state, handle_id) { Ok(promise) => { - let id = state.insert(promise); + let id = state.agent.insert(promise); unsafe { write(result_out, id) }.map_or_else(|error| error, |()| NAPI_OK) } Err(error) => { @@ -5326,7 +5382,7 @@ pub unsafe extern "C" fn snapi_bridge_unofficial_module_wrap_evaluate_sync( }; match evaluate_module_sync(state, handle_id, &mut Vec::new()) { Ok(namespace) => { - let id = state.insert(namespace.into()); + let id = state.agent.insert(namespace.into()); unsafe { write(result_out, id) }.map_or_else(|error| error, |()| NAPI_OK) } Err(error) => { @@ -5347,7 +5403,7 @@ pub unsafe extern "C" fn snapi_bridge_unofficial_module_wrap_get_namespace( let Some(namespace) = module_namespace(state, handle_id) else { return NAPI_INVALID_ARG; }; - let id = state.insert(namespace.into()); + let id = state.agent.insert(namespace.into()); unsafe { write(result_out, id) }.map_or_else(|error| error, |()| NAPI_OK) } @@ -5417,7 +5473,7 @@ pub unsafe extern "C" fn snapi_bridge_unofficial_module_wrap_get_state( .and_then(|module| module.error.clone()) }) .unwrap_or(JsValue::UNDEFINED); - let error_id = state.insert(error); + let error_id = state.agent.insert(error); if let Err(error) = unsafe { write(error_out, error_id) } { return error; } @@ -5461,10 +5517,10 @@ pub unsafe extern "C" fn snapi_bridge_unofficial_module_wrap_set_export( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(name) = state.get(export_name_id).and_then(JsValue::as_string) else { + let Some(name) = state.agent.get(export_name_id).and_then(JsValue::as_string) else { return NAPI_STRING_EXPECTED; }; - let Some(value) = state.get(export_value_id).cloned() else { + let Some(value) = state.agent.get(export_value_id).cloned() else { return NAPI_INVALID_ARG; }; let Some(module) = state.synthetic_modules.get_mut(&handle_id) else { @@ -5537,7 +5593,7 @@ pub unsafe extern "C" fn snapi_bridge_unofficial_module_wrap_create_required_mod .and_then(|namespace| wasmer_napi_create_module_facade(&namespace)) { Ok(facade) => { - let id = state.insert(facade.into()); + let id = state.agent.insert(facade.into()); unsafe { write(result_out, id) }.map_or_else(|error| error, |()| NAPI_OK) } Err(error) => { @@ -5557,7 +5613,7 @@ pub unsafe extern "C" fn snapi_bridge_instanceof( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let (Some(object), Some(ctor)) = (state.get(obj_id), state.get(ctor_id)) else { + let (Some(object), Some(ctor)) = (state.agent.get(obj_id), state.agent.get(ctor_id)) else { return NAPI_INVALID_ARG; }; if !ctor.is_function() { @@ -5575,11 +5631,11 @@ pub unsafe extern "C" fn snapi_bridge_coerce_to_bool( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(value) = state.get(id) else { + let Some(value) = state.agent.get(id) else { return NAPI_INVALID_ARG; }; let coerced = JsValue::from_bool(value.is_truthy()); - let id = state.insert(coerced); + let id = state.agent.insert(coerced); unsafe { write(out_id, id) }.map_or_else(|err| err, |()| NAPI_OK) } #[unsafe(no_mangle)] @@ -5591,12 +5647,12 @@ pub unsafe extern "C" fn snapi_bridge_coerce_to_number( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(value) = state.get(id).cloned() else { + let Some(value) = state.agent.get(id).cloned() else { return NAPI_INVALID_ARG; }; match wasmer_napi_number(&value) { Ok(number) => { - let id = state.insert(number); + let id = state.agent.insert(number); unsafe { write(out_id, id) }.map_or_else(|err| err, |()| NAPI_OK) } Err(error) => { @@ -5614,14 +5670,14 @@ pub unsafe extern "C" fn snapi_bridge_coerce_to_string( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(value) = state.get(id).cloned() else { + let Some(value) = state.agent.get(id).cloned() else { return NAPI_INVALID_ARG; }; // Convert in JS: a round trip through a Rust String would cost two // transcodes and replace lone surrogates with U+FFFD. match wasmer_napi_string(&value) { Ok(text) => { - let id = state.insert_primitive(text); + let id = state.agent.insert_primitive(text); unsafe { write(out_id, id) }.map_or_else(|err| err, |()| NAPI_OK) } Err(error) => { @@ -5639,13 +5695,13 @@ pub unsafe extern "C" fn snapi_bridge_coerce_to_object( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(value) = state.get(id).cloned() else { + let Some(value) = state.agent.get(id).cloned() else { return NAPI_INVALID_ARG; }; if value.is_null() || value.is_undefined() { return NAPI_OBJECT_EXPECTED; } - let id = state.insert(Object::from(value).into()); + let id = state.agent.insert(Object::from(value).into()); unsafe { write(out_id, id) }.map_or_else(|err| err, |()| NAPI_OK) } #[unsafe(no_mangle)] @@ -5658,7 +5714,7 @@ pub unsafe extern "C" fn snapi_bridge_has_property( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let (Some(object), Some(key)) = (state.get(obj_id), state.get(key_id)) else { + let (Some(object), Some(key)) = (state.agent.get(obj_id), state.agent.get(key_id)) else { return NAPI_INVALID_ARG; }; match Reflect::has(object, key) { @@ -5681,7 +5737,7 @@ pub unsafe extern "C" fn snapi_bridge_has_own_property( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let (Some(object), Some(key)) = (state.get(obj_id), state.get(key_id)) else { + let (Some(object), Some(key)) = (state.agent.get(obj_id), state.agent.get(key_id)) else { return NAPI_INVALID_ARG; }; let object = Object::from(object.clone()); @@ -5704,7 +5760,7 @@ pub unsafe extern "C" fn snapi_bridge_delete_property( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let (Some(object), Some(key)) = (state.get(obj_id), state.get(key_id)) else { + let (Some(object), Some(key)) = (state.agent.get(obj_id), state.agent.get(key_id)) else { return NAPI_INVALID_ARG; }; let object = Object::from(object.clone()); @@ -5740,7 +5796,7 @@ pub unsafe extern "C" fn snapi_bridge_has_element( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(object) = state.get(obj_id) else { + let Some(object) = state.agent.get(obj_id) else { return NAPI_INVALID_ARG; }; match Reflect::has(object, &JsValue::from_f64(index as f64)) { @@ -5763,7 +5819,7 @@ pub unsafe extern "C" fn snapi_bridge_delete_element( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(object) = state.get(obj_id) else { + let Some(object) = state.agent.get(obj_id) else { return NAPI_INVALID_ARG; }; let object = Object::from(object.clone()); @@ -5789,12 +5845,12 @@ pub unsafe extern "C" fn snapi_bridge_get_all_property_names( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(object) = state.get(obj_id) else { + let Some(object) = state.agent.get(obj_id) else { return NAPI_INVALID_ARG; }; match wasmer_napi_get_all_property_names(object, mode, filter, conversion) { Ok(keys) => { - let id = state.insert(keys.into()); + let id = state.agent.insert(keys.into()); unsafe { write(out_id, id) }.map_or_else(|err| err, |()| NAPI_OK) } Err(error) => { @@ -5812,11 +5868,11 @@ pub unsafe extern "C" fn snapi_bridge_get_prototype( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(object) = state.get(obj_id) else { + let Some(object) = state.agent.get(obj_id) else { return NAPI_INVALID_ARG; }; let proto = Object::get_prototype_of(&Object::from(object.clone())); - let id = state.insert(proto.into()); + let id = state.agent.insert(proto.into()); unsafe { write(out_id, id) }.map_or_else(|err| err, |()| NAPI_OK) } #[unsafe(no_mangle)] @@ -5824,7 +5880,7 @@ pub unsafe extern "C" fn snapi_bridge_object_freeze(env: SnapiEnv, obj_id: u32) let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(object) = state.get(obj_id) else { + let Some(object) = state.agent.get(obj_id) else { return NAPI_INVALID_ARG; }; Object::freeze(&Object::from(object.clone())); @@ -5835,7 +5891,7 @@ pub unsafe extern "C" fn snapi_bridge_object_seal(env: SnapiEnv, obj_id: u32) -> let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(object) = state.get(obj_id) else { + let Some(object) = state.agent.get(obj_id) else { return NAPI_INVALID_ARG; }; Object::seal(&Object::from(object.clone())); @@ -5901,7 +5957,7 @@ pub unsafe extern "C" fn snapi_bridge_create_symbol( if description_id == 0 { JsValue::UNDEFINED } else { - let Some(value) = state.get(description_id).cloned() else { + let Some(value) = state.agent.get(description_id).cloned() else { return NAPI_INVALID_ARG; }; if !value.is_string() { @@ -5967,7 +6023,11 @@ pub unsafe extern "C" fn snapi_bridge_get_date_value( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(date) = state.get(id).and_then(|value| value.dyn_ref::()) else { + let Some(date) = state + .agent + .get(id) + .and_then(|value| value.dyn_ref::()) + else { return NAPI_INVALID_ARG; }; unsafe { write(result, date.get_time()) }.map_or_else(|err| err, |()| NAPI_OK) @@ -5992,8 +6052,8 @@ pub unsafe extern "C" fn snapi_bridge_create_external_arraybuffer( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let id = state.insert(buffer.into()); - state.backing_tokens.insert(id, data_addr); + let id = state.agent.insert(buffer.into()); + state.agent.backing_tokens.insert(id, data_addr); if unsafe { write(out_id, id) }.is_err() { return NAPI_INVALID_ARG; } @@ -6021,9 +6081,9 @@ pub unsafe extern "C" fn snapi_bridge_create_external_buffer( return NAPI_INVALID_ARG; }; let array = Uint8Array::from(source); - let value = wasmer_napi_buffer_view(&array.buffer(), 0, array.length()); - let id = state.insert(value); - state.backing_tokens.insert(id, data_addr); + let value = wasmer_napi_buffer_view(&state.global_context, &array.buffer(), 0, array.length()); + let id = state.agent.insert(value); + state.agent.backing_tokens.insert(id, data_addr); if unsafe { write(out_id, id) }.is_err() { return NAPI_INVALID_ARG; } @@ -6055,7 +6115,7 @@ pub unsafe extern "C" fn snapi_bridge_is_sharedarraybuffer( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(value) = state.get(id) else { + let Some(value) = state.agent.get(id) else { return NAPI_INVALID_ARG; }; unsafe { @@ -6076,7 +6136,9 @@ pub unsafe extern "C" fn snapi_bridge_create_sharedarraybuffer( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let id = state.insert(SharedArrayBuffer::new(byte_length).into()); + let id = state + .agent + .insert(SharedArrayBuffer::new(byte_length).into()); if unsafe { write(data_out, 0) }.is_err() || unsafe { write(out_id, id) }.is_err() { NAPI_INVALID_ARG } else { @@ -6092,7 +6154,9 @@ pub unsafe extern "C" fn snapi_bridge_node_api_set_prototype( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let (Some(object), Some(prototype)) = (state.get(object_id), state.get(prototype_id)) else { + let (Some(object), Some(prototype)) = + (state.agent.get(object_id), state.agent.get(prototype_id)) + else { return NAPI_INVALID_ARG; }; let prototype = Object::from(prototype.clone()); @@ -6111,12 +6175,12 @@ pub unsafe extern "C" fn snapi_bridge_create_typedarray( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(buffer) = state.get(arraybuffer_id).cloned() else { + let Some(buffer) = state.agent.get(arraybuffer_id).cloned() else { return NAPI_INVALID_ARG; }; match wasmer_napi_typed_array(typ, &buffer, byte_offset, length) { Ok(value) => { - let id = state.insert(value); + let id = state.agent.insert(value); unsafe { write(out_id, id) }.map_or_else(|err| err, |()| NAPI_OK) } Err(error) => { @@ -6139,7 +6203,7 @@ pub unsafe extern "C" fn snapi_bridge_get_typedarray_info( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(value) = state.get(id).cloned() else { + let Some(value) = state.agent.get(id).cloned() else { return NAPI_INVALID_ARG; }; let kind = wasmer_napi_typed_array_kind(&value); @@ -6175,14 +6239,14 @@ pub unsafe extern "C" fn snapi_bridge_get_typedarray_info( return NAPI_INVALID_ARG; } if !backing_store_token_out.is_null() { - let backing_store_token = state.backing_store_token(id).unwrap_or(id as u64); + let backing_store_token = state.agent.backing_store_token(id).unwrap_or(id as u64); if unsafe { write(backing_store_token_out, backing_store_token) }.is_err() { return NAPI_INVALID_ARG; } } } if !arraybuffer_out.is_null() { - let buffer_id = state.insert(buffer); + let buffer_id = state.agent.insert(buffer); if unsafe { write(arraybuffer_out, buffer_id) }.is_err() { return NAPI_INVALID_ARG; } @@ -6230,8 +6294,8 @@ pub unsafe extern "C" fn snapi_bridge_create_external( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let id = state.insert(Object::new().into()); - state.externals.insert(id, data_val); + let id = state.agent.insert(Object::new().into()); + state.agent.externals.insert(id, data_val); unsafe { write(out_id, id) }.map_or_else(|err| err, |()| NAPI_OK) } #[unsafe(no_mangle)] @@ -6239,7 +6303,7 @@ pub unsafe extern "C" fn snapi_bridge_open_handle_scope(env: SnapiEnv, scope_out let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let id = state.open_value_frame(); + let id = state.agent.open_value_frame(); unsafe { write(scope_out, id) }.map_or_else(|err| err, |()| NAPI_OK) } #[unsafe(no_mangle)] @@ -6247,7 +6311,7 @@ pub unsafe extern "C" fn snapi_bridge_close_handle_scope(env: SnapiEnv, scope_id let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - if state.close_value_frame(scope_id) { + if state.agent.close_value_frame(scope_id) { NAPI_OK } else { NAPI_INVALID_ARG @@ -6262,7 +6326,7 @@ pub unsafe extern "C" fn snapi_bridge_get_value_external( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(value) = state.externals.get(&id).copied() else { + let Some(value) = state.agent.externals.get(&id).copied() else { return NAPI_INVALID_ARG; }; unsafe { write(data_out, value) }.map_or_else(|err| err, |()| NAPI_OK) @@ -6291,7 +6355,7 @@ pub unsafe extern "C" fn snapi_bridge_escape_handle( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - if state.get(escapee_id).is_none() || !state.escape_value(scope_id, escapee_id) { + if state.agent.get(escapee_id).is_none() || !state.agent.escape_value(scope_id, escapee_id) { return NAPI_INVALID_ARG; } unsafe { write(out_id, escapee_id) }.map_or_else(|err| err, |()| NAPI_OK) @@ -6381,14 +6445,14 @@ pub unsafe extern "C" fn snapi_bridge_wrap_finalized( } return NAPI_INVALID_ARG; }; - let Some(wrap_id) = state.wrap_id(obj_id, true) else { + let Some(wrap_id) = state.agent.wrap_id(obj_id, true) else { if reference_id != 0 { let _ = unsafe { snapi_bridge_delete_reference(env, reference_id) }; } return NAPI_INVALID_ARG; }; - if state.wraps.contains_key(&wrap_id) - || !state.register_guest_finalizer( + if state.agent.wraps.contains_key(&wrap_id) + || !state.agent.register_guest_finalizer( obj_id, guest_env, wasm_fn_ptr, @@ -6399,7 +6463,7 @@ pub unsafe extern "C" fn snapi_bridge_wrap_finalized( { false } else { - state.wraps.insert(wrap_id, native_data); + state.agent.wraps.insert(wrap_id, native_data); true } }; @@ -6436,7 +6500,7 @@ pub unsafe extern "C" fn snapi_bridge_add_finalizer_cb( } } let registered = unsafe { env_mut(env) }.is_ok_and(|state| { - state.register_guest_finalizer( + state.agent.register_guest_finalizer( obj_id, guest_env, wasm_fn_ptr, @@ -6495,7 +6559,7 @@ pub unsafe extern "C" fn snapi_bridge_get_new_target( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(info) = state.callback_infos.get(&cbinfo_id) else { + let Some(info) = state.agent.callback_infos.get(&cbinfo_id) else { return NAPI_INVALID_ARG; }; // A non-constructor callback succeeds with a null napi_value. The handle @@ -6534,7 +6598,11 @@ unsafe fn define_properties_impl( unsafe { *name_ids.add(index) } }; if name_id != 0 { - state.get(name_id).cloned().unwrap_or(JsValue::UNDEFINED) + state + .agent + .get(name_id) + .cloned() + .unwrap_or(JsValue::UNDEFINED) } else { if names.is_null() { return NAPI_INVALID_ARG; @@ -6580,7 +6648,7 @@ unsafe fn define_properties_impl( return Err(status); } let state = unsafe { env_mut(env) }?; - state.get(id).cloned().ok_or(NAPI_INVALID_ARG) + state.agent.get(id).cloned().ok_or(NAPI_INVALID_ARG) }; match property_type { @@ -6592,7 +6660,7 @@ unsafe fn define_properties_impl( }; let value = unsafe { env_mut(env) } .ok() - .and_then(|state| state.get(value_id).cloned()) + .and_then(|state| state.agent.get(value_id).cloned()) .unwrap_or(JsValue::UNDEFINED); let _ = Reflect::set(&descriptor, &JsValue::from_str("value"), &value); let _ = Reflect::set( @@ -6694,7 +6762,7 @@ pub unsafe extern "C" fn snapi_bridge_define_class( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(ctor) = state.get(ctor_id).cloned() else { + let Some(ctor) = state.agent.get(ctor_id).cloned() else { return NAPI_INVALID_ARG; }; match Reflect::get(&ctor, &JsValue::from_str("prototype")) { @@ -6787,7 +6855,7 @@ pub unsafe extern "C" fn snapi_bridge_define_properties( let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(object) = state.get(obj_id).cloned() else { + let Some(object) = state.agent.get(obj_id).cloned() else { return NAPI_INVALID_ARG; }; object @@ -6830,9 +6898,9 @@ mod tests { #[wasm_bindgen_test] fn get_new_target_reports_the_constructor_or_null() { with_env(|env, state| { - let target = state.insert(Object::new().into()); + let target = state.agent.insert(Object::new().into()); for (id, new_target) in [(7, target), (8, 0)] { - state.callback_infos.insert( + state.agent.callback_infos.insert( id, CallbackInfo { args: Vec::new(), @@ -6868,25 +6936,25 @@ mod tests { fn objects_keep_their_handle(state: &mut HostJsEnv) { let object: JsValue = Object::new().into(); - let id = state.insert(object.clone()); - assert_eq!(state.insert(object.clone()), id); + let id = state.agent.insert(object.clone()); + assert_eq!(state.agent.insert(object.clone()), id); assert_ne!( - state.insert_primitive("x".into()), - state.insert_primitive("x".into()) + state.agent.insert_primitive("x".into()), + state.agent.insert_primitive("x".into()) ); - let frame = state.open_value_frame(); + let frame = state.agent.open_value_frame(); let scoped: JsValue = Object::new().into(); - let stale = state.insert(scoped.clone()); - state.externals.insert(stale, 7); - assert!(state.close_value_frame(frame)); - assert!(state.get(stale).is_none()); + let stale = state.agent.insert(scoped.clone()); + state.agent.externals.insert(stale, 7); + assert!(state.agent.close_value_frame(frame)); + assert!(state.agent.get(stale).is_none()); // A closed frame's handle is stale: the object moves, with its data. - let fresh = state.insert(scoped.clone()); + let fresh = state.agent.insert(scoped.clone()); assert_ne!(fresh, stale); - assert!(Object::is(state.get(fresh).unwrap(), &scoped)); - assert_eq!(state.externals.get(&fresh), Some(&7)); - assert_eq!(state.insert(scoped), fresh); + assert!(Object::is(state.agent.get(fresh).unwrap(), &scoped)); + assert_eq!(state.agent.externals.get(&fresh), Some(&7)); + assert_eq!(state.agent.insert(scoped), fresh); } #[wasm_bindgen_test] @@ -6895,24 +6963,28 @@ mod tests { } fn wrap_ids_are_recorded_once(state: &mut HostJsEnv) { - let object = state.insert(Object::new().into()); - let number = state.insert_primitive(JsValue::from_f64(1.0)); - assert_eq!(state.wrap_id(object, false), None); - let id = state.wrap_id(object, true).unwrap(); - assert_eq!(state.wrap_id(object, false), Some(id)); - assert_eq!(state.wrap_id(object, true), Some(id)); - assert_eq!(state.wrap_id(number, true), None); - let other = state.insert(Object::new().into()); - assert_eq!(state.wrap_id(other, true), Some(id + 1)); + let object = state.agent.insert(Object::new().into()); + let number = state.agent.insert_primitive(JsValue::from_f64(1.0)); + assert_eq!(state.agent.wrap_id(object, false), None); + let id = state.agent.wrap_id(object, true).unwrap(); + assert_eq!(state.agent.wrap_id(object, false), Some(id)); + assert_eq!(state.agent.wrap_id(object, true), Some(id)); + assert_eq!(state.agent.wrap_id(number, true), None); + let other = state.agent.insert(Object::new().into()); + assert_eq!(state.agent.wrap_id(other, true), Some(id + 1)); } #[wasm_bindgen_test] fn number_getters_convert_like_node() { with_env(|env, state| { - let big = state.insert_primitive(JsValue::from_f64(4294967301.0)); - let negative = state.insert_primitive(JsValue::from_f64(-1.0)); - let infinite = state.insert_primitive(JsValue::from_f64(f64::INFINITY)); - let text = state.insert_primitive("1".into()); + let big = state + .agent + .insert_primitive(JsValue::from_f64(4294967301.0)); + let negative = state.agent.insert_primitive(JsValue::from_f64(-1.0)); + let infinite = state + .agent + .insert_primitive(JsValue::from_f64(f64::INFINITY)); + let text = state.agent.insert_primitive("1".into()); let (mut int32, mut uint32, mut int64) = (0i32, 0u32, 1i64); unsafe { assert_eq!(snapi_bridge_get_value_int32(env, big, &mut int32), NAPI_OK); @@ -6954,8 +7026,10 @@ mod tests { #[wasm_bindgen_test] fn coerce_to_string_keeps_lone_surrogates() { with_env(|env, state| { - let lone = state.insert_primitive(js_sys::JsString::from_char_code1(0xd800).into()); - let number = state.insert_primitive(JsValue::from_f64(1.5)); + let lone = state + .agent + .insert_primitive(js_sys::JsString::from_char_code1(0xd800).into()); + let number = state.agent.insert_primitive(JsValue::from_f64(1.5)); let mut out = 0; assert_eq!( unsafe { snapi_bridge_coerce_to_string(env, lone, &mut out) }, @@ -6963,6 +7037,7 @@ mod tests { ); let text: js_sys::JsString = unsafe { env_mut(env) } .unwrap() + .agent .get(out) .unwrap() .clone() @@ -6974,6 +7049,7 @@ mod tests { ); let text = unsafe { env_mut(env) } .unwrap() + .agent .get(out) .and_then(JsValue::as_string); assert_eq!(text.as_deref(), Some("1.5")); @@ -7008,6 +7084,7 @@ mod tests { } let retained: Function = unsafe { env_mut(env) } .unwrap() + .agent .get(handle) .unwrap() .clone() From 8249a6641168e423f1a49a4898d9cd8d6cb4d474 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Fri, 23 Oct 2026 16:21:33 +0200 Subject: [PATCH 005/150] Cover the agent split in the shared and host-JS tests - NativeFunctionCalledFromContextKeepsItsRealm (both engines): a native function made in the main env and called from a script running in a vm context sees the main global and creates objects with the main realm's Object.prototype. It fails on QuickJS before the trampoline fix and passes on V8 unchanged. - NearHeapLimitCallbackReceivesItsEnvironment (V8): with a 16 MiB old generation the near-heap-limit callback fires and receives the env and data it was configured with, and releasing the env with the slot still set is clean. The trampoline's data is now the agent. - host-JS context tests pass the env's context to context_eval, is_buffer and buffer_view explicitly. A new test checks that two contexts each evaluate in their own global for null, undefined and globalThis sandboxes, in either call order. Co-Authored-By: Claude Opus 5.5 --- tests/host-js/global-context.test.mjs | 61 ++++++----- tests/runners/test_21_general.cc | 57 ++++++++++ .../runners/test_65_unofficial_contextify.cc | 102 ++++++++++++++++++ 3 files changed, 196 insertions(+), 24 deletions(-) diff --git a/tests/host-js/global-context.test.mjs b/tests/host-js/global-context.test.mjs index 782a28402c..4970f721d2 100644 --- a/tests/host-js/global-context.test.mjs +++ b/tests/host-js/global-context.test.mjs @@ -18,7 +18,7 @@ const directory = await mkdtemp(join(tmpdir(), 'napi-context-test-')); let runtime; try { const modulePath = join(directory, 'context.mjs'); - await writeFile(modulePath, 'let wasmerNapiActiveGlobalContext;\n' + inline.slice(start, end)); + await writeFile(modulePath, inline.slice(start, end)); runtime = await import(pathToFileURL(modulePath)); } finally { await rm(directory, {recursive:true,force:true}); @@ -27,6 +27,8 @@ try { const create = runtime.wasmer_napi_create_global_context; const evaluate = runtime.wasmer_napi_context_eval; const callback = runtime.wasmer_napi_make_callback; +// VM sandboxes evaluate the same whichever environment runs them. +const host = create(); const stackFormattingSupported = (() => { const saved=Object.getOwnPropertyDescriptor(Error,'prepareStackTrace'),marker={}; try { @@ -40,31 +42,44 @@ const stackFormattingSupported = (() => { test('script this and globalThis refer to the virtual global', () => { const context = create(); - const values = evaluate(context.scope,'[this, globalThis, global]'); + const values = evaluate(context,context.scope,'[this, globalThis, global]'); assert.ok(values.every(value => value === context.scope)); }); +test('a null sandbox evaluates in the given context, whatever ran last', () => { + const a=create(), b=create(); + for (const sandbox of [null, undefined, globalThis]) { + assert.equal(evaluate(a,sandbox,'globalThis'),a.scope); + assert.equal(evaluate(b,sandbox,'globalThis'),b.scope); + assert.equal(evaluate(a,sandbox,'globalThis'),a.scope); + } + evaluate(a,null,'var answer=1'); + assert.equal(evaluate(b,null,'typeof answer'),'undefined'); + runtime.wasmer_napi_release_global_context(a); + runtime.wasmer_napi_release_global_context(b); +}); + test('VM script globals expose builtins without writing to the host global', () => { const sandbox = { answer:42 }; const other = {}; - const values = evaluate(sandbox,'[this, globalThis, global, this.RegExp, RegExp, answer]'); + const values = evaluate(host,sandbox,'[this, globalThis, global, this.RegExp, RegExp, answer]'); assert.ok(values.slice(0,3).every(value => value === values[0])); assert.notEqual(values[0],globalThis); assert.equal(values[3],RegExp); assert.equal(values[4],RegExp); assert.equal(values[5],42); - assert.equal(evaluate(sandbox,'this'),values[0], 'reuse the VM global across scripts'); + assert.equal(evaluate(host,sandbox,'this'),values[0], 'reuse the VM global across scripts'); // Edge stream cleanup uses vm.runInNewContext('this').RegExp this way. - assert.equal(evaluate(sandbox,'new this.RegExp("released", "g")[Symbol.replace]("released", "closed")'),'closed'); + assert.equal(evaluate(host,sandbox,'new this.RegExp("released", "g")[Symbol.replace]("released", "closed")'),'closed'); const hostProcess = globalThis.process; const hostFormatter = Error.prepareStackTrace; - evaluate(sandbox,'this.process={vm:true}; Error.prepareStackTrace=()=>"vm stack"; this.answer++'); + evaluate(host,sandbox,'this.process={vm:true}; Error.prepareStackTrace=()=>"vm stack"; this.answer++'); assert.equal(globalThis.process,hostProcess); assert.equal(Error.prepareStackTrace,hostFormatter); assert.equal(sandbox.answer,43); assert.deepEqual(sandbox.process,{vm:true}); - assert.notEqual(evaluate(other,'Error'),evaluate(sandbox,'Error')); - assert.notEqual(evaluate(other,'Error.prepareStackTrace'),evaluate(sandbox,'Error.prepareStackTrace')); + assert.notEqual(evaluate(host,other,'Error'),evaluate(host,sandbox,'Error')); + assert.notEqual(evaluate(host,other,'Error.prepareStackTrace'),evaluate(host,sandbox,'Error.prepareStackTrace')); }); test('global accessors retain lazy reads and context-owned writes', () => { @@ -90,7 +105,7 @@ test('global accessors retain lazy reads and context-owned writes', () => { test('a guest process assignment does not replace the worker process', () => { const original=globalThis.process; const a=create(), b=create(); - evaluate(a.scope,'globalThis.process={guest:"a"}'); + evaluate(a,a.scope,'globalThis.process={guest:"a"}'); assert.equal(globalThis.process,original); assert.equal(b.scope.process,original); assert.deepEqual(a.scope.process,{guest:'a'}); @@ -105,10 +120,9 @@ test('closing an inactive context disables only its callbacks', () => { assert.deepEqual(fnA.call(receiver,1,2),{receiver,args:[1,2]}); assert.equal(fnA2(),42); assert.throws(()=>fnB(),/active callback/); - runtime.wasmer_napi_activate_global_context(a); runtime.wasmer_napi_release_global_context(b); assert.equal(fnB(),undefined); - assert.equal(evaluate(undefined,'globalThis'),a.scope); + assert.equal(evaluate(a,undefined,'globalThis'),a.scope); assert.deepEqual(fnA.call(receiver,3),{receiver,args:[3]}); runtime.wasmer_napi_release_global_context(a); assert.equal(fnA(),undefined); @@ -158,7 +172,7 @@ test('retained callback wrappers do not retain closed contexts or dispatch captu test('Error constructors, static hooks and prototype writes stay local', () => { const a=create(), b=create(); const hook=Error.prepareStackTrace; - evaluate(a.scope,'Error.prepareStackTrace=()=>"guest-a"; Error.prototype.guest="a"; Error.stackTraceLimit=3;'); + evaluate(a,a.scope,'Error.prepareStackTrace=()=>"guest-a"; Error.prototype.guest="a"; Error.stackTraceLimit=3;'); assert.equal(Error.prepareStackTrace,hook); assert.equal(Error.prototype.guest,undefined); assert.notEqual(a.scope.Error,b.scope.Error); @@ -169,15 +183,15 @@ test('Error constructors, static hooks and prototype writes stay local', () => { assert.equal(ownMethods.toString.value,Error.prototype.toString); assert.equal(ownMethods.name.value,'Error'); assert.equal(ownMethods.message.value,''); - assert.equal(evaluate(a.scope,'Error.prototype.toString.call(new Error("details"))'),'Error: details'); + assert.equal(evaluate(a,a.scope,'Error.prototype.toString.call(new Error("details"))'),'Error: details'); assert.equal(Object.getPrototypeOf(a.scope.TypeError.prototype),a.scope.Error.prototype); - assert.equal(evaluate(a.scope,'new TypeError("typed").guest'),'a'); - assert.equal(evaluate(b.scope,'new TypeError("typed").guest'),undefined); + assert.equal(evaluate(a,a.scope,'new TypeError("typed").guest'),'a'); + assert.equal(evaluate(b,b.scope,'new TypeError("typed").guest'),undefined); }); test('callable errors, subclasses, causes and native N-API errors work', () => { const c=create(); - const values=evaluate(c.scope,`class CustomError extends Error {}; [Error('called'),new TypeError('typed',{cause:42}),new AggregateError([1,2],'many'),new CustomError('custom')]`); + const values=evaluate(c,c.scope,`class CustomError extends Error {}; [Error('called'),new TypeError('typed',{cause:42}),new AggregateError([1,2],'many'),new CustomError('custom')]`); for (const value of values) assert.ok(value instanceof c.scope.Error); assert.equal(values[0].message,'called'); assert.ok(values[1] instanceof c.scope.TypeError); @@ -195,7 +209,7 @@ test('callable errors, subclasses, causes and native N-API errors work', () => { test('custom stack formatting is lazy, receives the actual error and restores the host hook', {skip:!stackFormattingSupported}, () => { const c=create(), host=Object.getOwnPropertyDescriptor(Error,'prepareStackTrace'); c.scope.state={calls:0}; - const error=evaluate(c.scope,`Error.prepareStackTrace=(error,frames)=>{state.calls++;return {error,frames}}; new Error('custom',{cause:42})`); + const error=evaluate(c,c.scope,`Error.prepareStackTrace=(error,frames)=>{state.calls++;return {error,frames}}; new Error('custom',{cause:42})`); assert.equal(c.scope.state.calls,0); const stack=error.stack; assert.equal(stack.error,error); @@ -203,15 +217,15 @@ test('custom stack formatting is lazy, receives the actual error and restores th assert.equal(c.scope.state.calls,1); assert.equal(error.stack,stack); assert.deepEqual(Object.getOwnPropertyDescriptor(Error,'prepareStackTrace'),host); - evaluate(c.scope,'Error.prepareStackTrace=()=>{throw new RangeError("formatter failed")}'); - const bad=evaluate(c.scope,'new Error("bad")'); + evaluate(c,c.scope,'Error.prepareStackTrace=()=>{throw new RangeError("formatter failed")}'); + const bad=evaluate(c,c.scope,'new Error("bad")'); assert.throws(()=>bad.stack,/formatter failed/); assert.deepEqual(Object.getOwnPropertyDescriptor(Error,'prepareStackTrace'),host); }); test('Error.captureStackTrace targets use the local formatter', {skip:!stackFormattingSupported}, () => { const c=create(); - const object=evaluate(c.scope,`Error.prepareStackTrace=(object,frames)=>({object,frames}); const target={}; Error.captureStackTrace(target); target`); + const object=evaluate(c,c.scope,`Error.prepareStackTrace=(object,frames)=>({object,frames}); const target={}; Error.captureStackTrace(target); target`); assert.equal(object.stack.object,object); assert.ok(object.stack.frames.length>0); object.stack='overridden'; @@ -259,7 +273,7 @@ test('delayed stacks keep their owner and capture its frame limit', {skip:!stack a.scope.Error.prepareStackTrace=(error,frames)=>({owner:'a',error,frames}); b.scope.Error.prepareStackTrace=(error,frames)=>({owner:'b',error,frames}); const source='function first(){return second()} function second(){return third()} function third(){return new TypeError("delayed")} first()'; - const errorA=evaluate(a.scope,source), errorB=evaluate(b.scope,source); + const errorA=evaluate(a,a.scope,source), errorB=evaluate(b,b.scope,source); const stackB=errorB.stack, stackA=errorA.stack; assert.equal(stackA.owner,'a'); assert.equal(stackB.owner,'b'); @@ -276,8 +290,7 @@ function releasedGuestBufferReferences() { const context=create(); const memory=new WebAssembly.Memory({initial:32,maximum:64,shared:true}); context.scope.buffer=new Int32Array(memory.buffer); - evaluate(context.scope,'process={buffer}; Error.prepareStackTrace=()=>process.buffer;'); - runtime.wasmer_napi_activate_global_context(context); + evaluate(context,context.scope,'process={buffer}; Error.prepareStackTrace=()=>process.buffer;'); runtime.wasmer_napi_release_global_context(context); references.push(new WeakRef(memory.buffer)); } @@ -289,7 +302,7 @@ function releasedVmReferences() { for(let i=0;i<12;i++) { const memory=new WebAssembly.Memory({initial:32,maximum:64,shared:true}); const sandbox={buffer:new Int32Array(memory.buffer)}; - const scope=evaluate(sandbox,'Error.prepareStackTrace=()=>buffer; this'); + const scope=evaluate(host,sandbox,'Error.prepareStackTrace=()=>buffer; this'); references.push(new WeakRef(sandbox),new WeakRef(scope),new WeakRef(memory.buffer)); } return references; diff --git a/tests/runners/test_21_general.cc b/tests/runners/test_21_general.cc index d6ad76e1e4..6db26c6d1b 100644 --- a/tests/runners/test_21_general.cc +++ b/tests/runners/test_21_general.cc @@ -203,6 +203,63 @@ TEST_F(Test21General, NearHeapLimitCallbackUsesOneConfigurationSlot) { napi_ok); } +#if defined(NAPI_TEST_ENGINE_V8) +namespace { + +struct NearHeapLimitRecord { + napi_env env = nullptr; + void* data = nullptr; + int calls = 0; +}; + +size_t RecordNearHeapLimit(napi_env env, + void* data, + size_t current_heap_limit, + size_t /*initial_heap_limit*/) { + auto* record = static_cast(data); + record->env = env; + record->data = data; + record->calls++; + return current_heap_limit * 2; +} + +} // namespace + +// The trampoline hands the embedder the env and data it was configured with, +// and releasing the env with the slot still set is clean. +TEST_F(Test21General, NearHeapLimitCallbackReceivesItsEnvironment) { + unofficial_napi_env_create_options options{}; + InitializeTestEnvCreateOptions(&options); + options.max_old_generation_size_in_bytes = 16 * 1024 * 1024; + napi_env env = nullptr; + unofficial_napi_env_owner owner = nullptr; + ASSERT_EQ(unofficial_napi_create_env( + NAPI_TEST_MODULE_API_VERSION, &options, &env, &owner), + napi_ok); + + NearHeapLimitRecord record; + ASSERT_EQ(unofficial_napi_configure_near_heap_limit_callback( + env, RecordNearHeapLimit, &record, 0), + napi_ok); + + napi_value source = nullptr; + ASSERT_EQ(napi_create_string_utf8( + env, + "const keep = []; for (let i = 0; i < 400; i++) " + "keep.push(new Array(32 * 1024).fill(i)); keep.length", + NAPI_AUTO_LENGTH, + &source), + napi_ok); + napi_value result = nullptr; + ASSERT_EQ(napi_run_script(env, source, &result), napi_ok); + + EXPECT_GT(record.calls, 0); + EXPECT_EQ(record.env, env); + EXPECT_EQ(record.data, &record); + EXPECT_EQ(unofficial_napi_release_env(owner, nullptr), napi_ok); +} +#endif + TEST_F(Test21General, PortedCoreFlow) { EnvScope s(runtime_.get()); napi_value exports = nullptr; diff --git a/tests/runners/test_65_unofficial_contextify.cc b/tests/runners/test_65_unofficial_contextify.cc index fe060631a0..ef7e99cebd 100644 --- a/tests/runners/test_65_unofficial_contextify.cc +++ b/tests/runners/test_65_unofficial_contextify.cc @@ -56,8 +56,110 @@ napi_value CaptureDynamicImportId(napi_env env, napi_callback_info info) { } #endif +struct RealmProbe { + napi_ref main_global = nullptr; + napi_ref main_object_prototype = nullptr; + bool called = false; + bool sees_main_global = false; + bool creates_in_main_realm = false; +}; + +// Records which realm a native callback runs in. +napi_value ProbeRealm(napi_env env, napi_callback_info info) { + void* data = nullptr; + if (napi_get_cb_info(env, info, nullptr, nullptr, nullptr, &data) != napi_ok || + data == nullptr) { + return nullptr; + } + auto* probe = static_cast(data); + probe->called = true; + + napi_value global = nullptr; + napi_value main_global = nullptr; + if (napi_get_global(env, &global) != napi_ok || + napi_get_reference_value(env, probe->main_global, &main_global) != napi_ok || + napi_strict_equals(env, global, main_global, &probe->sees_main_global) != napi_ok) { + return nullptr; + } + + napi_value object = nullptr; + napi_value prototype = nullptr; + napi_value main_prototype = nullptr; + if (napi_create_object(env, &object) != napi_ok || + napi_get_prototype(env, object, &prototype) != napi_ok || + napi_get_reference_value(env, probe->main_object_prototype, &main_prototype) != napi_ok || + napi_strict_equals(env, prototype, main_prototype, &probe->creates_in_main_realm) != napi_ok) { + return nullptr; + } + return object; +} + } // namespace +// A native function keeps the realm it was created in, also when a script in +// another context calls it (as in Node and V8). +TEST_F(Test65UnofficialContextify, NativeFunctionCalledFromContextKeepsItsRealm) { + EnvScope s(runtime_.get()); + + RealmProbe probe; + napi_value global = nullptr; + napi_value object = nullptr; + napi_value object_prototype = nullptr; + ASSERT_EQ(napi_get_global(s.env, &global), napi_ok); + ASSERT_EQ(napi_create_object(s.env, &object), napi_ok); + ASSERT_EQ(napi_get_prototype(s.env, object, &object_prototype), napi_ok); + ASSERT_EQ(napi_create_reference(s.env, global, 1, &probe.main_global), napi_ok); + ASSERT_EQ(napi_create_reference(s.env, object_prototype, 1, &probe.main_object_prototype), + napi_ok); + + napi_value fn = nullptr; + ASSERT_EQ(napi_create_function(s.env, "probe", NAPI_AUTO_LENGTH, ProbeRealm, &probe, &fn), + napi_ok); + napi_value sandbox = nullptr; + ASSERT_EQ(napi_create_object(s.env, &sandbox), napi_ok); + ASSERT_EQ(napi_set_named_property(s.env, sandbox, "probe", fn), napi_ok); + + napi_value contextified = nullptr; + ASSERT_EQ(unofficial_napi_contextify_make_context(s.env, + sandbox, + Str(s.env, "ctx"), + Str(s.env, "test://origin"), + true, + true, + false, + Sym(s.env, "hdo"), + &contextified), + napi_ok); + + napi_value eval_result = nullptr; + const unofficial_napi_js_source source = unofficial_napi_js_source_from_text( + Str(s.env, "Object.getPrototypeOf(probe()) === Object.prototype")); + ASSERT_EQ(unofficial_napi_contextify_run_script(s.env, + sandbox, + &source, + Str(s.env, "probe.js"), + 0, + 0, + -1, + true, + false, + false, + Sym(s.env, "hdo"), + &eval_result), + napi_ok); + + EXPECT_TRUE(probe.called); + EXPECT_TRUE(probe.sees_main_global); + EXPECT_TRUE(probe.creates_in_main_realm); + // The object comes from the main realm, not the context's. + bool from_context_realm = true; + ASSERT_EQ(napi_get_value_bool(s.env, eval_result, &from_context_realm), napi_ok); + EXPECT_FALSE(from_context_realm); + + ASSERT_EQ(napi_delete_reference(s.env, probe.main_global), napi_ok); + ASSERT_EQ(napi_delete_reference(s.env, probe.main_object_prototype), napi_ok); +} + TEST_F(Test65UnofficialContextify, MakeRunRoundTrip) { EnvScope s(runtime_.get()); From 1bae87cd34616e2688dcedccd4bd39efff418969 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Fri, 23 Oct 2026 16:21:40 +0200 Subject: [PATCH 006/150] Add the realm-bound napi_env design and Phase 0 notes docs/realm-bound-env.md describes splitting each provider into an agent (the engine instance and its thread) and envs bound to exactly one realm. It covers why (each layer overrides the realm per call in its own way today), the state each layer would own, the API that follows (create_realm and get_realm, no context arguments), realm lifetime, the EdgeJS migration and a phased plan. Section 11 records what Phase 0 landed in V8, QuickJS, the bridge and host-JS, the test results, and what Phase 1 still has to settle. Co-Authored-By: Claude Opus 5.5 --- docs/realm-bound-env.md | 653 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 653 insertions(+) create mode 100644 docs/realm-bound-env.md diff --git a/docs/realm-bound-env.md b/docs/realm-bound-env.md new file mode 100644 index 0000000000..26d8d0fb9d --- /dev/null +++ b/docs/realm-bound-env.md @@ -0,0 +1,653 @@ +# Realm-bound `napi_env` + +Status: Phase 0 implemented on branch `refactor/agent-realm-phase0` (see +§11). Phases 1–4 are not started. + +**Proposal:** split each provider into an **agent**, which is the engine +instance and its thread, and **realm envs**. A realm env is a `napi_env` whose +realm is fixed when the env is created and never changes. Values and handle +scopes belong to the agent, so they work with every env of that agent. Host +hooks belong to the realm. An env lives exactly as long as its realm. + +What gets simpler: + +- **API.** No call takes a sandbox or context argument again. + `contextify_make_context` becomes `create_realm`. +- **Hooks.** The context-token hooks go away. +- **Branch not needed.** The `contextify_enter`/`leave` work on + `feat/contextify-enter-leave` is no longer needed. +- **QuickJS.** The provider stops switching a "current context". +- **host-JS.** The provider drops its fallback scopes and its active-context + switch. + +--- + +## 1. First principles: what an N-API call needs to know + +Every call needs to know four things: + +| # | What | Examples | +|---|---|---| +| A | **Agent**: which engine instance and thread. | Every call: handle allocation, throwing, GC. | +| R | **Realm**: which global object and intrinsics. | `create_object`, `create_error`, `create_function`, `create_promise`, `create_typedarray`, `get_global`, `run_script`, compiling, modules, and dispatching host hooks. | +| M | **Module instance**: which addon. | Instance data, cleanup hooks, the env passed to finalizers, API version. | +| T | **Per-call state** | Last error, pending exception, open handle scopes. | + +Today `napi_env` bundles A, M and T with a *default* R. Each layer then +overrides R per call in its own way: + +| Where | How the realm is overridden today | +|---|---| +| V8 | A `sandbox_or_null`, `parsing_context_or_undefined` or `context_or_undefined` argument, resolved by a linear scan of `g_context_records`. In about 9 places the provider uses the implicit current context instead of `env->context()`. | +| V8, `feat/contextify-enter-leave` | A selectable context stack (`context_scope`, `root_context()`) and LIFO tokens. | +| QuickJS | A mutable `current_context_`, switched at 23 `napi_env_context_scope__` sites. Every `napi_value__` carries its own `context_` tag. | +| host-JS | The module-global `wasmerNapiActiveGlobalContext`, switched per thread. vm sandboxes fall back to an anonymous global that belongs to no env. | + +**Principle:** R becomes an immutable property of the env. An env is a +capability for exactly one realm: everything done through env X happens in +realm X. No call ever has a second source of realm information. + +The rest of this document follows from that. + +## 2. What the code does today + +### V8 (`v8/src`) + +- **One env, one isolate, one context.** `unofficial_napi_create_env` creates a + fresh isolate, allocator and `v8::Context`, then calls + `unofficial_napi_create_env_from_context` (`unofficial_napi.cc:1785-1797, + 1902-2003`). +- **The owner is the agent.** `unofficial_napi_env_owner` is the + `UnofficialEnvScope`, which holds the isolate, the allocator, and + permanently open isolate, handle and context scopes. +- **vm contexts are records inside the one env.** Each `ContextRecord` (key + ref, context, own microtask queue) is pushed onto `g_context_records[env]`. + Lookups scan the list with `napi_strict_equals` + (`unofficial_napi_contextify.cc:848-861, 1333-1346`). +- **`module_wrap_create` resolves its context differently** from `run_script` + and `compile_function`. It uses `GetCreationContextChecked()` on any object + instead of looking up a contextify record. +- **Isolate-level state is spread over global maps** keyed by isolate or env: + `g_env_by_isolate` (last writer wins), `g_promise_hooks`, + `g_promise_reject_callbacks`, `g_prepare_stack_trace_callbacks`, + `g_profiler_states`, `g_module_wrap_states`, and the platform runner's single + `target_env_`. +- **The `Private::ForApi` keys are isolate-wide**, even though they are stored + on the env. +- **Inconsistent context use.** Places that mix the implicit current context + with `env->context()`: + - the `run_script` timeout error; + - `ImportModuleDynamicallyWithPhase`; + - `HostInitializeImportMetaObject`; + - `SyntheticModuleEvaluationSteps`; + - `PromiseHookCallback` and `PromiseRejectCallback`; + - `GetThrownAtString`; + - the serdes constructors; + - `make_context` called from a vm context. +- **Lifetimes.** Function payloads, external wrappers and serdes contexts live + in the env's slab and are freed only with the env. + +### QuickJS (`quickjs/src`) + +- **One env, one runtime, one main context.** The owner holds the + `JSRuntime` and the main `JSContext`. +- **Runtime hooks point at a single env.** The promise hook, rejection tracker + and module loader hooks are installed per runtime with the env as opaque, so + a second env would overwrite them. +- **Class ids are process-static.** +- **Native callbacks run in the caller's realm.** QuickJS does not switch + realms for C-function-data calls (`quickjs.c:6287`, a TODO). The trampoline + takes `JS_GetContextOpaque(caller_ctx)` and switches `current_context_` to + it (`napi_function.cc:67-77`). An addon function made in main and called + from a vm script sees the vm global. That differs from V8 and Node. +- **`module_wrap` ignores `context_or_undefined`.** Every module lives in main. +- **`compile_function` silently falls back to main** when the parsing context + is unknown. +- **vm contexts are never freed individually.** `dispose_context` is + unreachable; `fix/quickjs-contextify-collect` addresses this. +- **`last_exception_context_` is redundant.** QuickJS exceptions are + runtime-level. + +### host-JS (`src/snapi_js.rs`) + +- **One shared host realm.** Each env gets a virtual global: a `Proxy` over a + descriptor snapshot of `globalThis`. +- **vm sandboxes are emulated.** They are evaluated with `with (sandbox)`. + Names they don't define fall back to an anonymous global context, cached in + the module-global `wasmerNapiGlobalScopes` WeakMap and owned by no env. +- **`compile_function` with a parsing context uses the raw sandbox**, so + missing names fall through to the real host global. +- **Env behaviour depends on a module-global active-context pointer**, switched + in `env_mut`/`activate()` (`snapi_js.rs:1712-1762`). + +### Bridge and Rust (`src/`) + +- **The guest's `napi_env` is a u32 env id**, resolved on every import. The + "scope id" is the guest's handle to the `env_owner`, i.e. the teardown + capability. +- **`SnapiEnvState` (`napi_bridge_init.cc:119-172`) holds isolate-level + state:** value slots, scope frames, refs, deferreds, handle tables and + `active_callback_ctx`. +- **The budget treats env and isolate as the same:** `reserve_isolate` and + `commit_isolate`, `env_heap_charges[env_id]`, and the `env_registry` used by + `terminate_all`. +- **Callbacks capture `guest_env` at registration.** They always receive the + env that created them. +- **`attach_env` hooks are inert on native.** The bridge passes empty hooks. + +### EdgeJS (consumer) + +- **One env per isolate.** The env is both the principal realm and the + `edge::Environment` key (`g_environments`). +- **vm contexts are passed as sandbox `napi_value`s** together with the + principal env. +- **Hooks are set once, on the principal env:** dynamic import, + `import.meta`, promise reject, promise hooks and prepare-stack-trace. vm + modules depend on the provider routing them back to that env. +- **EdgeJS never asks for "the current env"**, never compares envs, and never + calls `napi_set_instance_data`. +- **Bindings rely on callbacks receiving their creating env:** + `napi_get_global(env)` → `process`/`internalBinding`, 86 call sites. +- **Context tokens are recorded in `attached_contexts_` but never read.** +- **Native addons share Edge's env** (`edge_process.cc:4477`), so their + instance data collides. + +### Node (reference) + +Node's `napi_env__` is already realm-bound: `isolate` plus `context_persistent`, +created per (addon, context). `js_native_api_v8.cc` uses `env->context()` +everywhere and never the current context. + +Node has three layers: + +- **`Environment`:** thread, loop and cleanup. +- **`Realm`:** principal or ShadowRealm. It holds the per-realm callbacks: + `prepare_stack_trace_callback`, `promise_reject_callback`, + `promise_hook_handler`, and `host_import_module_dynamically_callback` / + `host_initialize_import_meta_object_callback` (`env_properties.h:474-536`). +- **Plain contexts.** A vm context is assigned to the Environment with + `realm = nullptr` (`node_contextify.cc:330`). Its hooks fall back to the + principal realm: "Fallback to the principal realm if it's in a vm context" + (`module_wrap.cc:998-1001`). + +## 3. The object model + +``` +Platform (process) configure_runtime, V8 worker threads +└─ Agent isolate / JSRuntime / host worker; one thread at a time + │ the owner handle (unofficial_napi_env_owner) names it + ├─ values and handle scopes, pending exception, finalizer queue + ├─ default microtask queue, GC, heap limits and budget, near-heap-limit + ├─ terminate, interrupt, profiler, snapshots, hash seed, datetime + ├─ embedder hooks: foreground task, fatal, OOM + ├─ Private keys, class ids, context-free compiled code (UnboundScript) + └─ Realm env (napi_env) × N: one per ECMAScript realm + │ principal, vm context, ShadowRealm, frame... + ├─ context (immutable), global, cached intrinsics + │ (Buffer.prototype, typed array constructors) + ├─ parent env; host hooks fall back to the parent's when unset + │ promise reject, promise hooks, prepare stack trace, + │ dynamic import, import.meta, source maps + ├─ module records, sandbox link, own microtask queue, codegen policy + └─ addon state API version, instance data, cleanup hooks, + refs/wraps/finalizers, payload slabs, last error +``` + +### Invariants + +1. **An env's realm never changes.** No context arguments, no selection, no + tokens. +2. **Everything an env creates lives in its realm.** + - Objects, functions and errors made through env X are made in realm X. + When the current context differs, the provider enters X for the call; + otherwise it adds no work. + - A native callback receives the env that created it. V8 already enters the + function's creation context. QuickJS must take the env from the + function's data rather than from the caller's context. +3. **Values belong to the agent.** A `napi_value` (or a ref) from any env of + an agent is valid with every other env of the same agent, within its + handle scope. + - V8 gets this for free. + - QuickJS, the bridge and host-JS must move their value and scope tables + from the env to the agent. + - EdgeJS already relies on it: `run_script` results, `compileFunction` + with a parsing context, and `moveMessagePortToContext`. +4. **Host hooks belong to the realm, with a fallback to the parent.** + - An event is dispatched to the env of the realm where it happened. That + env's hook runs if set; otherwise the provider walks up the parent chain. + - This is Node's "vm context → principal realm" fallback, made explicit. + - A ShadowRealm or frame sets its own hooks. +5. **An env lives exactly as long as its realm.** See §4.5. + +### Addon instances + +Node gives each addon its own env per realm. The model allows that later as a +sibling env on the same realm that shares the realm state and has its own +addon state. That would fix the instance-data collision from Edge's +`process.dlopen`. This proposal starts with **one env per realm**, but keeps +the realm part of the provider struct separate from the addon part so that +per-addon envs need no ABI change later. + +## 4. API changes + +### 4.1 New + +```c +enum { UNOFFICIAL_NAPI_REALM_OPTIONS_VERSION = 1 }; + +typedef struct { + uint32_t size; + uint32_t version; + napi_value sandbox_or_null; // vm semantics: global property access goes to this object + napi_value name; // or undefined + napi_value origin; // or undefined + napi_value host_defined_option_id; + bool allow_code_gen_strings; + bool allow_code_gen_wasm; + bool own_microtask_queue; +} unofficial_napi_realm_options; + +// Creates a realm in env's agent. The new env falls back to env's host hooks +// until it sets its own. global_out receives the realm's global, or the +// sandbox when one is given. +napi_status unofficial_napi_create_realm( + napi_env parent, + const unofficial_napi_realm_options* options, + napi_env* realm_out, + napi_value* global_out); + +// Returns the env of the realm that owns `value`. `value` may be a realm +// global, a vm sandbox, or a function; V8 also accepts any object (by its +// creation context). The result is NULL when that realm has no env. +napi_status unofficial_napi_get_realm( + napi_env env, napi_value value, napi_env* realm_out); +``` + +`get_realm` replaces every sandbox-to-context lookup, including the linear +scans in V8. It is O(1): + +- V8: a context embedder-data slot. +- QuickJS: `JS_GetContextOpaque`. +- host-JS: a WeakMap. + +### 4.2 Lose their context argument + +| Today | After | +|---|---| +| `contextify_run_script(env, sandbox_or_null, source, …)` | `run_script(env, source, …)`, run in env's realm | +| `contextify_compile_function(env, …, parsing_context_or_undefined, …)` | Parameter removed; env is the parsing realm | +| `module_wrap_create`: `options.context_or_undefined` | Field removed (options v2); the module lives in env's realm | + +Once these calls no longer take a context, the `contextify_` prefix no longer +describes them. Consider renaming them to `unofficial_napi_run_script` and +`unofficial_napi_compile_function`. + +### 4.3 Removed + +- **`unofficial_napi_contextify_make_context`** → `create_realm`. +- **`context_token_assign` / `context_token_unassign` hooks.** The embedder + creates realms itself, and a realm's death runs that env's cleanup hooks. + Edge's `attached_contexts_` is already dead code. +- **`unofficial_napi_contextify_enter` / `leave`** (unmerged branch). They + are never needed: use the realm's env. + +### 4.4 Re-scoped, same signature + +**Per realm, with fallback to the parent:** + +- `set_promise_reject_callback` + - V8 dispatches by `promise->GetCreationContext()`. + - QuickJS dispatches by the tracker's `ctx`. +- `set_promise_hooks` + - V8's `Context::SetPromiseHooks` is already per context. + - This removes `NapiV8ApplyPromiseHooksToContextifyContexts`. +- `set_prepare_stack_trace_callback` +- `module_wrap_set_hooks` +- `configure_source_maps` +- `enqueue_microtask`: uses the realm's own queue if it has one, otherwise the + agent's. + +**Per agent; any env of the agent selects it:** + +- `collect_garbage` +- heap, space and code statistics +- `profile_*`, `take_heap_snapshot` +- `terminate_execution`, `cancel_terminate_execution`, `request_interrupt` +- `configure_near_heap_limit_callback` +- `get_hash_seed` +- `notify_datetime_configuration_change` +- continuation-preserved embedder data +- `create_private_symbol` +- `event_loop_checkpoint` +- bytecode handles: compiled code is not tied to a context (V8 + `UnboundScript`; QuickJS bytecode belongs to the runtime), so these become + usable by any realm of the agent instead of only "the creating + environment". + +**`attach_env`:** agent-level. It is accepted once, on the principal env, and +refused on any other env. + +**Optional: thread-safe agent handle.** Terminate and interrupt could take the +owner handle instead of an env when called from a foreign thread. That would +remove the "env used from another thread" special case that +`feat/concurrent-stores` has to carve out. + +### 4.5 Realm lifetime + +**The principal env** lives until `release_env(owner)`. + +**A created realm env** lives while its realm is reachable: its global or +sandbox, or anything made in it. + +- This is the lifetime model that `fix/contextify-weak-records` (V8) and + `fix/quickjs-contextify-collect` (QuickJS) already implement for vm + records. +- When the realm is collected, the provider does what Node does when an env + goes away before its isolate: + 1. runs the env's cleanup hooks; + 2. finalizes its refs, wraps and finalizers; + 3. neutralizes surviving externals (`hint->env = nullptr`); + 4. tells the bridge to drop the guest id. +- Env ids are never reused, so a stale id fails with `napi_invalid_arg`. + +**Why this is safe by construction.** Payloads, externals and wrappers created +through an env belong to objects in that env's realm. In V8, a function, and in +practice any object, keeps its native context alive. So the slabs cannot be +reached once the realm is gone. + +Two cases need explicit handling: + +- **Foreign objects.** Records an env attached to *another* realm's objects + (`napi_wrap`, `add_finalizer`, `create_reference` on a foreign object) are + finalized when the env is torn down. +- **QuickJS plain objects.** They don't keep their `JSContext` alive, so + externals must be neutralized at teardown. + +**Explicit detach (for example a frame being removed)** is a possible later +addition. It would need tombstoned payloads, because functions of a detached +realm can still be reachable. + +## 5. Changes inside each layer + +### V8 + +- **Agent.** `UnofficialEnvScope` grows into `napi_agent__` and absorbs: + - the isolate-keyed maps: hash seed, promise reject, promise hooks, + fatal/OOM, near-heap-limit, profiler; + - the principal env (replacing `g_env_by_isolate`); + - the foreground target; + - the `Private` keys; + - the isolate-level V8 callbacks (prepare stack trace, dynamic import, + import.meta, promise reject), as dispatchers that resolve + context → env → hook. +- **Context → env** goes through an embedder-data slot. It replaces + `FindRecordByKey`, `ResolveContextFromKey` and `GetModuleWrapEnvForIsolate`. +- **`napi_env__`** keeps the immutable context, the parent, per-realm hooks, + module records, the own microtask queue and the sandbox key. +- **Entering the realm.** The prologue of each N-API call that creates objects + enters `env->context()` only when it differs from the current context. That + keeps the same-realm path free; the enter/leave branch measured + `Context::Enter`/`Exit` at about 3 ns. +- **Deleted:** + - `g_context_records` and its scans; + - `NapiV8ApplyPromiseHooksToContextifyContexts`; + - the per-context prepare-stack-trace table; + - the context-token plumbing. + +### QuickJS + +- **Agent.** `napi_agent__` owns: + - the `JSRuntime`; + - class ids, made per runtime instead of static; + - the rejection tracker, promise hook and module loader as dispatchers via + `JS_GetContextOpaque(ctx)` → env; + - the job queue; + - the scope stack and value slots; + - the pending exception; + - `external_memory_` and the embedder hooks. +- **`napi_env__`** owns one `JSContext`. +- **Deleted:** `current_context_`, `napi_env_context_scope__` (23 sites), + `napi_value__::context_` tags and `last_exception_context_`. +- **The trampoline takes its env from `func_data`** (the creating env). This + is a deliberate behaviour change to match V8 and Node. +- **`module_wrap` and `compile_function`** honour the env's realm. + +### host-JS + +- **Split `HostJsEnv`** into: + - `HostJsAgent`, per worker: values, frames, refs, `object_ids`, + finalizers; + - `HostJsEnv`: `global_context`, instance data, modules. +- **`create_realm`** builds a new `global_context`, optionally over a sandbox. + This deletes the anonymous `wasmerNapiGlobalScopes` fallback and the + `evaluation_scope(parsing_context)` branch. +- **Pass the env's context explicitly** to `context_eval`, `is_buffer` and + `buffer_view`. That lets `wasmerNapiActiveGlobalContext` and the + `activate()` switch go. +- **Limit.** These realms stay virtual (`with`/`Proxy` over one host realm), + so intrinsics are shared. The API becomes uniform; real isolation would need + host ShadowRealm, iframes or `node:vm`, which is out of scope. + +### Bridge (`napi_bridge_init.cc`) + +- **Split `SnapiEnvState`:** + - `SnapiAgentState`: owner, value slots, scope frames, refs, deferreds, + handle tables (module_wrap, bytecode, profile, buffer lease), + `active_callback_ctx`, `value_limit`, the list of envs; + - `SnapiEnvState`: agent pointer, `napi_env`, callback registry. +- **Guest value ids become agent-scoped**, so they stay valid across that + agent's realms. +- **`g_envs` validation** maps env → agent. +- **Lock scope (side benefit).** With an agent object it is natural to replace + the process-global `g_mu`, taken on every `unofficial_*` call, with a + per-agent lock. + +### Rust (`src/env.rs`, `src/guest/napi.rs`) + +- **Agents get their own table.** `napi_scopes: scope_id → env_id` becomes + `agents: agent_id → { principal env, heap charge, registry entry }`. +- **Budget is per agent.** Isolate reservation and heap charges stay on + `create_env` only; `create_realm` charges no isolate, because a context + counts against its isolate's heap. +- **`env_registry` and `terminate_all`** hold agents instead of envs. +- **The bridge reports realm death** so the env id and its leases can be + dropped. +- **New guest imports** `unofficial_napi_create_realm` and + `unofficial_napi_get_realm`. +- **Changed signatures get new import names.** The old ones stay as shims for + one release; see §8. + +## 6. EdgeJS migration + +| Area | Change | +|---|---| +| `makeContext` | `create_realm`. Keep the `contextify_context_private_symbol` tag on the returned object. | +| `runInContext` | `get_realm(sandbox)`, then run on that env. | +| `compileFunction` | `get_realm(parsing_context)`, then compile on that env. | +| `ModuleWrap` | Create on `get_realm(context)`. Drop the "context given → skip bytecode cache" special case; the cache is per agent now. | +| Hooks | No change for vm contexts, because realm envs fall back to the principal env. A ShadowRealm later gets its own Edge `Realm` object holding the module loader state, binding registry and hooks, sharing the `edge::Environment`. | +| Isolate operations, workers | No change. | +| `attach_env` | No change: it is already called once, on the principal env. | +| Context-token handlers | Delete. | +| `process.dlopen` | Optional later: one addon env per addon. | + +What must not change: callbacks keep receiving their creating env, and values +stay usable across envs. Both are invariants in §3. + +## 7. Pitfalls + +- **Envs held past their realm.** An embedder that keeps a realm env must + also keep its realm reachable, for example by holding a ref to the global or + sandbox, or by listening on that env's cleanup hook. EdgeJS stores what it + needs on the sandbox, which satisfies this. +- **Cross-agent values remain invalid.** Workers still exchange values through + `unofficial_napi_message`. A cheap agent check on value-taking calls would + catch misuse in debug builds. +- **QuickJS behaviour change.** Callbacks called from vm code will see their + creating realm, as on V8. Any QuickJS-only test that expects the vm global + inside a callback will change. +- **Hook fallback is a policy.** It makes vm contexts behave like Node. Code + that wants isolation (ShadowRealm) must set hooks on its realm env. +- **Teardown order.** The agent tears down after all of its realm envs. The + principal env tears down last, then the isolate or runtime. + +## 8. Phased plan + +Every phase leaves the tests passing on V8, QuickJS and host-JS. + +**Phase 0: internal split, no ABI change.** +- Introduce agent structs in V8, QuickJS, host-JS and the bridge, and move the + isolate-level state into them. +- Make `env->context()` immutable everywhere. +- Fix the QuickJS trampoline. + +**Phase 1: realm envs, additive ABI.** +- Add `create_realm` and `get_realm`. +- `contextify_make_context` becomes a shim over `create_realm`. The old + context arguments resolve through `get_realm` and forward to the realm env. +- Dispatch hooks per realm with fallback to the parent. +- Collect realm envs. +- Make bridge value tables agent-scoped. +- Add the guest imports. + +**Phase 2: EdgeJS moves to realm envs** (§6). + +**Phase 3: remove the old surface.** +- Drop the context arguments, `make_context` and the context-token hooks. +- Bump the options structs (module create v2). +- Delete the records, scans and fallbacks listed in §5. + +**Phase 4, optional:** per-addon envs, and ShadowRealm in EdgeJS. + +## 9. Unmerged branches + +| Branch | Recommendation | +|---|---| +| `feat/contextify-enter-leave` | Superseded: "one realm per document or frame" becomes `create_realm` plus that env. Its commits are a list of the costs of a selectable context, which this design avoids: root vs selected context, the microtask queue split, finalizers and interrupts running in the wrong realm, the handle leak, and callback cost going from 5.9 to 11 ns. | +| `feat/concurrent-stores`, `perf/concurrent-envs` | Land first. "Ids never reused" and "scope id = env id" become "agent id = principal env id". Terminate and interrupt then target the agent. | +| `fix/contextify-weak-records`, `fix/quickjs-contextify-collect` | Land first. Their lifetime model is the realm-env lifetime in §4.5. | +| `feat/trusted-script` | No conflict. Its hook is installed once per isolate, which is agent-level. | + +## 10. Decisions to make + +1. **Hook fallback to the parent** (recommended, matches Node) or explicit + hooks per realm? +2. **Realm teardown:** GC only at first (recommended), or explicit detach from + the start? +3. **Per-addon envs:** now, or after realm envs (recommended)? +4. **Guest ABI:** additive imports plus shims, then removal (recommended), or + a `napi_extension_wasmer_v1` module? + +## 11. Phase 0: what landed + +Every engine now has an agent next to its env. Each agent still has exactly one +env, its principal env. There is no ABI change: public headers, guest imports +and the Rust↔C++ signatures are untouched. The one deliberate behaviour change +is the QuickJS trampoline. + +### V8 (`v8/src`) + +- **New `napi_agent__`** (`internal/napi_v8_agent.h`). It is owned by the owner + handle (`UnofficialEnvScope`) and found from an isolate through isolate data + slot 0. +- **Eight process-global maps are gone**, replaced by agent fields that need no + lock: `g_env_by_isolate`, `g_hash_seeds`, `g_tracking_allocators`, + `g_fatal_error_callbacks`, `g_near_heap_limit_callbacks`, + `g_profiler_states`, `g_promise_reject_callbacks` and `g_promise_hooks`. +- **Also moved to the agent:** + - the three `Private` keys; + - the embedder hooks (context tokens, foreground task, fatal and OOM); + - the microtask policy; + - the default dynamic-import hook. +- **Moved to the env (realm):** the promise-reject callback and the four + promise hooks. Dispatch goes isolate → agent → principal env; Phase 1 + resolves context → env instead. +- **`GetModuleWrapEnvForIsolate`** is an O(1) agent lookup instead of a scan. +- **`napi_agent__::Shutdown()`** now also removes the near-heap-limit + trampoline. Before, it stayed registered with the env pointer as data after + the env was freed. +- **Unchanged:** the env-keyed realm maps (`g_prepare_stack_trace_callbacks`, + `g_error_formatting_states`, `g_context_records`, `g_module_wrap_states`) and + `g_runtime_mu` around the platform. + +### QuickJS (`quickjs/src`) + +- **New `napi_agent__`** (`internal/napi_agent.{h,cc}`) holds: + - the runtime; + - the handle-scope stack; + - the pending exception; + - external memory and the embedder hooks; + - continuation data and promise context frames; + - the runtime-wide promise, rejection, import.meta and dynamic-import hooks, + installed with the agent as opaque. +- **The env has one immutable `JSContext`.** +- **Deleted:** + - `current_context_` and `napi_env_context_scope__` (16 sites); + - `main_context()` / `current_context()`; + - `last_exception_context_`; + - the per-value, per-ref and per-deferred context tags. Values hold only the + runtime. +- **Trampoline:** the env now comes from the function's own data, not the + caller's context. A native function called from a vm script now sees its + creating realm, as on V8 and Node. +- **New shared test:** `NativeFunctionCalledFromContextKeepsItsRealm`. +- **Teardown:** native callbacks are refused once teardown starts. Before, only + calls from the main context were refused. +- **Not done:** class ids are still process-static. + +### Bridge (`src/napi_bridge_init.cc`) + +- **`SnapiAgentState` holds:** the owner, value slots, scope frames, refs, + deferreds, handle tables, cbinfo invocations, `active_callback_ctx` and + `value_limit`. +- **`SnapiEnvState` holds:** the agent pointer, the `napi_env`, and the + callback registry and bindings. +- **Scope frames remember the env that opened them.** +- **The value cap counts across the agent's envs.** +- **Unchanged:** `g_mu` and `g_envs`. + +### host-JS (`src/snapi_js.rs`) + +- **`HostJsAgent` holds:** the handle tables and frames, `object_ids`, wraps, + references, deferreds, finalizers, pending callbacks and + `active_callback_ctx`. +- **`HostJsEnv` keeps:** its global context, `last_exception`, callbacks, + closures, instance data and modules. +- **No implicit active context any more.** The module-global + `wasmerNapiActiveGlobalContext`, `activate()` and the `ACTIVE_HOST_JS_ENV` + thread-local are gone. The JS helpers take the env's context explicitly. +- **Bug fix:** buffer views made by `create_bytes_value` and + `create_guest_buffer_view` used whichever env had been active last. +- **Unchanged:** vm sandbox semantics, including the fallback scope WeakMap. + +### Tests + +All counts are compared with `main`. + +| Suite | Before | After | +|---|---|---| +| V8 (native) | 97 | 99 | +| QuickJS (native, at the recorded submodule commit) | 96 | 97 | +| Rust lib / `v8_host_control` | 48 / 3 | 48 / 3 | +| Manifest, native + WASIX | 36 | 36 | +| host-JS node / bun | 15 / — | 16 / 13 passed, 3 skipped | +| host-JS wasm-bindgen | 15 | 15 | + +The new tests: + +- V8 `NearHeapLimitCallbackReceivesItsEnvironment`; +- shared `NativeFunctionCalledFromContextKeepsItsRealm`; +- a host-JS test that two contexts each evaluate in their own global. + +`make test-wasix-napi` does not work in standalone mode: the harness looks for +`./cargo-standalone.sh` under the temporary crate root. The manifest was run +with an equivalent script instead. + +### Notes for Phase 1 + +- Callback, finalizer and interrupt paths in the bridge and host-JS still + carry their env. Pending callbacks and finalizer drains read the exception of + the env passed to the drain. +- The per-env callback registry and the opener env on frames exist, but + nothing exercises them yet. +- `Box` needs a shared handle once several envs share an agent. From a3e13f20fce58f7bda16bdd019d519b109ab6f0e Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Fri, 23 Oct 2026 16:24:21 +0200 Subject: [PATCH 007/150] Drop the branch name from the design doc's status line The branch was renamed when pushed: the remote has a branch named `refactor`, so no `refactor/...` branch can exist next to it. Co-Authored-By: Claude Opus 5.5 --- docs/realm-bound-env.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/realm-bound-env.md b/docs/realm-bound-env.md index 26d8d0fb9d..4eaa96805d 100644 --- a/docs/realm-bound-env.md +++ b/docs/realm-bound-env.md @@ -1,7 +1,6 @@ # Realm-bound `napi_env` -Status: Phase 0 implemented on branch `refactor/agent-realm-phase0` (see -§11). Phases 1–4 are not started. +Status: Phase 0 implemented (see §11). Phases 1–4 are not started. **Proposal:** split each provider into an **agent**, which is the engine instance and its thread, and **realm envs**. A realm env is a `napi_env` whose From c8289a1cb9dce492c1257f7d74adc378d028358f Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Sun, 25 Oct 2026 09:59:07 +0100 Subject: [PATCH 008/150] Add realm handles for vm contexts An env keeps acting in its engine instance's main realm. A vm context is another realm of that instance, but not an env: - unofficial_napi_create_realm returns an unofficial_napi_realm and the realm's global (or sandbox); unofficial_napi_get_realm finds a realm by its global or sandbox. - Only the calls that run code take a realm: unofficial_napi_run_script and unofficial_napi_compile_function (which replace the contextify versions that took a sandbox or parsing context), module creation (options version 2, realm_or_null instead of context_or_undefined) and unofficial_napi_bytecode_open (options version 2). NULL means the env's realm. - A realm is collected when its global and everything made in it are unreachable. A realm handle, like a napi_value, is valid while its handle scope is open. - unofficial_napi_contextify_make_context and the context-token hooks are removed (env hooks version 2). In the guest ABI a realm id is the value id of the realm's global, so it needs no table and has a value id's lifetime. Co-Authored-By: Claude Opus 5.5 --- include/unofficial_napi.h | 145 ++++++--- include/unofficial_napi_wasm32_abi.h | 39 ++- src/guest/abi.rs | 203 ++++++++----- src/snapi.rs | 25 +- tests/CMakeLists.txt | 3 + tests/programs/manifest.json | 5 + tests/programs/run_script_test.c | 73 ++--- tests/programs/test_realm.c | 278 ++++++++++++++++++ tests/runners/test_21_general.cc | 3 + .../runners/test_65_unofficial_contextify.cc | 266 ++++++++--------- 10 files changed, 715 insertions(+), 325 deletions(-) create mode 100644 tests/programs/test_realm.c diff --git a/include/unofficial_napi.h b/include/unofficial_napi.h index 39a4f35cc7..a3c5703964 100644 --- a/include/unofficial_napi.h +++ b/include/unofficial_napi.h @@ -59,9 +59,6 @@ typedef struct { unofficial_napi_guest_heap guest_heap; } unofficial_napi_env_create_options; -typedef void (*unofficial_napi_context_token_callback)(napi_env env, - void* token, - void* data); typedef void (*unofficial_napi_foreground_task_callback)(napi_env env, void* data); typedef void (*unofficial_napi_foreground_task_cleanup)(napi_env env, @@ -80,25 +77,24 @@ typedef void (*unofficial_napi_oom_error_callback)(napi_env env, bool is_heap_oom, const char* detail); +// Bits 0 and 1 belonged to the context-token callbacks that version 2 of the +// hooks struct removed. They are not reused. typedef enum { - unofficial_napi_env_hook_context_token_assign = 1u << 0, - unofficial_napi_env_hook_context_token_unassign = 1u << 1, unofficial_napi_env_hook_enqueue_foreground_task = 1u << 2, unofficial_napi_env_hook_fatal_error = 1u << 3, unofficial_napi_env_hook_oom_error = 1u << 4, } unofficial_napi_env_hook; -enum { UNOFFICIAL_NAPI_ENV_HOOKS_VERSION = 1 }; +enum { UNOFFICIAL_NAPI_ENV_HOOKS_VERSION = 2 }; // Immutable embedder callbacks attached as one complete environment state // transition. `size` and `version` make additions ABI-compatible. `data` is // owned by the embedder and must remain valid until the environment is released. +// Version 2 removed the context-token callbacks; providers reject version 1. typedef struct { uint32_t size; uint32_t version; void* data; - unofficial_napi_context_token_callback context_token_assign_callback; - unofficial_napi_context_token_callback context_token_unassign_callback; unofficial_napi_enqueue_foreground_task_callback enqueue_foreground_task_callback; unofficial_napi_fatal_error_callback fatal_error_callback; unofficial_napi_oom_error_callback oom_error_callback; @@ -108,10 +104,6 @@ static inline uint64_t unofficial_napi_env_hooks_requested( const unofficial_napi_env_hooks* hooks) { if (hooks == NULL) return 0; uint64_t requested = 0; - if (hooks->context_token_assign_callback != NULL) - requested |= unofficial_napi_env_hook_context_token_assign; - if (hooks->context_token_unassign_callback != NULL) - requested |= unofficial_napi_env_hook_context_token_unassign; if (hooks->enqueue_foreground_task_callback != NULL) requested |= unofficial_napi_env_hook_enqueue_foreground_task; if (hooks->fatal_error_callback != NULL) @@ -134,6 +126,75 @@ NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_release_env( unofficial_napi_env_owner owner, struct uv_loop_s* loop_or_null); +// Realms. An env acts in one realm, its engine instance's main realm, for its +// whole life: every N-API call through it creates objects there, and the +// native functions it makes run there. +// +// A vm context is another realm of the same engine instance. It is not an env: +// unofficial_napi_create_realm makes one and returns an unofficial_napi_realm, +// and only the calls that run code take one (unofficial_napi_run_script, +// unofficial_napi_compile_function, module creation and +// unofficial_napi_bytecode_open). A NULL realm means the env's own realm. +// Hooks, instance data and cleanup hooks stay on the env: a hook fires for +// code running in any of its realms. +// +// A realm lives while its global (the sandbox, when it has one) or anything +// made in it is reachable, and is then collected. A realm handle, like a +// napi_value, is valid only while the handle scope it was obtained in is open; +// unofficial_napi_get_realm finds the realm again from its global. +typedef struct unofficial_napi_realm__* unofficial_napi_realm; + +enum { UNOFFICIAL_NAPI_REALM_OPTIONS_VERSION = 1 }; + +// With a sandbox object, global property access in the new realm reads and +// writes the sandbox, as with vm.createContext(sandbox). Otherwise the realm +// gets a fresh global. `name`, `origin` and `host_defined_option_id` may be +// NULL. The descriptor is observed only for the duration of the call. +typedef struct { + uint32_t size; + uint32_t version; + napi_value sandbox_or_null; + napi_value name; + napi_value origin; + napi_value host_defined_option_id; + bool allow_code_gen_strings; + bool allow_code_gen_wasm; + bool own_microtask_queue; +} unofficial_napi_realm_options; + +static inline void unofficial_napi_realm_options_init( + unofficial_napi_realm_options* options) { + if (options == NULL) return; +#ifdef __cplusplus + *options = {}; +#else + *options = (unofficial_napi_realm_options){0}; +#endif + options->size = sizeof(*options); + options->version = UNOFFICIAL_NAPI_REALM_OPTIONS_VERSION; + options->allow_code_gen_strings = true; + options->allow_code_gen_wasm = true; +} + +// Creates a realm in `env`'s engine instance. `global_out` receives the +// sandbox when one was given, else the realm's global; it may be NULL. A NULL +// `options` means the defaults of unofficial_napi_realm_options_init. A sandbox +// belongs to at most one realm; the env's own global may still be one. +NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_create_realm( + napi_env env, + const unofficial_napi_realm_options* options_or_null, + unofficial_napi_realm* realm_out, + napi_value* global_out); + +// Returns the realm whose global is `value`: a realm's own global, or the +// sandbox given to unofficial_napi_create_realm. `*realm_out` is NULL for any +// other object, the env's own global included. Fails with +// napi_object_expected when `value` is not an object. +NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_get_realm( + napi_env env, + napi_value value, + unofficial_napi_realm* realm_out); + NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_collect_garbage( napi_env env); NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_set_prepare_stack_trace_callback( @@ -584,21 +645,12 @@ NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_notify_datetime_configu NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_create_serdes_binding(napi_env env, napi_value* result_out); -// Unofficial helpers for implementing internalBinding('contextify') on embedders. -// These are engine-specific APIs and are not part of the public Node-API. -NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_contextify_make_context( - napi_env env, - napi_value sandbox_or_symbol, - napi_value name, - napi_value origin_or_undefined, - bool allow_code_gen_strings, - bool allow_code_gen_wasm, - bool own_microtask_queue, - napi_value host_defined_option_id, - napi_value* result_out); +// Script, function and module compilation. These are engine-specific APIs +// and are not part of the public Node-API. Each runs or compiles code in +// `realm_or_null`, or in the env's own realm when it is NULL. -// Provider-owned compiled JavaScript. The handle is bound to its creating -// environment and must be released explicitly. +// Provider-owned compiled JavaScript, compiled for one realm. The handle is +// bound to its env and must be released explicitly. typedef struct unofficial_napi_bytecode__* unofficial_napi_bytecode; // A tagged JS source for compile/eval APIs. Providers reject descriptors whose @@ -653,10 +705,12 @@ typedef enum { unofficial_napi_bytecode_cache_compile_on_reject = 0, unofficial_napi_bytecode_cache_validate_only = 1, } unofficial_napi_bytecode_cache_policy; -#define UNOFFICIAL_NAPI_BYTECODE_OPEN_OPTIONS_VERSION 1u +// Version 2 added `realm_or_null`, the realm the code is compiled for. +#define UNOFFICIAL_NAPI_BYTECODE_OPEN_OPTIONS_VERSION 2u typedef struct unofficial_napi_bytecode_open_options { uint32_t size; uint32_t version; + unofficial_napi_realm realm_or_null; napi_value source_text; napi_value filename; int32_t shape; @@ -693,9 +747,12 @@ NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_bytecode_release( napi_env env, unofficial_napi_bytecode bytecode); -NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_contextify_run_script( +// Runs a script in a realm. When the realm has its own microtask queue +// (unofficial_napi_realm_options.own_microtask_queue), the queue is drained +// after the script returns. +NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_run_script( napi_env env, - napi_value sandbox_or_null, + unofficial_napi_realm realm_or_null, const unofficial_napi_js_source* source, napi_value filename, int32_t line_offset, @@ -707,13 +764,14 @@ NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_contextify_run_script( napi_value host_defined_option_id, napi_value* result_out); -NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_contextify_compile_function( +// Compiles a function in a realm, as vm.compileFunction does. +NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_compile_function( napi_env env, + unofficial_napi_realm realm_or_null, const unofficial_napi_js_source* source, napi_value filename, int32_t line_offset, int32_t column_offset, - napi_value parsing_context_or_undefined, napi_value context_extensions_or_undefined, napi_value params_or_undefined, napi_value host_defined_option_id, @@ -733,8 +791,10 @@ typedef struct unofficial_napi_module__* unofficial_napi_module; // Versioned, tagged transaction for creating either kind of module. Keeping // creation behind one descriptor gives providers one validation boundary and -// lets the ABI grow without adding one import per module kind. -#define UNOFFICIAL_NAPI_MODULE_CREATE_OPTIONS_VERSION 1u +// lets the ABI grow without adding one import per module kind. The module +// lives in `realm_or_null`, or in the env's realm. Version 2 replaced +// `context_or_undefined` with it; providers reject version 1. +#define UNOFFICIAL_NAPI_MODULE_CREATE_OPTIONS_VERSION 2u typedef enum { unofficial_napi_module_source_text = 1, @@ -759,7 +819,7 @@ typedef struct { unofficial_napi_module_kind kind; napi_value wrapper; napi_value url; - napi_value context_or_undefined; + unofficial_napi_realm realm_or_null; union { unofficial_napi_source_text_module_options source_text; unofficial_napi_synthetic_module_options synthetic; @@ -877,15 +937,17 @@ static_assert(sizeof(unofficial_napi_env_create_options) == static_assert(sizeof(unofficial_napi_runtime_options) == sizeof(unofficial_napi_wasm32_runtime_options_v1)); static_assert(sizeof(unofficial_napi_env_hooks) == - sizeof(unofficial_napi_wasm32_env_hooks_v1)); + sizeof(unofficial_napi_wasm32_env_hooks_v2)); static_assert(sizeof(unofficial_napi_js_source) == sizeof(unofficial_napi_wasm32_js_source)); static_assert(sizeof(unofficial_napi_bytecode_open_options) == - sizeof(unofficial_napi_wasm32_bytecode_open_options_v1)); + sizeof(unofficial_napi_wasm32_bytecode_open_options_v2)); static_assert(sizeof(unofficial_napi_module_create_options) == - sizeof(unofficial_napi_wasm32_module_create_options_v1)); + sizeof(unofficial_napi_wasm32_module_create_options_v2)); static_assert(sizeof(unofficial_napi_module_hooks) == sizeof(unofficial_napi_wasm32_module_hooks_v1)); +static_assert(sizeof(unofficial_napi_realm_options) == + sizeof(unofficial_napi_wasm32_realm_options_v1)); #else _Static_assert(sizeof(unofficial_napi_env_create_options) == sizeof(unofficial_napi_wasm32_env_create_options_v1), @@ -894,20 +956,23 @@ _Static_assert(sizeof(unofficial_napi_runtime_options) == sizeof(unofficial_napi_wasm32_runtime_options_v1), "public runtime-options layout differs from its wasm32 wire ABI"); _Static_assert(sizeof(unofficial_napi_env_hooks) == - sizeof(unofficial_napi_wasm32_env_hooks_v1), + sizeof(unofficial_napi_wasm32_env_hooks_v2), "public env-hooks layout differs from its wasm32 wire ABI"); _Static_assert(sizeof(unofficial_napi_js_source) == sizeof(unofficial_napi_wasm32_js_source), "public JS-source layout differs from its wasm32 wire ABI"); _Static_assert(sizeof(unofficial_napi_bytecode_open_options) == - sizeof(unofficial_napi_wasm32_bytecode_open_options_v1), + sizeof(unofficial_napi_wasm32_bytecode_open_options_v2), "public bytecode-open layout differs from its wasm32 wire ABI"); _Static_assert(sizeof(unofficial_napi_module_create_options) == - sizeof(unofficial_napi_wasm32_module_create_options_v1), + sizeof(unofficial_napi_wasm32_module_create_options_v2), "public module-create layout differs from its wasm32 wire ABI"); _Static_assert(sizeof(unofficial_napi_module_hooks) == sizeof(unofficial_napi_wasm32_module_hooks_v1), "public module-hooks layout differs from its wasm32 wire ABI"); +_Static_assert(sizeof(unofficial_napi_realm_options) == + sizeof(unofficial_napi_wasm32_realm_options_v1), + "public realm-options layout differs from its wasm32 wire ABI"); #endif #endif diff --git a/include/unofficial_napi_wasm32_abi.h b/include/unofficial_napi_wasm32_abi.h index 96508dc99c..6881d3c268 100644 --- a/include/unofficial_napi_wasm32_abi.h +++ b/include/unofficial_napi_wasm32_abi.h @@ -30,12 +30,10 @@ typedef struct { uint32_t size; uint32_t version; uint32_t data; - uint32_t context_token_assign_callback; - uint32_t context_token_unassign_callback; uint32_t enqueue_foreground_task_callback; uint32_t fatal_error_callback; uint32_t oom_error_callback; -} unofficial_napi_wasm32_env_hooks_v1; +} unofficial_napi_wasm32_env_hooks_v2; typedef struct { int32_t kind; @@ -46,6 +44,7 @@ typedef struct { typedef struct { uint32_t size; uint32_t version; + uint32_t realm_or_null; uint32_t source_text; uint32_t filename; int32_t shape; @@ -58,7 +57,7 @@ typedef struct { uint8_t has_cache; uint8_t cache_policy; uint8_t reserved[2]; -} unofficial_napi_wasm32_bytecode_open_options_v1; +} unofficial_napi_wasm32_bytecode_open_options_v2; typedef struct { uint32_t size; @@ -66,9 +65,9 @@ typedef struct { int32_t kind; uint32_t wrapper; uint32_t url; - uint32_t context_or_undefined; + uint32_t realm_or_null; uint8_t payload[16]; -} unofficial_napi_wasm32_module_create_options_v1; +} unofficial_napi_wasm32_module_create_options_v2; typedef struct { uint32_t size; @@ -77,29 +76,45 @@ typedef struct { uint32_t initialize_import_meta_object; } unofficial_napi_wasm32_module_hooks_v1; +typedef struct { + uint32_t size; + uint32_t version; + uint32_t sandbox_or_null; + uint32_t name; + uint32_t origin; + uint32_t host_defined_option_id; + uint8_t allow_code_gen_strings; + uint8_t allow_code_gen_wasm; + uint8_t own_microtask_queue; + uint8_t reserved; +} unofficial_napi_wasm32_realm_options_v1; + #if defined(__cplusplus) static_assert(sizeof(unofficial_napi_wasm32_runtime_options_v1) == 16); static_assert(sizeof(unofficial_napi_wasm32_env_create_options_v1) == 48); -static_assert(sizeof(unofficial_napi_wasm32_env_hooks_v1) == 32); +static_assert(sizeof(unofficial_napi_wasm32_env_hooks_v2) == 24); static_assert(sizeof(unofficial_napi_wasm32_js_source) == 12); -static_assert(sizeof(unofficial_napi_wasm32_bytecode_open_options_v1) == 48); -static_assert(sizeof(unofficial_napi_wasm32_module_create_options_v1) == 40); +static_assert(sizeof(unofficial_napi_wasm32_bytecode_open_options_v2) == 52); +static_assert(sizeof(unofficial_napi_wasm32_module_create_options_v2) == 40); static_assert(sizeof(unofficial_napi_wasm32_module_hooks_v1) == 16); +static_assert(sizeof(unofficial_napi_wasm32_realm_options_v1) == 28); #else _Static_assert(sizeof(unofficial_napi_wasm32_runtime_options_v1) == 16, "wasm32 runtime-options wire layout changed"); _Static_assert(sizeof(unofficial_napi_wasm32_env_create_options_v1) == 48, "wasm32 env-create wire layout changed"); -_Static_assert(sizeof(unofficial_napi_wasm32_env_hooks_v1) == 32, +_Static_assert(sizeof(unofficial_napi_wasm32_env_hooks_v2) == 24, "wasm32 env-hooks wire layout changed"); _Static_assert(sizeof(unofficial_napi_wasm32_js_source) == 12, "wasm32 JS-source wire layout changed"); -_Static_assert(sizeof(unofficial_napi_wasm32_bytecode_open_options_v1) == 48, +_Static_assert(sizeof(unofficial_napi_wasm32_bytecode_open_options_v2) == 52, "wasm32 bytecode-open wire layout changed"); -_Static_assert(sizeof(unofficial_napi_wasm32_module_create_options_v1) == 40, +_Static_assert(sizeof(unofficial_napi_wasm32_module_create_options_v2) == 40, "wasm32 module-create wire layout changed"); _Static_assert(sizeof(unofficial_napi_wasm32_module_hooks_v1) == 16, "wasm32 module-hooks wire layout changed"); +_Static_assert(sizeof(unofficial_napi_wasm32_realm_options_v1) == 28, + "wasm32 realm-options wire layout changed"); #endif #endif // UNOFFICIAL_NAPI_WASM32_ABI_H_ diff --git a/src/guest/abi.rs b/src/guest/abi.rs index 7ba1584dac..09ed3183f3 100644 --- a/src/guest/abi.rs +++ b/src/guest/abi.rs @@ -32,12 +32,10 @@ struct Wasm32EnvCreateOptionsV1 { } #[repr(C)] -struct Wasm32EnvHooksV1 { +struct Wasm32EnvHooksV2 { size: u32, version: u32, data: u32, - context_token_assign_callback: u32, - context_token_unassign_callback: u32, enqueue_foreground_task_callback: u32, fatal_error_callback: u32, oom_error_callback: u32, @@ -51,9 +49,10 @@ struct Wasm32JsSource { } #[repr(C)] -struct Wasm32BytecodeOpenOptionsV1 { +struct Wasm32BytecodeOpenOptionsV2 { size: u32, version: u32, + realm_or_null: u32, source_text: u32, filename: u32, shape: i32, @@ -69,13 +68,13 @@ struct Wasm32BytecodeOpenOptionsV1 { } #[repr(C)] -struct Wasm32ModuleCreateOptionsV1 { +struct Wasm32ModuleCreateOptionsV2 { size: u32, version: u32, kind: i32, wrapper: u32, url: u32, - context_or_undefined: u32, + realm_or_null: u32, payload: [u8; 16], } @@ -102,24 +101,40 @@ struct Wasm32ModuleHooksV1 { initialize_import_meta_object: u32, } +#[repr(C)] +struct Wasm32RealmOptionsV1 { + size: u32, + version: u32, + sandbox_or_null: u32, + name: u32, + origin: u32, + host_defined_option_id: u32, + allow_code_gen_strings: u8, + allow_code_gen_wasm: u8, + own_microtask_queue: u8, + reserved: u8, +} + const JS_SOURCE_SIZE: usize = std::mem::size_of::(); const RUNTIME_OPTIONS_SIZE: usize = std::mem::size_of::(); const ENV_CREATE_PREFIX_SIZE: usize = std::mem::size_of::(); -const BYTECODE_OPEN_SIZE: usize = std::mem::size_of::(); -const MODULE_CREATE_PREFIX_SIZE: usize = std::mem::size_of::(); +const BYTECODE_OPEN_SIZE: usize = std::mem::size_of::(); +const MODULE_CREATE_SIZE: usize = std::mem::size_of::(); const MODULE_HOOKS_SIZE: usize = std::mem::size_of::(); -const ENV_HOOKS_SIZE: usize = std::mem::size_of::(); +const ENV_HOOKS_SIZE: usize = std::mem::size_of::(); +const REALM_OPTIONS_SIZE: usize = std::mem::size_of::(); const _: () = assert!(std::mem::size_of::() == 8); const _: () = assert!(JS_SOURCE_SIZE == 12); const _: () = assert!(RUNTIME_OPTIONS_SIZE == 16); const _: () = assert!(ENV_CREATE_PREFIX_SIZE == 48); -const _: () = assert!(BYTECODE_OPEN_SIZE == 48); -const _: () = assert!(MODULE_CREATE_PREFIX_SIZE == 40); +const _: () = assert!(BYTECODE_OPEN_SIZE == 52); +const _: () = assert!(MODULE_CREATE_SIZE == 40); const _: () = assert!(std::mem::size_of::() == 16); const _: () = assert!(std::mem::size_of::() == 16); const _: () = assert!(MODULE_HOOKS_SIZE == 16); -const _: () = assert!(ENV_HOOKS_SIZE == 32); +const _: () = assert!(ENV_HOOKS_SIZE == 24); +const _: () = assert!(REALM_OPTIONS_SIZE == 28); fn u32_at(bytes: &[u8], offset: usize) -> Option { Some(u32::from_le_bytes( @@ -268,6 +283,8 @@ pub(crate) fn read_js_source( } pub(crate) struct BytecodeOpen { + /// The guest realm id (0 for the env's own realm). + pub realm_or_null: u32, pub source_text: u32, pub filename: u32, pub shape: i32, @@ -284,18 +301,18 @@ pub(crate) fn read_bytecode_open( env: &mut FunctionEnvMut, guest_ptr: u32, ) -> Option { - let bytes = read_versioned(env, guest_ptr, BYTECODE_OPEN_SIZE, 1)?; + let bytes = read_versioned(env, guest_ptr, BYTECODE_OPEN_SIZE, 2)?; let cache_ptr = u32_at( &bytes, - std::mem::offset_of!(Wasm32BytecodeOpenOptionsV1, cache_bytes), + std::mem::offset_of!(Wasm32BytecodeOpenOptionsV2, cache_bytes), )?; let cache_length = u32_at( &bytes, - std::mem::offset_of!(Wasm32BytecodeOpenOptionsV1, cache_byte_length), + std::mem::offset_of!(Wasm32BytecodeOpenOptionsV2, cache_byte_length), )? as usize; - let has_cache = *bytes.get(std::mem::offset_of!(Wasm32BytecodeOpenOptionsV1, has_cache))?; + let has_cache = *bytes.get(std::mem::offset_of!(Wasm32BytecodeOpenOptionsV2, has_cache))?; let cache_policy = *bytes.get(std::mem::offset_of!( - Wasm32BytecodeOpenOptionsV1, + Wasm32BytecodeOpenOptionsV2, cache_policy ))?; let cache = if has_cache != 0 && cache_length != 0 { @@ -307,33 +324,37 @@ pub(crate) fn read_bytecode_open( Vec::new() }; Some(BytecodeOpen { + realm_or_null: u32_at( + &bytes, + std::mem::offset_of!(Wasm32BytecodeOpenOptionsV2, realm_or_null), + )?, source_text: u32_at( &bytes, - std::mem::offset_of!(Wasm32BytecodeOpenOptionsV1, source_text), + std::mem::offset_of!(Wasm32BytecodeOpenOptionsV2, source_text), )?, filename: u32_at( &bytes, - std::mem::offset_of!(Wasm32BytecodeOpenOptionsV1, filename), + std::mem::offset_of!(Wasm32BytecodeOpenOptionsV2, filename), )?, shape: i32_at( &bytes, - std::mem::offset_of!(Wasm32BytecodeOpenOptionsV1, shape), + std::mem::offset_of!(Wasm32BytecodeOpenOptionsV2, shape), )?, params_or_undefined: u32_at( &bytes, - std::mem::offset_of!(Wasm32BytecodeOpenOptionsV1, params_or_undefined), + std::mem::offset_of!(Wasm32BytecodeOpenOptionsV2, params_or_undefined), )?, host_defined_option_id: u32_at( &bytes, - std::mem::offset_of!(Wasm32BytecodeOpenOptionsV1, host_defined_option_id), + std::mem::offset_of!(Wasm32BytecodeOpenOptionsV2, host_defined_option_id), )?, line_offset: i32_at( &bytes, - std::mem::offset_of!(Wasm32BytecodeOpenOptionsV1, line_offset), + std::mem::offset_of!(Wasm32BytecodeOpenOptionsV2, line_offset), )?, column_offset: i32_at( &bytes, - std::mem::offset_of!(Wasm32BytecodeOpenOptionsV1, column_offset), + std::mem::offset_of!(Wasm32BytecodeOpenOptionsV2, column_offset), )?, cache, has_cache, @@ -345,7 +366,8 @@ pub(crate) struct ModuleCreate { pub kind: i32, pub wrapper: u32, pub url: u32, - pub context_or_undefined: u32, + /// The guest realm id (0 for the env's own realm). + pub realm_or_null: u32, pub source_text: u32, pub source_bytecode: u32, pub line_offset: i32, @@ -359,12 +381,12 @@ pub(crate) fn read_module_create( env: &mut FunctionEnvMut, guest_ptr: u32, ) -> Option { - let bytes = read_versioned(env, guest_ptr, MODULE_CREATE_PREFIX_SIZE, 1)?; + let bytes = read_versioned(env, guest_ptr, MODULE_CREATE_SIZE, 2)?; let kind = i32_at( &bytes, - std::mem::offset_of!(Wasm32ModuleCreateOptionsV1, kind), + std::mem::offset_of!(Wasm32ModuleCreateOptionsV2, kind), )?; - let payload_offset = std::mem::offset_of!(Wasm32ModuleCreateOptionsV1, payload); + let payload_offset = std::mem::offset_of!(Wasm32ModuleCreateOptionsV2, payload); let ( source_text, source_bytecode, @@ -425,15 +447,15 @@ pub(crate) fn read_module_create( kind, wrapper: u32_at( &bytes, - std::mem::offset_of!(Wasm32ModuleCreateOptionsV1, wrapper), + std::mem::offset_of!(Wasm32ModuleCreateOptionsV2, wrapper), )?, url: u32_at( &bytes, - std::mem::offset_of!(Wasm32ModuleCreateOptionsV1, url), + std::mem::offset_of!(Wasm32ModuleCreateOptionsV2, url), )?, - context_or_undefined: u32_at( + realm_or_null: u32_at( &bytes, - std::mem::offset_of!(Wasm32ModuleCreateOptionsV1, context_or_undefined), + std::mem::offset_of!(Wasm32ModuleCreateOptionsV2, realm_or_null), )?, source_text, source_bytecode, @@ -462,6 +484,72 @@ pub(crate) fn read_module_hooks( )) } +/// `unofficial_napi_realm_options` read from guest memory. Value fields are +/// guest napi_value ids; 0 means NULL. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub(crate) struct RealmOptions { + pub sandbox_or_null: u32, + pub name: u32, + pub origin: u32, + pub host_defined_option_id: u32, + pub allow_code_gen_strings: bool, + pub allow_code_gen_wasm: bool, + pub own_microtask_queue: bool, +} + +impl Default for RealmOptions { + /// The defaults of `unofficial_napi_realm_options_init`. + fn default() -> Self { + Self { + sandbox_or_null: 0, + name: 0, + origin: 0, + host_defined_option_id: 0, + allow_code_gen_strings: true, + allow_code_gen_wasm: true, + own_microtask_queue: false, + } + } +} + +/// Reads realm options at `guest_ptr`. A null pointer means the defaults; +/// `None` means the descriptor is out of bounds or has the wrong size or +/// version. +pub(crate) fn read_realm_options( + env: &mut FunctionEnvMut, + guest_ptr: u32, +) -> Option { + if guest_ptr == 0 { + return Some(RealmOptions::default()); + } + let bytes = read_versioned(env, guest_ptr, REALM_OPTIONS_SIZE, 1)?; + let flag = |offset: usize| bytes.get(offset).map(|byte| *byte != 0); + Some(RealmOptions { + sandbox_or_null: u32_at( + &bytes, + std::mem::offset_of!(Wasm32RealmOptionsV1, sandbox_or_null), + )?, + name: u32_at(&bytes, std::mem::offset_of!(Wasm32RealmOptionsV1, name))?, + origin: u32_at(&bytes, std::mem::offset_of!(Wasm32RealmOptionsV1, origin))?, + host_defined_option_id: u32_at( + &bytes, + std::mem::offset_of!(Wasm32RealmOptionsV1, host_defined_option_id), + )?, + allow_code_gen_strings: flag(std::mem::offset_of!( + Wasm32RealmOptionsV1, + allow_code_gen_strings + ))?, + allow_code_gen_wasm: flag(std::mem::offset_of!( + Wasm32RealmOptionsV1, + allow_code_gen_wasm + ))?, + own_microtask_queue: flag(std::mem::offset_of!( + Wasm32RealmOptionsV1, + own_microtask_queue + ))?, + }) +} + pub(crate) struct EnvHooks { pub fatal: u32, pub oom: u32, @@ -472,56 +560,19 @@ pub(crate) fn read_env_hooks( env: &mut FunctionEnvMut, guest_ptr: u32, ) -> Option { - let bytes = read_versioned(env, guest_ptr, ENV_HOOKS_SIZE, 1)?; - let hook_fields = [ - ( - Wasm32EnvHooksV1::context_token_assign_callback_offset(), - 1u64 << 0, - ), - ( - Wasm32EnvHooksV1::context_token_unassign_callback_offset(), - 1u64 << 1, - ), - ( - Wasm32EnvHooksV1::enqueue_foreground_task_callback_offset(), - 1u64 << 2, - ), - (Wasm32EnvHooksV1::fatal_error_callback_offset(), 1u64 << 3), - (Wasm32EnvHooksV1::oom_error_callback_offset(), 1u64 << 4), - ]; + let bytes = read_versioned(env, guest_ptr, ENV_HOOKS_SIZE, 2)?; + let enqueue = std::mem::offset_of!(Wasm32EnvHooksV2, enqueue_foreground_task_callback); + let fatal = std::mem::offset_of!(Wasm32EnvHooksV2, fatal_error_callback); + let oom = std::mem::offset_of!(Wasm32EnvHooksV2, oom_error_callback); let mut requested = 0; - for (offset, bit) in hook_fields { + for (offset, bit) in [(enqueue, 1u64 << 2), (fatal, 1u64 << 3), (oom, 1u64 << 4)] { if u32_at(&bytes, offset)? != 0 { requested |= bit; } } Some(EnvHooks { - fatal: u32_at( - &bytes, - std::mem::offset_of!(Wasm32EnvHooksV1, fatal_error_callback), - )?, - oom: u32_at( - &bytes, - std::mem::offset_of!(Wasm32EnvHooksV1, oom_error_callback), - )?, + fatal: u32_at(&bytes, fatal)?, + oom: u32_at(&bytes, oom)?, requested, }) } - -impl Wasm32EnvHooksV1 { - const fn context_token_assign_callback_offset() -> usize { - std::mem::offset_of!(Self, context_token_assign_callback) - } - const fn context_token_unassign_callback_offset() -> usize { - std::mem::offset_of!(Self, context_token_unassign_callback) - } - const fn enqueue_foreground_task_callback_offset() -> usize { - std::mem::offset_of!(Self, enqueue_foreground_task_callback) - } - const fn fatal_error_callback_offset() -> usize { - std::mem::offset_of!(Self, fatal_error_callback) - } - const fn oom_error_callback_offset() -> usize { - std::mem::offset_of!(Self, oom_error_callback) - } -} diff --git a/src/snapi.rs b/src/snapi.rs index 32027301c8..0abb021253 100644 --- a/src/snapi.rs +++ b/src/snapi.rs @@ -281,20 +281,26 @@ unsafe extern "C" { cjs_var_in_scope: i32, result_out: *mut i32, ) -> i32; - pub fn snapi_bridge_unofficial_contextify_make_context( + // Realm ids are the value id of the realm's global (its sandbox, when it + // has one); 0 means the env's own realm. Like any value id, a realm id is + // valid only while its scope frame is open. + pub fn snapi_bridge_unofficial_create_realm( env: SnapiEnv, - sandbox_or_symbol_id: u32, + sandbox_id: u32, name_id: u32, origin_id: u32, + host_defined_option_id: u32, allow_code_gen_strings: i32, allow_code_gen_wasm: i32, own_microtask_queue: i32, - host_defined_option_id: u32, - result_out: *mut u32, + realm_out: *mut u32, + global_out: *mut u32, ) -> i32; - pub fn snapi_bridge_unofficial_contextify_run_script( + pub fn snapi_bridge_unofficial_get_realm(env: SnapiEnv, value_id: u32, realm_out: *mut u32) + -> i32; + pub fn snapi_bridge_unofficial_run_script( env: SnapiEnv, - sandbox_or_null_id: u32, + realm_id: u32, source_text_id: u32, source_bytecode_id: u32, filename_id: u32, @@ -307,14 +313,14 @@ unsafe extern "C" { host_defined_option_id: u32, result_out: *mut u32, ) -> i32; - pub fn snapi_bridge_unofficial_contextify_compile_function( + pub fn snapi_bridge_unofficial_compile_function( env: SnapiEnv, + realm_id: u32, source_text_id: u32, source_bytecode_id: u32, filename_id: u32, line_offset: i32, column_offset: i32, - parsing_context_id: u32, context_extensions_id: u32, params_id: u32, host_defined_option_id: u32, @@ -322,6 +328,7 @@ unsafe extern "C" { ) -> i32; pub fn snapi_bridge_unofficial_bytecode_open( env: SnapiEnv, + realm_id: u32, source_text_id: u32, filename_id: u32, shape: i32, @@ -348,7 +355,7 @@ unsafe extern "C" { kind: i32, wrapper_id: u32, url_id: u32, - context_id: u32, + realm_id: u32, source_text_id: u32, source_bytecode_id: u32, line_offset: i32, diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt index 8ab62ef0c3..e5ab3d2fe0 100644 --- a/tests/CMakeLists.txt +++ b/tests/CMakeLists.txt @@ -321,6 +321,9 @@ add_fixture_test(${_napi_test_prefix}_test_41_instance_data add_fixture_test(${_napi_test_prefix}_test_65_unofficial_contextify runners/test_65_unofficial_contextify.cc ) +add_fixture_test(${_napi_test_prefix}_test_66_unofficial_realm + runners/test_66_unofficial_realm.cc +) add_fixture_test(${_napi_test_prefix}_test_allocator src/napi_allocator_test.cc diff --git a/tests/programs/manifest.json b/tests/programs/manifest.json index 378288e64a..1ae04a7f0c 100644 --- a/tests/programs/manifest.json +++ b/tests/programs/manifest.json @@ -179,6 +179,11 @@ "name": "test_high_guest_pointers", "description": "Guest pointers >= 2 GiB are read from and written to, not rejected or skipped", "expected_stdout": "TEST_HIGH_GUEST_POINTERS_OK=1\n" + }, + { + "name": "test_realm", + "description": "Realm envs: own globals, shared values, callbacks in their realm, get_realm, sandbox realms, modules and vm calls through realm envs, release with live realms", + "expected_stdout": "realm has its own global\nvalues cross envs: x=7\ncallback saw the realm env and the realm global\nget_realm finds both envs\nsandbox realm: input=5 output=10\nrealm module through the parent env: tag=21\nvm results: run=4 function=30 module=5\nreleased an env with live realm envs\nTEST_REALM_OK=1\n" } ] } diff --git a/tests/programs/run_script_test.c b/tests/programs/run_script_test.c index db0d3c5004..f53cd5304e 100644 --- a/tests/programs/run_script_test.c +++ b/tests/programs/run_script_test.c @@ -140,7 +140,6 @@ static int CreateSourceModule(napi_env env, const char* url, const char* text, options.kind = unofficial_napi_module_source_text; options.wrapper = wrapper; options.url = url_value; - options.context_or_undefined = undefined; options.payload.source_text.source = &source; options.payload.source_text.host_defined_option_id = undefined; unofficial_napi_module_create_result result = {0}; @@ -346,10 +345,10 @@ int main(void) { CHECK_OR_FAIL(marker == 41, "the second environment mutated the first global"); NAPI_CALL(env, unofficial_napi_release_env(env2_scope, NULL)); - // Every code-generation path must select its execution scope explicitly. - // In particular, vm compile-function and module compilation must honor the - // supplied context rather than falling back to the active environment or - // the Wasmer worker's control-plane global. + // Every code-generation call runs in its env's realm. In particular, vm + // scripts, compiled functions and modules made through a realm env must + // not fall back to the parent environment or the Wasmer worker's + // control-plane global. napi_value undefined_value; NAPI_CALL(env, napi_get_undefined(env, &undefined_value)); napi_value sandbox; @@ -358,17 +357,13 @@ int main(void) { NAPI_CALL(env, napi_create_int32(env, 73, &context_marker)); NAPI_CALL(env, napi_set_named_property( env, sandbox, "__napi_context_marker", context_marker)); - napi_value context; - NAPI_CALL(env, unofficial_napi_contextify_make_context( - env, - sandbox, - undefined_value, - undefined_value, - true, - true, - true, - undefined_value, - &context)); + unofficial_napi_realm_options realm_options; + unofficial_napi_realm_options_init(&realm_options); + realm_options.sandbox_or_null = sandbox; + realm_options.own_microtask_queue = true; + napi_env context_env = NULL; + NAPI_CALL(env, unofficial_napi_create_realm( + env, &realm_options, &context_env, NULL)); napi_value context_source_text; NAPI_CALL(env, napi_create_string_utf8( @@ -379,9 +374,8 @@ int main(void) { const unofficial_napi_js_source context_source = unofficial_napi_js_source_from_text(context_source_text); napi_value context_result; - NAPI_CALL(env, unofficial_napi_contextify_run_script( - env, - context, + NAPI_CALL(context_env, unofficial_napi_run_script( + context_env, &context_source, undefined_value, 0, @@ -394,7 +388,7 @@ int main(void) { &context_result)); NAPI_CALL(env, napi_get_value_int32(env, context_result, &marker)); CHECK_OR_FAIL(marker == 73, - "contextify_run_script escaped its explicit context"); + "run_script escaped its env's realm"); napi_value parameters; napi_value context_extensions; @@ -421,13 +415,12 @@ int main(void) { const unofficial_napi_js_source function_source = unofficial_napi_js_source_from_text(function_source_text); napi_value compiled; - NAPI_CALL(env, unofficial_napi_contextify_compile_function( - env, + NAPI_CALL(context_env, unofficial_napi_compile_function( + context_env, &function_source, undefined_value, 0, 0, - context, context_extensions, parameters, undefined_value, @@ -447,7 +440,7 @@ int main(void) { &function_result)); NAPI_CALL(env, napi_get_value_int32(env, function_result, &marker)); CHECK_OR_FAIL(marker == 147, - "compile_function escaped its parsing context"); + "compile_function escaped its env's realm"); napi_value module_wrapper; napi_value module_url; @@ -472,12 +465,11 @@ int main(void) { module_options.kind = unofficial_napi_module_source_text; module_options.wrapper = module_wrapper; module_options.url = module_url; - module_options.context_or_undefined = context; module_options.payload.source_text.source = &module_source; module_options.payload.source_text.host_defined_option_id = undefined_value; unofficial_napi_module_create_result module_create_result = {0}; - NAPI_CALL(env, unofficial_napi_module_wrap_create( - env, &module_options, &module_create_result)); + NAPI_CALL(context_env, unofficial_napi_module_wrap_create( + context_env, &module_options, &module_create_result)); unofficial_napi_module module = module_create_result.module; CHECK_OR_FAIL(module != NULL, "module compilation did not return a handle"); @@ -488,8 +480,8 @@ int main(void) { int32_t module_status = -1; napi_value module_error = NULL; bool module_has_async_graph = false; - NAPI_CALL(env, unofficial_napi_module_wrap_get_state( - env, + NAPI_CALL(context_env, unofficial_napi_module_wrap_get_state( + context_env, module, &module_status, &module_error, @@ -500,13 +492,13 @@ int main(void) { "module snapshot did not return an undefined error value"); CHECK_OR_FAIL(!module_has_async_graph, "uninstantiated module reported an async graph"); - NAPI_CALL(env, unofficial_napi_module_wrap_link( - env, module, 0, NULL)); - NAPI_CALL(env, unofficial_napi_module_wrap_instantiate(env, module)); + NAPI_CALL(context_env, unofficial_napi_module_wrap_link( + context_env, module, 0, NULL)); + NAPI_CALL(context_env, unofficial_napi_module_wrap_instantiate(context_env, module)); module_status = -1; module_has_async_graph = true; - NAPI_CALL(env, unofficial_napi_module_wrap_get_state( - env, + NAPI_CALL(context_env, unofficial_napi_module_wrap_get_state( + context_env, module, &module_status, NULL, @@ -516,22 +508,22 @@ int main(void) { CHECK_OR_FAIL(!module_has_async_graph, "synchronous module reported an async graph"); napi_value module_result; - NAPI_CALL(env, unofficial_napi_module_wrap_evaluate_sync( - env, + NAPI_CALL(context_env, unofficial_napi_module_wrap_evaluate_sync( + context_env, module, module_url, module_url, &module_result)); napi_value module_namespace; napi_value module_observed; - NAPI_CALL(env, unofficial_napi_module_wrap_get_namespace( - env, module, &module_namespace)); + NAPI_CALL(context_env, unofficial_napi_module_wrap_get_namespace( + context_env, module, &module_namespace)); NAPI_CALL(env, napi_get_named_property( env, module_namespace, "observed", &module_observed)); NAPI_CALL(env, napi_get_value_int32(env, module_observed, &marker)); CHECK_OR_FAIL(marker == 73, - "module evaluation escaped its explicit context"); - NAPI_CALL(env, unofficial_napi_module_wrap_destroy(env, module)); + "module evaluation escaped its env's realm"); + NAPI_CALL(context_env, unofficial_napi_module_wrap_destroy(context_env, module)); // Creating the CommonJS facade evaluates the original module internally, // so a synthetic module's guest evaluation callback must be able to re-enter @@ -561,7 +553,6 @@ int main(void) { synthetic_options.kind = unofficial_napi_module_synthetic; synthetic_options.wrapper = module_wrapper; synthetic_options.url = module_url; - synthetic_options.context_or_undefined = undefined_value; synthetic_options.payload.synthetic.export_names = facade_exports; synthetic_options.payload.synthetic.synthetic_evaluation_steps = facade_evaluation_steps; diff --git a/tests/programs/test_realm.c b/tests/programs/test_realm.c new file mode 100644 index 0000000000..3893d733e0 --- /dev/null +++ b/tests/programs/test_realm.c @@ -0,0 +1,278 @@ +#include +#include +#include +#include + +#include "napi_test_helpers.h" +#include "node_api.h" +#include "unofficial_napi.h" + +typedef struct { + napi_value expected_global; + napi_env env; + bool saw_expected_global; + int calls; +} callback_record; + +// Values made inside a callback die when it returns, so the global is +// compared here. +static napi_value NAPI_CDECL RecordCallback(napi_env env, napi_callback_info info) { + void* data = NULL; + if (napi_get_cb_info(env, info, NULL, NULL, NULL, &data) != napi_ok || data == NULL) { + return NULL; + } + callback_record* record = (callback_record*)data; + record->env = env; + record->calls++; + napi_value global = NULL; + if (napi_get_global(env, &global) != napi_ok || + napi_strict_equals(env, global, record->expected_global, + &record->saw_expected_global) != napi_ok) { + return NULL; + } + napi_value object = NULL; + if (napi_create_object(env, &object) != napi_ok) return NULL; + return object; +} + +static napi_status RunScript(napi_env env, const char* source, napi_value* result) { + napi_value script = NULL; + napi_status status = napi_create_string_utf8(env, source, NAPI_AUTO_LENGTH, &script); + if (status != napi_ok) return status; + return napi_run_script(env, script, result); +} + +static napi_status RunInt32(napi_env env, const char* source, int32_t* out) { + napi_value result = NULL; + napi_status status = RunScript(env, source, &result); + if (status != napi_ok) return status; + return napi_get_value_int32(env, result, out); +} + +static bool StrictEquals(napi_env env, napi_value a, napi_value b) { + bool same = false; + return napi_strict_equals(env, a, b, &same) == napi_ok && same; +} + +static napi_value Str(napi_env env, const char* value) { + napi_value out = NULL; + if (napi_create_string_utf8(env, value, NAPI_AUTO_LENGTH, &out) != napi_ok) return NULL; + return out; +} + +static napi_status ReadInt32Export(napi_env env, + unofficial_napi_module module, + const char* name, + int32_t* out) { + napi_value ns = NULL; + napi_value value = NULL; + napi_status status = unofficial_napi_module_wrap_get_namespace(env, module, &ns); + if (status != napi_ok) return status; + status = napi_get_named_property(env, ns, name, &value); + if (status != napi_ok) return status; + return napi_get_value_int32(env, value, out); +} + +// Links, instantiates and evaluates a module with no imports. +static napi_status EvaluateModule(napi_env env, unofficial_napi_module module) { + napi_status status = unofficial_napi_module_wrap_link(env, module, 0, NULL); + if (status != napi_ok) return status; + status = unofficial_napi_module_wrap_instantiate(env, module); + if (status != napi_ok) return status; + napi_value result = NULL; + return unofficial_napi_module_wrap_evaluate(env, module, -1, false, &result); +} + +int main(void) { + napi_env env = napi_wasm_init_env(); + CHECK_OR_FAIL(env != NULL, "napi_wasm_init_env returned NULL"); + + // A realm has its own global. + napi_env realm = NULL; + napi_value realm_global = NULL; + NAPI_CALL(env, unofficial_napi_create_realm(env, NULL, &realm, &realm_global)); + CHECK_OR_FAIL(realm != NULL && realm != env, "create_realm did not return a new env"); + napi_value env_global = NULL; + napi_value realm_own_global = NULL; + NAPI_CALL(env, napi_get_global(env, &env_global)); + NAPI_CALL(realm, napi_get_global(realm, &realm_own_global)); + CHECK_OR_FAIL(StrictEquals(env, realm_own_global, realm_global), + "the realm env's global is not the one create_realm returned"); + CHECK_OR_FAIL(!StrictEquals(env, env_global, realm_global), + "the realm shares its parent's global"); + printf("realm has its own global\n"); + + // Values made through one env are usable through the other. + napi_value shared = NULL; + NAPI_CALL(env, napi_create_object(env, &shared)); + NAPI_CALL(realm, napi_set_named_property(realm, realm_global, "shared", shared)); + int32_t x = 0; + NAPI_CALL(realm, RunInt32(realm, "shared.x = 7", &x)); + napi_value x_value = NULL; + NAPI_CALL(env, napi_get_named_property(env, shared, "x", &x_value)); + NAPI_CALL(env, napi_get_value_int32(env, x_value, &x)); + CHECK_OR_FAIL(x == 7, "a value did not cross envs"); + printf("values cross envs: x=%d\n", x); + + // A native function made through the realm env runs in that realm, also + // when the parent's script calls it. + callback_record record = {realm_global, NULL, false, 0}; + napi_value fn = NULL; + NAPI_CALL(realm, napi_create_function( + realm, "probe", NAPI_AUTO_LENGTH, RecordCallback, &record, &fn)); + NAPI_CALL(env, napi_set_named_property(env, env_global, "probe", fn)); + napi_value probe_result = NULL; + NAPI_CALL(env, RunScript(env, "probe()", &probe_result)); + CHECK_OR_FAIL(record.calls == 1, "the callback did not run"); + CHECK_OR_FAIL(record.env == realm, "the callback did not get the realm env"); + CHECK_OR_FAIL(record.saw_expected_global, "the callback did not see the realm's global"); + printf("callback saw the realm env and the realm global\n"); + + // get_realm maps globals back to their envs. + napi_env found = NULL; + NAPI_CALL(env, unofficial_napi_get_realm(env, realm_global, &found)); + CHECK_OR_FAIL(found == realm, "get_realm(realm global) did not return the realm env"); + found = NULL; + NAPI_CALL(realm, unofficial_napi_get_realm(realm, env_global, &found)); + CHECK_OR_FAIL(found == env, "get_realm(parent global) did not return the parent env"); + printf("get_realm finds both envs\n"); + + // A sandbox realm reads and writes the sandbox. + napi_value sandbox = NULL; + napi_value five = NULL; + NAPI_CALL(env, napi_create_object(env, &sandbox)); + NAPI_CALL(env, napi_create_int32(env, 5, &five)); + NAPI_CALL(env, napi_set_named_property(env, sandbox, "input", five)); + unofficial_napi_realm_options options; + unofficial_napi_realm_options_init(&options); + options.sandbox_or_null = sandbox; + napi_env sandbox_realm = NULL; + napi_value sandbox_global = NULL; + NAPI_CALL(env, unofficial_napi_create_realm(env, &options, &sandbox_realm, &sandbox_global)); + CHECK_OR_FAIL(StrictEquals(env, sandbox_global, sandbox), + "create_realm did not return the sandbox as the global"); + napi_value source_text = NULL; + NAPI_CALL(env, napi_create_string_utf8( + env, "output = input * 2; input", NAPI_AUTO_LENGTH, &source_text)); + napi_value filename = NULL; + NAPI_CALL(env, napi_create_string_utf8(env, "sandbox.js", NAPI_AUTO_LENGTH, &filename)); + const unofficial_napi_js_source source = unofficial_napi_js_source_from_text(source_text); + napi_value run_result = NULL; + NAPI_CALL(sandbox_realm, unofficial_napi_run_script(sandbox_realm, + &source, + filename, + 0, + 0, + -1, + true, + false, + false, + NULL, + &run_result)); + int32_t input = 0; + NAPI_CALL(env, napi_get_value_int32(env, run_result, &input)); + napi_value output_value = NULL; + int32_t output = 0; + NAPI_CALL(env, napi_get_named_property(env, sandbox, "output", &output_value)); + NAPI_CALL(env, napi_get_value_int32(env, output_value, &output)); + CHECK_OR_FAIL(input == 5 && output == 10, "the sandbox realm did not use the sandbox"); + printf("sandbox realm: input=%d output=%d\n", input, output); + + // A module made through a realm env evaluates in that realm, and its + // handle works through the parent env too. + int32_t tag = 0; + NAPI_CALL(realm, RunInt32(realm, "globalThis.tag = 21", &tag)); + napi_value undefined = NULL; + NAPI_CALL(env, napi_get_undefined(env, &undefined)); + napi_value wrapper = NULL; + NAPI_CALL(env, napi_create_object(env, &wrapper)); + const unofficial_napi_js_source module_source = + unofficial_napi_js_source_from_text(Str(env, "export const tag = globalThis.tag;")); + unofficial_napi_module_create_options module_options = {0}; + module_options.size = sizeof(module_options); + module_options.version = UNOFFICIAL_NAPI_MODULE_CREATE_OPTIONS_VERSION; + module_options.kind = unofficial_napi_module_source_text; + module_options.wrapper = wrapper; + module_options.url = Str(env, "file:///realm.mjs"); + module_options.payload.source_text.source = &module_source; + module_options.payload.source_text.host_defined_option_id = undefined; + unofficial_napi_module_create_result created = {0}; + NAPI_CALL(realm, unofficial_napi_module_wrap_create(realm, &module_options, &created)); + NAPI_CALL(env, EvaluateModule(env, created.module)); + tag = 0; + NAPI_CALL(env, ReadInt32Export(env, created.module, "tag", &tag)); + NAPI_CALL(env, unofficial_napi_module_wrap_destroy(env, created.module)); + CHECK_OR_FAIL(tag == 21, "the module did not evaluate in the realm"); + printf("realm module through the parent env: tag=%d\n", tag); + + // A script, a compiled function and a module made through a sandbox + // realm's env all see the sandbox (x = 3). + napi_value context_sandbox = NULL; + napi_value three = NULL; + NAPI_CALL(env, napi_create_object(env, &context_sandbox)); + NAPI_CALL(env, napi_create_int32(env, 3, &three)); + NAPI_CALL(env, napi_set_named_property(env, context_sandbox, "x", three)); + unofficial_napi_realm_options context_options; + unofficial_napi_realm_options_init(&context_options); + context_options.sandbox_or_null = context_sandbox; + napi_env context_realm = NULL; + NAPI_CALL(env, unofficial_napi_create_realm(env, &context_options, &context_realm, NULL)); + const unofficial_napi_js_source run_source = + unofficial_napi_js_source_from_text(Str(env, "x + 1")); + const unofficial_napi_js_source function_source = + unofficial_napi_js_source_from_text(Str(env, "return x * 10;")); + const unofficial_napi_js_source x_module_source = + unofficial_napi_js_source_from_text(Str(env, "export const y = x + 2;")); + napi_value value = NULL; + int32_t ran = 0; + NAPI_CALL(context_realm, unofficial_napi_run_script(context_realm, &run_source, Str(env, "a.js"), + 0, 0, -1, true, false, false, NULL, + &value)); + NAPI_CALL(env, napi_get_value_int32(env, value, &ran)); + napi_value compiled = NULL; + int32_t called = 0; + NAPI_CALL(context_realm, unofficial_napi_compile_function(context_realm, &function_source, + Str(env, "f.js"), 0, 0, undefined, + undefined, undefined, &compiled)); + NAPI_CALL(env, napi_get_named_property(env, compiled, "function", &fn)); + NAPI_CALL(env, napi_call_function(env, undefined, fn, 0, NULL, &value)); + NAPI_CALL(env, napi_get_value_int32(env, value, &called)); + NAPI_CALL(env, napi_create_object(env, &wrapper)); + module_options.wrapper = wrapper; + module_options.url = Str(env, "file:///x.mjs"); + module_options.payload.source_text.source = &x_module_source; + NAPI_CALL(context_realm, unofficial_napi_module_wrap_create(context_realm, &module_options, + &created)); + int32_t exported = 0; + NAPI_CALL(env, EvaluateModule(env, created.module)); + NAPI_CALL(env, ReadInt32Export(env, created.module, "y", &exported)); + NAPI_CALL(env, unofficial_napi_module_wrap_destroy(env, created.module)); + CHECK_OR_FAIL(ran == 4 && called == 30 && exported == 5, + "the realm env did not run in its sandbox's realm"); + printf("vm results: run=%d function=%d module=%d\n", ran, called, exported); + + // Releasing an env with live realm envs, nested ones included, releases + // them with it. + napi_env env2 = NULL; + unofficial_napi_env_owner env2_scope = NULL; + NAPI_CALL(env, unofficial_napi_create_env(8, NULL, &env2, &env2_scope)); + napi_env env2_realm = NULL; + napi_env env2_nested = NULL; + NAPI_CALL(env2, unofficial_napi_create_realm(env2, NULL, &env2_realm, NULL)); + NAPI_CALL(env2_realm, unofficial_napi_create_realm(env2_realm, NULL, &env2_nested, NULL)); + int32_t nested_value = 0; + NAPI_CALL(env2_nested, RunInt32(env2_nested, "globalThis.v = 12", &nested_value)); + CHECK_OR_FAIL(nested_value == 12, "the nested realm did not run"); + NAPI_CALL(env, unofficial_napi_release_env(env2_scope, NULL)); +#ifdef __wasm__ + // Guest env ids of released realm envs no longer resolve. (Natively the + // handles are freed pointers and must not be used.) + napi_value stale_global = NULL; + CHECK_OR_FAIL(napi_get_global(env2_realm, &stale_global) != napi_ok && + napi_get_global(env2_nested, &stale_global) != napi_ok, + "a released realm env still resolves"); +#endif + printf("released an env with live realm envs\n"); + + return PrintSuccess("TEST_REALM"); +} diff --git a/tests/runners/test_21_general.cc b/tests/runners/test_21_general.cc index 6db26c6d1b..236c394b13 100644 --- a/tests/runners/test_21_general.cc +++ b/tests/runners/test_21_general.cc @@ -161,6 +161,9 @@ TEST_F(Test21General, EnvironmentHooksAttachAtomicallyOnce) { invalid.version += 1; uint64_t accepted_hooks = 0; EXPECT_EQ(unofficial_napi_attach_env(env, &invalid, &accepted_hooks), napi_invalid_arg); + // Version 1 had the context-token callbacks, which version 2 removed. + invalid.version = 1; + EXPECT_EQ(unofficial_napi_attach_env(env, &invalid, &accepted_hooks), napi_invalid_arg); ASSERT_EQ(unofficial_napi_attach_env(env, &hooks, &accepted_hooks), napi_ok); EXPECT_EQ(accepted_hooks, 0); EXPECT_EQ(unofficial_napi_attach_env(env, &hooks, &accepted_hooks), napi_invalid_arg); diff --git a/tests/runners/test_65_unofficial_contextify.cc b/tests/runners/test_65_unofficial_contextify.cc index ef7e99cebd..f2b545ba04 100644 --- a/tests/runners/test_65_unofficial_contextify.cc +++ b/tests/runners/test_65_unofficial_contextify.cc @@ -20,6 +20,21 @@ napi_value Sym(napi_env env, const char* value) { return out; } +// Creates a realm over `sandbox` with the options vm.createContext passes. +napi_status CreateSandboxRealm(napi_env env, + napi_value sandbox, + bool own_microtask_queue, + napi_env* realm_out) { + unofficial_napi_realm_options options; + unofficial_napi_realm_options_init(&options); + options.sandbox_or_null = sandbox; + options.name = Str(env, "ctx"); + options.origin = Str(env, "test://origin"); + options.host_defined_option_id = Sym(env, "hdo"); + options.own_microtask_queue = own_microtask_queue; + return unofficial_napi_create_realm(env, &options, realm_out, nullptr); +} + #if defined(NAPI_TEST_ENGINE_V8) constexpr char kPreparedStack[] = "Error: sentinel\n" @@ -119,33 +134,23 @@ TEST_F(Test65UnofficialContextify, NativeFunctionCalledFromContextKeepsItsRealm) ASSERT_EQ(napi_create_object(s.env, &sandbox), napi_ok); ASSERT_EQ(napi_set_named_property(s.env, sandbox, "probe", fn), napi_ok); - napi_value contextified = nullptr; - ASSERT_EQ(unofficial_napi_contextify_make_context(s.env, - sandbox, - Str(s.env, "ctx"), - Str(s.env, "test://origin"), - true, - true, - false, - Sym(s.env, "hdo"), - &contextified), - napi_ok); + napi_env realm = nullptr; + ASSERT_EQ(CreateSandboxRealm(s.env, sandbox, false, &realm), napi_ok); napi_value eval_result = nullptr; const unofficial_napi_js_source source = unofficial_napi_js_source_from_text( Str(s.env, "Object.getPrototypeOf(probe()) === Object.prototype")); - ASSERT_EQ(unofficial_napi_contextify_run_script(s.env, - sandbox, - &source, - Str(s.env, "probe.js"), - 0, - 0, - -1, - true, - false, - false, - Sym(s.env, "hdo"), - &eval_result), + ASSERT_EQ(unofficial_napi_run_script(realm, + &source, + Str(s.env, "probe.js"), + 0, + 0, + -1, + true, + false, + false, + Sym(s.env, "hdo"), + &eval_result), napi_ok); EXPECT_TRUE(probe.called); @@ -160,40 +165,30 @@ TEST_F(Test65UnofficialContextify, NativeFunctionCalledFromContextKeepsItsRealm) ASSERT_EQ(napi_delete_reference(s.env, probe.main_object_prototype), napi_ok); } -TEST_F(Test65UnofficialContextify, MakeRunRoundTrip) { +TEST_F(Test65UnofficialContextify, CreateRealmRunRoundTrip) { EnvScope s(runtime_.get()); napi_value sandbox = nullptr; ASSERT_EQ(napi_create_object(s.env, &sandbox), napi_ok); - napi_value result = nullptr; - ASSERT_EQ(unofficial_napi_contextify_make_context(s.env, - sandbox, - Str(s.env, "ctx"), - Str(s.env, "test://origin"), - true, - true, - true, - Sym(s.env, "hdo"), - &result), - napi_ok); - ASSERT_NE(result, nullptr); + napi_env realm = nullptr; + ASSERT_EQ(CreateSandboxRealm(s.env, sandbox, true, &realm), napi_ok); + ASSERT_NE(realm, nullptr); napi_value eval_result = nullptr; const unofficial_napi_js_source run_source = unofficial_napi_js_source_from_text(Str(s.env, "globalThis.answer = 42; answer")); - ASSERT_EQ(unofficial_napi_contextify_run_script(s.env, - sandbox, - &run_source, - Str(s.env, "ctx.js"), - 0, - 0, - -1, - true, - false, - false, - Sym(s.env, "hdo"), - &eval_result), + ASSERT_EQ(unofficial_napi_run_script(realm, + &run_source, + Str(s.env, "ctx.js"), + 0, + 0, + -1, + true, + false, + false, + Sym(s.env, "hdo"), + &eval_result), napi_ok); ASSERT_NE(eval_result, nullptr); @@ -209,7 +204,7 @@ TEST_F(Test65UnofficialContextify, MakeRunRoundTrip) { } #if defined(NAPI_TEST_ENGINE_V8) -TEST_F(Test65UnofficialContextify, MakeContextPreservesThrownProxyException) { +TEST_F(Test65UnofficialContextify, CreateRealmPreservesThrownProxyException) { EnvScope s(runtime_.get()); napi_value source = Str( @@ -225,18 +220,9 @@ TEST_F(Test65UnofficialContextify, MakeContextPreservesThrownProxyException) { ASSERT_EQ(napi_get_named_property(s.env, fixture, "sentinel", &sentinel), napi_ok); ASSERT_EQ(napi_get_named_property(s.env, fixture, "sandbox", &sandbox), napi_ok); - napi_value result = nullptr; - EXPECT_EQ(unofficial_napi_contextify_make_context(s.env, - sandbox, - Str(s.env, "ctx"), - Str(s.env, "test://origin"), - true, - true, - false, - Sym(s.env, "hdo"), - &result), - napi_pending_exception); - EXPECT_EQ(result, nullptr); + napi_env realm = nullptr; + EXPECT_EQ(CreateSandboxRealm(s.env, sandbox, false, &realm), napi_pending_exception); + EXPECT_EQ(realm, nullptr); bool pending = false; ASSERT_EQ(napi_is_exception_pending(s.env, &pending), napi_ok); @@ -255,18 +241,9 @@ TEST_F(Test65UnofficialContextify, SandboxGlobalThisIsNotEnumerableForDeepFreeze napi_value sandbox = nullptr; ASSERT_EQ(napi_create_object(s.env, &sandbox), napi_ok); - napi_value result = nullptr; - ASSERT_EQ(unofficial_napi_contextify_make_context(s.env, - sandbox, - Str(s.env, "ctx"), - Str(s.env, "test://origin"), - true, - true, - true, - Sym(s.env, "hdo"), - &result), - napi_ok); - ASSERT_NE(result, nullptr); + napi_env realm = nullptr; + ASSERT_EQ(CreateSandboxRealm(s.env, sandbox, true, &realm), napi_ok); + ASSERT_NE(realm, nullptr); #if defined(NAPI_TEST_ENGINE_QUICKJS) // QuickJS keeps its context marker on the sandbox rather than copying it @@ -332,18 +309,17 @@ globalThis.__RSC_MANIFEST["/x"].ok; )JS"; const unofficial_napi_js_source freeze_source = unofficial_napi_js_source_from_text( Str(s.env, freeze_script.c_str())); - ASSERT_EQ(unofficial_napi_contextify_run_script(s.env, - sandbox, - &freeze_source, - Str(s.env, "deep_freeze.js"), - 0, - 0, - -1, - true, - false, - false, - Sym(s.env, "hdo"), - &eval_result), + ASSERT_EQ(unofficial_napi_run_script(realm, + &freeze_source, + Str(s.env, "deep_freeze.js"), + 0, + 0, + -1, + true, + false, + false, + Sym(s.env, "hdo"), + &eval_result), napi_ok); ASSERT_NE(eval_result, nullptr); @@ -369,16 +345,15 @@ TEST_F(Test65UnofficialContextify, CompileFunctionAndCachedData) { napi_value out = nullptr; const unofficial_napi_js_source fn_source = unofficial_napi_js_source_from_text(Str(s.env, "return a + b;")); - ASSERT_EQ(unofficial_napi_contextify_compile_function(s.env, - &fn_source, - Str(s.env, "fn.js"), - 0, - 0, - undef, - context_extensions, - params, - Sym(s.env, "hdo"), - &out), + ASSERT_EQ(unofficial_napi_compile_function(s.env, + &fn_source, + Str(s.env, "fn.js"), + 0, + 0, + context_extensions, + params, + Sym(s.env, "hdo"), + &out), napi_ok); ASSERT_NE(out, nullptr); @@ -479,7 +454,6 @@ TEST_F(Test65UnofficialContextify, ModuleStateIsOneAtomicSnapshot) { create_options.kind = unofficial_napi_module_source_text; create_options.wrapper = wrapper; create_options.url = Str(s.env, "state.mjs"); - create_options.context_or_undefined = undefined; create_options.payload.source_text.source = &source; create_options.payload.source_text.host_defined_option_id = undefined; unofficial_napi_module_create_result create_result{}; @@ -489,6 +463,10 @@ TEST_F(Test65UnofficialContextify, ModuleStateIsOneAtomicSnapshot) { EXPECT_EQ(unofficial_napi_module_wrap_create(s.env, &invalid_options, &create_result), napi_invalid_arg); invalid_options = create_options; + invalid_options.version = 1; + EXPECT_EQ(unofficial_napi_module_wrap_create(s.env, &invalid_options, &create_result), + napi_invalid_arg); + invalid_options = create_options; invalid_options.version++; EXPECT_EQ(unofficial_napi_module_wrap_create(s.env, &invalid_options, &create_result), napi_invalid_arg); @@ -562,7 +540,6 @@ TEST_F(Test65UnofficialContextify, SyncModuleErrorDoesNotLeaveUnhandledRejection options.kind = unofficial_napi_module_source_text; options.wrapper = wrapper; options.url = Str(s.env, "throwing.mjs"); - options.context_or_undefined = undefined; options.payload.source_text.source = &source; options.payload.source_text.host_defined_option_id = undefined; unofficial_napi_module_create_result created{}; @@ -656,16 +633,15 @@ TEST_F(Test65UnofficialContextify, const unofficial_napi_js_source source = unofficial_napi_js_source_from_bytecode(bytecode); napi_value compiled = nullptr; - EXPECT_EQ(unofficial_napi_contextify_compile_function(s.env, - &source, - Str(s.env, "host-id.js"), - 0, - 0, - undefined, - undefined, - undefined, - host_id, - &compiled), + EXPECT_EQ(unofficial_napi_compile_function(s.env, + &source, + Str(s.env, "host-id.js"), + 0, + 0, + undefined, + undefined, + host_id, + &compiled), napi_ok); EXPECT_NE(compiled, nullptr); @@ -745,16 +721,15 @@ globalThis.Function = function Function() { napi_value out = nullptr; const unofficial_napi_js_source fn_source = unofficial_napi_js_source_from_text(Str(s.env, "return value + 1;")); - ASSERT_EQ(unofficial_napi_contextify_compile_function(s.env, - &fn_source, - Str(s.env, "no-global-function.js"), - 0, - 0, - undef, - undef, - params, - undef, - &out), + ASSERT_EQ(unofficial_napi_compile_function(s.env, + &fn_source, + Str(s.env, "no-global-function.js"), + 0, + 0, + undef, + params, + undef, + &out), napi_ok); ASSERT_NE(out, nullptr); @@ -783,16 +758,15 @@ TEST_F(Test65UnofficialContextify, CompileFunctionAcceptsHashbangBody) { napi_value out = nullptr; const unofficial_napi_js_source hashbang_source = unofficial_napi_js_source_from_text( Str(s.env, "#!/usr/bin/env node\nreturn 42;")); - ASSERT_EQ(unofficial_napi_contextify_compile_function(s.env, - &hashbang_source, - Str(s.env, ""), - 0, - 0, - undef, - undef, - undef, - undef, - &out), + ASSERT_EQ(unofficial_napi_compile_function(s.env, + &hashbang_source, + Str(s.env, ""), + 0, + 0, + undef, + undef, + undef, + &out), napi_ok); ASSERT_NE(out, nullptr); @@ -819,16 +793,15 @@ TEST_F(Test65UnofficialContextify, CompileFunctionRejectsBomBeforeHashbang) { napi_value out = nullptr; const unofficial_napi_js_source bom_source = unofficial_napi_js_source_from_text( Str(s.env, "\xEF\xBB\xBF#!/usr/bin/env node\nreturn 42;")); - EXPECT_EQ(unofficial_napi_contextify_compile_function(s.env, - &bom_source, - Str(s.env, "bom_hashbang.js"), - 0, - 0, - undef, - undef, - undef, - undef, - &out), + EXPECT_EQ(unofficial_napi_compile_function(s.env, + &bom_source, + Str(s.env, "bom_hashbang.js"), + 0, + 0, + undef, + undef, + undef, + &out), napi_pending_exception); bool pending = false; @@ -892,16 +865,15 @@ TEST_F(Test65UnofficialContextify, CjsCompileAndSyntaxDetection) { napi_value out = nullptr; const unofficial_napi_js_source cjs_source = unofficial_napi_js_source_from_text(Str(s.env, "module.exports = 1;")); - ASSERT_EQ(unofficial_napi_contextify_compile_function(s.env, - &cjs_source, - Str(s.env, "cjs.js"), - 0, - 0, - undef, - undef, - params, - undef, - &out), + ASSERT_EQ(unofficial_napi_compile_function(s.env, + &cjs_source, + Str(s.env, "cjs.js"), + 0, + 0, + undef, + params, + undef, + &out), napi_ok); ASSERT_NE(out, nullptr); napi_value fn = nullptr; From eed1fab744a4fb05306aad8f703304464609620c Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Sun, 25 Oct 2026 09:59:07 +0100 Subject: [PATCH 009/150] Test realm handles and realm collection - test_66 (new): creating and finding realms, code, functions, modules and bytecode in a realm, native functions staying in the env's realm, the env's hooks firing for realm code, and realms collected with their global (from #109's tests). - test_65 makes its vm contexts with create_realm; test_21 and test_65 reject version 1 hooks and module options. - test_realm (new) and run_script_test cover the same through the guest ABI. Co-Authored-By: Claude Opus 5.5 --- tests/programs/manifest.json | 4 +- tests/programs/run_script_test.c | 56 +- tests/programs/test_realm.c | 256 ++++---- .../runners/test_65_unofficial_contextify.cc | 25 +- tests/runners/test_66_unofficial_realm.cc | 602 ++++++++++++++++++ 5 files changed, 783 insertions(+), 160 deletions(-) create mode 100644 tests/runners/test_66_unofficial_realm.cc diff --git a/tests/programs/manifest.json b/tests/programs/manifest.json index 1ae04a7f0c..1597fa785c 100644 --- a/tests/programs/manifest.json +++ b/tests/programs/manifest.json @@ -182,8 +182,8 @@ }, { "name": "test_realm", - "description": "Realm envs: own globals, shared values, callbacks in their realm, get_realm, sandbox realms, modules and vm calls through realm envs, release with live realms", - "expected_stdout": "realm has its own global\nvalues cross envs: x=7\ncallback saw the realm env and the realm global\nget_realm finds both envs\nsandbox realm: input=5 output=10\nrealm module through the parent env: tag=21\nvm results: run=4 function=30 module=5\nreleased an env with live realm envs\nTEST_REALM_OK=1\n" + "description": "Realms: own globals, shared values, native functions in the env's realm, get_realm, sandbox realms, scripts, functions, modules and bytecode in a realm, collection of dropped realms, release with live realms", + "expected_stdout": "realm has its own global\nvalues cross realms: x=7\nnative function stays in the env's realm\nget_realm finds the realm by its global\nsandbox realm: input=5 output=10\nvm results: run=4 function=30 module=5 bytecode=6\ncollected 6 of 6 dropped realms\nreleased an env with live realms\nTEST_REALM_OK=1\n" } ] } diff --git a/tests/programs/run_script_test.c b/tests/programs/run_script_test.c index f53cd5304e..368f2bd7e4 100644 --- a/tests/programs/run_script_test.c +++ b/tests/programs/run_script_test.c @@ -345,10 +345,9 @@ int main(void) { CHECK_OR_FAIL(marker == 41, "the second environment mutated the first global"); NAPI_CALL(env, unofficial_napi_release_env(env2_scope, NULL)); - // Every code-generation call runs in its env's realm. In particular, vm - // scripts, compiled functions and modules made through a realm env must - // not fall back to the parent environment or the Wasmer worker's - // control-plane global. + // Code run, compiled or made as a module for a realm runs there. In + // particular it must not fall back to the env's own global or the Wasmer + // worker's control-plane global. napi_value undefined_value; NAPI_CALL(env, napi_get_undefined(env, &undefined_value)); napi_value sandbox; @@ -361,9 +360,9 @@ int main(void) { unofficial_napi_realm_options_init(&realm_options); realm_options.sandbox_or_null = sandbox; realm_options.own_microtask_queue = true; - napi_env context_env = NULL; + unofficial_napi_realm context_realm = NULL; NAPI_CALL(env, unofficial_napi_create_realm( - env, &realm_options, &context_env, NULL)); + env, &realm_options, &context_realm, NULL)); napi_value context_source_text; NAPI_CALL(env, napi_create_string_utf8( @@ -374,8 +373,9 @@ int main(void) { const unofficial_napi_js_source context_source = unofficial_napi_js_source_from_text(context_source_text); napi_value context_result; - NAPI_CALL(context_env, unofficial_napi_run_script( - context_env, + NAPI_CALL(env, unofficial_napi_run_script( + env, + context_realm, &context_source, undefined_value, 0, @@ -388,7 +388,7 @@ int main(void) { &context_result)); NAPI_CALL(env, napi_get_value_int32(env, context_result, &marker)); CHECK_OR_FAIL(marker == 73, - "run_script escaped its env's realm"); + "run_script escaped its realm"); napi_value parameters; napi_value context_extensions; @@ -415,8 +415,9 @@ int main(void) { const unofficial_napi_js_source function_source = unofficial_napi_js_source_from_text(function_source_text); napi_value compiled; - NAPI_CALL(context_env, unofficial_napi_compile_function( - context_env, + NAPI_CALL(env, unofficial_napi_compile_function( + env, + context_realm, &function_source, undefined_value, 0, @@ -440,7 +441,7 @@ int main(void) { &function_result)); NAPI_CALL(env, napi_get_value_int32(env, function_result, &marker)); CHECK_OR_FAIL(marker == 147, - "compile_function escaped its env's realm"); + "compile_function escaped its realm"); napi_value module_wrapper; napi_value module_url; @@ -465,11 +466,12 @@ int main(void) { module_options.kind = unofficial_napi_module_source_text; module_options.wrapper = module_wrapper; module_options.url = module_url; + module_options.realm_or_null = context_realm; module_options.payload.source_text.source = &module_source; module_options.payload.source_text.host_defined_option_id = undefined_value; unofficial_napi_module_create_result module_create_result = {0}; - NAPI_CALL(context_env, unofficial_napi_module_wrap_create( - context_env, &module_options, &module_create_result)); + NAPI_CALL(env, unofficial_napi_module_wrap_create( + env, &module_options, &module_create_result)); unofficial_napi_module module = module_create_result.module; CHECK_OR_FAIL(module != NULL, "module compilation did not return a handle"); @@ -480,8 +482,8 @@ int main(void) { int32_t module_status = -1; napi_value module_error = NULL; bool module_has_async_graph = false; - NAPI_CALL(context_env, unofficial_napi_module_wrap_get_state( - context_env, + NAPI_CALL(env, unofficial_napi_module_wrap_get_state( + env, module, &module_status, &module_error, @@ -492,13 +494,13 @@ int main(void) { "module snapshot did not return an undefined error value"); CHECK_OR_FAIL(!module_has_async_graph, "uninstantiated module reported an async graph"); - NAPI_CALL(context_env, unofficial_napi_module_wrap_link( - context_env, module, 0, NULL)); - NAPI_CALL(context_env, unofficial_napi_module_wrap_instantiate(context_env, module)); + NAPI_CALL(env, unofficial_napi_module_wrap_link( + env, module, 0, NULL)); + NAPI_CALL(env, unofficial_napi_module_wrap_instantiate(env, module)); module_status = -1; module_has_async_graph = true; - NAPI_CALL(context_env, unofficial_napi_module_wrap_get_state( - context_env, + NAPI_CALL(env, unofficial_napi_module_wrap_get_state( + env, module, &module_status, NULL, @@ -508,22 +510,22 @@ int main(void) { CHECK_OR_FAIL(!module_has_async_graph, "synchronous module reported an async graph"); napi_value module_result; - NAPI_CALL(context_env, unofficial_napi_module_wrap_evaluate_sync( - context_env, + NAPI_CALL(env, unofficial_napi_module_wrap_evaluate_sync( + env, module, module_url, module_url, &module_result)); napi_value module_namespace; napi_value module_observed; - NAPI_CALL(context_env, unofficial_napi_module_wrap_get_namespace( - context_env, module, &module_namespace)); + NAPI_CALL(env, unofficial_napi_module_wrap_get_namespace( + env, module, &module_namespace)); NAPI_CALL(env, napi_get_named_property( env, module_namespace, "observed", &module_observed)); NAPI_CALL(env, napi_get_value_int32(env, module_observed, &marker)); CHECK_OR_FAIL(marker == 73, - "module evaluation escaped its env's realm"); - NAPI_CALL(context_env, unofficial_napi_module_wrap_destroy(context_env, module)); + "module evaluation escaped its realm"); + NAPI_CALL(env, unofficial_napi_module_wrap_destroy(env, module)); // Creating the CommonJS facade evaluates the original module internally, // so a synthetic module's guest evaluation callback must be able to re-enter diff --git a/tests/programs/test_realm.c b/tests/programs/test_realm.c index 3893d733e0..4e35fd83fe 100644 --- a/tests/programs/test_realm.c +++ b/tests/programs/test_realm.c @@ -35,16 +35,28 @@ static napi_value NAPI_CDECL RecordCallback(napi_env env, napi_callback_info inf return object; } -static napi_status RunScript(napi_env env, const char* source, napi_value* result) { - napi_value script = NULL; - napi_status status = napi_create_string_utf8(env, source, NAPI_AUTO_LENGTH, &script); +// Runs `source` in `realm`, or in the env's own realm when it is NULL. +static napi_status RunIn(napi_env env, + unofficial_napi_realm realm, + const char* source, + napi_value* result) { + napi_value text = NULL; + napi_value filename = NULL; + napi_status status = napi_create_string_utf8(env, source, NAPI_AUTO_LENGTH, &text); + if (status != napi_ok) return status; + status = napi_create_string_utf8(env, "realm.js", NAPI_AUTO_LENGTH, &filename); if (status != napi_ok) return status; - return napi_run_script(env, script, result); + const unofficial_napi_js_source script = unofficial_napi_js_source_from_text(text); + return unofficial_napi_run_script( + env, realm, &script, filename, 0, 0, -1, true, false, false, NULL, result); } -static napi_status RunInt32(napi_env env, const char* source, int32_t* out) { +static napi_status RunInInt32(napi_env env, + unofficial_napi_realm realm, + const char* source, + int32_t* out) { napi_value result = NULL; - napi_status status = RunScript(env, source, &result); + napi_status status = RunIn(env, realm, source, &result); if (status != napi_ok) return status; return napi_get_value_int32(env, result, out); } @@ -88,54 +100,54 @@ int main(void) { CHECK_OR_FAIL(env != NULL, "napi_wasm_init_env returned NULL"); // A realm has its own global. - napi_env realm = NULL; + unofficial_napi_realm realm = NULL; napi_value realm_global = NULL; NAPI_CALL(env, unofficial_napi_create_realm(env, NULL, &realm, &realm_global)); - CHECK_OR_FAIL(realm != NULL && realm != env, "create_realm did not return a new env"); + CHECK_OR_FAIL(realm != NULL, "create_realm did not return a realm"); napi_value env_global = NULL; napi_value realm_own_global = NULL; NAPI_CALL(env, napi_get_global(env, &env_global)); - NAPI_CALL(realm, napi_get_global(realm, &realm_own_global)); + NAPI_CALL(env, RunIn(env, realm, "globalThis", &realm_own_global)); CHECK_OR_FAIL(StrictEquals(env, realm_own_global, realm_global), - "the realm env's global is not the one create_realm returned"); + "the realm's global is not the one create_realm returned"); CHECK_OR_FAIL(!StrictEquals(env, env_global, realm_global), - "the realm shares its parent's global"); + "the realm shares the env's global"); printf("realm has its own global\n"); - // Values made through one env are usable through the other. + // Values cross realms. napi_value shared = NULL; NAPI_CALL(env, napi_create_object(env, &shared)); - NAPI_CALL(realm, napi_set_named_property(realm, realm_global, "shared", shared)); + NAPI_CALL(env, napi_set_named_property(env, realm_global, "shared", shared)); int32_t x = 0; - NAPI_CALL(realm, RunInt32(realm, "shared.x = 7", &x)); + NAPI_CALL(env, RunInInt32(env, realm, "shared.x = 7", &x)); napi_value x_value = NULL; NAPI_CALL(env, napi_get_named_property(env, shared, "x", &x_value)); NAPI_CALL(env, napi_get_value_int32(env, x_value, &x)); - CHECK_OR_FAIL(x == 7, "a value did not cross envs"); - printf("values cross envs: x=%d\n", x); + CHECK_OR_FAIL(x == 7, "a value did not cross realms"); + printf("values cross realms: x=%d\n", x); - // A native function made through the realm env runs in that realm, also - // when the parent's script calls it. - callback_record record = {realm_global, NULL, false, 0}; + // A native function belongs to the env's realm, also when code in another + // realm calls it. + callback_record record = {env_global, NULL, false, 0}; napi_value fn = NULL; - NAPI_CALL(realm, napi_create_function( - realm, "probe", NAPI_AUTO_LENGTH, RecordCallback, &record, &fn)); - NAPI_CALL(env, napi_set_named_property(env, env_global, "probe", fn)); + NAPI_CALL(env, napi_create_function( + env, "probe", NAPI_AUTO_LENGTH, RecordCallback, &record, &fn)); + NAPI_CALL(env, napi_set_named_property(env, realm_global, "probe", fn)); napi_value probe_result = NULL; - NAPI_CALL(env, RunScript(env, "probe()", &probe_result)); + NAPI_CALL(env, RunIn(env, realm, "probe()", &probe_result)); CHECK_OR_FAIL(record.calls == 1, "the callback did not run"); - CHECK_OR_FAIL(record.env == realm, "the callback did not get the realm env"); - CHECK_OR_FAIL(record.saw_expected_global, "the callback did not see the realm's global"); - printf("callback saw the realm env and the realm global\n"); + CHECK_OR_FAIL(record.env == env, "the callback did not get its env"); + CHECK_OR_FAIL(record.saw_expected_global, "the callback did not see the env's global"); + printf("native function stays in the env's realm\n"); - // get_realm maps globals back to their envs. - napi_env found = NULL; + // get_realm finds a realm by its global; the env's own global is not one. + unofficial_napi_realm found = NULL; NAPI_CALL(env, unofficial_napi_get_realm(env, realm_global, &found)); - CHECK_OR_FAIL(found == realm, "get_realm(realm global) did not return the realm env"); - found = NULL; - NAPI_CALL(realm, unofficial_napi_get_realm(realm, env_global, &found)); - CHECK_OR_FAIL(found == env, "get_realm(parent global) did not return the parent env"); - printf("get_realm finds both envs\n"); + CHECK_OR_FAIL(found == realm, "get_realm(realm global) did not return the realm"); + found = realm; + NAPI_CALL(env, unofficial_napi_get_realm(env, env_global, &found)); + CHECK_OR_FAIL(found == NULL, "get_realm(env global) returned a realm"); + printf("get_realm finds the realm by its global\n"); // A sandbox realm reads and writes the sandbox. napi_value sandbox = NULL; @@ -146,31 +158,16 @@ int main(void) { unofficial_napi_realm_options options; unofficial_napi_realm_options_init(&options); options.sandbox_or_null = sandbox; - napi_env sandbox_realm = NULL; + unofficial_napi_realm sandbox_realm = NULL; napi_value sandbox_global = NULL; NAPI_CALL(env, unofficial_napi_create_realm(env, &options, &sandbox_realm, &sandbox_global)); CHECK_OR_FAIL(StrictEquals(env, sandbox_global, sandbox), "create_realm did not return the sandbox as the global"); - napi_value source_text = NULL; - NAPI_CALL(env, napi_create_string_utf8( - env, "output = input * 2; input", NAPI_AUTO_LENGTH, &source_text)); - napi_value filename = NULL; - NAPI_CALL(env, napi_create_string_utf8(env, "sandbox.js", NAPI_AUTO_LENGTH, &filename)); - const unofficial_napi_js_source source = unofficial_napi_js_source_from_text(source_text); - napi_value run_result = NULL; - NAPI_CALL(sandbox_realm, unofficial_napi_run_script(sandbox_realm, - &source, - filename, - 0, - 0, - -1, - true, - false, - false, - NULL, - &run_result)); + found = NULL; + NAPI_CALL(env, unofficial_napi_get_realm(env, sandbox, &found)); + CHECK_OR_FAIL(found == sandbox_realm, "get_realm(sandbox) did not return its realm"); int32_t input = 0; - NAPI_CALL(env, napi_get_value_int32(env, run_result, &input)); + NAPI_CALL(env, RunInInt32(env, sandbox_realm, "output = input * 2; input", &input)); napi_value output_value = NULL; int32_t output = 0; NAPI_CALL(env, napi_get_named_property(env, sandbox, "output", &output_value)); @@ -178,101 +175,114 @@ int main(void) { CHECK_OR_FAIL(input == 5 && output == 10, "the sandbox realm did not use the sandbox"); printf("sandbox realm: input=%d output=%d\n", input, output); - // A module made through a realm env evaluates in that realm, and its - // handle works through the parent env too. - int32_t tag = 0; - NAPI_CALL(realm, RunInt32(realm, "globalThis.tag = 21", &tag)); - napi_value undefined = NULL; - NAPI_CALL(env, napi_get_undefined(env, &undefined)); - napi_value wrapper = NULL; - NAPI_CALL(env, napi_create_object(env, &wrapper)); - const unofficial_napi_js_source module_source = - unofficial_napi_js_source_from_text(Str(env, "export const tag = globalThis.tag;")); - unofficial_napi_module_create_options module_options = {0}; - module_options.size = sizeof(module_options); - module_options.version = UNOFFICIAL_NAPI_MODULE_CREATE_OPTIONS_VERSION; - module_options.kind = unofficial_napi_module_source_text; - module_options.wrapper = wrapper; - module_options.url = Str(env, "file:///realm.mjs"); - module_options.payload.source_text.source = &module_source; - module_options.payload.source_text.host_defined_option_id = undefined; - unofficial_napi_module_create_result created = {0}; - NAPI_CALL(realm, unofficial_napi_module_wrap_create(realm, &module_options, &created)); - NAPI_CALL(env, EvaluateModule(env, created.module)); - tag = 0; - NAPI_CALL(env, ReadInt32Export(env, created.module, "tag", &tag)); - NAPI_CALL(env, unofficial_napi_module_wrap_destroy(env, created.module)); - CHECK_OR_FAIL(tag == 21, "the module did not evaluate in the realm"); - printf("realm module through the parent env: tag=%d\n", tag); - - // A script, a compiled function and a module made through a sandbox - // realm's env all see the sandbox (x = 3). + // A script, a compiled function, a module and bytecode, all for a sandbox + // realm, see the sandbox (x = 3). napi_value context_sandbox = NULL; napi_value three = NULL; NAPI_CALL(env, napi_create_object(env, &context_sandbox)); NAPI_CALL(env, napi_create_int32(env, 3, &three)); NAPI_CALL(env, napi_set_named_property(env, context_sandbox, "x", three)); - unofficial_napi_realm_options context_options; - unofficial_napi_realm_options_init(&context_options); - context_options.sandbox_or_null = context_sandbox; - napi_env context_realm = NULL; - NAPI_CALL(env, unofficial_napi_create_realm(env, &context_options, &context_realm, NULL)); - const unofficial_napi_js_source run_source = - unofficial_napi_js_source_from_text(Str(env, "x + 1")); + options.sandbox_or_null = context_sandbox; + unofficial_napi_realm context_realm = NULL; + NAPI_CALL(env, unofficial_napi_create_realm(env, &options, &context_realm, NULL)); + napi_value undefined = NULL; + NAPI_CALL(env, napi_get_undefined(env, &undefined)); + int32_t ran = 0; + NAPI_CALL(env, RunInInt32(env, context_realm, "x + 1", &ran)); const unofficial_napi_js_source function_source = unofficial_napi_js_source_from_text(Str(env, "return x * 10;")); - const unofficial_napi_js_source x_module_source = - unofficial_napi_js_source_from_text(Str(env, "export const y = x + 2;")); - napi_value value = NULL; - int32_t ran = 0; - NAPI_CALL(context_realm, unofficial_napi_run_script(context_realm, &run_source, Str(env, "a.js"), - 0, 0, -1, true, false, false, NULL, - &value)); - NAPI_CALL(env, napi_get_value_int32(env, value, &ran)); napi_value compiled = NULL; + napi_value value = NULL; int32_t called = 0; - NAPI_CALL(context_realm, unofficial_napi_compile_function(context_realm, &function_source, - Str(env, "f.js"), 0, 0, undefined, - undefined, undefined, &compiled)); + NAPI_CALL(env, unofficial_napi_compile_function(env, context_realm, &function_source, + Str(env, "f.js"), 0, 0, undefined, undefined, + undefined, &compiled)); NAPI_CALL(env, napi_get_named_property(env, compiled, "function", &fn)); NAPI_CALL(env, napi_call_function(env, undefined, fn, 0, NULL, &value)); NAPI_CALL(env, napi_get_value_int32(env, value, &called)); + napi_value wrapper = NULL; NAPI_CALL(env, napi_create_object(env, &wrapper)); + const unofficial_napi_js_source module_source = + unofficial_napi_js_source_from_text(Str(env, "export const y = x + 2;")); + unofficial_napi_module_create_options module_options = {0}; + module_options.size = sizeof(module_options); + module_options.version = UNOFFICIAL_NAPI_MODULE_CREATE_OPTIONS_VERSION; + module_options.kind = unofficial_napi_module_source_text; module_options.wrapper = wrapper; module_options.url = Str(env, "file:///x.mjs"); - module_options.payload.source_text.source = &x_module_source; - NAPI_CALL(context_realm, unofficial_napi_module_wrap_create(context_realm, &module_options, - &created)); + module_options.realm_or_null = context_realm; + module_options.payload.source_text.source = &module_source; + module_options.payload.source_text.host_defined_option_id = undefined; + unofficial_napi_module_create_result created = {0}; + NAPI_CALL(env, unofficial_napi_module_wrap_create(env, &module_options, &created)); int32_t exported = 0; NAPI_CALL(env, EvaluateModule(env, created.module)); NAPI_CALL(env, ReadInt32Export(env, created.module, "y", &exported)); NAPI_CALL(env, unofficial_napi_module_wrap_destroy(env, created.module)); - CHECK_OR_FAIL(ran == 4 && called == 30 && exported == 5, - "the realm env did not run in its sandbox's realm"); - printf("vm results: run=%d function=%d module=%d\n", ran, called, exported); + unofficial_napi_bytecode_open_options open_options = {0}; + open_options.size = sizeof(open_options); + open_options.version = UNOFFICIAL_NAPI_BYTECODE_OPEN_OPTIONS_VERSION; + open_options.realm_or_null = context_realm; + open_options.source_text = Str(env, "x * 2"); + open_options.filename = Str(env, "b.js"); + open_options.shape = unofficial_napi_bytecode_shape_script; + open_options.params_or_undefined = undefined; + open_options.host_defined_option_id = undefined; + unofficial_napi_bytecode_open_result opened = {0}; + NAPI_CALL(env, unofficial_napi_bytecode_open(env, &open_options, &opened)); + const unofficial_napi_js_source bytecode_source = + unofficial_napi_js_source_from_bytecode(opened.bytecode); + int32_t from_bytecode = 0; + NAPI_CALL(env, unofficial_napi_run_script(env, context_realm, &bytecode_source, + Str(env, "b.js"), 0, 0, -1, true, false, false, + NULL, &value)); + NAPI_CALL(env, napi_get_value_int32(env, value, &from_bytecode)); + NAPI_CALL(env, unofficial_napi_bytecode_release(env, opened.bytecode)); + CHECK_OR_FAIL(ran == 4 && called == 30 && exported == 5 && from_bytecode == 6, + "code did not run in its sandbox's realm"); + printf("vm results: run=%d function=%d module=%d bytecode=%d\n", ran, called, exported, + from_bytecode); + + // Realms nothing refers to any more are collected. + enum { kDropped = 6 }; + napi_ref dropped[kDropped]; + for (int i = 0; i < kDropped; ++i) { + napi_handle_scope scope = NULL; + NAPI_CALL(env, napi_open_handle_scope(env, &scope)); + napi_value dropped_sandbox = NULL; + if (i % 2 == 0) NAPI_CALL(env, napi_create_object(env, &dropped_sandbox)); + options.sandbox_or_null = dropped_sandbox; + unofficial_napi_realm dropped_realm = NULL; + napi_value dropped_global = NULL; + NAPI_CALL(env, unofficial_napi_create_realm(env, &options, &dropped_realm, &dropped_global)); + napi_value ignored = NULL; + NAPI_CALL(env, RunIn(env, dropped_realm, "globalThis.payload = new Array(1024).fill(1)", + &ignored)); + NAPI_CALL(env, napi_create_reference(env, dropped_global, 0, &dropped[i])); + NAPI_CALL(env, napi_close_handle_scope(env, scope)); + } + NAPI_CALL(env, unofficial_napi_collect_garbage(env)); + int collected = 0; + for (int i = 0; i < kDropped; ++i) { + napi_value global = NULL; + NAPI_CALL(env, napi_get_reference_value(env, dropped[i], &global)); + if (global == NULL) collected++; + NAPI_CALL(env, napi_delete_reference(env, dropped[i])); + } + CHECK_OR_FAIL(collected == kDropped, "a dropped realm was not collected"); + printf("collected %d of %d dropped realms\n", collected, kDropped); - // Releasing an env with live realm envs, nested ones included, releases - // them with it. + // Releasing an env with live realms releases them with it. napi_env env2 = NULL; unofficial_napi_env_owner env2_scope = NULL; NAPI_CALL(env, unofficial_napi_create_env(8, NULL, &env2, &env2_scope)); - napi_env env2_realm = NULL; - napi_env env2_nested = NULL; + unofficial_napi_realm env2_realm = NULL; NAPI_CALL(env2, unofficial_napi_create_realm(env2, NULL, &env2_realm, NULL)); - NAPI_CALL(env2_realm, unofficial_napi_create_realm(env2_realm, NULL, &env2_nested, NULL)); - int32_t nested_value = 0; - NAPI_CALL(env2_nested, RunInt32(env2_nested, "globalThis.v = 12", &nested_value)); - CHECK_OR_FAIL(nested_value == 12, "the nested realm did not run"); + int32_t realm_value = 0; + NAPI_CALL(env2, RunInInt32(env2, env2_realm, "globalThis.v = 12", &realm_value)); + CHECK_OR_FAIL(realm_value == 12, "the second env's realm did not run"); NAPI_CALL(env, unofficial_napi_release_env(env2_scope, NULL)); -#ifdef __wasm__ - // Guest env ids of released realm envs no longer resolve. (Natively the - // handles are freed pointers and must not be used.) - napi_value stale_global = NULL; - CHECK_OR_FAIL(napi_get_global(env2_realm, &stale_global) != napi_ok && - napi_get_global(env2_nested, &stale_global) != napi_ok, - "a released realm env still resolves"); -#endif - printf("released an env with live realm envs\n"); + printf("released an env with live realms\n"); return PrintSuccess("TEST_REALM"); } diff --git a/tests/runners/test_65_unofficial_contextify.cc b/tests/runners/test_65_unofficial_contextify.cc index f2b545ba04..ad0aabaef5 100644 --- a/tests/runners/test_65_unofficial_contextify.cc +++ b/tests/runners/test_65_unofficial_contextify.cc @@ -24,7 +24,7 @@ napi_value Sym(napi_env env, const char* value) { napi_status CreateSandboxRealm(napi_env env, napi_value sandbox, bool own_microtask_queue, - napi_env* realm_out) { + unofficial_napi_realm* realm_out) { unofficial_napi_realm_options options; unofficial_napi_realm_options_init(&options); options.sandbox_or_null = sandbox; @@ -134,13 +134,14 @@ TEST_F(Test65UnofficialContextify, NativeFunctionCalledFromContextKeepsItsRealm) ASSERT_EQ(napi_create_object(s.env, &sandbox), napi_ok); ASSERT_EQ(napi_set_named_property(s.env, sandbox, "probe", fn), napi_ok); - napi_env realm = nullptr; + unofficial_napi_realm realm = nullptr; ASSERT_EQ(CreateSandboxRealm(s.env, sandbox, false, &realm), napi_ok); napi_value eval_result = nullptr; const unofficial_napi_js_source source = unofficial_napi_js_source_from_text( Str(s.env, "Object.getPrototypeOf(probe()) === Object.prototype")); - ASSERT_EQ(unofficial_napi_run_script(realm, + ASSERT_EQ(unofficial_napi_run_script(s.env, + realm, &source, Str(s.env, "probe.js"), 0, @@ -171,14 +172,15 @@ TEST_F(Test65UnofficialContextify, CreateRealmRunRoundTrip) { napi_value sandbox = nullptr; ASSERT_EQ(napi_create_object(s.env, &sandbox), napi_ok); - napi_env realm = nullptr; + unofficial_napi_realm realm = nullptr; ASSERT_EQ(CreateSandboxRealm(s.env, sandbox, true, &realm), napi_ok); ASSERT_NE(realm, nullptr); napi_value eval_result = nullptr; const unofficial_napi_js_source run_source = unofficial_napi_js_source_from_text(Str(s.env, "globalThis.answer = 42; answer")); - ASSERT_EQ(unofficial_napi_run_script(realm, + ASSERT_EQ(unofficial_napi_run_script(s.env, + realm, &run_source, Str(s.env, "ctx.js"), 0, @@ -220,7 +222,7 @@ TEST_F(Test65UnofficialContextify, CreateRealmPreservesThrownProxyException) { ASSERT_EQ(napi_get_named_property(s.env, fixture, "sentinel", &sentinel), napi_ok); ASSERT_EQ(napi_get_named_property(s.env, fixture, "sandbox", &sandbox), napi_ok); - napi_env realm = nullptr; + unofficial_napi_realm realm = nullptr; EXPECT_EQ(CreateSandboxRealm(s.env, sandbox, false, &realm), napi_pending_exception); EXPECT_EQ(realm, nullptr); @@ -241,7 +243,7 @@ TEST_F(Test65UnofficialContextify, SandboxGlobalThisIsNotEnumerableForDeepFreeze napi_value sandbox = nullptr; ASSERT_EQ(napi_create_object(s.env, &sandbox), napi_ok); - napi_env realm = nullptr; + unofficial_napi_realm realm = nullptr; ASSERT_EQ(CreateSandboxRealm(s.env, sandbox, true, &realm), napi_ok); ASSERT_NE(realm, nullptr); @@ -309,7 +311,8 @@ globalThis.__RSC_MANIFEST["/x"].ok; )JS"; const unofficial_napi_js_source freeze_source = unofficial_napi_js_source_from_text( Str(s.env, freeze_script.c_str())); - ASSERT_EQ(unofficial_napi_run_script(realm, + ASSERT_EQ(unofficial_napi_run_script(s.env, + realm, &freeze_source, Str(s.env, "deep_freeze.js"), 0, @@ -346,6 +349,7 @@ TEST_F(Test65UnofficialContextify, CompileFunctionAndCachedData) { const unofficial_napi_js_source fn_source = unofficial_napi_js_source_from_text(Str(s.env, "return a + b;")); ASSERT_EQ(unofficial_napi_compile_function(s.env, + nullptr, &fn_source, Str(s.env, "fn.js"), 0, @@ -634,6 +638,7 @@ TEST_F(Test65UnofficialContextify, unofficial_napi_js_source_from_bytecode(bytecode); napi_value compiled = nullptr; EXPECT_EQ(unofficial_napi_compile_function(s.env, + nullptr, &source, Str(s.env, "host-id.js"), 0, @@ -722,6 +727,7 @@ globalThis.Function = function Function() { const unofficial_napi_js_source fn_source = unofficial_napi_js_source_from_text(Str(s.env, "return value + 1;")); ASSERT_EQ(unofficial_napi_compile_function(s.env, + nullptr, &fn_source, Str(s.env, "no-global-function.js"), 0, @@ -759,6 +765,7 @@ TEST_F(Test65UnofficialContextify, CompileFunctionAcceptsHashbangBody) { const unofficial_napi_js_source hashbang_source = unofficial_napi_js_source_from_text( Str(s.env, "#!/usr/bin/env node\nreturn 42;")); ASSERT_EQ(unofficial_napi_compile_function(s.env, + nullptr, &hashbang_source, Str(s.env, ""), 0, @@ -794,6 +801,7 @@ TEST_F(Test65UnofficialContextify, CompileFunctionRejectsBomBeforeHashbang) { const unofficial_napi_js_source bom_source = unofficial_napi_js_source_from_text( Str(s.env, "\xEF\xBB\xBF#!/usr/bin/env node\nreturn 42;")); EXPECT_EQ(unofficial_napi_compile_function(s.env, + nullptr, &bom_source, Str(s.env, "bom_hashbang.js"), 0, @@ -866,6 +874,7 @@ TEST_F(Test65UnofficialContextify, CjsCompileAndSyntaxDetection) { const unofficial_napi_js_source cjs_source = unofficial_napi_js_source_from_text(Str(s.env, "module.exports = 1;")); ASSERT_EQ(unofficial_napi_compile_function(s.env, + nullptr, &cjs_source, Str(s.env, "cjs.js"), 0, diff --git a/tests/runners/test_66_unofficial_realm.cc b/tests/runners/test_66_unofficial_realm.cc new file mode 100644 index 0000000000..f0988e95c5 --- /dev/null +++ b/tests/runners/test_66_unofficial_realm.cc @@ -0,0 +1,602 @@ +#ifdef NAPI_MODULE +#undef NAPI_MODULE +#endif +#include "node_api.h" + +#include "test_env.h" + +#include "unofficial_napi.h" + +#include +#include + +class Test66UnofficialRealm : public FixtureTestBase {}; + +namespace { + +napi_value Str(napi_env env, const char* value) { + napi_value out = nullptr; + if (napi_create_string_utf8(env, value, NAPI_AUTO_LENGTH, &out) != napi_ok) return nullptr; + return out; +} + +napi_value Eval(napi_env env, const char* source) { + napi_value result = nullptr; + if (napi_run_script(env, Str(env, source), &result) != napi_ok) return nullptr; + return result; +} + +// Runs `source` in `realm` (the env's own realm when null). +napi_value RunIn(napi_env env, unofficial_napi_realm realm, const char* source) { + const unofficial_napi_js_source script = unofficial_napi_js_source_from_text(Str(env, source)); + napi_value result = nullptr; + if (unofficial_napi_run_script(env, realm, &script, Str(env, "realm.js"), 0, 0, -1, true, false, + false, nullptr, &result) != napi_ok) { + return nullptr; + } + return result; +} + +bool StrictEquals(napi_env env, napi_value a, napi_value b) { + bool same = false; + return napi_strict_equals(env, a, b, &same) == napi_ok && same; +} + +napi_value Global(napi_env env) { + napi_value global = nullptr; + if (napi_get_global(env, &global) != napi_ok) return nullptr; + return global; +} + +napi_value Prototype(napi_env env, napi_value object) { + napi_value prototype = nullptr; + if (napi_get_prototype(env, object, &prototype) != napi_ok) return nullptr; + return prototype; +} + +int32_t Int32(napi_env env, napi_value value) { + int32_t out = -1; + if (value == nullptr || napi_get_value_int32(env, value, &out) != napi_ok) return -1; + return out; +} + +std::string Utf8(napi_env env, napi_value value) { + char buffer[256] = {}; + size_t length = 0; + if (value == nullptr || + napi_get_value_string_utf8(env, value, buffer, sizeof(buffer), &length) != napi_ok) { + return std::string(); + } + return std::string(buffer, length); +} + +unofficial_napi_realm CreateRealm(napi_env env, + napi_value* global_out = nullptr, + napi_value sandbox = nullptr, + bool own_microtask_queue = false) { + unofficial_napi_realm_options options; + unofficial_napi_realm_options_init(&options); + options.sandbox_or_null = sandbox; + options.own_microtask_queue = own_microtask_queue; + unofficial_napi_realm realm = nullptr; + if (unofficial_napi_create_realm(env, &options, &realm, global_out) != napi_ok) return nullptr; + return realm; +} + +bool IsCollected(napi_env env, napi_ref ref) { + napi_value value = nullptr; + return napi_get_reference_value(env, ref, &value) == napi_ok && value == nullptr; +} + +struct CallRecord { + napi_env env = nullptr; + bool saw_env_global = false; + bool made_env_object = false; + int calls = 0; +}; + +// Records the env a native callback gets, and which realm its global and the +// objects it makes belong to. +napi_value RecordCall(napi_env env, napi_callback_info info) { + void* data = nullptr; + if (napi_get_cb_info(env, info, nullptr, nullptr, nullptr, &data) != napi_ok) return nullptr; + auto* record = static_cast(data); + record->env = env; + record->calls++; + napi_value env_global = Eval(env, "globalThis"); + record->saw_env_global = StrictEquals(env, Global(env), env_global); + napi_value object = nullptr; + if (napi_create_object(env, &object) != napi_ok) return nullptr; + record->made_env_object = + StrictEquals(env, Prototype(env, object), Eval(env, "Object.prototype")); + return object; +} + +} // namespace + +TEST_F(Test66UnofficialRealm, CreateRealmValidatesItsArguments) { + EnvScope s(runtime_.get()); + unofficial_napi_realm realm = nullptr; + + EXPECT_EQ(unofficial_napi_create_realm(nullptr, nullptr, &realm, nullptr), napi_invalid_arg); + EXPECT_EQ(unofficial_napi_create_realm(s.env, nullptr, nullptr, nullptr), napi_invalid_arg); + + unofficial_napi_realm_options options; + unofficial_napi_realm_options_init(&options); + EXPECT_TRUE(options.allow_code_gen_strings); + EXPECT_TRUE(options.allow_code_gen_wasm); + EXPECT_FALSE(options.own_microtask_queue); + + options.size = sizeof(options) - 1; + EXPECT_EQ(unofficial_napi_create_realm(s.env, &options, &realm, nullptr), napi_invalid_arg); + unofficial_napi_realm_options_init(&options); + options.version += 1; + EXPECT_EQ(unofficial_napi_create_realm(s.env, &options, &realm, nullptr), napi_invalid_arg); + EXPECT_EQ(realm, nullptr); + + napi_value number = nullptr; + ASSERT_EQ(napi_create_int32(s.env, 1, &number), napi_ok); + unofficial_napi_realm_options_init(&options); + options.sandbox_or_null = number; + EXPECT_NE(unofficial_napi_create_realm(s.env, &options, &realm, nullptr), napi_ok); + + // A sandbox belongs to one realm. + napi_value sandbox = nullptr; + ASSERT_EQ(napi_create_object(s.env, &sandbox), napi_ok); + ASSERT_NE(CreateRealm(s.env, nullptr, sandbox), nullptr); + options.sandbox_or_null = sandbox; + realm = nullptr; + EXPECT_EQ(unofficial_napi_create_realm(s.env, &options, &realm, nullptr), napi_invalid_arg); + EXPECT_EQ(realm, nullptr); +} + +// As with vm.createContext(globalThis) in Node. +TEST_F(Test66UnofficialRealm, TheEnvsGlobalCanBeASandbox) { + EnvScope s(runtime_.get()); + unofficial_napi_realm realm = CreateRealm(s.env, nullptr, Global(s.env)); + ASSERT_NE(realm, nullptr); + EXPECT_NE(RunIn(s.env, realm, "!function() { var x = Object; }()"), nullptr); +} + +TEST_F(Test66UnofficialRealm, RealmHasItsOwnGlobal) { + EnvScope s(runtime_.get()); + napi_value realm_global = nullptr; + unofficial_napi_realm realm = CreateRealm(s.env, &realm_global); + ASSERT_NE(realm, nullptr); + ASSERT_NE(realm_global, nullptr); + + EXPECT_TRUE(StrictEquals(s.env, RunIn(s.env, realm, "globalThis"), realm_global)); + EXPECT_FALSE(StrictEquals(s.env, realm_global, Global(s.env))); + EXPECT_TRUE(StrictEquals(s.env, RunIn(s.env, nullptr, "globalThis"), Global(s.env))); + EXPECT_TRUE(StrictEquals(s.env, Eval(s.env, "globalThis"), Global(s.env))); + + // The realm has its own intrinsics. + EXPECT_FALSE( + StrictEquals(s.env, RunIn(s.env, realm, "Object.prototype"), Eval(s.env, "Object.prototype"))); +} + +TEST_F(Test66UnofficialRealm, ValuesCrossRealms) { + EnvScope s(runtime_.get()); + napi_value realm_global = nullptr; + unofficial_napi_realm realm = CreateRealm(s.env, &realm_global); + ASSERT_NE(realm, nullptr); + + napi_value shared = nullptr; + ASSERT_EQ(napi_create_object(s.env, &shared), napi_ok); + ASSERT_EQ(napi_set_named_property(s.env, realm_global, "shared", shared), napi_ok); + EXPECT_EQ(Int32(s.env, RunIn(s.env, realm, "shared.x = 7")), 7); + napi_value x = nullptr; + ASSERT_EQ(napi_get_named_property(s.env, shared, "x", &x), napi_ok); + EXPECT_EQ(Int32(s.env, x), 7); +} + +// A native function belongs to the env's realm, also when code in another +// realm calls it, as in Node. +TEST_F(Test66UnofficialRealm, NativeFunctionsStayInTheEnvsRealm) { + EnvScope s(runtime_.get()); + napi_value realm_global = nullptr; + unofficial_napi_realm realm = CreateRealm(s.env, &realm_global); + ASSERT_NE(realm, nullptr); + + CallRecord record; + napi_value fn = nullptr; + ASSERT_EQ(napi_create_function(s.env, "probe", NAPI_AUTO_LENGTH, RecordCall, &record, &fn), + napi_ok); + ASSERT_EQ(napi_set_named_property(s.env, realm_global, "probe", fn), napi_ok); + + napi_value result = RunIn(s.env, realm, "probe()"); + ASSERT_NE(result, nullptr); + EXPECT_EQ(record.calls, 1); + EXPECT_EQ(record.env, s.env); + EXPECT_TRUE(record.saw_env_global); + EXPECT_TRUE(record.made_env_object); + EXPECT_TRUE(StrictEquals(s.env, Prototype(s.env, result), Eval(s.env, "Object.prototype"))); +} + +TEST_F(Test66UnofficialRealm, GetRealmFindsRealmsByTheirGlobal) { + EnvScope s(runtime_.get()); + napi_value realm_global = nullptr; + unofficial_napi_realm realm = CreateRealm(s.env, &realm_global); + ASSERT_NE(realm, nullptr); + napi_value sandbox = nullptr; + ASSERT_EQ(napi_create_object(s.env, &sandbox), napi_ok); + unofficial_napi_realm sandbox_realm = CreateRealm(s.env, nullptr, sandbox); + ASSERT_NE(sandbox_realm, nullptr); + + unofficial_napi_realm found = nullptr; + ASSERT_EQ(unofficial_napi_get_realm(s.env, realm_global, &found), napi_ok); + EXPECT_EQ(found, realm); + found = nullptr; + ASSERT_EQ(unofficial_napi_get_realm(s.env, sandbox, &found), napi_ok); + EXPECT_EQ(found, sandbox_realm); + + // The env's own global and other objects, functions included, are not a + // realm's global. + found = realm; + ASSERT_EQ(unofficial_napi_get_realm(s.env, Global(s.env), &found), napi_ok); + EXPECT_EQ(found, nullptr); + for (const char* source : {"(function f() {})", "({})", "[]"}) { + napi_value object = RunIn(s.env, realm, source); + ASSERT_NE(object, nullptr); + found = realm; + ASSERT_EQ(unofficial_napi_get_realm(s.env, object, &found), napi_ok) << source; + EXPECT_EQ(found, nullptr) << source; + } + + napi_value number = nullptr; + ASSERT_EQ(napi_create_int32(s.env, 1, &number), napi_ok); + EXPECT_EQ(unofficial_napi_get_realm(s.env, number, &found), napi_object_expected); + EXPECT_EQ(unofficial_napi_get_realm(s.env, nullptr, &found), napi_invalid_arg); + EXPECT_EQ(unofficial_napi_get_realm(s.env, realm_global, nullptr), napi_invalid_arg); +} + +TEST_F(Test66UnofficialRealm, SandboxRealmReadsAndWritesTheSandbox) { + EnvScope s(runtime_.get()); + napi_value sandbox = nullptr; + ASSERT_EQ(napi_create_object(s.env, &sandbox), napi_ok); + napi_value five = nullptr; + ASSERT_EQ(napi_create_int32(s.env, 5, &five), napi_ok); + ASSERT_EQ(napi_set_named_property(s.env, sandbox, "input", five), napi_ok); + + napi_value global_out = nullptr; + unofficial_napi_realm realm = CreateRealm(s.env, &global_out, sandbox); + ASSERT_NE(realm, nullptr); + EXPECT_TRUE(StrictEquals(s.env, global_out, sandbox)); + + EXPECT_EQ(Int32(s.env, RunIn(s.env, realm, "output = input * 2; input")), 5); + napi_value output = nullptr; + ASSERT_EQ(napi_get_named_property(s.env, sandbox, "output", &output), napi_ok); + EXPECT_EQ(Int32(s.env, output), 10); + EXPECT_EQ(Utf8(s.env, Eval(s.env, "typeof output")), "undefined"); +} + +TEST_F(Test66UnofficialRealm, ScriptsAndFunctionsRunInTheirRealm) { + EnvScope s(runtime_.get()); + napi_value realm_global = nullptr; + unofficial_napi_realm realm = CreateRealm(s.env, &realm_global); + ASSERT_NE(realm, nullptr); + + napi_value undefined = nullptr; + ASSERT_EQ(napi_get_undefined(s.env, &undefined), napi_ok); + const unofficial_napi_js_source body = + unofficial_napi_js_source_from_text(Str(s.env, "return globalThis;")); + for (unofficial_napi_realm target : {realm, static_cast(nullptr)}) { + napi_value compiled = nullptr; + ASSERT_EQ(unofficial_napi_compile_function(s.env, target, &body, Str(s.env, "f.js"), 0, 0, + undefined, undefined, undefined, &compiled), + napi_ok); + napi_value fn = nullptr; + ASSERT_EQ(napi_get_named_property(s.env, compiled, "function", &fn), napi_ok); + napi_value returned = nullptr; + ASSERT_EQ(napi_call_function(s.env, undefined, fn, 0, nullptr, &returned), napi_ok); + EXPECT_TRUE(StrictEquals(s.env, returned, target != nullptr ? realm_global : Global(s.env))); + } +} + +TEST_F(Test66UnofficialRealm, ModulesEvaluateInTheirRealm) { + EnvScope s(runtime_.get()); + napi_value realm_global = nullptr; + unofficial_napi_realm realm = CreateRealm(s.env, &realm_global); + ASSERT_NE(realm, nullptr); + + napi_value wrapper = nullptr; + napi_value undefined = nullptr; + ASSERT_EQ(napi_create_object(s.env, &wrapper), napi_ok); + ASSERT_EQ(napi_get_undefined(s.env, &undefined), napi_ok); + const unofficial_napi_js_source source = + unofficial_napi_js_source_from_text(Str(s.env, "export const g = globalThis;")); + unofficial_napi_module_create_options options{}; + options.size = sizeof(options); + options.version = UNOFFICIAL_NAPI_MODULE_CREATE_OPTIONS_VERSION; + options.kind = unofficial_napi_module_source_text; + options.wrapper = wrapper; + options.url = Str(s.env, "realm.mjs"); + options.realm_or_null = realm; + options.payload.source_text.source = &source; + options.payload.source_text.host_defined_option_id = undefined; + unofficial_napi_module_create_result created{}; + ASSERT_EQ(unofficial_napi_module_wrap_create(s.env, &options, &created), napi_ok); + ASSERT_EQ(unofficial_napi_module_wrap_link(s.env, created.module, 0, nullptr), napi_ok); + ASSERT_EQ(unofficial_napi_module_wrap_instantiate(s.env, created.module), napi_ok); + napi_value evaluated = nullptr; + ASSERT_EQ(unofficial_napi_module_wrap_evaluate(s.env, created.module, -1, false, &evaluated), + napi_ok); + napi_value ns = nullptr; + ASSERT_EQ(unofficial_napi_module_wrap_get_namespace(s.env, created.module, &ns), napi_ok); + napi_value g = nullptr; + ASSERT_EQ(napi_get_named_property(s.env, ns, "g", &g), napi_ok); + EXPECT_TRUE(StrictEquals(s.env, g, realm_global)); + EXPECT_FALSE(StrictEquals(s.env, g, Global(s.env))); + EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, created.module), napi_ok); +} + +TEST_F(Test66UnofficialRealm, BytecodeIsOpenedForARealm) { + EnvScope s(runtime_.get()); + napi_value realm_global = nullptr; + unofficial_napi_realm realm = CreateRealm(s.env, &realm_global); + ASSERT_NE(realm, nullptr); + + napi_value undefined = nullptr; + ASSERT_EQ(napi_get_undefined(s.env, &undefined), napi_ok); + unofficial_napi_bytecode_open_options options{}; + options.size = sizeof(options); + options.version = UNOFFICIAL_NAPI_BYTECODE_OPEN_OPTIONS_VERSION; + options.source_text = Str(s.env, "globalThis"); + options.filename = Str(s.env, "bytecode.js"); + options.shape = unofficial_napi_bytecode_shape_script; + options.params_or_undefined = undefined; + options.host_defined_option_id = undefined; + unofficial_napi_bytecode_open_result opened{}; + + unofficial_napi_bytecode_open_options v1 = options; + v1.version = 1; + EXPECT_EQ(unofficial_napi_bytecode_open(s.env, &v1, &opened), napi_invalid_arg); + + for (unofficial_napi_realm target : {realm, static_cast(nullptr)}) { + options.realm_or_null = target; + opened = {}; + ASSERT_EQ(unofficial_napi_bytecode_open(s.env, &options, &opened), napi_ok); + ASSERT_NE(opened.bytecode, nullptr); + const unofficial_napi_js_source source = + unofficial_napi_js_source_from_bytecode(opened.bytecode); + napi_value result = nullptr; + ASSERT_EQ(unofficial_napi_run_script(s.env, target, &source, Str(s.env, "bytecode.js"), 0, 0, + -1, true, false, false, nullptr, &result), + napi_ok); + EXPECT_TRUE(StrictEquals(s.env, result, target != nullptr ? realm_global : Global(s.env))); + EXPECT_EQ(unofficial_napi_bytecode_release(s.env, opened.bytecode), napi_ok); + } +} + +// An exception thrown in a realm is pending on the env afterwards. +TEST_F(Test66UnofficialRealm, ExceptionsInARealmArePendingOnTheEnv) { + EnvScope s(runtime_.get()); + unofficial_napi_realm realm = CreateRealm(s.env); + ASSERT_NE(realm, nullptr); + + const unofficial_napi_js_source script = + unofficial_napi_js_source_from_text(Str(s.env, "throw new Error('inside realm')")); + napi_value result = nullptr; + EXPECT_EQ(unofficial_napi_run_script(s.env, realm, &script, Str(s.env, "throw.js"), 0, 0, -1, + true, false, false, nullptr, &result), + napi_pending_exception); + bool pending = false; + ASSERT_EQ(napi_is_exception_pending(s.env, &pending), napi_ok); + ASSERT_TRUE(pending); + napi_value error = nullptr; + ASSERT_EQ(napi_get_and_clear_last_exception(s.env, &error), napi_ok); + napi_value message = nullptr; + ASSERT_EQ(napi_get_named_property(s.env, error, "message", &message), napi_ok); + EXPECT_EQ(Utf8(s.env, message), "inside realm"); +} + +// The env's hooks fire for code running in any of its realms. +TEST_F(Test66UnofficialRealm, PromiseRejectCallbackFiresForRealms) { + EnvScope s(runtime_.get()); + unofficial_napi_realm realm = CreateRealm(s.env); + ASSERT_NE(realm, nullptr); + + napi_value callback = Eval(s.env, + "globalThis.rejections = 0;" + "(event) => { if (event === 0) rejections++; }"); + ASSERT_NE(callback, nullptr); + ASSERT_EQ(unofficial_napi_set_promise_reject_callback(s.env, callback), napi_ok); + + ASSERT_NE(Eval(s.env, "Promise.reject(1); 0"), nullptr); + ASSERT_NE(RunIn(s.env, realm, "Promise.reject(2); 0"), nullptr); + EXPECT_EQ(Int32(s.env, Eval(s.env, "rejections")), 2); +} + +// A realm lives while its global, or anything made in it, is reachable, and +// is collected with it. +TEST_F(Test66UnofficialRealm, RealmIsCollectedWithItsGlobal) { + EnvScope s(runtime_.get()); + + // Realms over a sandbox, with and without their own microtask queue, and + // realms with a fresh global. + constexpr int kRealms = 9; + napi_ref globals[kRealms] = {}; + for (int i = 0; i < kRealms; ++i) { + napi_handle_scope scope = nullptr; + ASSERT_EQ(napi_open_handle_scope(s.env, &scope), napi_ok); + napi_value sandbox = nullptr; + if (i % 3 != 2) ASSERT_EQ(napi_create_object(s.env, &sandbox), napi_ok); + napi_value global = nullptr; + unofficial_napi_realm realm = CreateRealm(s.env, &global, sandbox, i % 3 == 0); + ASSERT_NE(realm, nullptr); + ASSERT_NE(RunIn(s.env, realm, "globalThis.payload = new Array(4096).fill(1); 1"), nullptr); + ASSERT_EQ(napi_create_reference(s.env, global, 0, &globals[i]), napi_ok); + ASSERT_EQ(napi_close_handle_scope(s.env, scope), napi_ok); + } + + // A sandbox still referenced keeps its realm. + napi_ref kept = nullptr; + { + napi_handle_scope scope = nullptr; + ASSERT_EQ(napi_open_handle_scope(s.env, &scope), napi_ok); + napi_value sandbox = nullptr; + ASSERT_EQ(napi_create_object(s.env, &sandbox), napi_ok); + unofficial_napi_realm realm = CreateRealm(s.env, nullptr, sandbox); + ASSERT_NE(realm, nullptr); + ASSERT_NE(RunIn(s.env, realm, "globalThis.marker = 42; 1"), nullptr); + ASSERT_EQ(napi_create_reference(s.env, sandbox, 1, &kept), napi_ok); + ASSERT_EQ(napi_close_handle_scope(s.env, scope), napi_ok); + } + + ASSERT_EQ(unofficial_napi_collect_garbage(s.env), napi_ok); + for (napi_ref global : globals) { + EXPECT_TRUE(IsCollected(s.env, global)); + ASSERT_EQ(napi_delete_reference(s.env, global), napi_ok); + } + + // Making more realms releases what the collected ones left behind. + for (int i = 0; i < 4; ++i) { + napi_handle_scope scope = nullptr; + ASSERT_EQ(napi_open_handle_scope(s.env, &scope), napi_ok); + ASSERT_NE(CreateRealm(s.env), nullptr); + ASSERT_EQ(napi_close_handle_scope(s.env, scope), napi_ok); + } + + napi_value sandbox = nullptr; + ASSERT_EQ(napi_get_reference_value(s.env, kept, &sandbox), napi_ok); + ASSERT_NE(sandbox, nullptr); + unofficial_napi_realm realm = nullptr; + ASSERT_EQ(unofficial_napi_get_realm(s.env, sandbox, &realm), napi_ok); + ASSERT_NE(realm, nullptr); + EXPECT_EQ(Int32(s.env, RunIn(s.env, realm, "marker")), 42); + ASSERT_EQ(napi_delete_reference(s.env, kept), napi_ok); +} + +// A realm stays usable while anything made in it is reachable, after its +// global's handle is gone and the provider released collected realms. +TEST_F(Test66UnofficialRealm, RealmOutlivesItsGlobalHandleWhileReachable) { + EnvScope s(runtime_.get()); + + napi_ref functions = nullptr; + napi_ref weak_sandbox = nullptr; + { + napi_handle_scope scope = nullptr; + ASSERT_EQ(napi_open_handle_scope(s.env, &scope), napi_ok); + napi_value sandbox = nullptr; + ASSERT_EQ(napi_create_object(s.env, &sandbox), napi_ok); + unofficial_napi_realm realm = CreateRealm(s.env, nullptr, sandbox, true); + ASSERT_NE(realm, nullptr); + napi_value made = RunIn(s.env, realm, + "globalThis.state = 0;" + "[() => { Promise.resolve().then(() => { state++; }); return 7; }]"); + ASSERT_NE(made, nullptr); + ASSERT_EQ(napi_create_reference(s.env, made, 1, &functions), napi_ok); + ASSERT_EQ(napi_create_reference(s.env, sandbox, 0, &weak_sandbox), napi_ok); + ASSERT_EQ(napi_close_handle_scope(s.env, scope), napi_ok); + } + + ASSERT_EQ(unofficial_napi_collect_garbage(s.env), napi_ok); + for (int i = 0; i < 4; ++i) { + napi_handle_scope scope = nullptr; + ASSERT_EQ(napi_open_handle_scope(s.env, &scope), napi_ok); + napi_value other = nullptr; + ASSERT_EQ(napi_create_object(s.env, &other), napi_ok); + ASSERT_NE(CreateRealm(s.env, nullptr, other, true), nullptr); + ASSERT_EQ(napi_close_handle_scope(s.env, scope), napi_ok); + } + ASSERT_EQ(unofficial_napi_collect_garbage(s.env), napi_ok); + + { + napi_handle_scope scope = nullptr; + ASSERT_EQ(napi_open_handle_scope(s.env, &scope), napi_ok); + // The function keeps its realm, and so the sandbox, alive. + napi_value sandbox = nullptr; + ASSERT_EQ(napi_get_reference_value(s.env, weak_sandbox, &sandbox), napi_ok); + ASSERT_NE(sandbox, nullptr); + unofficial_napi_realm realm = nullptr; + ASSERT_EQ(unofficial_napi_get_realm(s.env, sandbox, &realm), napi_ok); + ASSERT_NE(realm, nullptr); + + napi_value array = nullptr, function = nullptr, undefined = nullptr, result = nullptr; + ASSERT_EQ(napi_get_reference_value(s.env, functions, &array), napi_ok); + ASSERT_EQ(napi_get_element(s.env, array, 0, &function), napi_ok); + ASSERT_EQ(napi_get_undefined(s.env, &undefined), napi_ok); + ASSERT_EQ(napi_call_function(s.env, undefined, function, 0, nullptr, &result), napi_ok); + EXPECT_EQ(Int32(s.env, result), 7); +#if defined(NAPI_TEST_ENGINE_V8) + // The microtask went to the realm's own queue, which drains after a + // script runs there. + ASSERT_NE(RunIn(s.env, realm, "0"), nullptr); + EXPECT_EQ(Int32(s.env, RunIn(s.env, realm, "state")), 1); +#endif + ASSERT_EQ(napi_close_handle_scope(s.env, scope), napi_ok); + } + + // Once nothing made in the realm is reachable, it is collected. + ASSERT_EQ(napi_delete_reference(s.env, functions), napi_ok); + ASSERT_EQ(unofficial_napi_collect_garbage(s.env), napi_ok); + EXPECT_TRUE(IsCollected(s.env, weak_sandbox)); + ASSERT_EQ(napi_delete_reference(s.env, weak_sandbox), napi_ok); +} + +#if defined(NAPI_TEST_ENGINE_V8) +namespace { + +struct ImportProbe { + napi_env env = nullptr; + std::string specifier; +}; + +napi_value ProbeDynamicImport(napi_env env, napi_callback_info info) { + size_t argc = 2; + napi_value argv[2] = {nullptr, nullptr}; + void* data = nullptr; + if (napi_get_cb_info(env, info, &argc, argv, nullptr, &data) != napi_ok || argc < 2) { + return nullptr; + } + auto* probe = static_cast(data); + probe->env = env; + probe->specifier = Utf8(env, argv[1]); + napi_value result = nullptr; + napi_create_object(env, &result); + return result; +} + +} // namespace + +TEST_F(Test66UnofficialRealm, DynamicImportInARealmUsesTheEnvsHook) { + EnvScope s(runtime_.get()); + unofficial_napi_realm realm = CreateRealm(s.env); + ASSERT_NE(realm, nullptr); + + ImportProbe probe; + napi_value callback = nullptr; + ASSERT_EQ(napi_create_function(s.env, "import", NAPI_AUTO_LENGTH, ProbeDynamicImport, &probe, + &callback), + napi_ok); + const unofficial_napi_module_hooks hooks = { + sizeof(unofficial_napi_module_hooks), UNOFFICIAL_NAPI_MODULE_HOOKS_VERSION, callback, + nullptr}; + ASSERT_EQ(unofficial_napi_module_wrap_set_hooks(s.env, &hooks), napi_ok); + ASSERT_NE(RunIn(s.env, realm, "import('from-realm'); 0"), nullptr); + EXPECT_EQ(probe.env, s.env); + EXPECT_EQ(probe.specifier, "from-realm"); +} + +TEST_F(Test66UnofficialRealm, PrepareStackTraceCallbackRunsForRealms) { + EnvScope s(runtime_.get()); + unofficial_napi_realm realm = CreateRealm(s.env); + ASSERT_NE(realm, nullptr); + + ASSERT_EQ(unofficial_napi_set_prepare_stack_trace_callback( + s.env, Eval(s.env, "() => 'prepared stack'")), + napi_ok); + EXPECT_EQ(Utf8(s.env, RunIn(s.env, realm, "new Error('x').stack")), "prepared stack"); + EXPECT_EQ(Utf8(s.env, Eval(s.env, "new Error('x').stack")), "prepared stack"); +} + +TEST_F(Test66UnofficialRealm, OwnMicrotaskQueueDrainsAfterEvaluationInTheRealm) { + EnvScope s(runtime_.get()); + unofficial_napi_realm realm = CreateRealm(s.env, nullptr, nullptr, true); + ASSERT_NE(realm, nullptr); + EXPECT_EQ(Int32(s.env, RunIn(s.env, realm, + "globalThis.ran = 0; Promise.resolve().then(() => { ran = 1; }); 0")), + 0); + EXPECT_EQ(Int32(s.env, RunIn(s.env, realm, "ran")), 1); +} +#endif From f2c058176e01cd7e36ff211a16bbeedbf8c71066 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Sun, 25 Oct 2026 10:03:31 +0100 Subject: [PATCH 010/150] V8: realm handles with collectable realms - create_realm makes a context and a realm record the env owns; the context's embedder-data slot 33 points at the record, so get_realm is a creation-context lookup and needs no scan. - The record holds its context weakly (as #109 does for contextify records): a realm lives while its global, or anything made in it, is reachable. The next create_realm frees records of collected realms, and only then their own microtask queues. - run_script, compile_function, module creation and bytecode_open take a realm; NULL is the env's context. - The sandbox-keyed context records, their linear scans, make_context and the context-token hooks are gone. Co-Authored-By: Claude Opus 5.5 --- v8/src/internal/napi_v8_agent.h | 3 - v8/src/internal/napi_v8_env.h | 13 + v8/src/unofficial_napi.cc | 3 - v8/src/unofficial_napi_contextify.cc | 351 ++++++++++----------------- 4 files changed, 147 insertions(+), 223 deletions(-) diff --git a/v8/src/internal/napi_v8_agent.h b/v8/src/internal/napi_v8_agent.h index 9980781a78..2d14ea394a 100644 --- a/v8/src/internal/napi_v8_agent.h +++ b/v8/src/internal/napi_v8_agent.h @@ -52,9 +52,6 @@ struct napi_agent__ { bool embedder_hooks_attached = false; unofficial_napi_fatal_error_callback fatal_error_callback = nullptr; unofficial_napi_oom_error_callback oom_error_callback = nullptr; - unofficial_napi_context_token_callback context_token_assign_callback = nullptr; - unofficial_napi_context_token_callback context_token_unassign_callback = nullptr; - void* context_token_callback_data = nullptr; unofficial_napi_enqueue_foreground_task_callback enqueue_foreground_task_callback = nullptr; void* enqueue_foreground_task_target = nullptr; diff --git a/v8/src/internal/napi_v8_env.h b/v8/src/internal/napi_v8_env.h index ba585fa779..270776e5d0 100644 --- a/v8/src/internal/napi_v8_env.h +++ b/v8/src/internal/napi_v8_env.h @@ -57,6 +57,17 @@ struct napi_callback_info__ { virtual void* data() const = 0; }; +// A realm made with unofficial_napi_create_realm (a vm context). Its context +// is held weakly: the realm lives while its global, or anything made in it, +// is reachable. The env frees the record once the context is gone, and only +// then the realm's own microtask queue, which V8 holds by raw pointer for the +// context's lifetime. +struct unofficial_napi_realm__ { + napi_env env = nullptr; + v8::Global context; + std::unique_ptr own_microtask_queue; +}; + struct napi_env__ { explicit napi_env__(v8::Local context, int32_t module_api_version); ~napi_env__(); @@ -114,6 +125,8 @@ struct napi_env__ { // unofficial_napi_set_promise_hooks (init, before, after, resolve). v8::Global promise_reject_callback; std::array, 4> promise_hooks; + // The realms this env made, live or awaiting release. + std::vector> realms; #if defined(NAPI_ENABLE_LIFETIME_TRACKER) && defined(NAPI_ENABLE_LIFETIME_PERIODIC_STATS) napi::periodic_gate__ lifetime_stats_gate_{2000}; diff --git a/v8/src/unofficial_napi.cc b/v8/src/unofficial_napi.cc index 00123dc5a0..caeee116ad 100644 --- a/v8/src/unofficial_napi.cc +++ b/v8/src/unofficial_napi.cc @@ -1680,9 +1680,6 @@ napi_status NAPI_CDECL unofficial_napi_attach_env( napi_agent__* agent = env->agent; agent->fatal_error_callback = hooks->fatal_error_callback; agent->oom_error_callback = hooks->oom_error_callback; - agent->context_token_assign_callback = hooks->context_token_assign_callback; - agent->context_token_unassign_callback = hooks->context_token_unassign_callback; - agent->context_token_callback_data = hooks->data; agent->enqueue_foreground_task_callback = hooks->enqueue_foreground_task_callback; agent->enqueue_foreground_task_target = hooks->data; agent->embedder_hooks_attached = true; diff --git a/v8/src/unofficial_napi_contextify.cc b/v8/src/unofficial_napi_contextify.cc index 0ded77d73d..240f775ae9 100644 --- a/v8/src/unofficial_napi_contextify.cc +++ b/v8/src/unofficial_napi_contextify.cc @@ -40,15 +40,9 @@ namespace { constexpr int kHostDefinedOptionsId = 8; constexpr int kHostDefinedOptionsLength = 9; -struct ContextRecord { - napi_ref key_ref = nullptr; - v8::Global context; - std::unique_ptr own_microtask_queue; -}; - -std::mutex g_context_mu; -std::unordered_map> g_context_records; -std::unordered_set g_context_cleanup_hooks; +// Context embedder-data slot that points at a realm's record. Kept clear of +// the low slots V8 and debuggers use. +constexpr int kRealmContextSlot = 33; struct SavedOwnProperty { v8::Global key; @@ -782,37 +776,6 @@ bool RestoreOwnProperties(v8::Isolate* isolate, return true; } -void CleanupContextRecords(void* arg) { - napi_env env = static_cast(arg); - - std::lock_guard lock(g_context_mu); - g_context_cleanup_hooks.erase(env); - auto it = g_context_records.find(env); - if (it == g_context_records.end()) return; - for (auto& rec : it->second) { - if (rec.key_ref != nullptr && env->agent != nullptr && - env->agent->context_token_unassign_callback != nullptr) { - env->agent->context_token_unassign_callback( - env, rec.key_ref, env->agent->context_token_callback_data); - } - if (rec.key_ref != nullptr) { - napi_delete_reference(env, rec.key_ref); - rec.key_ref = nullptr; - } - rec.context.Reset(); - rec.own_microtask_queue.reset(); - } - g_context_records.erase(it); -} - -void EnsureContextCleanupHook(napi_env env) { - auto [it, inserted] = g_context_cleanup_hooks.emplace(env); - if (!inserted) return; - if (napi_add_env_cleanup_hook(env, CleanupContextRecords, env) != napi_ok) { - g_context_cleanup_hooks.erase(it); - } -} - void CleanupModuleWrapState(void* arg) { napi_env env = static_cast(arg); @@ -847,21 +810,6 @@ void EnsureModuleWrapCleanupHook(napi_env env) { } } -ContextRecord* FindRecordByKey(napi_env env, napi_value key) { - auto it = g_context_records.find(env); - if (it == g_context_records.end()) return nullptr; - for (auto& rec : it->second) { - if (rec.key_ref == nullptr) continue; - napi_value candidate = nullptr; - if (napi_get_reference_value(env, rec.key_ref, &candidate) != napi_ok || candidate == nullptr) continue; - bool same = false; - if (napi_strict_equals(env, candidate, key, &same) == napi_ok && same) { - return &rec; - } - } - return nullptr; -} - napi_value GetRefValue(napi_env env, napi_ref ref) { if (env == nullptr || ref == nullptr) return nullptr; napi_value out = nullptr; @@ -1313,39 +1261,30 @@ v8::MaybeLocal LinkRequiredFacadeOriginal(v8::Local con return state->temporary_required_module_facade_original->module.Get(context->GetIsolate()); } -bool StoreRecord(napi_env env, - napi_value key, - v8::Local context, - std::unique_ptr own_microtask_queue) { - EnsureContextCleanupHook(env); - - ContextRecord record; - if (napi_create_reference(env, key, 1, &record.key_ref) != napi_ok || record.key_ref == nullptr) { - return false; - } - record.context.Reset(env->isolate, context); - record.own_microtask_queue = std::move(own_microtask_queue); - if (env->agent != nullptr && env->agent->context_token_assign_callback != nullptr) { - env->agent->context_token_assign_callback( - env, record.key_ref, env->agent->context_token_callback_data); +// The realm whose context is `context`, or null for any other context. +unofficial_napi_realm RealmForContext(v8::Local context) { + if (context.IsEmpty() || + context->GetNumberOfEmbedderDataFields() <= static_cast(kRealmContextSlot)) { + return nullptr; } - g_context_records[env].push_back(std::move(record)); - return true; + return static_cast( + context->GetAlignedPointerFromEmbedderData(kRealmContextSlot)); } -bool ResolveContextFromKey(napi_env env, - napi_value key, - v8::Local* context_out, - v8::MicrotaskQueue** microtask_queue_out) { - if (context_out == nullptr || microtask_queue_out == nullptr) return false; - *microtask_queue_out = nullptr; - ContextRecord* rec = FindRecordByKey(env, key); - if (rec == nullptr) return false; - v8::Local context = rec->context.Get(env->isolate); - if (context.IsEmpty()) return false; - *context_out = context; - *microtask_queue_out = rec->own_microtask_queue ? rec->own_microtask_queue.get() : nullptr; - return true; +// The context code for `realm` runs in: the env's own for a null realm. +// Empty when the realm is not one of `env`'s or was collected. +v8::Local RealmContext(napi_env env, unofficial_napi_realm realm) { + if (realm == nullptr) return env->context(); + if (realm->env != env) return v8::Local(); + return realm->context.Get(env->isolate); +} + +// Frees the records of realms whose context was collected. +void ReleaseCollectedRealms(napi_env env) { + auto& realms = env->realms; + realms.erase(std::remove_if(realms.begin(), realms.end(), + [](const auto& realm) { return realm->context.IsEmpty(); }), + realms.end()); } bool CompileAsModule(v8::Isolate* isolate, @@ -1536,12 +1475,12 @@ v8::ScriptOrigin BytecodeOrigin(v8::Isolate* isolate, // from the produced code cache. Returns false on a compile error (exception // captured in try_catch). bool CompileBytecodeRecord(napi_env env, + v8::Local context, BytecodeRecord* record, v8::Local host_id_symbol, bool consume, bool* rejected_out) { v8::Isolate* isolate = env->isolate; - v8::Local context = env->context(); if (rejected_out != nullptr) *rejected_out = false; @@ -1633,105 +1572,85 @@ bool CompileBytecodeRecord(napi_env env, } // namespace bool NapiV8IsContextifyContext(napi_env env, v8::Local context) { - if (env == nullptr || env->isolate == nullptr || context.IsEmpty()) return false; - std::lock_guard lock(g_context_mu); - auto it = g_context_records.find(env); - if (it == g_context_records.end()) return false; - for (auto& rec : it->second) { - v8::Local candidate = rec.context.Get(env->isolate); - if (!candidate.IsEmpty() && candidate == context) { - return true; - } - } - return false; + unofficial_napi_realm realm = RealmForContext(context); + return realm != nullptr && realm->env == env; } void NapiV8ApplyPromiseHooksToContextifyContexts(napi_env env) { if (env == nullptr || env->isolate == nullptr) return; - - std::lock_guard lock(g_context_mu); - auto it = g_context_records.find(env); - if (it == g_context_records.end()) return; - - for (auto& rec : it->second) { - v8::Local context = rec.context.Get(env->isolate); - if (!context.IsEmpty()) { - NapiV8ApplyPromiseHooksToContext(env, context); - } + for (const auto& realm : env->realms) { + v8::Local context = realm->context.Get(env->isolate); + if (!context.IsEmpty()) NapiV8ApplyPromiseHooksToContext(env, context); } } extern "C" { -napi_status NAPI_CDECL unofficial_napi_contextify_make_context( +napi_status NAPI_CDECL unofficial_napi_create_realm( napi_env env, - napi_value sandbox_or_symbol, - napi_value name, - napi_value origin_or_undefined, - bool allow_code_gen_strings, - bool allow_code_gen_wasm, - bool own_microtask_queue, - napi_value host_defined_option_id, - napi_value* result_out) { - if (env == nullptr || sandbox_or_symbol == nullptr || name == nullptr || result_out == nullptr) { - return napi_invalid_arg; + const unofficial_napi_realm_options* options_or_null, + unofficial_napi_realm* realm_out, + napi_value* global_out) { + if (env == nullptr || realm_out == nullptr) return napi_invalid_arg; + unofficial_napi_realm_options options; + unofficial_napi_realm_options_init(&options); + if (options_or_null != nullptr) { + if (options_or_null->size < sizeof(options) || + options_or_null->version != UNOFFICIAL_NAPI_REALM_OPTIONS_VERSION) { + return napi_invalid_arg; + } + options = *options_or_null; } - (void)allow_code_gen_wasm; + *realm_out = nullptr; + ReleaseCollectedRealms(env); v8::Isolate* isolate = env->isolate; v8::EscapableHandleScope handle_scope(isolate); v8::Local current = env->context(); v8::Context::Scope current_scope(current); - napi_valuetype sandbox_type = napi_undefined; - if (napi_typeof(env, sandbox_or_symbol, &sandbox_type) != napi_ok) { - return napi_invalid_arg; - } - - const bool vanilla = sandbox_type == napi_symbol; - if (!vanilla && sandbox_type != napi_object && sandbox_type != napi_function) { - return napi_invalid_arg; + // A sandbox becomes the new realm's global and keeps its own properties. A + // sandbox belongs to one realm; the env's own global may still be one. + v8::Local sandbox; + if (options.sandbox_or_null != nullptr) { + v8::Local raw = napi_v8_unwrap_value(options.sandbox_or_null); + if (raw.IsEmpty() || !raw->IsObject()) return napi_object_expected; + sandbox = raw.As(); + v8::Local owner; + if (sandbox->GetCreationContext().ToLocal(&owner) && owner->Global() == sandbox && + RealmForContext(owner) != nullptr) { + return napi_invalid_arg; + } } v8::Local host_id_symbol; - if (host_defined_option_id != nullptr) { - v8::Local host_raw = napi_v8_unwrap_value(host_defined_option_id); + if (options.host_defined_option_id != nullptr) { + v8::Local host_raw = napi_v8_unwrap_value(options.host_defined_option_id); if (!host_raw.IsEmpty() && host_raw->IsSymbol()) { host_id_symbol = host_raw.As(); } } - std::unique_ptr own_queue; - v8::MicrotaskQueue* queue = nullptr; - if (own_microtask_queue) { - own_queue = v8::MicrotaskQueue::New(isolate, v8::MicrotasksPolicy::kExplicit); - queue = own_queue.get(); + auto realm = std::make_unique(); + realm->env = env; + if (options.own_microtask_queue) { + realm->own_microtask_queue = v8::MicrotaskQueue::New(isolate, v8::MicrotasksPolicy::kExplicit); } std::vector saved_properties; - v8::Local sandbox_object; v8::MaybeLocal maybe_global_object; - if (!vanilla) { - v8::Local sandbox_value = - napi_v8_unwrap_value(sandbox_or_symbol); - if (sandbox_value.IsEmpty() || !sandbox_value->IsObject()) { - return napi_invalid_arg; - } - sandbox_object = sandbox_value.As(); - + if (!sandbox.IsEmpty()) { // Reading a proxy's own keys or values may run JavaScript and throw. Keep // the exception boundary local to that operation: successful context // creation must retain V8's normal, uncaught lifecycle. v8::TryCatch try_catch(isolate); - if (!SnapshotOwnProperties( - isolate, current, sandbox_object, &saved_properties)) { + if (!SnapshotOwnProperties(isolate, current, sandbox, &saved_properties)) { if (try_catch.HasCaught() && !try_catch.HasTerminated()) { - napi_v8_set_last_exception( - env, try_catch.Exception(), try_catch.Message()); + napi_v8_set_last_exception(env, try_catch.Exception(), try_catch.Message()); } return napi_pending_exception; } - maybe_global_object = sandbox_value; + maybe_global_object = sandbox; } v8::Local context = @@ -1740,54 +1659,63 @@ napi_status NAPI_CDECL unofficial_napi_contextify_make_context( v8::MaybeLocal(), maybe_global_object, v8::DeserializeInternalFieldsCallback(), - queue); - - if (context.IsEmpty()) { - return napi_pending_exception; - } + realm->own_microtask_queue.get()); + if (context.IsEmpty()) return napi_pending_exception; context->SetSecurityToken(current->GetSecurityToken()); - context->AllowCodeGenerationFromStrings(allow_code_gen_strings); + context->AllowCodeGenerationFromStrings(options.allow_code_gen_strings); + context->SetAlignedPointerInEmbedderData(kRealmContextSlot, realm.get()); NapiV8ApplyPromiseHooksToContext(env, context); + realm->context.Reset(isolate, context); + realm->context.SetWeak(); + unofficial_napi_realm handle = realm.get(); + env->realms.push_back(std::move(realm)); - v8::Local key_object; - if (vanilla) { - key_object = context->Global(); - } else { - key_object = sandbox_object; - if (!RestoreOwnProperties( - isolate, context, key_object, saved_properties)) { - return napi_pending_exception; - } - } - - napi_value key_napi = napi_v8_wrap_value(env, handle_scope.Escape(key_object)); - if (key_napi == nullptr) return napi_generic_failure; - - { - std::lock_guard lock(g_context_mu); - if (FindRecordByKey(env, key_napi) != nullptr) { - return napi_invalid_arg; - } - if (!StoreRecord(env, key_napi, context, std::move(own_queue))) { - return napi_generic_failure; - } + v8::Local global = sandbox.IsEmpty() ? context->Global() : sandbox; + if (!sandbox.IsEmpty() && !RestoreOwnProperties(isolate, context, sandbox, saved_properties)) { + return napi_pending_exception; } // Align with lib internal/vm.js isContext() checks in Edge. - v8::Local property_context = vanilla ? context : current; - SetApiPrivate(property_context, key_object, "node:contextify:context", key_object); + v8::Local property_context = sandbox.IsEmpty() ? context : current; + SetApiPrivate(property_context, global, "node:contextify:context", global); SetApiPrivate(property_context, - key_object, + global, "node:host_defined_option_symbol", host_id_symbol.IsEmpty() ? v8::Undefined(isolate) : host_id_symbol.As()); - *result_out = key_napi; + // The global stays in the caller's handle scope, which keeps the realm, and + // so the handle, valid while that scope is open. + napi_value global_napi = napi_v8_wrap_value(env, handle_scope.Escape(global)); + if (global_napi == nullptr) return napi_generic_failure; + if (global_out != nullptr) *global_out = global_napi; + *realm_out = handle; + return napi_ok; +} + +napi_status NAPI_CDECL unofficial_napi_get_realm(napi_env env, + napi_value value, + unofficial_napi_realm* realm_out) { + if (env == nullptr || value == nullptr || realm_out == nullptr) return napi_invalid_arg; + *realm_out = nullptr; + v8::Local raw = napi_v8_unwrap_value(value); + if (raw.IsEmpty() || !raw->IsObject()) return napi_object_expected; + // A sandbox becomes its realm's global, so both resolve through the + // creation context. + v8::HandleScope handle_scope(env->isolate); + v8::Local object = raw.As(); + v8::Local context; + if (!object->GetCreationContext().ToLocal(&context) || context->Global() != object) { + return napi_ok; + } + unofficial_napi_realm realm = RealmForContext(context); + if (realm != nullptr && realm->env == env) *realm_out = realm; return napi_ok; } static napi_status BytecodeCompile( napi_env env, + v8::Local context, napi_value source_text, napi_value filename, int32_t shape, @@ -1805,7 +1733,6 @@ static napi_status BytecodeCompile( v8::Isolate* isolate = env->isolate; v8::HandleScope handle_scope(isolate); - v8::Local context = env->context(); v8::Context::Scope context_scope(context); auto record = std::make_unique(); @@ -1824,7 +1751,7 @@ static napi_status BytecodeCompile( } } v8::TryCatch try_catch(isolate); - if (!CompileBytecodeRecord(env, record.get(), host_id_symbol, /*consume=*/false, nullptr)) { + if (!CompileBytecodeRecord(env, context, record.get(), host_id_symbol, /*consume=*/false, nullptr)) { if (try_catch.HasCaught() && !try_catch.HasTerminated()) { if (can_parse_as_module_out != nullptr && shape != unofficial_napi_bytecode_shape_module && !try_catch.Message().IsEmpty()) { @@ -1854,6 +1781,7 @@ static napi_status BytecodeCompile( static napi_status BytecodeDeserialize( napi_env env, + v8::Local context, const uint8_t* bytes, size_t byte_length, napi_value source_text, @@ -1872,7 +1800,6 @@ static napi_status BytecodeDeserialize( v8::Isolate* isolate = env->isolate; v8::HandleScope handle_scope(isolate); - v8::Local context = env->context(); v8::Context::Scope context_scope(context); auto record = std::make_unique(); @@ -1891,7 +1818,7 @@ static napi_status BytecodeDeserialize( } bool rejected = false; v8::TryCatch try_catch(isolate); - if (!CompileBytecodeRecord(env, record.get(), host_id_symbol, /*consume=*/true, &rejected)) { + if (!CompileBytecodeRecord(env, context, record.get(), host_id_symbol, /*consume=*/true, &rejected)) { // The retained source is expected to be valid; a compile failure here // means the cache/source pairing is unusable. Report as a rejection. if (rejected_out != nullptr) *rejected_out = true; @@ -1919,11 +1846,15 @@ napi_status NAPI_CDECL unofficial_napi_bytecode_open( return napi_invalid_arg; } *result = {}; + v8::HandleScope handle_scope(env->isolate); + v8::Local context = RealmContext(env, options->realm_or_null); + if (context.IsEmpty()) return napi_invalid_arg; if (options->has_cache != 0 && options->cache_bytes != nullptr && options->cache_byte_length != 0) { bool rejected = false; const napi_status status = BytecodeDeserialize(env, + context, options->cache_bytes, options->cache_byte_length, options->source_text, @@ -1947,6 +1878,7 @@ napi_status NAPI_CDECL unofficial_napi_bytecode_open( } bool can_parse_as_module = false; const napi_status status = BytecodeCompile(env, + context, options->source_text, options->filename, options->shape, @@ -1989,9 +1921,9 @@ napi_status NAPI_CDECL unofficial_napi_bytecode_release( return napi_ok; } -napi_status NAPI_CDECL unofficial_napi_contextify_run_script( +napi_status NAPI_CDECL unofficial_napi_run_script( napi_env env, - napi_value sandbox_or_null, + unofficial_napi_realm realm_or_null, const unofficial_napi_js_source* source, napi_value filename, int32_t line_offset, @@ -2013,15 +1945,10 @@ napi_status NAPI_CDECL unofficial_napi_contextify_run_script( v8::Local current = env->context(); v8::Context::Scope current_scope(current); - v8::Local target_context = current; - v8::MicrotaskQueue* target_queue = nullptr; - - if (!IsNullish(env, sandbox_or_null)) { - std::lock_guard lock(g_context_mu); - if (!ResolveContextFromKey(env, sandbox_or_null, &target_context, &target_queue)) { - return napi_invalid_arg; - } - } + v8::Local target_context = RealmContext(env, realm_or_null); + if (target_context.IsEmpty()) return napi_invalid_arg; + v8::MicrotaskQueue* target_queue = + realm_or_null != nullptr ? realm_or_null->own_microtask_queue.get() : nullptr; BytecodeRecord* bytecode_record = BytecodeRecordFromSource(source); if (bytecode_record != nullptr && @@ -2144,13 +2071,13 @@ napi_status NAPI_CDECL unofficial_napi_contextify_run_script( return *result_out == nullptr ? napi_generic_failure : napi_ok; } -napi_status NAPI_CDECL unofficial_napi_contextify_compile_function( +napi_status NAPI_CDECL unofficial_napi_compile_function( napi_env env, + unofficial_napi_realm realm_or_null, const unofficial_napi_js_source* source, napi_value filename, int32_t line_offset, int32_t column_offset, - napi_value parsing_context_or_undefined, napi_value context_extensions_or_undefined, napi_value params_or_undefined, napi_value host_defined_option_id, @@ -2165,14 +2092,8 @@ napi_status NAPI_CDECL unofficial_napi_contextify_compile_function( v8::Local current = env->context(); v8::Context::Scope current_scope(current); - v8::Local parsing_context = current; - if (!IsNullish(env, parsing_context_or_undefined)) { - std::lock_guard lock(g_context_mu); - v8::MicrotaskQueue* ignored = nullptr; - if (!ResolveContextFromKey(env, parsing_context_or_undefined, &parsing_context, &ignored)) { - return napi_invalid_arg; - } - } + v8::Local parsing_context = RealmContext(env, realm_or_null); + if (parsing_context.IsEmpty()) return napi_invalid_arg; BytecodeRecord* bytecode_record = BytecodeRecordFromSource(source); if (bytecode_record != nullptr && @@ -2382,7 +2303,7 @@ static napi_status CreateSourceTextModule( napi_env env, napi_value wrapper, napi_value url, - napi_value context_or_undefined, + unofficial_napi_realm realm_or_null, const unofficial_napi_js_source* source, int32_t line_offset, int32_t column_offset, @@ -2398,10 +2319,8 @@ static napi_status CreateSourceTextModule( EnsureModuleWrapCleanupHook(env); v8::Isolate* isolate = env->isolate; v8::HandleScope handle_scope(isolate); - v8::Local context = - !IsNullish(env, context_or_undefined) && napi_v8_unwrap_value(context_or_undefined)->IsObject() - ? napi_v8_unwrap_value(context_or_undefined).As()->GetCreationContextChecked() - : env->context(); + v8::Local context = RealmContext(env, realm_or_null); + if (context.IsEmpty()) return napi_invalid_arg; v8::Context::Scope context_scope(context); BytecodeRecord* bytecode_record = BytecodeRecordFromSource(source); @@ -2518,7 +2437,7 @@ static napi_status CreateSyntheticModule( napi_env env, napi_value wrapper, napi_value url, - napi_value context_or_undefined, + unofficial_napi_realm realm_or_null, napi_value export_names, napi_value synthetic_eval_steps, unofficial_napi_module* module_out) { @@ -2534,10 +2453,8 @@ static napi_status CreateSyntheticModule( EnsureModuleWrapCleanupHook(env); v8::Isolate* isolate = env->isolate; v8::HandleScope handle_scope(isolate); - v8::Local context = - !IsNullish(env, context_or_undefined) && napi_v8_unwrap_value(context_or_undefined)->IsObject() - ? napi_v8_unwrap_value(context_or_undefined).As()->GetCreationContextChecked() - : env->context(); + v8::Local context = RealmContext(env, realm_or_null); + if (context.IsEmpty()) return napi_invalid_arg; v8::Context::Scope context_scope(context); uint32_t export_count = 0; @@ -2590,7 +2507,7 @@ napi_status NAPI_CDECL unofficial_napi_module_wrap_create( env, options->wrapper, options->url, - options->context_or_undefined, + options->realm_or_null, options->payload.source_text.source, options->payload.source_text.line_offset, options->payload.source_text.column_offset, @@ -2602,7 +2519,7 @@ napi_status NAPI_CDECL unofficial_napi_module_wrap_create( env, options->wrapper, options->url, - options->context_or_undefined, + options->realm_or_null, options->payload.synthetic.export_names, options->payload.synthetic.synthetic_evaluation_steps, &result_out->module); From 2d3e4c760872408ef2677033d411cef2de241176 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Sun, 25 Oct 2026 10:17:27 +0100 Subject: [PATCH 011/150] Say that two handles for one realm may differ In the guest ABI a realm handle is a value id, so like napi_values two handles for one realm can differ. The header says so, and the tests compare realms by their globals instead of by handle. Co-Authored-By: Claude Opus 5.5 --- include/unofficial_napi.h | 5 +++-- tests/programs/test_realm.c | 12 +++++++++--- tests/runners/test_66_unofficial_realm.cc | 11 +++++++++-- 3 files changed, 21 insertions(+), 7 deletions(-) diff --git a/include/unofficial_napi.h b/include/unofficial_napi.h index a3c5703964..3c12046c97 100644 --- a/include/unofficial_napi.h +++ b/include/unofficial_napi.h @@ -140,8 +140,9 @@ NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_release_env( // // A realm lives while its global (the sandbox, when it has one) or anything // made in it is reachable, and is then collected. A realm handle, like a -// napi_value, is valid only while the handle scope it was obtained in is open; -// unofficial_napi_get_realm finds the realm again from its global. +// napi_value, is valid only while the handle scope it was obtained in is open, +// and two handles for one realm may differ; unofficial_napi_get_realm finds +// the realm again from its global. typedef struct unofficial_napi_realm__* unofficial_napi_realm; enum { UNOFFICIAL_NAPI_REALM_OPTIONS_VERSION = 1 }; diff --git a/tests/programs/test_realm.c b/tests/programs/test_realm.c index 4e35fd83fe..cf5aecea76 100644 --- a/tests/programs/test_realm.c +++ b/tests/programs/test_realm.c @@ -141,9 +141,15 @@ int main(void) { printf("native function stays in the env's realm\n"); // get_realm finds a realm by its global; the env's own global is not one. + // Like napi_values, two handles for one realm may differ, so the check runs + // code through the handle found. unofficial_napi_realm found = NULL; + napi_value found_global = NULL; NAPI_CALL(env, unofficial_napi_get_realm(env, realm_global, &found)); - CHECK_OR_FAIL(found == realm, "get_realm(realm global) did not return the realm"); + CHECK_OR_FAIL(found != NULL, "get_realm(realm global) found no realm"); + NAPI_CALL(env, RunIn(env, found, "globalThis", &found_global)); + CHECK_OR_FAIL(StrictEquals(env, found_global, realm_global), + "get_realm(realm global) returned another realm"); found = realm; NAPI_CALL(env, unofficial_napi_get_realm(env, env_global, &found)); CHECK_OR_FAIL(found == NULL, "get_realm(env global) returned a realm"); @@ -165,9 +171,9 @@ int main(void) { "create_realm did not return the sandbox as the global"); found = NULL; NAPI_CALL(env, unofficial_napi_get_realm(env, sandbox, &found)); - CHECK_OR_FAIL(found == sandbox_realm, "get_realm(sandbox) did not return its realm"); + CHECK_OR_FAIL(found != NULL, "get_realm(sandbox) found no realm"); int32_t input = 0; - NAPI_CALL(env, RunInInt32(env, sandbox_realm, "output = input * 2; input", &input)); + NAPI_CALL(env, RunInInt32(env, found, "output = input * 2; input", &input)); napi_value output_value = NULL; int32_t output = 0; NAPI_CALL(env, napi_get_named_property(env, sandbox, "output", &output_value)); diff --git a/tests/runners/test_66_unofficial_realm.cc b/tests/runners/test_66_unofficial_realm.cc index f0988e95c5..f5579cffa9 100644 --- a/tests/runners/test_66_unofficial_realm.cc +++ b/tests/runners/test_66_unofficial_realm.cc @@ -83,6 +83,12 @@ unofficial_napi_realm CreateRealm(napi_env env, return realm; } +// Two handles for one realm may differ, so realms compare by their globals. +bool SameRealm(napi_env env, unofficial_napi_realm a, unofficial_napi_realm b) { + return a != nullptr && b != nullptr && + StrictEquals(env, RunIn(env, a, "globalThis"), RunIn(env, b, "globalThis")); +} + bool IsCollected(napi_env env, napi_ref ref) { napi_value value = nullptr; return napi_get_reference_value(env, ref, &value) == napi_ok && value == nullptr; @@ -225,10 +231,11 @@ TEST_F(Test66UnofficialRealm, GetRealmFindsRealmsByTheirGlobal) { unofficial_napi_realm found = nullptr; ASSERT_EQ(unofficial_napi_get_realm(s.env, realm_global, &found), napi_ok); - EXPECT_EQ(found, realm); + EXPECT_TRUE(SameRealm(s.env, found, realm)); found = nullptr; ASSERT_EQ(unofficial_napi_get_realm(s.env, sandbox, &found), napi_ok); - EXPECT_EQ(found, sandbox_realm); + EXPECT_TRUE(SameRealm(s.env, found, sandbox_realm)); + EXPECT_FALSE(SameRealm(s.env, found, realm)); // The env's own global and other objects, functions included, are not a // realm's global. From 50c8d4fa94c5c7a220ac0d129343a1b6c1835020 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Sun, 25 Oct 2026 10:17:27 +0100 Subject: [PATCH 012/150] Bridge: realm ids are value ids of realm globals - snapi_bridge_unofficial_create_realm and _get_realm return the value id of the realm's global (or sandbox) as the realm id; run_script, compile_function, module creation and bytecode_open resolve it again with unofficial_napi_get_realm. The bridge keeps no realm table, and a realm id lives as long as its value id. - New guest imports unofficial_napi_create_realm, unofficial_napi_get_realm, unofficial_napi_run_script and unofficial_napi_compile_function; the contextify make_context, run_script and compile_function imports are gone. Co-Authored-By: Claude Opus 5.5 --- src/guest/napi.rs | 95 +++++++++++++++++++----------- src/napi_bridge_init.cc | 126 +++++++++++++++++++++++++--------------- 2 files changed, 139 insertions(+), 82 deletions(-) diff --git a/src/guest/napi.rs b/src/guest/napi.rs index 74db7faeb1..d52a370234 100644 --- a/src/guest/napi.rs +++ b/src/guest/napi.rs @@ -1113,46 +1113,71 @@ fn guest_unofficial_napi_contextify_contains_module_syntax( status } -#[allow(clippy::too_many_arguments)] -fn guest_unofficial_napi_contextify_make_context( +/// A guest realm id is the value id of the realm's global (or sandbox); 0 is +/// the env's own realm. See `snapi_bridge_unofficial_create_realm`. +fn guest_unofficial_napi_create_realm( mut env: FunctionEnvMut, napi_env: u32, - sandbox_or_symbol: u32, - name: u32, - origin_or_undefined: u32, - allow_code_gen_strings: i32, - allow_code_gen_wasm: i32, - own_microtask_queue: i32, - host_defined_option_id: u32, - result_ptr: u32, + options_ptr: u32, + realm_out_ptr: u32, + global_out_ptr: u32, ) -> i32 { + let Some(options) = abi::read_realm_options(&mut env, options_ptr) else { + return 1; + }; + if realm_out_ptr == 0 { + return 1; + } let env_handle = snapi_env(&env, napi_env); - let mut result_id = 0u32; + let mut realm_id = 0u32; + let mut global_id = 0u32; let status = unsafe { - snapi_bridge_unofficial_contextify_make_context( + snapi_bridge_unofficial_create_realm( env_handle, - sandbox_or_symbol, - name, - origin_or_undefined, - allow_code_gen_strings, - allow_code_gen_wasm, - own_microtask_queue, - host_defined_option_id, - &mut result_id, + options.sandbox_or_null, + options.name, + options.origin, + options.host_defined_option_id, + i32::from(options.allow_code_gen_strings), + i32::from(options.allow_code_gen_wasm), + i32::from(options.own_microtask_queue), + &mut realm_id, + &mut global_id, ) }; - if status == 0 && result_ptr != 0 { - write_guest_u32(&mut env, result_ptr, result_id); + if status == 0 { + write_guest_u32(&mut env, realm_out_ptr, realm_id); + if global_out_ptr != 0 { + write_guest_u32(&mut env, global_out_ptr, global_id); + } + } + status +} + +fn guest_unofficial_napi_get_realm( + mut env: FunctionEnvMut, + napi_env: u32, + value: u32, + realm_out_ptr: u32, +) -> i32 { + if realm_out_ptr == 0 { + return 1; + } + let env_handle = snapi_env(&env, napi_env); + let mut realm_id = 0u32; + let status = unsafe { snapi_bridge_unofficial_get_realm(env_handle, value, &mut realm_id) }; + if status == 0 { + write_guest_u32(&mut env, realm_out_ptr, realm_id); } status } #[allow(clippy::too_many_arguments)] #[allow(clippy::result_large_err)] -fn guest_unofficial_napi_contextify_run_script( +fn guest_unofficial_napi_run_script( mut env: FunctionEnvMut, napi_env: u32, - sandbox_or_null: u32, + realm: u32, source: u32, filename: u32, line_offset: i32, @@ -1170,9 +1195,9 @@ fn guest_unofficial_napi_contextify_run_script( let env_handle = snapi_env(&env, napi_env); let mut result_id = 0u32; let status = with_cb_context(&mut env, napi_env, || unsafe { - snapi_bridge_unofficial_contextify_run_script( + snapi_bridge_unofficial_run_script( env_handle, - sandbox_or_null, + realm, source_text, source_bytecode, filename, @@ -1193,14 +1218,14 @@ fn guest_unofficial_napi_contextify_run_script( } #[allow(clippy::too_many_arguments)] -fn guest_unofficial_napi_contextify_compile_function( +fn guest_unofficial_napi_compile_function( mut env: FunctionEnvMut, napi_env: u32, + realm: u32, source: u32, filename: u32, line_offset: i32, column_offset: i32, - parsing_context_or_undefined: u32, context_extensions_or_undefined: u32, params_or_undefined: u32, host_defined_option_id: u32, @@ -1212,14 +1237,14 @@ fn guest_unofficial_napi_contextify_compile_function( let env_handle = snapi_env(&env, napi_env); let mut result_id = 0u32; let status = unsafe { - snapi_bridge_unofficial_contextify_compile_function( + snapi_bridge_unofficial_compile_function( env_handle, + realm, source_text, source_bytecode, filename, line_offset, column_offset, - parsing_context_or_undefined, context_extensions_or_undefined, params_or_undefined, host_defined_option_id, @@ -1253,6 +1278,7 @@ fn guest_unofficial_napi_bytecode_open( let status = unsafe { snapi_bridge_unofficial_bytecode_open( env_handle, + options.realm_or_null, options.source_text, options.filename, options.shape, @@ -1328,7 +1354,7 @@ fn guest_unofficial_napi_module_wrap_create( options.kind, options.wrapper, options.url, - options.context_or_undefined, + options.realm_or_null, options.source_text, options.source_bytecode, options.line_offset, @@ -4911,9 +4937,10 @@ pub fn register_napi_imports( "unofficial_napi_take_heap_snapshot" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_take_heap_snapshot), "unofficial_napi_create_serdes_binding" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_create_serdes_binding), "unofficial_napi_contextify_contains_module_syntax" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_contextify_contains_module_syntax), - "unofficial_napi_contextify_make_context" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_contextify_make_context), - "unofficial_napi_contextify_run_script" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_contextify_run_script), - "unofficial_napi_contextify_compile_function" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_contextify_compile_function), + "unofficial_napi_create_realm" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_create_realm), + "unofficial_napi_get_realm" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_get_realm), + "unofficial_napi_run_script" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_run_script), + "unofficial_napi_compile_function" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_compile_function), "unofficial_napi_bytecode_open" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_bytecode_open), "unofficial_napi_bytecode_serialize" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_bytecode_serialize), "unofficial_napi_bytecode_release" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_bytecode_release), diff --git a/src/napi_bridge_init.cc b/src/napi_bridge_init.cc index 7c0dacd833..e5bf06eb21 100644 --- a/src/napi_bridge_init.cc +++ b/src/napi_bridge_init.cc @@ -3787,47 +3787,75 @@ extern "C" int snapi_bridge_unofficial_contextify_contains_module_syntax( return napi_ok; } -extern "C" int snapi_bridge_unofficial_contextify_make_context( - SnapiEnvState* env_state, - uint32_t sandbox_or_symbol_id, - uint32_t name_id, - uint32_t origin_id, - int allow_code_gen_strings, - int allow_code_gen_wasm, - int own_microtask_queue, - uint32_t host_defined_option_id, - uint32_t* result_out) { +// A guest realm id is the value id of the realm's global (its sandbox, when +// it has one); 0 is the env's own realm. Resolving it again on each call means +// the bridge keeps no realm table, and the id lives as long as its value id. +static bool ResolveRealm(SnapiEnvState& state, uint32_t realm_id, unofficial_napi_realm* realm_out) { + *realm_out = nullptr; + if (realm_id == 0) return true; + napi_value global = LoadValue(state, realm_id); + return global != nullptr && + unofficial_napi_get_realm(state.env, global, realm_out) == napi_ok && + *realm_out != nullptr; +} + +extern "C" int snapi_bridge_unofficial_create_realm(SnapiEnvState* env_state, + uint32_t sandbox_id, + uint32_t name_id, + uint32_t origin_id, + uint32_t host_defined_option_id, + int32_t allow_code_gen_strings, + int32_t allow_code_gen_wasm, + int32_t own_microtask_queue, + uint32_t* realm_out, + uint32_t* global_out) { + auto* bridge_state = RequireEnvState(env_state); + if (bridge_state == nullptr || realm_out == nullptr) return napi_invalid_arg; + std::lock_guard lock(g_mu); + // A nonzero id must resolve; 0 means the field is NULL. + auto load_optional = [bridge_state](uint32_t id, napi_value* out) { + *out = id == 0 ? nullptr : LoadValue(*bridge_state, id); + return id == 0 || *out != nullptr; + }; + unofficial_napi_realm_options options; + unofficial_napi_realm_options_init(&options); + if (!load_optional(sandbox_id, &options.sandbox_or_null) || + !load_optional(name_id, &options.name) || + !load_optional(origin_id, &options.origin) || + !load_optional(host_defined_option_id, &options.host_defined_option_id)) { + return napi_invalid_arg; + } + options.allow_code_gen_strings = allow_code_gen_strings != 0; + options.allow_code_gen_wasm = allow_code_gen_wasm != 0; + options.own_microtask_queue = own_microtask_queue != 0; + unofficial_napi_realm realm = nullptr; + napi_value global = nullptr; + napi_status s = unofficial_napi_create_realm(bridge_state->env, &options, &realm, &global); + if (s != napi_ok) return s; + const uint32_t global_id = StoreValue(*bridge_state, global); + *realm_out = global_id; + if (global_out != nullptr) *global_out = global_id; + return napi_ok; +} + +extern "C" int snapi_bridge_unofficial_get_realm(SnapiEnvState* env_state, + uint32_t value_id, + uint32_t* realm_out) { auto* bridge_state = RequireEnvState(env_state); - if (bridge_state == nullptr) return napi_invalid_arg; - napi_env env = bridge_state->env; + if (bridge_state == nullptr || realm_out == nullptr) return napi_invalid_arg; std::lock_guard lock(g_mu); - napi_value sandbox_or_symbol = LoadValue(*bridge_state, sandbox_or_symbol_id); - napi_value name = LoadValue(*bridge_state, name_id); - napi_value origin = origin_id == 0 ? nullptr : LoadValue(*bridge_state, origin_id); - napi_value host_defined_option = - host_defined_option_id == 0 ? nullptr : LoadValue(*bridge_state, host_defined_option_id); - if (sandbox_or_symbol == nullptr || name == nullptr) return napi_invalid_arg; - if (origin_id != 0 && origin == nullptr) return napi_invalid_arg; - if (host_defined_option_id != 0 && host_defined_option == nullptr) return napi_invalid_arg; - napi_value result = nullptr; - napi_status s = unofficial_napi_contextify_make_context( - env, - sandbox_or_symbol, - name, - origin, - allow_code_gen_strings != 0, - allow_code_gen_wasm != 0, - own_microtask_queue != 0, - host_defined_option, - &result); + napi_value value = LoadValue(*bridge_state, value_id); + if (value == nullptr) return napi_invalid_arg; + unofficial_napi_realm realm = nullptr; + napi_status s = unofficial_napi_get_realm(bridge_state->env, value, &realm); if (s != napi_ok) return s; - if (result_out != nullptr) *result_out = StoreValue(*bridge_state, result); + *realm_out = realm != nullptr ? value_id : 0; return napi_ok; } -extern "C" int snapi_bridge_unofficial_contextify_run_script( +extern "C" int snapi_bridge_unofficial_run_script( SnapiEnvState* env_state, - uint32_t sandbox_or_null_id, + uint32_t realm_id, uint32_t source_text_id, uint32_t source_bytecode_id, uint32_t filename_id, @@ -3843,23 +3871,23 @@ extern "C" int snapi_bridge_unofficial_contextify_run_script( if (bridge_state == nullptr) return napi_invalid_arg; napi_env env = bridge_state->env; std::lock_guard lock(g_mu); - napi_value sandbox_or_null = sandbox_or_null_id == 0 ? nullptr : LoadValue(*bridge_state, sandbox_or_null_id); + unofficial_napi_realm realm = nullptr; + if (!ResolveRealm(*bridge_state, realm_id, &realm)) return napi_invalid_arg; napi_value source_text = source_text_id == 0 ? nullptr : LoadValue(*bridge_state, source_text_id); unofficial_napi_bytecode source_bytecode = LoadBytecodeHandle(*bridge_state, source_bytecode_id); napi_value filename = LoadValue(*bridge_state, filename_id); napi_value host_defined_option = host_defined_option_id == 0 ? nullptr : LoadValue(*bridge_state, host_defined_option_id); - if (sandbox_or_null_id != 0 && sandbox_or_null == nullptr) return napi_invalid_arg; if ((source_text == nullptr && source_bytecode == nullptr) || filename == nullptr) return napi_invalid_arg; if (host_defined_option_id != 0 && host_defined_option == nullptr) return napi_invalid_arg; const unofficial_napi_js_source source = source_text != nullptr ? unofficial_napi_js_source_from_text(source_text) : unofficial_napi_js_source_from_bytecode(source_bytecode); napi_value result = nullptr; - napi_status s = unofficial_napi_contextify_run_script( + napi_status s = unofficial_napi_run_script( env, - sandbox_or_null, + realm, &source, filename, line_offset, @@ -3875,14 +3903,14 @@ extern "C" int snapi_bridge_unofficial_contextify_run_script( return napi_ok; } -extern "C" int snapi_bridge_unofficial_contextify_compile_function( +extern "C" int snapi_bridge_unofficial_compile_function( SnapiEnvState* env_state, + uint32_t realm_id, uint32_t source_text_id, uint32_t source_bytecode_id, uint32_t filename_id, int32_t line_offset, int32_t column_offset, - uint32_t parsing_context_id, uint32_t context_extensions_id, uint32_t params_id, uint32_t host_defined_option_id, @@ -3895,14 +3923,14 @@ extern "C" int snapi_bridge_unofficial_contextify_compile_function( unofficial_napi_bytecode source_bytecode = LoadBytecodeHandle(*bridge_state, source_bytecode_id); napi_value filename = LoadValue(*bridge_state, filename_id); - napi_value parsing_context = parsing_context_id == 0 ? nullptr : LoadValue(*bridge_state, parsing_context_id); + unofficial_napi_realm realm = nullptr; + if (!ResolveRealm(*bridge_state, realm_id, &realm)) return napi_invalid_arg; napi_value context_extensions = context_extensions_id == 0 ? nullptr : LoadValue(*bridge_state, context_extensions_id); napi_value params = params_id == 0 ? nullptr : LoadValue(*bridge_state, params_id); napi_value host_defined_option = host_defined_option_id == 0 ? nullptr : LoadValue(*bridge_state, host_defined_option_id); if ((source_text == nullptr && source_bytecode == nullptr) || filename == nullptr) return napi_invalid_arg; - if (parsing_context_id != 0 && parsing_context == nullptr) return napi_invalid_arg; if (context_extensions_id != 0 && context_extensions == nullptr) return napi_invalid_arg; if (params_id != 0 && params == nullptr) return napi_invalid_arg; if (host_defined_option_id != 0 && host_defined_option == nullptr) return napi_invalid_arg; @@ -3910,13 +3938,13 @@ extern "C" int snapi_bridge_unofficial_contextify_compile_function( ? unofficial_napi_js_source_from_text(source_text) : unofficial_napi_js_source_from_bytecode(source_bytecode); napi_value result = nullptr; - napi_status s = unofficial_napi_contextify_compile_function( + napi_status s = unofficial_napi_compile_function( env, + realm, &source, filename, line_offset, column_offset, - parsing_context, context_extensions, params, host_defined_option, @@ -3928,6 +3956,7 @@ extern "C" int snapi_bridge_unofficial_contextify_compile_function( extern "C" int snapi_bridge_unofficial_bytecode_open( SnapiEnvState* env_state, + uint32_t realm_id, uint32_t source_text_id, uint32_t filename_id, int32_t shape, @@ -3957,6 +3986,7 @@ extern "C" int snapi_bridge_unofficial_bytecode_open( unofficial_napi_bytecode_open_options options{}; options.size = sizeof(options); options.version = UNOFFICIAL_NAPI_BYTECODE_OPEN_OPTIONS_VERSION; + if (!ResolveRealm(*bridge_state, realm_id, &options.realm_or_null)) return napi_invalid_arg; options.source_text = source_text; options.filename = filename; options.shape = shape; @@ -4017,7 +4047,7 @@ extern "C" int snapi_bridge_unofficial_module_wrap_create( int32_t kind, uint32_t wrapper_id, uint32_t url_id, - uint32_t context_id, + uint32_t realm_id, uint32_t source_text_id, uint32_t source_bytecode_id, int32_t line_offset, @@ -4034,7 +4064,6 @@ extern "C" int snapi_bridge_unofficial_module_wrap_create( std::lock_guard lock(g_mu); napi_value wrapper = LoadValue(*bridge_state, wrapper_id); napi_value url = LoadValue(*bridge_state, url_id); - napi_value context = context_id == 0 ? nullptr : LoadValue(*bridge_state, context_id); napi_value source_text = source_text_id == 0 ? nullptr : LoadValue(*bridge_state, source_text_id); unofficial_napi_bytecode source_bytecode = LoadBytecodeHandle(*bridge_state, source_bytecode_id); @@ -4046,7 +4075,8 @@ extern "C" int snapi_bridge_unofficial_module_wrap_create( ? nullptr : LoadValue(*bridge_state, synthetic_eval_steps_id); if (wrapper == nullptr || url == nullptr) return napi_invalid_arg; - if (context_id != 0 && context == nullptr) return napi_invalid_arg; + unofficial_napi_realm realm = nullptr; + if (!ResolveRealm(*bridge_state, realm_id, &realm)) return napi_invalid_arg; if (host_defined_option_id != 0 && host_defined_option == nullptr) return napi_invalid_arg; if (export_names_id != 0 && export_names == nullptr) return napi_invalid_arg; if (synthetic_eval_steps_id != 0 && synthetic_eval_steps == nullptr) { @@ -4060,7 +4090,7 @@ extern "C" int snapi_bridge_unofficial_module_wrap_create( options.kind = static_cast(kind); options.wrapper = wrapper; options.url = url; - options.context_or_undefined = context; + options.realm_or_null = realm; switch (options.kind) { case unofficial_napi_module_source_text: if (source_text == nullptr && source_bytecode == nullptr) return napi_invalid_arg; From 2d924e060ca1690be3d2a3a87f9405984b5aba76 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Sun, 25 Oct 2026 10:11:40 +0100 Subject: [PATCH 013/150] host-JS: realm handles and collectable realms A host-JS realm id is the value id of the realm's key: its sandbox, or its fresh global. 0 means the env's own realm. There is no realm table. - Each env keeps a WeakMap registry from a realm's key and scope to its global context. A key keeps the first realm made for it, and lookups only see the env's own registry. Realm 0 never goes through the registry, so vm.createContext(globalThis) makes a realm over the env global without changing how the env itself evaluates. - create_realm and get_realm replace contextify_make_context. run_script, compile_function, bytecode_open and module create take the realm id; an id that names no realm is napi_invalid_arg. - The guest layer registers unofficial_napi_create_realm, get_realm, run_script and compile_function, and reads realm_or_null for modules and bytecode. The contextify imports are gone. - Name, origin, codegen and own-microtask-queue options have no effect on host-JS realms, which share their intrinsics. Tests: node WeakRef tests (--expose-gc) check that realms nothing refers to are collected while their registry lives, and that a duplicate sandbox, a non-realm value and another registry find nothing. wasm-bindgen tests cover run_script, compile_function and bytecode_open per realm. Co-Authored-By: Claude Opus 5.5 --- src/guest/napi_js.rs | 100 +++++--- src/snapi_js.rs | 357 +++++++++++++++++++++----- tests/host-js/global-context.test.mjs | 133 +++++++--- 3 files changed, 457 insertions(+), 133 deletions(-) diff --git a/src/guest/napi_js.rs b/src/guest/napi_js.rs index 81141e3690..3568606ff2 100644 --- a/src/guest/napi_js.rs +++ b/src/guest/napi_js.rs @@ -1555,45 +1555,71 @@ fn guest_unofficial_napi_contextify_contains_module_syntax( status } -#[allow(clippy::too_many_arguments)] -fn guest_unofficial_napi_contextify_make_context( +// A guest realm id is the value id of the realm's global (its sandbox, when it +// has one); 0 means the env's own realm. + +fn guest_unofficial_napi_create_realm( mut env: FunctionEnvMut, napi_env: u32, - sandbox_or_symbol: u32, - name: u32, - origin_or_undefined: u32, - allow_code_gen_strings: i32, - allow_code_gen_wasm: i32, - own_microtask_queue: i32, - host_defined_option_id: u32, - result_ptr: u32, + options_ptr: u32, + realm_out_ptr: u32, + global_out_ptr: u32, ) -> i32 { - let env_handle = snapi_env(&env, napi_env); - let mut result_id = 0u32; + let Some(options) = abi::read_realm_options(&mut env, options_ptr) else { + return 1; + }; + if realm_out_ptr == 0 { + return 1; + } + let mut realm = 0u32; + let mut global = 0u32; let status = unsafe { - snapi_bridge_unofficial_contextify_make_context( - env_handle, - sandbox_or_symbol, - name, - origin_or_undefined, - allow_code_gen_strings, - allow_code_gen_wasm, - own_microtask_queue, - host_defined_option_id, - &mut result_id, + snapi_bridge_unofficial_create_realm( + snapi_env(&env, napi_env), + options.sandbox_or_null, + options.name, + options.origin, + options.host_defined_option_id, + i32::from(options.allow_code_gen_strings), + i32::from(options.allow_code_gen_wasm), + i32::from(options.own_microtask_queue), + &mut realm, + &mut global, ) }; - if status == 0 && result_ptr != 0 { - write_guest_u32(&mut env, result_ptr, result_id); + if status != 0 { + return status; + } + write_guest_u32(&mut env, realm_out_ptr, realm); + if global_out_ptr != 0 { + write_guest_u32(&mut env, global_out_ptr, global); + } + 0 +} + +fn guest_unofficial_napi_get_realm( + mut env: FunctionEnvMut, + napi_env: u32, + value: u32, + realm_out_ptr: u32, +) -> i32 { + if realm_out_ptr == 0 { + return 1; + } + let mut realm = 0u32; + let status = + unsafe { snapi_bridge_unofficial_get_realm(snapi_env(&env, napi_env), value, &mut realm) }; + if status == 0 { + write_guest_u32(&mut env, realm_out_ptr, realm); } status } #[allow(clippy::too_many_arguments)] -fn guest_unofficial_napi_contextify_run_script( +fn guest_unofficial_napi_run_script( mut env: FunctionEnvMut, napi_env: u32, - sandbox_or_null: u32, + realm: u32, source_ptr: u32, filename: u32, line_offset: i32, @@ -1611,9 +1637,9 @@ fn guest_unofficial_napi_contextify_run_script( }; let mut result_id = 0u32; let status = unsafe { - snapi_bridge_unofficial_contextify_run_script( + snapi_bridge_unofficial_run_script( env_handle, - sandbox_or_null, + realm, source_text, source_bytecode, filename, @@ -1634,14 +1660,14 @@ fn guest_unofficial_napi_contextify_run_script( } #[allow(clippy::too_many_arguments)] -fn guest_unofficial_napi_contextify_compile_function( +fn guest_unofficial_napi_compile_function( mut env: FunctionEnvMut, napi_env: u32, + realm: u32, source_ptr: u32, filename: u32, line_offset: i32, column_offset: i32, - parsing_context_or_undefined: u32, context_extensions_or_undefined: u32, params_or_undefined: u32, host_defined_option_id: u32, @@ -1653,14 +1679,14 @@ fn guest_unofficial_napi_contextify_compile_function( }; let mut result_id = 0u32; let status = unsafe { - snapi_bridge_unofficial_contextify_compile_function( + snapi_bridge_unofficial_compile_function( env_handle, + realm, source_text, source_bytecode, filename, line_offset, column_offset, - parsing_context_or_undefined, context_extensions_or_undefined, params_or_undefined, host_defined_option_id, @@ -1694,6 +1720,7 @@ fn guest_unofficial_napi_bytecode_open( let status = unsafe { snapi_bridge_unofficial_bytecode_open( env_handle, + options.realm_or_null, options.source_text, options.filename, options.shape, @@ -1769,7 +1796,7 @@ fn guest_unofficial_napi_module_wrap_create( options.kind, options.wrapper, options.url, - options.context_or_undefined, + options.realm_or_null, options.source_text, options.source_bytecode, options.line_offset, @@ -5661,9 +5688,10 @@ pub fn register_napi_imports( "unofficial_napi_take_heap_snapshot" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_take_heap_snapshot), "unofficial_napi_create_serdes_binding" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_create_serdes_binding), "unofficial_napi_contextify_contains_module_syntax" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_contextify_contains_module_syntax), - "unofficial_napi_contextify_make_context" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_contextify_make_context), - "unofficial_napi_contextify_run_script" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_contextify_run_script), - "unofficial_napi_contextify_compile_function" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_contextify_compile_function), + "unofficial_napi_create_realm" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_create_realm), + "unofficial_napi_get_realm" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_get_realm), + "unofficial_napi_run_script" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_run_script), + "unofficial_napi_compile_function" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_compile_function), "unofficial_napi_bytecode_open" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_bytecode_open), "unofficial_napi_bytecode_serialize" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_bytecode_serialize), "unofficial_napi_bytecode_release" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_bytecode_release), diff --git a/src/snapi_js.rs b/src/snapi_js.rs index 62e779cf27..b756635a77 100644 --- a/src/snapi_js.rs +++ b/src/snapi_js.rs @@ -465,7 +465,6 @@ export function wasmer_napi_make_callback(context, dispatch) { return dispatch?.(this, args, new.target); }; } -const wasmerNapiGlobalScopes = new WeakMap(); function wasmerNapiCreateGlobalScope(scopeTarget, fallback = globalThis) { const scope = new Proxy(scopeTarget, { has(target, key) { @@ -500,7 +499,6 @@ function wasmerNapiCreateGlobalScope(scopeTarget, fallback = globalThis) { return true; }, }); - wasmerNapiGlobalScopes.set(scope,scope); return scope; } export function wasmer_napi_create_global_context() { @@ -520,23 +518,47 @@ export function wasmer_napi_release_global_context(context) { // Retained JS wrappers must stop calling Rust before its closures are dropped. context.callbacks.dispatches = undefined; } -// Evaluates `source` for the environment that owns `context`. A null sandbox, -// the host global and the context's own global all mean that context. -export function wasmer_napi_context_eval(context, sandbox, source) { - if (sandbox == null || sandbox === globalThis || sandbox === context.scope) { - sandbox = context.scope; +// Realms made with create_realm, by their global and, for a sandbox realm, +// by the sandbox. Each env has its own registry, so realms never cross envs. +// It is weak: a realm is collected with its global and everything made in it. +export function wasmer_napi_create_realm_registry() { + return new WeakMap(); +} +// Makes a realm with a fresh global, or one whose global property access goes +// to `sandbox` first, as with vm.createContext(sandbox), and returns its key: +// the sandbox, or the realm's global. A key keeps the first realm made for it. +export function wasmer_napi_create_realm_context(registry, sandbox) { + const base = wasmer_napi_create_global_context(); + let context = base; + let key = base.scope; + if (sandbox != null) { + context = { + scopeTarget: base.scopeTarget, + callbacks: base.callbacks, + scope: wasmerNapiCreateGlobalScope(sandbox, base.scope), + sandbox, + }; + key = sandbox; } - // A VM's global facade exposes the same builtins as bare identifiers while - // preserving the caller's sandbox bindings. Keep its defaults context-local - // so writes to process and Error hooks cannot reach the worker global. - let scope = wasmerNapiGlobalScopes.get(sandbox); - if (!scope) { - scope = wasmerNapiCreateGlobalScope(sandbox,wasmer_napi_create_global_context().scope); - wasmerNapiGlobalScopes.set(sandbox,scope); + for (const value of [key, context.scope]) { + if (!registry.has(value)) registry.set(value, context); } - sandbox = scope; - return Function('sandbox', 'source', - 'with (sandbox) { return eval(source); }').call(sandbox, sandbox, source); + return key; +} +// The realm context whose global or sandbox is `value`, or undefined. +export function wasmer_napi_realm_context(registry, value) { + const isObject = (typeof value === 'object' && value !== null) || + typeof value === 'function'; + return isObject ? registry.get(value) : undefined; +} +// Evaluates `source` in `context`. The context's scope exposes builtins as +// bare identifiers and keeps its own defaults, so writes to process and Error +// hooks cannot reach the worker global; a sandbox realm resolves identifiers +// on its sandbox first. +export function wasmer_napi_context_eval(context, source) { + const scope = context.scope; + return Function('scope', 'source', + 'with (scope) { return eval(source); }').call(scope, scope, source); } function wasmerNapiLowerDynamicImports(params, source, filename) { const names = Array.from(params, String); @@ -1135,12 +1157,11 @@ extern "C" { fn wasmer_napi_create_global_context() -> JsValue; fn wasmer_napi_global_context_scope(context: &JsValue) -> JsValue; fn wasmer_napi_release_global_context(context: &JsValue); + fn wasmer_napi_create_realm_registry() -> JsValue; + fn wasmer_napi_create_realm_context(registry: &JsValue, sandbox: &JsValue) -> JsValue; + fn wasmer_napi_realm_context(registry: &JsValue, value: &JsValue) -> JsValue; #[wasm_bindgen(catch)] - fn wasmer_napi_context_eval( - context: &JsValue, - sandbox: &JsValue, - source: &str, - ) -> Result; + fn wasmer_napi_context_eval(context: &JsValue, source: &str) -> Result; #[wasm_bindgen(catch)] fn wasmer_napi_compile_function( scope: &JsValue, @@ -1387,6 +1408,8 @@ struct HostJsAgent { struct HostJsEnv { agent: Box, global_context: JsValue, + /// The realms made with create_realm, by global and sandbox (a WeakMap). + realms: JsValue, live_env_addr: Rc>, /// Pending exception of calls made through this environment. last_exception: Option, @@ -1434,6 +1457,7 @@ impl HostJsEnv { Self { agent: Box::new(HostJsAgent::new()), global_context: wasmer_napi_create_global_context(), + realms: wasmer_napi_create_realm_registry(), live_env_addr: Rc::new(Cell::new(0)), last_exception: None, next_callback: 1, @@ -1771,20 +1795,26 @@ unsafe fn env_mut<'a>(env: SnapiEnv) -> Result<&'a mut HostJsEnv, i32> { Ok(unsafe { &mut *env.cast::() }) } -fn evaluation_scope(state: &HostJsEnv, context_id: u32) -> Result { - if context_id == 0 { - return Ok(wasmer_napi_global_context_scope(&state.global_context)); +/// The global context of the realm `realm_id` names: the env's own for 0, +/// else the realm whose global or sandbox has that value id. +fn realm_context(state: &HostJsEnv, realm_id: u32) -> Result { + if realm_id == 0 { + return Ok(state.global_context.clone()); } - let Some(context) = state.agent.get(context_id) else { - return Err(NAPI_INVALID_ARG); - }; - if context.is_null() || context.is_undefined() { - Ok(wasmer_napi_global_context_scope(&state.global_context)) + let key = state.agent.get(realm_id).ok_or(NAPI_INVALID_ARG)?; + let context = wasmer_napi_realm_context(&state.realms, key); + if context.is_undefined() { + Err(NAPI_INVALID_ARG) } else { - Ok(context.clone()) + Ok(context) } } +/// The scope code compiled for the realm `realm_id` resolves identifiers in. +fn realm_scope(state: &HostJsEnv, realm_id: u32) -> Result { + realm_context(state, realm_id).map(|context| wasmer_napi_global_context_scope(&context)) +} + unsafe fn write(out: *mut T, value: T) -> Result<(), i32> { if out.is_null() { return Err(NAPI_INVALID_ARG); @@ -2882,7 +2912,7 @@ pub unsafe extern "C" fn snapi_bridge_run_script(env: SnapiEnv, script: u32, out // realm, allowing Node bootstrap code from one N-API environment to mutate // the SDK scheduler and leak state into every other environment hosted by // that worker. - match wasmer_napi_context_eval(&state.global_context, &JsValue::NULL, &source) { + match wasmer_napi_context_eval(&state.global_context, &source) { Ok(value) => { let id = state.agent.insert(value); unsafe { write(out, id) }.map_or_else(|e| e, |_| NAPI_OK) @@ -4429,47 +4459,89 @@ pub unsafe extern "C" fn snapi_bridge_unofficial_contextify_contains_module_synt }); unsafe { write(result_out, i32::from(is_module)) }.map_or_else(|err| err, |()| NAPI_OK) } +/// Makes a realm, with a fresh global or over the sandbox `sandbox_id`, and +/// writes its key's value id (the sandbox, or the realm's global) to both +/// outs: the key's value id is the realm id. The other options have no effect +/// on host-JS realms, which share their intrinsics. #[unsafe(no_mangle)] -pub unsafe extern "C" fn snapi_bridge_unofficial_contextify_make_context( +#[allow(clippy::too_many_arguments)] +pub unsafe extern "C" fn snapi_bridge_unofficial_create_realm( env: SnapiEnv, - sandbox_or_symbol_id: u32, + sandbox_id: u32, name_id: u32, origin_id: u32, + host_defined_option_id: u32, allow_code_gen_strings: i32, allow_code_gen_wasm: i32, own_microtask_queue: i32, - host_defined_option_id: u32, - result_out: *mut u32, + realm_out: *mut u32, + global_out: *mut u32, ) -> i32 { let _ = ( name_id, origin_id, + host_defined_option_id, allow_code_gen_strings, allow_code_gen_wasm, own_microtask_queue, - host_defined_option_id, ); let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let sandbox = if sandbox_or_symbol_id == 0 { - Object::new().into() + if realm_out.is_null() { + return NAPI_INVALID_ARG; + } + let sandbox = if sandbox_id == 0 { + JsValue::NULL } else { - state - .agent - .get(sandbox_or_symbol_id) - .cloned() - .unwrap_or_else(|| Object::new().into()) + let Some(value) = state.agent.get(sandbox_id).cloned() else { + return NAPI_INVALID_ARG; + }; + if !(value.is_object() || value.is_function()) { + return NAPI_OBJECT_EXPECTED; + } + // A sandbox belongs to one realm. The env's own global is not a + // realm's, so it may still be one, as with vm.createContext(globalThis). + if !wasmer_napi_realm_context(&state.realms, &value).is_undefined() { + return NAPI_INVALID_ARG; + } + value }; - let _ = Reflect::set(&sandbox, &JsValue::from_str("global"), &sandbox); - let _ = Reflect::set(&sandbox, &JsValue::from_str("globalThis"), &sandbox); - let id = state.agent.insert(sandbox); - unsafe { write(result_out, id) }.map_or_else(|err| err, |()| NAPI_OK) + let key = wasmer_napi_create_realm_context(&state.realms, &sandbox); + let id = state.agent.insert(key); + if !global_out.is_null() { + // Only a null out pointer makes write fail. + let _ = unsafe { write(global_out, id) }; + } + unsafe { write(realm_out, id) }.map_or_else(|err| err, |()| NAPI_OK) } +/// Writes `value_id` when that value is a realm's global or sandbox, else 0. #[unsafe(no_mangle)] -pub unsafe extern "C" fn snapi_bridge_unofficial_contextify_run_script( +pub unsafe extern "C" fn snapi_bridge_unofficial_get_realm( env: SnapiEnv, - sandbox_or_null_id: u32, + value_id: u32, + realm_out: *mut u32, +) -> i32 { + let Ok(state) = (unsafe { env_mut(env) }) else { + return NAPI_INVALID_ARG; + }; + if realm_out.is_null() { + return NAPI_INVALID_ARG; + } + let Some(value) = state.agent.get(value_id) else { + return NAPI_INVALID_ARG; + }; + if !(value.is_object() || value.is_function()) { + return NAPI_OBJECT_EXPECTED; + } + let is_realm = !wasmer_napi_realm_context(&state.realms, value).is_undefined(); + unsafe { write(realm_out, if is_realm { value_id } else { 0 }) } + .map_or_else(|err| err, |()| NAPI_OK) +} +#[unsafe(no_mangle)] +pub unsafe extern "C" fn snapi_bridge_unofficial_run_script( + env: SnapiEnv, + realm_id: u32, source_text_id: u32, source_bytecode_id: u32, filename_id: u32, @@ -4500,12 +4572,11 @@ pub unsafe extern "C" fn snapi_bridge_unofficial_contextify_run_script( Ok(source) => source, Err(status) => return status, }; - let sandbox = state - .agent - .get(sandbox_or_null_id) - .cloned() - .unwrap_or(JsValue::NULL); - match wasmer_napi_context_eval(&state.global_context, &sandbox, &source) { + let context = match realm_context(state, realm_id) { + Ok(context) => context, + Err(status) => return status, + }; + match wasmer_napi_context_eval(&context, &source) { Ok(value) => { let id = state.agent.insert(value); unsafe { write(result_out, id) }.map_or_else(|err| err, |()| NAPI_OK) @@ -4517,14 +4588,14 @@ pub unsafe extern "C" fn snapi_bridge_unofficial_contextify_run_script( } } #[unsafe(no_mangle)] -pub unsafe extern "C" fn snapi_bridge_unofficial_contextify_compile_function( +pub unsafe extern "C" fn snapi_bridge_unofficial_compile_function( env: SnapiEnv, + realm_id: u32, source_text_id: u32, source_bytecode_id: u32, filename_id: u32, line_offset: i32, column_offset: i32, - parsing_context_id: u32, context_extensions_id: u32, params_id: u32, host_defined_option_id: u32, @@ -4561,7 +4632,7 @@ pub unsafe extern "C" fn snapi_bridge_unofficial_contextify_compile_function( .get(filename_id) .and_then(JsValue::as_string) .unwrap_or_default(); - let scope = match evaluation_scope(state, parsing_context_id) { + let scope = match realm_scope(state, realm_id) { Ok(scope) => scope, Err(status) => return status, }; @@ -4615,6 +4686,7 @@ pub unsafe extern "C" fn snapi_bridge_unofficial_contextify_compile_function( #[unsafe(no_mangle)] pub unsafe extern "C" fn snapi_bridge_unofficial_bytecode_open( env: SnapiEnv, + realm_id: u32, source_text_id: u32, filename_id: u32, shape: i32, @@ -4676,7 +4748,10 @@ pub unsafe extern "C" fn snapi_bridge_unofficial_bytecode_open( } } } - let scope = wasmer_napi_global_context_scope(&state.global_context); + let scope = match realm_scope(state, realm_id) { + Ok(scope) => scope, + Err(status) => return status, + }; let context_extensions = Array::new(); let compile_result = match shape { 0 => wasmer_napi_validate_script(&source, &filename), @@ -4750,7 +4825,7 @@ unsafe fn host_js_create_source_text_module( env: SnapiEnv, wrapper_id: u32, url_id: u32, - context_id: u32, + realm_id: u32, source_text_id: u32, source_bytecode_id: u32, line_offset: i32, @@ -4775,7 +4850,7 @@ unsafe fn host_js_create_source_text_module( Err(status) => return status, }; - let scope = match evaluation_scope(state, context_id) { + let scope = match realm_scope(state, realm_id) { Ok(scope) => scope, Err(status) => return status, }; @@ -4852,14 +4927,14 @@ unsafe fn host_js_create_synthetic_module( env: SnapiEnv, wrapper_id: u32, url_id: u32, - context_id: u32, + realm_id: u32, export_names_id: u32, synthetic_eval_steps_id: u32, handle_out: *mut u32, requests_out: *mut u32, has_top_level_await_out: *mut u8, ) -> i32 { - let _ = (url_id, context_id); + let _ = (url_id, realm_id); let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; @@ -4929,7 +5004,7 @@ pub unsafe extern "C" fn snapi_bridge_unofficial_module_wrap_create( kind: i32, wrapper_id: u32, url_id: u32, - context_id: u32, + realm_id: u32, source_text_id: u32, source_bytecode_id: u32, line_offset: i32, @@ -4947,7 +5022,7 @@ pub unsafe extern "C" fn snapi_bridge_unofficial_module_wrap_create( env, wrapper_id, url_id, - context_id, + realm_id, source_text_id, source_bytecode_id, line_offset, @@ -4963,7 +5038,7 @@ pub unsafe extern "C" fn snapi_bridge_unofficial_module_wrap_create( env, wrapper_id, url_id, - context_id, + realm_id, export_names_id, synthetic_eval_steps_id, handle_out, @@ -7056,6 +7131,154 @@ mod tests { }); } + /// Runs `source` in the realm `realm` (the env's own for 0). + fn run_in(env: SnapiEnv, realm: u32, source: &str) -> Result { + let state = unsafe { env_mut(env) }.unwrap(); + let script = state.agent.insert_primitive(source.into()); + let mut out = 0; + let status = unsafe { + snapi_bridge_unofficial_run_script(env, realm, script, 0, 0, 0, 0, -1, 1, 0, 0, 0, &mut out) + }; + if status != NAPI_OK { + return Err(status); + } + Ok(unsafe { env_mut(env) }.unwrap().agent.get(out).unwrap().clone()) + } + + fn new_realm(env: SnapiEnv, sandbox: u32) -> Result { + let (mut realm, mut global) = (0, 0); + let status = unsafe { + snapi_bridge_unofficial_create_realm(env, sandbox, 0, 0, 0, 1, 1, 0, &mut realm, &mut global) + }; + if status != NAPI_OK { + return Err(status); + } + assert_eq!(realm, global); + Ok(realm) + } + + fn realm_of(env: SnapiEnv, value: u32) -> Result { + let mut realm = u32::MAX; + match unsafe { snapi_bridge_unofficial_get_realm(env, value, &mut realm) } { + NAPI_OK => Ok(realm), + status => Err(status), + } + } + + #[wasm_bindgen_test] + fn realm_ids_name_the_realm_of_their_global_or_sandbox() { + with_env(|env, state| { + let sandbox: JsValue = Object::new().into(); + Reflect::set(&sandbox, &"x".into(), &JsValue::from_f64(2.0)).unwrap(); + let sandbox_id = state.agent.insert(sandbox); + let realm = new_realm(env, sandbox_id).unwrap(); + assert_eq!(realm, sandbox_id); + assert_eq!(run_in(env, realm, "x + 1").unwrap().as_f64(), Some(3.0)); + assert_eq!( + run_in(env, 0, "typeof x").unwrap().as_string().as_deref(), + Some("undefined") + ); + assert_eq!(realm_of(env, sandbox_id), Ok(sandbox_id)); + + // A sandbox belongs to one realm. + assert_eq!(new_realm(env, sandbox_id), Err(NAPI_INVALID_ARG)); + + // A realm with a fresh global is named by its global. + let fresh = new_realm(env, 0).unwrap(); + let global = run_in(env, fresh, "globalThis").unwrap(); + let state = unsafe { env_mut(env) }.unwrap(); + assert!(Object::is(&global, state.agent.get(fresh).unwrap())); + assert_eq!(realm_of(env, fresh), Ok(fresh)); + + // Other objects and the env's own global name no realm. + let state = unsafe { env_mut(env) }.unwrap(); + let other = state.agent.insert(Object::new().into()); + let number = state.agent.insert_primitive(JsValue::from_f64(1.0)); + assert_eq!(realm_of(env, other), Ok(0)); + assert_eq!(realm_of(env, number), Err(NAPI_OBJECT_EXPECTED)); + assert_eq!(run_in(env, other, "1").unwrap_err(), NAPI_INVALID_ARG); + let mut env_global = 0; + assert_eq!(unsafe { snapi_bridge_get_global(env, &mut env_global) }, NAPI_OK); + assert_eq!(realm_of(env, env_global), Ok(0)); + // It may still be a sandbox, as with vm.createContext(globalThis), + // and the env keeps evaluating in its own context. + assert!(new_realm(env, env_global).is_ok()); + let own = run_in(env, 0, "globalThis").unwrap(); + let state = unsafe { env_mut(env) }.unwrap(); + assert!(Object::is(&own, state.agent.get(env_global).unwrap())); + }); + } + + #[wasm_bindgen_test] + fn functions_and_bytecode_compile_for_their_realm() { + with_env(|env, state| { + let sandbox: JsValue = Object::new().into(); + Reflect::set(&sandbox, &"x".into(), &JsValue::from_f64(5.0)).unwrap(); + let sandbox_id = state.agent.insert(sandbox); + let realm = new_realm(env, sandbox_id).unwrap(); + + let state = unsafe { env_mut(env) }.unwrap(); + let body = state.agent.insert_primitive("return x * 2;".into()); + let mut compiled = 0; + assert_eq!( + unsafe { + snapi_bridge_unofficial_compile_function( + env, realm, body, 0, 0, 0, 0, 0, 0, 0, &mut compiled, + ) + }, + NAPI_OK + ); + let state = unsafe { env_mut(env) }.unwrap(); + let function: Function = + Reflect::get(state.agent.get(compiled).unwrap(), &"function".into()) + .unwrap() + .unchecked_into(); + assert_eq!(function.call0(&JsValue::UNDEFINED).unwrap().as_f64(), Some(10.0)); + + let source = state.agent.insert_primitive("x".into()); + let open = |realm_id: u32, out: &mut u32| { + let (mut rejected, mut module) = (0, 0); + unsafe { + snapi_bridge_unofficial_bytecode_open( + env, + realm_id, + source, + 0, + 0, + 0, + 0, + 0, + 0, + ptr::null(), + 0, + 0, + 0, + out, + &mut rejected, + &mut module, + ) + } + }; + let mut bytecode = 0; + assert_eq!(open(realm, &mut bytecode), NAPI_OK); + let state = unsafe { env_mut(env) }.unwrap(); + let other = state.agent.insert(Object::new().into()); + let mut unused = 0; + assert_eq!(open(other, &mut unused), NAPI_INVALID_ARG); + let mut out = 0; + assert_eq!( + unsafe { + snapi_bridge_unofficial_run_script( + env, realm, 0, bytecode, 0, 0, 0, -1, 1, 0, 0, 0, &mut out, + ) + }, + NAPI_OK + ); + let state = unsafe { env_mut(env) }.unwrap(); + assert_eq!(state.agent.get(out).unwrap().as_f64(), Some(5.0)); + }); + } + #[wasm_bindgen_test] fn released_callbacks_do_not_keep_externref_roots_and_remain_callable() { let before = wasm_bindgen::externref_heap_live_count(); diff --git a/tests/host-js/global-context.test.mjs b/tests/host-js/global-context.test.mjs index 4970f721d2..7cab133910 100644 --- a/tests/host-js/global-context.test.mjs +++ b/tests/host-js/global-context.test.mjs @@ -27,8 +27,16 @@ try { const create = runtime.wasmer_napi_create_global_context; const evaluate = runtime.wasmer_napi_context_eval; const callback = runtime.wasmer_napi_make_callback; -// VM sandboxes evaluate the same whichever environment runs them. +const createRegistry = runtime.wasmer_napi_create_realm_registry; +const createRealm = runtime.wasmer_napi_create_realm_context; +const realmOf = runtime.wasmer_napi_realm_context; const host = create(); +const registry = createRegistry(); +// The realm of `sandbox` in the shared test registry, made on first use. +const sandboxRealm = (sandbox) => { + if (realmOf(registry, sandbox) === undefined) createRealm(registry, sandbox); + return realmOf(registry, sandbox); +}; const stackFormattingSupported = (() => { const saved=Object.getOwnPropertyDescriptor(Error,'prepareStackTrace'),marker={}; try { @@ -42,19 +50,18 @@ const stackFormattingSupported = (() => { test('script this and globalThis refer to the virtual global', () => { const context = create(); - const values = evaluate(context,context.scope,'[this, globalThis, global]'); + const values = evaluate(context,'[this, globalThis, global]'); assert.ok(values.every(value => value === context.scope)); }); -test('a null sandbox evaluates in the given context, whatever ran last', () => { +test('each context evaluates in itself, whatever ran last', () => { const a=create(), b=create(); - for (const sandbox of [null, undefined, globalThis]) { - assert.equal(evaluate(a,sandbox,'globalThis'),a.scope); - assert.equal(evaluate(b,sandbox,'globalThis'),b.scope); - assert.equal(evaluate(a,sandbox,'globalThis'),a.scope); + for (let i=0;i<2;i++) { + assert.equal(evaluate(a,'globalThis'),a.scope); + assert.equal(evaluate(b,'globalThis'),b.scope); } - evaluate(a,null,'var answer=1'); - assert.equal(evaluate(b,null,'typeof answer'),'undefined'); + evaluate(a,'globalThis.answer=1'); + assert.equal(evaluate(b,'typeof answer'),'undefined'); runtime.wasmer_napi_release_global_context(a); runtime.wasmer_napi_release_global_context(b); }); @@ -62,24 +69,24 @@ test('a null sandbox evaluates in the given context, whatever ran last', () => { test('VM script globals expose builtins without writing to the host global', () => { const sandbox = { answer:42 }; const other = {}; - const values = evaluate(host,sandbox,'[this, globalThis, global, this.RegExp, RegExp, answer]'); + const values = evaluate(sandboxRealm(sandbox),'[this, globalThis, global, this.RegExp, RegExp, answer]'); assert.ok(values.slice(0,3).every(value => value === values[0])); assert.notEqual(values[0],globalThis); assert.equal(values[3],RegExp); assert.equal(values[4],RegExp); assert.equal(values[5],42); - assert.equal(evaluate(host,sandbox,'this'),values[0], 'reuse the VM global across scripts'); + assert.equal(evaluate(sandboxRealm(sandbox),'this'),values[0], 'reuse the VM global across scripts'); // Edge stream cleanup uses vm.runInNewContext('this').RegExp this way. - assert.equal(evaluate(host,sandbox,'new this.RegExp("released", "g")[Symbol.replace]("released", "closed")'),'closed'); + assert.equal(evaluate(sandboxRealm(sandbox),'new this.RegExp("released", "g")[Symbol.replace]("released", "closed")'),'closed'); const hostProcess = globalThis.process; const hostFormatter = Error.prepareStackTrace; - evaluate(host,sandbox,'this.process={vm:true}; Error.prepareStackTrace=()=>"vm stack"; this.answer++'); + evaluate(sandboxRealm(sandbox),'this.process={vm:true}; Error.prepareStackTrace=()=>"vm stack"; this.answer++'); assert.equal(globalThis.process,hostProcess); assert.equal(Error.prepareStackTrace,hostFormatter); assert.equal(sandbox.answer,43); assert.deepEqual(sandbox.process,{vm:true}); - assert.notEqual(evaluate(host,other,'Error'),evaluate(host,sandbox,'Error')); - assert.notEqual(evaluate(host,other,'Error.prepareStackTrace'),evaluate(host,sandbox,'Error.prepareStackTrace')); + assert.notEqual(evaluate(sandboxRealm(other),'Error'),evaluate(sandboxRealm(sandbox),'Error')); + assert.notEqual(evaluate(sandboxRealm(other),'Error.prepareStackTrace'),evaluate(sandboxRealm(sandbox),'Error.prepareStackTrace')); }); test('global accessors retain lazy reads and context-owned writes', () => { @@ -105,7 +112,7 @@ test('global accessors retain lazy reads and context-owned writes', () => { test('a guest process assignment does not replace the worker process', () => { const original=globalThis.process; const a=create(), b=create(); - evaluate(a,a.scope,'globalThis.process={guest:"a"}'); + evaluate(a,'globalThis.process={guest:"a"}'); assert.equal(globalThis.process,original); assert.equal(b.scope.process,original); assert.deepEqual(a.scope.process,{guest:'a'}); @@ -122,7 +129,7 @@ test('closing an inactive context disables only its callbacks', () => { assert.throws(()=>fnB(),/active callback/); runtime.wasmer_napi_release_global_context(b); assert.equal(fnB(),undefined); - assert.equal(evaluate(a,undefined,'globalThis'),a.scope); + assert.equal(evaluate(a,'globalThis'),a.scope); assert.deepEqual(fnA.call(receiver,3),{receiver,args:[3]}); runtime.wasmer_napi_release_global_context(a); assert.equal(fnA(),undefined); @@ -172,7 +179,7 @@ test('retained callback wrappers do not retain closed contexts or dispatch captu test('Error constructors, static hooks and prototype writes stay local', () => { const a=create(), b=create(); const hook=Error.prepareStackTrace; - evaluate(a,a.scope,'Error.prepareStackTrace=()=>"guest-a"; Error.prototype.guest="a"; Error.stackTraceLimit=3;'); + evaluate(a,'Error.prepareStackTrace=()=>"guest-a"; Error.prototype.guest="a"; Error.stackTraceLimit=3;'); assert.equal(Error.prepareStackTrace,hook); assert.equal(Error.prototype.guest,undefined); assert.notEqual(a.scope.Error,b.scope.Error); @@ -183,15 +190,15 @@ test('Error constructors, static hooks and prototype writes stay local', () => { assert.equal(ownMethods.toString.value,Error.prototype.toString); assert.equal(ownMethods.name.value,'Error'); assert.equal(ownMethods.message.value,''); - assert.equal(evaluate(a,a.scope,'Error.prototype.toString.call(new Error("details"))'),'Error: details'); + assert.equal(evaluate(a,'Error.prototype.toString.call(new Error("details"))'),'Error: details'); assert.equal(Object.getPrototypeOf(a.scope.TypeError.prototype),a.scope.Error.prototype); - assert.equal(evaluate(a,a.scope,'new TypeError("typed").guest'),'a'); - assert.equal(evaluate(b,b.scope,'new TypeError("typed").guest'),undefined); + assert.equal(evaluate(a,'new TypeError("typed").guest'),'a'); + assert.equal(evaluate(b,'new TypeError("typed").guest'),undefined); }); test('callable errors, subclasses, causes and native N-API errors work', () => { const c=create(); - const values=evaluate(c,c.scope,`class CustomError extends Error {}; [Error('called'),new TypeError('typed',{cause:42}),new AggregateError([1,2],'many'),new CustomError('custom')]`); + const values=evaluate(c,`class CustomError extends Error {}; [Error('called'),new TypeError('typed',{cause:42}),new AggregateError([1,2],'many'),new CustomError('custom')]`); for (const value of values) assert.ok(value instanceof c.scope.Error); assert.equal(values[0].message,'called'); assert.ok(values[1] instanceof c.scope.TypeError); @@ -209,7 +216,7 @@ test('callable errors, subclasses, causes and native N-API errors work', () => { test('custom stack formatting is lazy, receives the actual error and restores the host hook', {skip:!stackFormattingSupported}, () => { const c=create(), host=Object.getOwnPropertyDescriptor(Error,'prepareStackTrace'); c.scope.state={calls:0}; - const error=evaluate(c,c.scope,`Error.prepareStackTrace=(error,frames)=>{state.calls++;return {error,frames}}; new Error('custom',{cause:42})`); + const error=evaluate(c,`Error.prepareStackTrace=(error,frames)=>{state.calls++;return {error,frames}}; new Error('custom',{cause:42})`); assert.equal(c.scope.state.calls,0); const stack=error.stack; assert.equal(stack.error,error); @@ -217,15 +224,15 @@ test('custom stack formatting is lazy, receives the actual error and restores th assert.equal(c.scope.state.calls,1); assert.equal(error.stack,stack); assert.deepEqual(Object.getOwnPropertyDescriptor(Error,'prepareStackTrace'),host); - evaluate(c,c.scope,'Error.prepareStackTrace=()=>{throw new RangeError("formatter failed")}'); - const bad=evaluate(c,c.scope,'new Error("bad")'); + evaluate(c,'Error.prepareStackTrace=()=>{throw new RangeError("formatter failed")}'); + const bad=evaluate(c,'new Error("bad")'); assert.throws(()=>bad.stack,/formatter failed/); assert.deepEqual(Object.getOwnPropertyDescriptor(Error,'prepareStackTrace'),host); }); test('Error.captureStackTrace targets use the local formatter', {skip:!stackFormattingSupported}, () => { const c=create(); - const object=evaluate(c,c.scope,`Error.prepareStackTrace=(object,frames)=>({object,frames}); const target={}; Error.captureStackTrace(target); target`); + const object=evaluate(c,`Error.prepareStackTrace=(object,frames)=>({object,frames}); const target={}; Error.captureStackTrace(target); target`); assert.equal(object.stack.object,object); assert.ok(object.stack.frames.length>0); object.stack='overridden'; @@ -273,7 +280,7 @@ test('delayed stacks keep their owner and capture its frame limit', {skip:!stack a.scope.Error.prepareStackTrace=(error,frames)=>({owner:'a',error,frames}); b.scope.Error.prepareStackTrace=(error,frames)=>({owner:'b',error,frames}); const source='function first(){return second()} function second(){return third()} function third(){return new TypeError("delayed")} first()'; - const errorA=evaluate(a,a.scope,source), errorB=evaluate(b,b.scope,source); + const errorA=evaluate(a,source), errorB=evaluate(b,source); const stackB=errorB.stack, stackA=errorA.stack; assert.equal(stackA.owner,'a'); assert.equal(stackB.owner,'b'); @@ -290,7 +297,7 @@ function releasedGuestBufferReferences() { const context=create(); const memory=new WebAssembly.Memory({initial:32,maximum:64,shared:true}); context.scope.buffer=new Int32Array(memory.buffer); - evaluate(context,context.scope,'process={buffer}; Error.prepareStackTrace=()=>process.buffer;'); + evaluate(context,'process={buffer}; Error.prepareStackTrace=()=>process.buffer;'); runtime.wasmer_napi_release_global_context(context); references.push(new WeakRef(memory.buffer)); } @@ -302,8 +309,10 @@ function releasedVmReferences() { for(let i=0;i<12;i++) { const memory=new WebAssembly.Memory({initial:32,maximum:64,shared:true}); const sandbox={buffer:new Int32Array(memory.buffer)}; - const scope=evaluate(host,sandbox,'Error.prepareStackTrace=()=>buffer; this'); - references.push(new WeakRef(sandbox),new WeakRef(scope),new WeakRef(memory.buffer)); + const realm=sandboxRealm(sandbox); + const scope=evaluate(realm,'Error.prepareStackTrace=()=>buffer; this'); + references.push(new WeakRef(sandbox),new WeakRef(scope),new WeakRef(realm), + new WeakRef(memory.buffer)); } return references; } @@ -324,6 +333,70 @@ test('cached VM globals and their guest buffers are collectible', async () => { await assertCollected(releasedVmReferences()); }); +function droppedRealmReferences(own) { + const references=[]; + for(let i=0;i<12;i++) { + const key=createRealm(own,i%2 ? {i} : null); + const realm=realmOf(own,key); + evaluate(realm,'globalThis.payload=new Array(1024).fill(1)'); + references.push(new WeakRef(key),new WeakRef(realm),new WeakRef(realm.scope)); + } + return references; +} + +test('realms nothing refers to are collected, also while their registry lives', async () => { + const own=createRegistry(); + const kept={}; + createRealm(own,kept); + await assertCollected(droppedRealmReferences(own)); + // The registry and a realm whose sandbox is still referenced survive. + assert.equal(evaluate(realmOf(own,kept),'typeof payload'),'undefined'); +}); + +test('realms are found by their global or sandbox only', () => { + const own=createRegistry(); + const sandbox={x:1}; + const key=createRealm(own,sandbox); + assert.equal(key,sandbox); + const realm=realmOf(own,sandbox); + assert.ok(realm); + assert.equal(realmOf(own,realm.scope),realm); + assert.equal(evaluate(realm,'x + 1'),2); + const fresh=realmOf(own,createRealm(own,null)); + assert.equal(evaluate(fresh,'globalThis'),fresh.scope); + for (const value of [{},function(){},[],host.scope,1,'s',null,undefined]) { + assert.equal(realmOf(own,value),undefined); + } +}); + +test('a sandbox keeps the first realm made for it', () => { + const own=createRegistry(); + const sandbox={}; + createRealm(own,sandbox); + const first=realmOf(own,sandbox); + createRealm(own,sandbox); + assert.equal(realmOf(own,sandbox),first); +}); + +test('realm registries do not share realms', () => { + const a=createRegistry(), b=createRegistry(); + const sandbox={}; + createRealm(a,sandbox); + assert.equal(realmOf(b,sandbox),undefined); + createRealm(b,sandbox); + assert.notEqual(realmOf(a,sandbox),realmOf(b,sandbox)); +}); + +test('a realm over the env global leaves the env context alone', () => { + const env=create(), own=createRegistry(); + createRealm(own,env.scope); + const realm=realmOf(own,env.scope); + assert.notEqual(realm,env); + assert.equal(evaluate(env,'globalThis'),env.scope); + evaluate(realm,'globalThis.viaRealm=1'); + assert.equal(env.scope.viaRealm,1); +}); + test('closed virtual contexts and their guest buffers are collectible', async () => { // Keep creator variables out of the suspended async frame, and finish the // WeakRef creation job before collecting its targets. From 4266d872181d556fc2c4ee76bee099d8b8ab7166 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Sun, 25 Oct 2026 10:20:05 +0100 Subject: [PATCH 014/150] Give QuickJS realm handles for vm contexts A vm context is now a realm of the env's runtime: create_realm makes a JSContext, with or without a sandbox, and returns its record as an unofficial_napi_realm. run_script, compile_function, module creation and bytecode_open run or compile in that realm's context, or in the env's for NULL. A sandbox realm keeps the copy-in/out sync; a realm with a fresh global needs none. get_realm looks a realm up by its global or sandbox. make_context, dispose_context and the sandbox-taking signatures are gone. Realms are collected with what they belong to. Under private symbols the sandbox (or a fresh realm's global) holds a function of the realm, which keeps the context alive, and a sandbox realm's global holds the sandbox, so the collector sees the whole cycle. The record holds that object through a native weak link and borrows the context; collected records are released when the next realm is made. Bytecode handles and modules of a realm hold its context. Hooks are called with this = undefined, since they fire for code in any realm of the env. On QuickJS a realm's pending job keeps it alive (engine commit 7ddf9e3), so the realm-lifetime test drains the job queue before it checks that the realm is collected. Co-Authored-By: Claude Opus 5.5 --- quickjs/src/internal/napi_contextify.cc | 456 ++++++++++++++-------- quickjs/src/internal/napi_contextify.h | 49 ++- quickjs/src/internal/napi_module_wrap.cc | 81 ++-- quickjs/src/internal/napi_module_wrap.h | 9 +- quickjs/src/internal/napi_promises.cc | 5 +- quickjs/src/unofficial_napi.cc | 72 ++-- tests/runners/test_66_unofficial_realm.cc | 6 + 7 files changed, 424 insertions(+), 254 deletions(-) diff --git a/quickjs/src/internal/napi_contextify.cc b/quickjs/src/internal/napi_contextify.cc index 49aa28203c..c151eca148 100644 --- a/quickjs/src/internal/napi_contextify.cc +++ b/quickjs/src/internal/napi_contextify.cc @@ -40,6 +40,18 @@ namespace quickjs::detail return JS_IsObject(a) && JS_IsObject(b) && JS_VALUE_GET_PTR(a) == JS_VALUE_GET_PTR(b); } + // Private links between a realm's context and the object it belongs + // to: invisible to script, removable by the provider. + constexpr int k_contextify_link_flags = + JS_PROP_HAS_VALUE | JS_PROP_HAS_WRITABLE | + JS_PROP_HAS_CONFIGURABLE | JS_PROP_CONFIGURABLE | + JS_PROP_HAS_ENUMERABLE | JS_PROP_NO_EXOTIC; + + JSValue contextify_anchor(JSContext *, JSValueConst, int, JSValueConst *) + { + return JS_UNDEFINED; + } + bool atom_equals_cstr(JSContext *ctx, JSAtom atom, const char *name) { JSAtom expected = JS_NewAtom(ctx, name); @@ -91,18 +103,26 @@ namespace quickjs::detail } } // namespace + // A realm: a context on the env's runtime, and the sandbox it mirrors when + // it has one. The realm belongs to its key (the sandbox, or the realm's + // global when it has none), not to this record. Under private symbols the + // key holds a function of the realm (which keeps the context alive) and a + // sandbox realm's global holds its sandbox, so the collector sees every + // edge and collects the realm with its key. The record holds the key + // weakly and borrows the context, the global and the sandbox, which stay + // valid while the key lives. struct napi_contextify__::context_record { - explicit context_record(napi_env owner, - JSContext *parent_context, - JSValueConst parent_sandbox, - JSContext *child_context, - JSValue child_global, - JSValueConst host_defined_option) + context_record(napi_env owner, + JSContext *parent_context, + JSValueConst sandbox_or_undefined, + JSContext *child_context, + JSValueConst child_global, + JSValueConst host_defined_option) : env{owner}, parent_ctx{parent_context}, ctx{child_context}, - sandbox{JS_DupValue(parent_context, parent_sandbox)}, + sandbox{sandbox_or_undefined}, global{child_global}, host_defined_option_id{JS_DupValue(parent_context, host_defined_option)} { @@ -113,30 +133,45 @@ namespace quickjs::detail close(); } + bool live() const + { + return !disposed && !collected; + } + + bool has_sandbox() const + { + return JS_IsObject(sandbox); + } + + JSValueConst key() const + { + return has_sandbox() ? sandbox : global; + } + + static void key_collected(JSRuntime *, void *opaque) + { + // Runs while the collector frees the key; the context may go in + // the same pass. Only mark the record: it is released later. + static_cast(opaque)->collected = true; + } + void close() { if (disposed) return; disposed = true; - if (ctx != nullptr) - { - for (JSAtom atom : baseline_atoms) - JS_FreeAtom(ctx, atom); - baseline_atoms.clear(); - JS_FreeValue(ctx, global); - global = JS_UNDEFINED; - JS_SetContextOpaque(ctx, nullptr); + JSRuntime *rt = JS_GetRuntime(parent_ctx); + JS_DeleteNativeWeakRefLink(rt, &key_link); + if (owns_context && ctx != nullptr) JS_FreeContext(ctx); - ctx = nullptr; - } - if (parent_ctx != nullptr) - { - JS_FreeValue(parent_ctx, sandbox); - JS_FreeValue(parent_ctx, host_defined_option_id); - } - sandbox = JS_UNDEFINED; + for (JSAtom atom : baseline_atoms) + JS_FreeAtomRT(rt, atom); + baseline_atoms.clear(); + JS_FreeValueRT(rt, host_defined_option_id); host_defined_option_id = JS_UNDEFINED; - parent_ctx = nullptr; + sandbox = JS_UNDEFINED; + global = JS_UNDEFINED; + ctx = nullptr; } bool has_baseline_atom(JSAtom atom) const @@ -146,11 +181,18 @@ namespace quickjs::detail napi_env env = nullptr; JSContext *parent_ctx = nullptr; - JSContext *ctx = nullptr; - JSValue sandbox = JS_UNDEFINED; - JSValue global = JS_UNDEFINED; + JSContext *ctx = nullptr; // Borrowed; valid while live(). + JSValueConst sandbox = JS_UNDEFINED; // Borrowed; undefined without one. + JSValueConst global = JS_UNDEFINED; // Borrowed; valid while live(). JSValue host_defined_option_id = JS_UNDEFINED; std::vector baseline_atoms; + JSNativeWeakRefLink key_link{}; + // The key holds the link to the context. + bool anchored = false; + // The key cannot hold the link (a sandbox that is not extensible): the + // record keeps the context until the sandbox is collected. + bool owns_context = false; + bool collected = false; bool disposed = false; }; @@ -170,7 +212,20 @@ namespace quickjs::detail { if (torn_down_) return; + // Contexts that outlive the environment must not point at it. + for (const auto &record : contexts_) + { + if (record->live() || (!record->disposed && record->owns_context)) + JS_SetContextOpaque(record->ctx, nullptr); + } + records_by_global_.clear(); contexts_.clear(); + if (context_link_atom_ != JS_ATOM_NULL) + JS_FreeAtom(ctx_, context_link_atom_); + if (sandbox_link_atom_ != JS_ATOM_NULL) + JS_FreeAtom(ctx_, sandbox_link_atom_); + context_link_atom_ = JS_ATOM_NULL; + sandbox_link_atom_ = JS_ATOM_NULL; JS_FreeValue(ctx_, source_map_error_source_callback_); source_map_error_source_callback_ = JS_UNDEFINED; torn_down_ = true; @@ -313,20 +368,22 @@ namespace quickjs::detail return napi_ok; } - napi_contextify__::context_record *napi_contextify__::find_context_record(JSValueConst sandbox) const + napi_contextify__::context_record *napi_contextify__::find_live_record(JSValueConst global_or_sandbox) const { - for (const auto &record : contexts_) - { - if (record != nullptr && !record->disposed && is_same_object(record->sandbox, sandbox)) - return record.get(); - } - return nullptr; + if (!JS_IsObject(global_or_sandbox)) + return nullptr; + auto it = records_by_global_.find(JS_VALUE_GET_PTR(global_or_sandbox)); + return it != records_by_global_.end() && it->second->live() ? it->second : nullptr; } napi_contextify__::context_record *napi_contextify__::create_context_record( - JSValueConst sandbox, - JSValueConst host_defined_option_id) + JSValueConst sandbox_or_undefined, + JSValueConst host_defined_option_id, + napi_value *key_out) { + prune_collected_records(); + if (!ensure_link_atoms()) + return nullptr; JSRuntime *rt = JS_GetRuntime(ctx_); JSContext *child_ctx = JS_NewContext(rt); if (child_ctx == nullptr) @@ -342,28 +399,89 @@ namespace quickjs::detail auto record = std::make_unique(env_, ctx_, - sandbox, + sandbox_or_undefined, child_ctx, child_global, host_defined_option_id); + // The context keeps its global alive; the record borrows it. + JS_FreeValue(child_ctx, child_global); context_record *raw = record.get(); - contexts_.push_back(std::move(record)); - if (collect_global_baseline(raw) != napi_ok) + + // A function made in the realm keeps its context alive. The links are + // own properties even on a Proxy sandbox: no trap sees them. + JSValueConst key = raw->key(); + bool linked = false; + JSValue anchor = JS_NewCFunction(child_ctx, contextify_anchor, "contextify", 0); + if (!JS_IsException(anchor)) { - destroy_context_record(raw); + int stored = JS_DefinePropertyValue(ctx_, key, context_link_atom_, anchor, k_contextify_link_flags); + raw->anchored = stored > 0; + if (stored > 0) + linked = !raw->has_sandbox() || + JS_DefinePropertyValue(child_ctx, raw->global, sandbox_link_atom_, + JS_DupValue(child_ctx, raw->sandbox), + k_contextify_link_flags) > 0; + else if (stored == 0) + linked = raw->owns_context = true; + } + linked = linked && JS_AddNativeWeakRefLink(ctx_, key, &raw->key_link, + context_record::key_collected, raw) >= 0; + // The current scope holds the key, and so the realm, before this + // function lets go of the context. + if (!linked || (raw->has_sandbox() && collect_global_baseline(raw) != napi_ok) || + napi_util__::wrap_dup(env_, key, key_out) != napi_ok) + { + if (JS_HasException(child_ctx)) + JS_FreeValue(child_ctx, JS_GetException(child_ctx)); + if (raw->anchored) + { + JS_DeleteProperty(ctx_, key, context_link_atom_, 0); + JS_DeleteProperty(child_ctx, raw->global, sandbox_link_atom_, 0); + } + JS_SetContextOpaque(child_ctx, nullptr); + // A record that owns the context releases it; otherwise drop ours. + const bool owned = raw->owns_context; + record.reset(); + if (!owned) + JS_FreeContext(child_ctx); return nullptr; } + + records_by_global_[JS_VALUE_GET_PTR(raw->global)] = raw; + if (raw->has_sandbox()) + records_by_global_[JS_VALUE_GET_PTR(raw->sandbox)] = raw; + contexts_.push_back(std::move(record)); + // From here the key (or, when it cannot hold the link, the record) + // owns the context. + if (!raw->owns_context) + JS_FreeContext(child_ctx); return raw; } - void napi_contextify__::destroy_context_record(context_record *record) + // Releases the records of collected realms. + void napi_contextify__::prune_collected_records() { - if (record == nullptr) - return; - auto it = std::find_if(contexts_.begin(), contexts_.end(), [record](const auto &entry) - { return entry.get() == record; }); - if (it != contexts_.end()) - contexts_.erase(it); + for (auto it = records_by_global_.begin(); it != records_by_global_.end();) + it = it->second->collected ? records_by_global_.erase(it) : std::next(it); + contexts_.erase(std::remove_if(contexts_.begin(), contexts_.end(), [](const auto &entry) + { return entry->collected; }), + contexts_.end()); + } + + bool napi_contextify__::ensure_link_atoms() + { + if (context_link_atom_ != JS_ATOM_NULL && sandbox_link_atom_ != JS_ATOM_NULL) + return true; + JSValue context_symbol = JS_NewPrivateSymbol(ctx_, "contextify context"); + JSValue sandbox_symbol = JS_NewPrivateSymbol(ctx_, "contextify sandbox"); + if (!JS_IsException(context_symbol) && !JS_IsException(sandbox_symbol)) + { + context_link_atom_ = JS_ValueToAtom(ctx_, context_symbol); + sandbox_link_atom_ = JS_ValueToAtom(ctx_, sandbox_symbol); + } + JS_FreeValue(ctx_, context_symbol); + JS_FreeValue(ctx_, sandbox_symbol); + return context_link_atom_ != JS_ATOM_NULL && sandbox_link_atom_ != JS_ATOM_NULL; } bool napi_contextify__::compile_trace_enabled() const @@ -696,51 +814,73 @@ namespace quickjs::detail return napi_ok; } - napi_status napi_contextify__::make_context(napi_value sandbox_or_symbol, - napi_value name, - napi_value origin_or_undefined, - bool allow_code_gen_strings, - bool allow_code_gen_wasm, - bool own_microtask_queue, - napi_value host_defined_option_id, - napi_value *result_out) + napi_status napi_contextify__::create_realm(const unofficial_napi_realm_options &options, + unofficial_napi_realm *realm_out, + napi_value *global_out) { - (void)name; - (void)origin_or_undefined; - (void)allow_code_gen_strings; - (void)allow_code_gen_wasm; - (void)own_microtask_queue; - if (!napi_util__::check_env(env_) || sandbox_or_symbol == nullptr || result_out == nullptr) + // QuickJS has no per-realm code-generation switches or microtask + // queues; name and origin only label V8 inspector contexts. + if (!napi_util__::check_env(env_) || realm_out == nullptr) return napi_invalid_arg; - JSValue sandbox = napi_quickjs_value_inner(env_, sandbox_or_symbol); - if (!JS_IsObject(sandbox)) - return napi_invalid_arg; - context_record *record = find_context_record(sandbox); + JSValueConst sandbox = JS_UNDEFINED; + if (options.sandbox_or_null != nullptr) + { + sandbox = napi_quickjs_value_inner(env_, options.sandbox_or_null); + if (!JS_IsObject(sandbox)) + return napi_object_expected; + if (find_live_record(sandbox) != nullptr) + return napi_invalid_arg; + } + JSValueConst host_id = options.host_defined_option_id == nullptr + ? JS_UNDEFINED + : napi_quickjs_value_inner(env_, options.host_defined_option_id); + napi_value key = nullptr; + context_record *record = create_context_record(sandbox, host_id, &key); if (record == nullptr) + return napi_util__::return_pending_if_caught(env_, "Failed to create QuickJS context"); + if (record->has_sandbox()) { - JSValue host_id = host_defined_option_id == nullptr ? JS_UNDEFINED : napi_quickjs_value_inner(env_, host_defined_option_id); - record = create_context_record(sandbox, host_id); - if (record == nullptr) - return napi_util__::return_pending_if_caught(env_, "Failed to create QuickJS context"); + napi_status status = define_contextify_internal_property(env_, + ctx_, + sandbox, + "__quickjs_contextified", + JS_NewBool(ctx_, true)); + if (status == napi_ok) + status = define_contextify_internal_property(env_, + ctx_, + sandbox, + "globalThis", + JS_DupValue(ctx_, sandbox)); + if (status != napi_ok) + return status; } - napi_status status = define_contextify_internal_property(env_, - ctx_, - sandbox, - "__quickjs_contextified", - JS_NewBool(ctx_, true)); - if (status != napi_ok) - return status; - status = define_contextify_internal_property(env_, - ctx_, - sandbox, - "globalThis", - JS_DupValue(ctx_, sandbox)); - if (status != napi_ok) - return status; - return napi_util__::wrap_dup(env_, sandbox, result_out); + // The handle is valid while the current scope holds the key. + *realm_out = reinterpret_cast(record); + if (global_out != nullptr) + *global_out = key; + return napi_ok; } - napi_status napi_contextify__::run_script(napi_value sandbox_or_null, + napi_status napi_contextify__::get_realm(napi_value value, unofficial_napi_realm *realm_out) const + { + if (!napi_util__::check_env(env_) || value == nullptr || realm_out == nullptr) + return napi_invalid_arg; + JSValueConst object = napi_quickjs_value_inner(env_, value); + if (!JS_IsObject(object)) + return napi_object_expected; + *realm_out = reinterpret_cast(find_live_record(object)); + return napi_ok; + } + + JSContext *napi_contextify__::realm_context(unofficial_napi_realm realm) const + { + if (realm == nullptr) + return ctx_; + auto *record = reinterpret_cast(realm); + return record->live() ? record->ctx : nullptr; + } + + napi_status napi_contextify__::run_script(unofficial_napi_realm realm, const unofficial_napi_js_source *source, napi_value filename, int32_t line_offset, @@ -764,22 +904,10 @@ namespace quickjs::detail if (bytecode_record != nullptr && bytecode_record->shape != unofficial_napi_bytecode_shape_script) return napi_invalid_arg; + auto *record = reinterpret_cast(realm); + if (record != nullptr && !record->live()) + return napi_invalid_arg; env_->module_wrap().register_dynamic_import_referrer(filename, host_defined_option_id); - context_record *record = nullptr; - if (sandbox_or_null != nullptr && !JS_IsNull(napi_quickjs_value_inner(env_, sandbox_or_null))) - { - if (!napi_util__::is_truthy_property(env_, sandbox_or_null, "__quickjs_contextified")) - { - env_->module_wrap().unregister_dynamic_import_referrer(filename, host_defined_option_id); - return napi_invalid_arg; - } - record = find_context_record(napi_quickjs_value_inner(env_, sandbox_or_null)); - if (record == nullptr || record->disposed) - { - env_->module_wrap().unregister_dynamic_import_referrer(filename, host_defined_option_id); - return napi_invalid_arg; - } - } std::string src = bytecode_record != nullptr ? bytecode_record->source_utf8 : napi_util__::to_utf8(env_, source->text); @@ -787,19 +915,27 @@ namespace quickjs::detail JSValue result = JS_UNDEFINED; if (record != nullptr) { - napi_status sync_status = sync_sandbox_to_context(record); + napi_status sync_status = record->has_sandbox() ? sync_sandbox_to_context(record) : napi_ok; if (sync_status != napi_ok) { env_->module_wrap().unregister_dynamic_import_referrer(filename, host_defined_option_id); return sync_status; } - JSEvalOptions options{ - .version = JS_EVAL_OPTIONS_VERSION, - .eval_flags = JS_EVAL_TYPE_GLOBAL, - .filename = label.c_str(), - .line_num = std::max(1, line_offset + 1), - }; - result = JS_EvalThis2(record->ctx, record->global, src.c_str(), src.size(), &options); + if (bytecode_record != nullptr && bytecode_record->ctx == record->ctx && + !JS_IsUndefined(bytecode_record->artifact)) + { + result = JS_EvalFunction(record->ctx, JS_DupValue(record->ctx, bytecode_record->artifact)); + } + else + { + JSEvalOptions options{ + .version = JS_EVAL_OPTIONS_VERSION, + .eval_flags = JS_EVAL_TYPE_GLOBAL, + .filename = label.c_str(), + .line_num = std::max(1, line_offset + 1), + }; + result = JS_EvalThis2(record->ctx, record->global, src.c_str(), src.size(), &options); + } if (JS_IsException(result)) { JSValue exc = JS_GetException(record->ctx); @@ -807,7 +943,7 @@ namespace quickjs::detail env_->module_wrap().unregister_dynamic_import_referrer(filename, host_defined_option_id); return napi_quickjs_set_last_error(env_, napi_pending_exception, "Exception while running contextify script"); } - sync_status = sync_context_to_sandbox(record); + sync_status = record->has_sandbox() ? sync_context_to_sandbox(record) : napi_ok; if (sync_status != napi_ok) { JS_FreeValue(record->ctx, result); @@ -819,7 +955,8 @@ namespace quickjs::detail return (*result_out == nullptr) ? napi_generic_failure : napi_ok; } - if (bytecode_record != nullptr && !JS_IsUndefined(bytecode_record->artifact)) + if (bytecode_record != nullptr && bytecode_record->ctx == ctx_ && + !JS_IsUndefined(bytecode_record->artifact)) { // JS_EvalFunction consumes its argument; the artifact stays reusable. result = JS_EvalFunction(ctx_, JS_DupValue(ctx_, bytecode_record->artifact)); @@ -834,24 +971,11 @@ namespace quickjs::detail return napi_util__::wrap_owned(env_, result, result_out); } - napi_status napi_contextify__::dispose_context(napi_value sandbox_or_context_global) - { - if (!napi_util__::check_env(env_) || sandbox_or_context_global == nullptr) - return napi_invalid_arg; - JSValue sandbox = napi_quickjs_value_inner(env_, sandbox_or_context_global); - if (!JS_IsObject(sandbox)) - return napi_invalid_arg; - context_record *record = find_context_record(sandbox); - if (record != nullptr) - destroy_context_record(record); - return define_contextify_internal_property(env_, ctx_, sandbox, "__quickjs_contextified", JS_NewBool(ctx_, false)); - } - - napi_status napi_contextify__::compile_function(const unofficial_napi_js_source *source, + napi_status napi_contextify__::compile_function(unofficial_napi_realm realm, + const unofficial_napi_js_source *source, napi_value filename, int32_t line_offset, int32_t column_offset, - napi_value parsing_context_or_undefined, napi_value context_extensions_or_undefined, napi_value params_or_undefined, napi_value host_defined_option_id, @@ -867,6 +991,9 @@ namespace quickjs::detail if (bytecode_record != nullptr && bytecode_record->shape != unofficial_napi_bytecode_shape_cjs_function) return napi_invalid_arg; + auto *record = reinterpret_cast(realm); + if (record != nullptr && !record->live()) + return napi_invalid_arg; std::vector params; if (params_or_undefined != nullptr && JS_IsArray(napi_quickjs_value_inner(env_, params_or_undefined))) @@ -894,23 +1021,22 @@ namespace quickjs::detail source_url = napi_util__::to_utf8(env_, filename); } - context_record *record = nullptr; - if (parsing_context_or_undefined != nullptr && - !JS_IsUndefined(napi_quickjs_value_inner(env_, parsing_context_or_undefined)) && - !JS_IsNull(napi_quickjs_value_inner(env_, parsing_context_or_undefined))) + JSContext *compile_ctx = record == nullptr ? ctx_ : record->ctx; + // The function sees the sandbox's globals as they are now. + if (record != nullptr && record->has_sandbox()) { - record = find_context_record(napi_quickjs_value_inner(env_, parsing_context_or_undefined)); + napi_status sync_status = sync_sandbox_to_context(record); + if (sync_status != napi_ok) + return sync_status; } - JSContext *compile_ctx = record == nullptr ? ctx_ : record->ctx; - JSValue fn = JS_UNDEFINED; bool have_fn = false; - if (bytecode_record != nullptr && compile_ctx == ctx_ && + if (bytecode_record != nullptr && bytecode_record->ctx == compile_ctx && !JS_IsUndefined(bytecode_record->artifact)) { // The handle's artifact is the compiled function; reuse it directly. - fn = JS_DupValue(ctx_, bytecode_record->artifact); + fn = JS_DupValue(compile_ctx, bytecode_record->artifact); have_fn = true; } @@ -929,8 +1055,7 @@ namespace quickjs::detail if (JS_IsException(fn)) { JSValue exc = JS_GetException(compile_ctx); - if (compile_ctx == ctx_) - annotate_compile_exception(exc, diagnostic_source, source_url, line_offset, column_offset); + annotate_compile_exception(exc, diagnostic_source, source_url, line_offset, column_offset); napi_util__::set_last_exception(env_, exc); return napi_pending_exception; } @@ -1047,7 +1172,8 @@ namespace quickjs::detail } } - napi_status napi_contextify__::bytecode_compile(napi_value source_text, + napi_status napi_contextify__::bytecode_compile(JSContext *target, + napi_value source_text, napi_value filename, int32_t shape, napi_value params_or_undefined, @@ -1059,14 +1185,15 @@ namespace quickjs::detail { (void)host_defined_option_id; // QuickJS handles HDO at record registration. (void)column_offset; // QuickJS JS_Eval2 keys only on line_num. - if (!napi_util__::check_env(env_) || source_text == nullptr || bytecode_out == nullptr) + if (!napi_util__::check_env(env_) || target == nullptr || source_text == nullptr || + bytecode_out == nullptr) return napi_invalid_arg; *bytecode_out = nullptr; if (can_parse_as_module_out != nullptr) *can_parse_as_module_out = false; auto record = std::make_unique(); - record->ctx = ctx_; + record->ctx = target; record->source_utf8 = napi_util__::to_utf8(env_, source_text); record->filename_utf8 = filename != nullptr ? napi_util__::to_utf8(env_, filename) : std::string(); record->shape = shape; @@ -1075,11 +1202,11 @@ namespace quickjs::detail if (shape == unofficial_napi_bytecode_shape_cjs_function) { std::vector produced; - JSValue fn = compile_cjs_function(ctx_, record->source_utf8, record->filename_utf8, + JSValue fn = compile_cjs_function(target, record->source_utf8, record->filename_utf8, record->params, nullptr, nullptr, 0, true, &produced, nullptr); if (JS_IsException(fn)) { - JSValue exc = JS_GetException(ctx_); + JSValue exc = JS_GetException(target); if (can_parse_as_module_out != nullptr) *can_parse_as_module_out = can_parse_as_module(record->source_utf8, record->filename_utf8); napi_util__::set_last_exception(env_, exc); @@ -1099,10 +1226,10 @@ namespace quickjs::detail .filename = record->filename_utf8.empty() ? "" : record->filename_utf8.c_str(), .line_num = std::max(1, line_offset + 1), }; - JSValue compiled = JS_Eval2(ctx_, record->source_utf8.c_str(), record->source_utf8.size(), &options); + JSValue compiled = JS_Eval2(target, record->source_utf8.c_str(), record->source_utf8.size(), &options); if (JS_IsException(compiled)) { - JSValue exc = JS_GetException(ctx_); + JSValue exc = JS_GetException(target); if (!is_module && can_parse_as_module_out != nullptr) *can_parse_as_module_out = can_parse_as_module(record->source_utf8, record->filename_utf8); napi_util__::set_last_exception(env_, exc); @@ -1111,19 +1238,19 @@ namespace quickjs::detail size_t serialized_size = 0; const int write_flags = is_module ? (JS_WRITE_OBJ_BYTECODE | JS_WRITE_OBJ_REFERENCE) : JS_WRITE_OBJ_BYTECODE; - uint8_t *serialized = JS_WriteObject(ctx_, &serialized_size, compiled, write_flags); + uint8_t *serialized = JS_WriteObject(target, &serialized_size, compiled, write_flags); if (serialized != nullptr) { record->bytes.assign(serialized, serialized + serialized_size); - js_free(ctx_, serialized); + js_free(target, serialized); } else { // JS_WriteObject raised an exception (e.g. OOM); drop it so it // does not leak pending out of this napi_ok return. The handle // still holds the live artifact; only serialization is lost. - JSValue exc = JS_GetException(ctx_); - JS_FreeValue(ctx_, exc); + JSValue exc = JS_GetException(target); + JS_FreeValue(target, exc); } record->artifact = compiled; } @@ -1132,11 +1259,14 @@ namespace quickjs::detail return napi_invalid_arg; } + if (target != ctx_) + JS_DupContext(target); *bytecode_out = reinterpret_cast(record.release()); return napi_ok; } - napi_status napi_contextify__::bytecode_deserialize(const uint8_t *bytes, + napi_status napi_contextify__::bytecode_deserialize(JSContext *target, + const uint8_t *bytes, size_t byte_length, napi_value source_text, napi_value filename, @@ -1147,15 +1277,15 @@ namespace quickjs::detail bool *rejected_out) { (void)host_defined_option_id; // QuickJS handles HDO at record registration. - if (!napi_util__::check_env(env_) || bytes == nullptr || byte_length == 0 || - source_text == nullptr || bytecode_out == nullptr) + if (!napi_util__::check_env(env_) || target == nullptr || bytes == nullptr || + byte_length == 0 || source_text == nullptr || bytecode_out == nullptr) return napi_invalid_arg; *bytecode_out = nullptr; if (rejected_out != nullptr) *rejected_out = false; auto record = std::make_unique(); - record->ctx = ctx_; + record->ctx = target; record->source_utf8 = napi_util__::to_utf8(env_, source_text); record->filename_utf8 = filename != nullptr ? napi_util__::to_utf8(env_, filename) : std::string(); record->shape = shape; @@ -1187,15 +1317,15 @@ namespace quickjs::detail { std::unique_ptr guard; if (is_module) - guard = std::make_unique(JS_GetRuntime(ctx_)); + guard = std::make_unique(JS_GetRuntime(target)); const int read_flags = is_module ? (JS_READ_OBJ_BYTECODE | JS_READ_OBJ_REFERENCE) : JS_READ_OBJ_BYTECODE; - restored = JS_ReadObject(ctx_, record->bytes.data(), record->bytes.size(), read_flags); + restored = JS_ReadObject(target, record->bytes.data(), record->bytes.size(), read_flags); } if (JS_IsException(restored)) { - JSValue exc = JS_GetException(ctx_); - JS_FreeValue(ctx_, exc); + JSValue exc = JS_GetException(target); + JS_FreeValue(target, exc); if (rejected_out != nullptr) *rejected_out = true; return napi_ok; @@ -1205,11 +1335,11 @@ namespace quickjs::detail { // Evaluating the serialized wrapper expression yields the function // without running its body. - JSValue fn = JS_EvalFunction(ctx_, restored); + JSValue fn = JS_EvalFunction(target, restored); if (JS_IsException(fn)) { - JSValue exc = JS_GetException(ctx_); - JS_FreeValue(ctx_, exc); + JSValue exc = JS_GetException(target); + JS_FreeValue(target, exc); if (rejected_out != nullptr) *rejected_out = true; return napi_ok; @@ -1221,6 +1351,8 @@ namespace quickjs::detail record->artifact = restored; } + if (target != ctx_) + JS_DupContext(target); *bytecode_out = reinterpret_cast(record.release()); return napi_ok; } @@ -1255,8 +1387,12 @@ namespace quickjs::detail if (bytecode == nullptr) return napi_invalid_arg; auto *record = reinterpret_cast(bytecode); - if (record->ctx != nullptr && !JS_IsUndefined(record->artifact)) - JS_FreeValue(record->ctx, record->artifact); + if (record->ctx != nullptr) + { + JS_FreeValueRT(JS_GetRuntime(record->ctx), record->artifact); + if (record->ctx != ctx_) + JS_FreeContext(record->ctx); + } delete record; return napi_ok; } diff --git a/quickjs/src/internal/napi_contextify.h b/quickjs/src/internal/napi_contextify.h index 9936fc2221..94eaa9e809 100644 --- a/quickjs/src/internal/napi_contextify.h +++ b/quickjs/src/internal/napi_contextify.h @@ -8,6 +8,7 @@ #include #include #include +#include #include namespace quickjs::detail @@ -31,15 +32,17 @@ namespace quickjs::detail napi_status preserve_error_source_message(napi_value error); napi_status configure_source_maps(bool enabled, napi_value callback); - napi_status make_context(napi_value sandbox_or_symbol, - napi_value name, - napi_value origin_or_undefined, - bool allow_code_gen_strings, - bool allow_code_gen_wasm, - bool own_microtask_queue, - napi_value host_defined_option_id, - napi_value *result_out); - napi_status run_script(napi_value sandbox_or_null, + // Realms: a JSContext on the env's runtime, with its sandbox when it + // has one. An unofficial_napi_realm is a context_record. + napi_status create_realm(const unofficial_napi_realm_options &options, + unofficial_napi_realm *realm_out, + napi_value *global_out); + napi_status get_realm(napi_value value, unofficial_napi_realm *realm_out) const; + // The context code for `realm` runs in: the realm's, or the env's + // for NULL. + JSContext *realm_context(unofficial_napi_realm realm) const; + + napi_status run_script(unofficial_napi_realm realm, const unofficial_napi_js_source *source, napi_value filename, int32_t line_offset, @@ -50,12 +53,11 @@ namespace quickjs::detail bool break_on_first_line, napi_value host_defined_option_id, napi_value *result_out); - napi_status dispose_context(napi_value sandbox_or_context_global); - napi_status compile_function(const unofficial_napi_js_source *source, + napi_status compile_function(unofficial_napi_realm realm, + const unofficial_napi_js_source *source, napi_value filename, int32_t line_offset, int32_t column_offset, - napi_value parsing_context_or_undefined, napi_value context_extensions_or_undefined, napi_value params_or_undefined, napi_value host_defined_option_id, @@ -65,7 +67,8 @@ namespace quickjs::detail napi_value resource_name_or_undefined, bool cjs_var_in_scope, bool *result_out); - napi_status bytecode_compile(napi_value source_text, + napi_status bytecode_compile(JSContext *target, + napi_value source_text, napi_value filename, int32_t shape, napi_value params_or_undefined, @@ -74,7 +77,8 @@ namespace quickjs::detail int32_t column_offset, unofficial_napi_bytecode *bytecode_out, bool *can_parse_as_module_out); - napi_status bytecode_deserialize(const uint8_t *bytes, + napi_status bytecode_deserialize(JSContext *target, + const uint8_t *bytes, size_t byte_length, napi_value source_text, napi_value filename, @@ -111,10 +115,12 @@ namespace quickjs::detail const std::string &resource_name, int32_t line_offset, int32_t column_offset); - context_record *find_context_record(JSValueConst sandbox) const; - context_record *create_context_record(JSValueConst sandbox, - JSValueConst host_defined_option_id); - void destroy_context_record(context_record *record); + context_record *find_live_record(JSValueConst global_or_sandbox) const; + context_record *create_context_record(JSValueConst sandbox_or_undefined, + JSValueConst host_defined_option_id, + napi_value *key_out); + void prune_collected_records(); + bool ensure_link_atoms(); // Owning environment and QuickJS context. napi_env env_; @@ -124,6 +130,13 @@ namespace quickjs::detail bool source_maps_enabled_ = false; JSValue source_map_error_source_callback_; std::vector> contexts_; + // A realm's global and its sandbox to the realm. Entries of collected + // realms stay until the next prune; a new realm at the same address + // replaces them. + std::unordered_map records_by_global_; + // Private symbols linking a realm's context and its sandbox. + JSAtom context_link_atom_ = JS_ATOM_NULL; + JSAtom sandbox_link_atom_ = JS_ATOM_NULL; // Subsystem lifecycle. bool torn_down_ = false; diff --git a/quickjs/src/internal/napi_module_wrap.cc b/quickjs/src/internal/napi_module_wrap.cc index 61a5dabaa5..da5d0efbc1 100644 --- a/quickjs/src/internal/napi_module_wrap.cc +++ b/quickjs/src/internal/napi_module_wrap.cc @@ -106,7 +106,8 @@ struct napi_module_wrap__::request_record struct napi_module_wrap__::record { - napi_module_wrap__ *owner = nullptr; + // The realm the module lives in; the record holds it unless it is the env's. + JSContext *ctx = nullptr; JSModuleDef *module = nullptr; JSValue module_value = JS_UNDEFINED; JSValue wrapper = JS_UNDEFINED; @@ -220,6 +221,8 @@ void napi_module_wrap__::free_record(record *entry) JS_FreeValue(ctx_, entry->host_defined_option_id); JS_FreeValue(ctx_, entry->synthetic_eval_steps); JS_FreeValue(ctx_, entry->source_object); + if (entry->ctx != nullptr && entry->ctx != ctx_) + JS_FreeContext(entry->ctx); delete entry; } @@ -400,10 +403,7 @@ JSValue napi_module_wrap__::call_callback(JSValueConst callback, { if (!JS_IsFunction(ctx_, callback)) return JS_UNDEFINED; - JSValue global = JS_GetGlobalObject(ctx_); - JSValue result = JS_Call(ctx_, callback, global, argc, argv); - JS_FreeValue(ctx_, global); - return result; + return JS_Call(ctx_, callback, JS_UNDEFINED, argc, argv); } napi_status napi_module_wrap__::cache_module_requests(record *entry) @@ -437,18 +437,18 @@ napi_status napi_module_wrap__::cache_module_requests(record *entry) return napi_ok; } -napi_status napi_module_wrap__::create_source_text(napi_value wrapper, +napi_status napi_module_wrap__::create_source_text(JSContext *ctx, + napi_value wrapper, napi_value url, - napi_value context_or_undefined, const unofficial_napi_js_source *source, int32_t line_offset, int32_t column_offset, napi_value host_defined_option_id, unofficial_napi_module *module_out) { - (void)context_or_undefined; (void)column_offset; - if (!napi_util__::check_value(env_, wrapper) || + if (ctx == nullptr || + !napi_util__::check_value(env_, wrapper) || !napi_util__::check_value(env_, url) || !unofficial_napi_js_source_is_valid(source) || module_out == nullptr) @@ -473,7 +473,7 @@ napi_status napi_module_wrap__::create_source_text(napi_value wrapper, JSValue module_value = JS_UNDEFINED; if (bytecode_record != nullptr && !JS_IsUndefined(bytecode_record->artifact) && - bytecode_record->ctx == ctx_) + bytecode_record->ctx == ctx) { // Reuse the deserialized/compiled module artifact: same JSModuleDef the // bytecode handle registered, so import.meta/dynamic-import records and @@ -488,7 +488,7 @@ napi_status napi_module_wrap__::create_source_text(napi_value wrapper, .filename = url_string.empty() ? "" : url_string.c_str(), .line_num = line_offset + 1, }; - module_value = JS_Eval2(ctx_, source_string.c_str(), + module_value = JS_Eval2(ctx, source_string.c_str(), source_string.size(), &options); } if (JS_IsException(module_value)) @@ -497,7 +497,7 @@ napi_status napi_module_wrap__::create_source_text(napi_value wrapper, return return_pending_exception("Module compile failed"); } - JSModuleDef *module = JS_GetModuleDef(ctx_, module_value); + JSModuleDef *module = JS_GetModuleDef(ctx, module_value); if (module == nullptr) { JS_FreeValue(ctx_, host_id); @@ -512,7 +512,7 @@ napi_status napi_module_wrap__::create_source_text(napi_value wrapper, JS_FreeValue(ctx_, module_value); return napi_generic_failure; } - entry->owner = this; + entry->ctx = ctx == ctx_ ? ctx : JS_DupContext(ctx); entry->module = module; entry->module_value = module_value; entry->wrapper = JS_DupValue(ctx_, napi_quickjs_value_inner(env_, wrapper)); @@ -535,15 +535,15 @@ napi_status napi_module_wrap__::create_source_text(napi_value wrapper, return napi_ok; } -napi_status napi_module_wrap__::create_synthetic(napi_value wrapper, +napi_status napi_module_wrap__::create_synthetic(JSContext *ctx, + napi_value wrapper, napi_value url, - napi_value context_or_undefined, napi_value export_names, napi_value synthetic_eval_steps, unofficial_napi_module *module_out) { - (void)context_or_undefined; - if (!napi_util__::check_value(env_, wrapper) || + if (ctx == nullptr || + !napi_util__::check_value(env_, wrapper) || !napi_util__::check_value(env_, url) || !napi_util__::check_value(env_, export_names) || !napi_util__::check_value(env_, synthetic_eval_steps) || @@ -552,7 +552,7 @@ napi_status napi_module_wrap__::create_synthetic(napi_value wrapper, *module_out = nullptr; std::string url_string = napi_util__::to_utf8(env_, url); - JSModuleDef *module = JS_NewCModule(ctx_, + JSModuleDef *module = JS_NewCModule(ctx, url_string.empty() ? "" : url_string.c_str(), synthetic_init); if (module == nullptr) @@ -569,14 +569,14 @@ napi_status napi_module_wrap__::create_synthetic(napi_value wrapper, return return_pending_exception("Failed to read synthetic export name"); std::string name = value_to_string(ctx_, name_value); JS_FreeValue(ctx_, name_value); - if (JS_AddModuleExport(ctx_, module, name.c_str()) < 0) + if (JS_AddModuleExport(ctx, module, name.c_str()) < 0) return return_pending_exception("Failed to add synthetic export"); } auto *entry = new (std::nothrow) record{}; if (entry == nullptr) return napi_generic_failure; - entry->owner = this; + entry->ctx = ctx == ctx_ ? ctx : JS_DupContext(ctx); entry->module = module; entry->module_value = JS_DupModuleValue(ctx_, module); entry->wrapper = JS_DupValue(ctx_, napi_quickjs_value_inner(env_, wrapper)); @@ -687,7 +687,7 @@ napi_status napi_module_wrap__::instantiate(unofficial_napi_module module) record *entry = find(module); if (entry == nullptr) return napi_util__::invalid_arg(env_); - if (JS_LinkModule(ctx_, entry->module) < 0) + if (JS_LinkModule(entry->ctx, entry->module) < 0) return return_pending_exception("Module linking failed"); return napi_ok; } @@ -702,7 +702,7 @@ 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_); - JSValue promise = JS_EvaluateModule(ctx_, entry->module); + JSValue promise = JS_EvaluateModule(entry->ctx, entry->module); if (JS_IsException(promise)) return return_pending_exception("Failed to evaluate module"); return wrap_owned(promise, result_out); @@ -719,7 +719,7 @@ napi_status napi_module_wrap__::evaluate_sync(unofficial_napi_module module, if (entry == nullptr || result_out == nullptr) return napi_util__::invalid_arg(env_); - JSValue promise = JS_EvaluateModule(ctx_, entry->module); + JSValue promise = JS_EvaluateModule(entry->ctx, entry->module); if (JS_IsException(promise)) return return_pending_exception("Failed to evaluate module"); @@ -1007,6 +1007,7 @@ napi_status napi_module_wrap__::create_required_module_facade(unofficial_napi_mo if (entry == nullptr || result_out == nullptr) return napi_util__::invalid_arg(env_); + JSContext *ctx = entry->ctx; std::string filename = ""; static constexpr const char *kFacadeSource = @@ -1019,50 +1020,50 @@ napi_status napi_module_wrap__::create_required_module_facade(unofficial_napi_mo .filename = filename.c_str(), .line_num = 1, }; - JSValue facade_value = JS_Eval2(ctx_, kFacadeSource, std::strlen(kFacadeSource), + JSValue facade_value = JS_Eval2(ctx, kFacadeSource, std::strlen(kFacadeSource), &options); if (JS_IsException(facade_value)) return return_pending_exception("Failed to compile required module facade"); - JSModuleDef *facade = JS_GetModuleDef(ctx_, facade_value); + JSModuleDef *facade = JS_GetModuleDef(ctx, facade_value); if (facade == nullptr) { - JS_FreeValue(ctx_, facade_value); + JS_FreeValue(ctx, facade_value); return napi_generic_failure; } - if (JS_GetModuleRequestCount(ctx_, facade) < 1 || - JS_SetModuleRequestModule(ctx_, facade, 0, entry->module) < 0 || - JS_LinkModule(ctx_, facade) < 0) + if (JS_GetModuleRequestCount(ctx, facade) < 1 || + JS_SetModuleRequestModule(ctx, facade, 0, entry->module) < 0 || + JS_LinkModule(ctx, facade) < 0) { - JS_FreeValue(ctx_, facade_value); + JS_FreeValue(ctx, facade_value); return return_pending_exception("Failed to link required module facade"); } - JSValue promise = JS_EvaluateModule(ctx_, facade); + JSValue promise = JS_EvaluateModule(ctx, facade); if (JS_IsException(promise)) { - JS_FreeValue(ctx_, facade_value); + JS_FreeValue(ctx, facade_value); return return_pending_exception("Failed to evaluate required module facade"); } - JSPromiseStateEnum state = JS_PromiseState(ctx_, promise); + JSPromiseStateEnum state = JS_PromiseState(ctx, promise); if (state == JS_PROMISE_REJECTED) { - JSValue reason = JS_PromiseResult(ctx_, promise); - JS_FreeValue(ctx_, promise); - JS_FreeValue(ctx_, facade_value); + JSValue reason = JS_PromiseResult(ctx, promise); + JS_FreeValue(ctx, promise); + JS_FreeValue(ctx, facade_value); env_->set_last_exception(reason); return napi_pending_exception; } - JS_FreeValue(ctx_, promise); + JS_FreeValue(ctx, promise); if (state != JS_PROMISE_FULFILLED) { - JS_FreeValue(ctx_, facade_value); + JS_FreeValue(ctx, facade_value); return throw_error("ERR_REQUIRE_ASYNC_MODULE", "require() cannot be used on an ESM graph with top-level await"); } - JSValue ns = JS_GetModuleNamespace(ctx_, facade); - JS_FreeValue(ctx_, facade_value); + JSValue ns = JS_GetModuleNamespace(ctx, facade); + JS_FreeValue(ctx, facade_value); if (JS_IsException(ns)) return return_pending_exception("Failed to get required module facade namespace"); return wrap_owned(ns, result_out); diff --git a/quickjs/src/internal/napi_module_wrap.h b/quickjs/src/internal/napi_module_wrap.h index ffcd7f1834..171d64b068 100644 --- a/quickjs/src/internal/napi_module_wrap.h +++ b/quickjs/src/internal/napi_module_wrap.h @@ -21,17 +21,18 @@ class napi_module_wrap__ void teardown(); - napi_status create_source_text(napi_value wrapper, + // A module lives in the realm whose context `ctx` is. + napi_status create_source_text(JSContext *ctx, + napi_value wrapper, napi_value url, - napi_value context_or_undefined, const unofficial_napi_js_source *source, int32_t line_offset, int32_t column_offset, napi_value host_defined_option_id, unofficial_napi_module *module_out); - napi_status create_synthetic(napi_value wrapper, + napi_status create_synthetic(JSContext *ctx, + napi_value wrapper, napi_value url, - napi_value context_or_undefined, napi_value export_names, napi_value synthetic_eval_steps, unofficial_napi_module *module_out); diff --git a/quickjs/src/internal/napi_promises.cc b/quickjs/src/internal/napi_promises.cc index ccc1666f9f..14a24370ee 100644 --- a/quickjs/src/internal/napi_promises.cc +++ b/quickjs/src/internal/napi_promises.cc @@ -80,9 +80,8 @@ void napi_promises__::call_function(JSValueConst function, int argc, JSValueCons if (context_ == nullptr || !JS_IsFunction(context_, function)) return; - JSValue global = JS_GetGlobalObject(context_); - JSValue ret = JS_Call(context_, function, global, argc, argv); - JS_FreeValue(context_, global); + // A hook fires for code in any realm of the env, so it gets no receiver. + JSValue ret = JS_Call(context_, function, JS_UNDEFINED, argc, argv); if (JS_IsException(ret)) { clear_pending_exception_if_any(); diff --git a/quickjs/src/unofficial_napi.cc b/quickjs/src/unofficial_napi.cc index 89770dab23..1e2062e683 100644 --- a/quickjs/src/unofficial_napi.cc +++ b/quickjs/src/unofficial_napi.cc @@ -1111,31 +1111,37 @@ extern "C" return napi_ok; } - napi_status NAPI_CDECL unofficial_napi_contextify_make_context( + napi_status NAPI_CDECL unofficial_napi_create_realm( napi_env env, - napi_value sandbox_or_symbol, - napi_value name, - napi_value origin_or_undefined, - bool allow_code_gen_strings, - bool allow_code_gen_wasm, - bool own_microtask_queue, - napi_value host_defined_option_id, - napi_value *result_out) + const unofficial_napi_realm_options *options_or_null, + unofficial_napi_realm *realm_out, + napi_value *global_out) { - return napi_util__::check_env(env) ? env->contextify().make_context(sandbox_or_symbol, - name, - origin_or_undefined, - allow_code_gen_strings, - allow_code_gen_wasm, - own_microtask_queue, - host_defined_option_id, - result_out) - : napi_invalid_arg; + unofficial_napi_realm_options options; + unofficial_napi_realm_options_init(&options); + if (options_or_null != nullptr) + { + if (options_or_null->size < sizeof(options) || + options_or_null->version != UNOFFICIAL_NAPI_REALM_OPTIONS_VERSION) + return napi_invalid_arg; + options = *options_or_null; + } + return napi_util__::check_env(env) ? env->contextify().create_realm(options, realm_out, global_out) + : napi_invalid_arg; + } + + napi_status NAPI_CDECL unofficial_napi_get_realm( + napi_env env, + napi_value value, + unofficial_napi_realm *realm_out) + { + return napi_util__::check_env(env) ? env->contextify().get_realm(value, realm_out) + : napi_invalid_arg; } - napi_status NAPI_CDECL unofficial_napi_contextify_run_script( + napi_status NAPI_CDECL unofficial_napi_run_script( napi_env env, - napi_value sandbox_or_null, + unofficial_napi_realm realm_or_null, const unofficial_napi_js_source *source, napi_value filename, int32_t line_offset, @@ -1147,7 +1153,7 @@ extern "C" napi_value host_defined_option_id, napi_value *result_out) { - return napi_util__::check_env(env) ? env->contextify().run_script(sandbox_or_null, + return napi_util__::check_env(env) ? env->contextify().run_script(realm_or_null, source, filename, line_offset, @@ -1175,11 +1181,15 @@ extern "C" return napi_invalid_arg; *result = {}; + JSContext *target = env->contextify().realm_context(options->realm_or_null); + if (target == nullptr) + return napi_invalid_arg; if (options->has_cache != 0 && options->cache_bytes != nullptr && options->cache_byte_length != 0) { bool rejected = false; - napi_status status = env->contextify().bytecode_deserialize(options->cache_bytes, + napi_status status = env->contextify().bytecode_deserialize(target, + options->cache_bytes, options->cache_byte_length, options->source_text, options->filename, @@ -1204,7 +1214,8 @@ extern "C" options->cache_policy == unofficial_napi_bytecode_cache_validate_only) return napi_ok; bool can_parse_as_module = false; - napi_status status = env->contextify().bytecode_compile(options->source_text, + napi_status status = env->contextify().bytecode_compile(target, + options->source_text, options->filename, options->shape, options->params_or_undefined, @@ -1233,23 +1244,23 @@ extern "C" : napi_invalid_arg; } - napi_status NAPI_CDECL unofficial_napi_contextify_compile_function( + napi_status NAPI_CDECL unofficial_napi_compile_function( napi_env env, + unofficial_napi_realm realm_or_null, const unofficial_napi_js_source *source, napi_value filename, int32_t line_offset, int32_t column_offset, - napi_value parsing_context_or_undefined, napi_value context_extensions_or_undefined, napi_value params_or_undefined, napi_value host_defined_option_id, napi_value *result_out) { - return napi_util__::check_env(env) ? env->contextify().compile_function(source, + return napi_util__::check_env(env) ? env->contextify().compile_function(realm_or_null, + source, filename, line_offset, column_offset, - parsing_context_or_undefined, context_extensions_or_undefined, params_or_undefined, host_defined_option_id, @@ -1284,14 +1295,17 @@ extern "C" result_out == nullptr) return napi_invalid_arg; *result_out = {}; + JSContext *ctx = env->contextify().realm_context(options->realm_or_null); + if (ctx == nullptr) + return napi_invalid_arg; napi_status status = napi_invalid_arg; switch (options->kind) { case unofficial_napi_module_source_text: status = env->module_wrap().create_source_text( + ctx, options->wrapper, options->url, - options->context_or_undefined, options->payload.source_text.source, options->payload.source_text.line_offset, options->payload.source_text.column_offset, @@ -1300,9 +1314,9 @@ extern "C" break; case unofficial_napi_module_synthetic: status = env->module_wrap().create_synthetic( + ctx, options->wrapper, options->url, - options->context_or_undefined, options->payload.synthetic.export_names, options->payload.synthetic.synthetic_evaluation_steps, &result_out->module); diff --git a/tests/runners/test_66_unofficial_realm.cc b/tests/runners/test_66_unofficial_realm.cc index f5579cffa9..8353e05330 100644 --- a/tests/runners/test_66_unofficial_realm.cc +++ b/tests/runners/test_66_unofficial_realm.cc @@ -530,6 +530,12 @@ TEST_F(Test66UnofficialRealm, RealmOutlivesItsGlobalHandleWhileReachable) { // script runs there. ASSERT_NE(RunIn(s.env, realm, "0"), nullptr); EXPECT_EQ(Int32(s.env, RunIn(s.env, realm, "state")), 1); +#else + // The microtask went to the engine's one job queue; until it runs, the + // pending job keeps its realm alive. + ASSERT_EQ(unofficial_napi_event_loop_checkpoint( + s.env, unofficial_napi_event_loop_checkpoint_microtasks, true, nullptr), + napi_ok); #endif ASSERT_EQ(napi_close_handle_scope(s.env, scope), napi_ok); } From 474582577f58a931345d711040f0cdc807694188 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Sun, 25 Oct 2026 10:36:18 +0100 Subject: [PATCH 015/150] Rewrite the design doc for realm handles An env is one engine instance's view from its main realm, and a vm context is a realm handle that only the calls that run code take. The doc covers the API, how each provider makes and collects realms, how EdgeJS uses them, what is not done and how this differs from the earlier realm-env attempts. It is renamed to realms.md, since vm contexts are no longer envs. Co-Authored-By: Claude Opus 5.5 --- docs/realm-bound-env.md | 652 ---------------------------------------- docs/realms.md | 108 +++++++ 2 files changed, 108 insertions(+), 652 deletions(-) delete mode 100644 docs/realm-bound-env.md create mode 100644 docs/realms.md diff --git a/docs/realm-bound-env.md b/docs/realm-bound-env.md deleted file mode 100644 index 4eaa96805d..0000000000 --- a/docs/realm-bound-env.md +++ /dev/null @@ -1,652 +0,0 @@ -# Realm-bound `napi_env` - -Status: Phase 0 implemented (see §11). Phases 1–4 are not started. - -**Proposal:** split each provider into an **agent**, which is the engine -instance and its thread, and **realm envs**. A realm env is a `napi_env` whose -realm is fixed when the env is created and never changes. Values and handle -scopes belong to the agent, so they work with every env of that agent. Host -hooks belong to the realm. An env lives exactly as long as its realm. - -What gets simpler: - -- **API.** No call takes a sandbox or context argument again. - `contextify_make_context` becomes `create_realm`. -- **Hooks.** The context-token hooks go away. -- **Branch not needed.** The `contextify_enter`/`leave` work on - `feat/contextify-enter-leave` is no longer needed. -- **QuickJS.** The provider stops switching a "current context". -- **host-JS.** The provider drops its fallback scopes and its active-context - switch. - ---- - -## 1. First principles: what an N-API call needs to know - -Every call needs to know four things: - -| # | What | Examples | -|---|---|---| -| A | **Agent**: which engine instance and thread. | Every call: handle allocation, throwing, GC. | -| R | **Realm**: which global object and intrinsics. | `create_object`, `create_error`, `create_function`, `create_promise`, `create_typedarray`, `get_global`, `run_script`, compiling, modules, and dispatching host hooks. | -| M | **Module instance**: which addon. | Instance data, cleanup hooks, the env passed to finalizers, API version. | -| T | **Per-call state** | Last error, pending exception, open handle scopes. | - -Today `napi_env` bundles A, M and T with a *default* R. Each layer then -overrides R per call in its own way: - -| Where | How the realm is overridden today | -|---|---| -| V8 | A `sandbox_or_null`, `parsing_context_or_undefined` or `context_or_undefined` argument, resolved by a linear scan of `g_context_records`. In about 9 places the provider uses the implicit current context instead of `env->context()`. | -| V8, `feat/contextify-enter-leave` | A selectable context stack (`context_scope`, `root_context()`) and LIFO tokens. | -| QuickJS | A mutable `current_context_`, switched at 23 `napi_env_context_scope__` sites. Every `napi_value__` carries its own `context_` tag. | -| host-JS | The module-global `wasmerNapiActiveGlobalContext`, switched per thread. vm sandboxes fall back to an anonymous global that belongs to no env. | - -**Principle:** R becomes an immutable property of the env. An env is a -capability for exactly one realm: everything done through env X happens in -realm X. No call ever has a second source of realm information. - -The rest of this document follows from that. - -## 2. What the code does today - -### V8 (`v8/src`) - -- **One env, one isolate, one context.** `unofficial_napi_create_env` creates a - fresh isolate, allocator and `v8::Context`, then calls - `unofficial_napi_create_env_from_context` (`unofficial_napi.cc:1785-1797, - 1902-2003`). -- **The owner is the agent.** `unofficial_napi_env_owner` is the - `UnofficialEnvScope`, which holds the isolate, the allocator, and - permanently open isolate, handle and context scopes. -- **vm contexts are records inside the one env.** Each `ContextRecord` (key - ref, context, own microtask queue) is pushed onto `g_context_records[env]`. - Lookups scan the list with `napi_strict_equals` - (`unofficial_napi_contextify.cc:848-861, 1333-1346`). -- **`module_wrap_create` resolves its context differently** from `run_script` - and `compile_function`. It uses `GetCreationContextChecked()` on any object - instead of looking up a contextify record. -- **Isolate-level state is spread over global maps** keyed by isolate or env: - `g_env_by_isolate` (last writer wins), `g_promise_hooks`, - `g_promise_reject_callbacks`, `g_prepare_stack_trace_callbacks`, - `g_profiler_states`, `g_module_wrap_states`, and the platform runner's single - `target_env_`. -- **The `Private::ForApi` keys are isolate-wide**, even though they are stored - on the env. -- **Inconsistent context use.** Places that mix the implicit current context - with `env->context()`: - - the `run_script` timeout error; - - `ImportModuleDynamicallyWithPhase`; - - `HostInitializeImportMetaObject`; - - `SyntheticModuleEvaluationSteps`; - - `PromiseHookCallback` and `PromiseRejectCallback`; - - `GetThrownAtString`; - - the serdes constructors; - - `make_context` called from a vm context. -- **Lifetimes.** Function payloads, external wrappers and serdes contexts live - in the env's slab and are freed only with the env. - -### QuickJS (`quickjs/src`) - -- **One env, one runtime, one main context.** The owner holds the - `JSRuntime` and the main `JSContext`. -- **Runtime hooks point at a single env.** The promise hook, rejection tracker - and module loader hooks are installed per runtime with the env as opaque, so - a second env would overwrite them. -- **Class ids are process-static.** -- **Native callbacks run in the caller's realm.** QuickJS does not switch - realms for C-function-data calls (`quickjs.c:6287`, a TODO). The trampoline - takes `JS_GetContextOpaque(caller_ctx)` and switches `current_context_` to - it (`napi_function.cc:67-77`). An addon function made in main and called - from a vm script sees the vm global. That differs from V8 and Node. -- **`module_wrap` ignores `context_or_undefined`.** Every module lives in main. -- **`compile_function` silently falls back to main** when the parsing context - is unknown. -- **vm contexts are never freed individually.** `dispose_context` is - unreachable; `fix/quickjs-contextify-collect` addresses this. -- **`last_exception_context_` is redundant.** QuickJS exceptions are - runtime-level. - -### host-JS (`src/snapi_js.rs`) - -- **One shared host realm.** Each env gets a virtual global: a `Proxy` over a - descriptor snapshot of `globalThis`. -- **vm sandboxes are emulated.** They are evaluated with `with (sandbox)`. - Names they don't define fall back to an anonymous global context, cached in - the module-global `wasmerNapiGlobalScopes` WeakMap and owned by no env. -- **`compile_function` with a parsing context uses the raw sandbox**, so - missing names fall through to the real host global. -- **Env behaviour depends on a module-global active-context pointer**, switched - in `env_mut`/`activate()` (`snapi_js.rs:1712-1762`). - -### Bridge and Rust (`src/`) - -- **The guest's `napi_env` is a u32 env id**, resolved on every import. The - "scope id" is the guest's handle to the `env_owner`, i.e. the teardown - capability. -- **`SnapiEnvState` (`napi_bridge_init.cc:119-172`) holds isolate-level - state:** value slots, scope frames, refs, deferreds, handle tables and - `active_callback_ctx`. -- **The budget treats env and isolate as the same:** `reserve_isolate` and - `commit_isolate`, `env_heap_charges[env_id]`, and the `env_registry` used by - `terminate_all`. -- **Callbacks capture `guest_env` at registration.** They always receive the - env that created them. -- **`attach_env` hooks are inert on native.** The bridge passes empty hooks. - -### EdgeJS (consumer) - -- **One env per isolate.** The env is both the principal realm and the - `edge::Environment` key (`g_environments`). -- **vm contexts are passed as sandbox `napi_value`s** together with the - principal env. -- **Hooks are set once, on the principal env:** dynamic import, - `import.meta`, promise reject, promise hooks and prepare-stack-trace. vm - modules depend on the provider routing them back to that env. -- **EdgeJS never asks for "the current env"**, never compares envs, and never - calls `napi_set_instance_data`. -- **Bindings rely on callbacks receiving their creating env:** - `napi_get_global(env)` → `process`/`internalBinding`, 86 call sites. -- **Context tokens are recorded in `attached_contexts_` but never read.** -- **Native addons share Edge's env** (`edge_process.cc:4477`), so their - instance data collides. - -### Node (reference) - -Node's `napi_env__` is already realm-bound: `isolate` plus `context_persistent`, -created per (addon, context). `js_native_api_v8.cc` uses `env->context()` -everywhere and never the current context. - -Node has three layers: - -- **`Environment`:** thread, loop and cleanup. -- **`Realm`:** principal or ShadowRealm. It holds the per-realm callbacks: - `prepare_stack_trace_callback`, `promise_reject_callback`, - `promise_hook_handler`, and `host_import_module_dynamically_callback` / - `host_initialize_import_meta_object_callback` (`env_properties.h:474-536`). -- **Plain contexts.** A vm context is assigned to the Environment with - `realm = nullptr` (`node_contextify.cc:330`). Its hooks fall back to the - principal realm: "Fallback to the principal realm if it's in a vm context" - (`module_wrap.cc:998-1001`). - -## 3. The object model - -``` -Platform (process) configure_runtime, V8 worker threads -└─ Agent isolate / JSRuntime / host worker; one thread at a time - │ the owner handle (unofficial_napi_env_owner) names it - ├─ values and handle scopes, pending exception, finalizer queue - ├─ default microtask queue, GC, heap limits and budget, near-heap-limit - ├─ terminate, interrupt, profiler, snapshots, hash seed, datetime - ├─ embedder hooks: foreground task, fatal, OOM - ├─ Private keys, class ids, context-free compiled code (UnboundScript) - └─ Realm env (napi_env) × N: one per ECMAScript realm - │ principal, vm context, ShadowRealm, frame... - ├─ context (immutable), global, cached intrinsics - │ (Buffer.prototype, typed array constructors) - ├─ parent env; host hooks fall back to the parent's when unset - │ promise reject, promise hooks, prepare stack trace, - │ dynamic import, import.meta, source maps - ├─ module records, sandbox link, own microtask queue, codegen policy - └─ addon state API version, instance data, cleanup hooks, - refs/wraps/finalizers, payload slabs, last error -``` - -### Invariants - -1. **An env's realm never changes.** No context arguments, no selection, no - tokens. -2. **Everything an env creates lives in its realm.** - - Objects, functions and errors made through env X are made in realm X. - When the current context differs, the provider enters X for the call; - otherwise it adds no work. - - A native callback receives the env that created it. V8 already enters the - function's creation context. QuickJS must take the env from the - function's data rather than from the caller's context. -3. **Values belong to the agent.** A `napi_value` (or a ref) from any env of - an agent is valid with every other env of the same agent, within its - handle scope. - - V8 gets this for free. - - QuickJS, the bridge and host-JS must move their value and scope tables - from the env to the agent. - - EdgeJS already relies on it: `run_script` results, `compileFunction` - with a parsing context, and `moveMessagePortToContext`. -4. **Host hooks belong to the realm, with a fallback to the parent.** - - An event is dispatched to the env of the realm where it happened. That - env's hook runs if set; otherwise the provider walks up the parent chain. - - This is Node's "vm context → principal realm" fallback, made explicit. - - A ShadowRealm or frame sets its own hooks. -5. **An env lives exactly as long as its realm.** See §4.5. - -### Addon instances - -Node gives each addon its own env per realm. The model allows that later as a -sibling env on the same realm that shares the realm state and has its own -addon state. That would fix the instance-data collision from Edge's -`process.dlopen`. This proposal starts with **one env per realm**, but keeps -the realm part of the provider struct separate from the addon part so that -per-addon envs need no ABI change later. - -## 4. API changes - -### 4.1 New - -```c -enum { UNOFFICIAL_NAPI_REALM_OPTIONS_VERSION = 1 }; - -typedef struct { - uint32_t size; - uint32_t version; - napi_value sandbox_or_null; // vm semantics: global property access goes to this object - napi_value name; // or undefined - napi_value origin; // or undefined - napi_value host_defined_option_id; - bool allow_code_gen_strings; - bool allow_code_gen_wasm; - bool own_microtask_queue; -} unofficial_napi_realm_options; - -// Creates a realm in env's agent. The new env falls back to env's host hooks -// until it sets its own. global_out receives the realm's global, or the -// sandbox when one is given. -napi_status unofficial_napi_create_realm( - napi_env parent, - const unofficial_napi_realm_options* options, - napi_env* realm_out, - napi_value* global_out); - -// Returns the env of the realm that owns `value`. `value` may be a realm -// global, a vm sandbox, or a function; V8 also accepts any object (by its -// creation context). The result is NULL when that realm has no env. -napi_status unofficial_napi_get_realm( - napi_env env, napi_value value, napi_env* realm_out); -``` - -`get_realm` replaces every sandbox-to-context lookup, including the linear -scans in V8. It is O(1): - -- V8: a context embedder-data slot. -- QuickJS: `JS_GetContextOpaque`. -- host-JS: a WeakMap. - -### 4.2 Lose their context argument - -| Today | After | -|---|---| -| `contextify_run_script(env, sandbox_or_null, source, …)` | `run_script(env, source, …)`, run in env's realm | -| `contextify_compile_function(env, …, parsing_context_or_undefined, …)` | Parameter removed; env is the parsing realm | -| `module_wrap_create`: `options.context_or_undefined` | Field removed (options v2); the module lives in env's realm | - -Once these calls no longer take a context, the `contextify_` prefix no longer -describes them. Consider renaming them to `unofficial_napi_run_script` and -`unofficial_napi_compile_function`. - -### 4.3 Removed - -- **`unofficial_napi_contextify_make_context`** → `create_realm`. -- **`context_token_assign` / `context_token_unassign` hooks.** The embedder - creates realms itself, and a realm's death runs that env's cleanup hooks. - Edge's `attached_contexts_` is already dead code. -- **`unofficial_napi_contextify_enter` / `leave`** (unmerged branch). They - are never needed: use the realm's env. - -### 4.4 Re-scoped, same signature - -**Per realm, with fallback to the parent:** - -- `set_promise_reject_callback` - - V8 dispatches by `promise->GetCreationContext()`. - - QuickJS dispatches by the tracker's `ctx`. -- `set_promise_hooks` - - V8's `Context::SetPromiseHooks` is already per context. - - This removes `NapiV8ApplyPromiseHooksToContextifyContexts`. -- `set_prepare_stack_trace_callback` -- `module_wrap_set_hooks` -- `configure_source_maps` -- `enqueue_microtask`: uses the realm's own queue if it has one, otherwise the - agent's. - -**Per agent; any env of the agent selects it:** - -- `collect_garbage` -- heap, space and code statistics -- `profile_*`, `take_heap_snapshot` -- `terminate_execution`, `cancel_terminate_execution`, `request_interrupt` -- `configure_near_heap_limit_callback` -- `get_hash_seed` -- `notify_datetime_configuration_change` -- continuation-preserved embedder data -- `create_private_symbol` -- `event_loop_checkpoint` -- bytecode handles: compiled code is not tied to a context (V8 - `UnboundScript`; QuickJS bytecode belongs to the runtime), so these become - usable by any realm of the agent instead of only "the creating - environment". - -**`attach_env`:** agent-level. It is accepted once, on the principal env, and -refused on any other env. - -**Optional: thread-safe agent handle.** Terminate and interrupt could take the -owner handle instead of an env when called from a foreign thread. That would -remove the "env used from another thread" special case that -`feat/concurrent-stores` has to carve out. - -### 4.5 Realm lifetime - -**The principal env** lives until `release_env(owner)`. - -**A created realm env** lives while its realm is reachable: its global or -sandbox, or anything made in it. - -- This is the lifetime model that `fix/contextify-weak-records` (V8) and - `fix/quickjs-contextify-collect` (QuickJS) already implement for vm - records. -- When the realm is collected, the provider does what Node does when an env - goes away before its isolate: - 1. runs the env's cleanup hooks; - 2. finalizes its refs, wraps and finalizers; - 3. neutralizes surviving externals (`hint->env = nullptr`); - 4. tells the bridge to drop the guest id. -- Env ids are never reused, so a stale id fails with `napi_invalid_arg`. - -**Why this is safe by construction.** Payloads, externals and wrappers created -through an env belong to objects in that env's realm. In V8, a function, and in -practice any object, keeps its native context alive. So the slabs cannot be -reached once the realm is gone. - -Two cases need explicit handling: - -- **Foreign objects.** Records an env attached to *another* realm's objects - (`napi_wrap`, `add_finalizer`, `create_reference` on a foreign object) are - finalized when the env is torn down. -- **QuickJS plain objects.** They don't keep their `JSContext` alive, so - externals must be neutralized at teardown. - -**Explicit detach (for example a frame being removed)** is a possible later -addition. It would need tombstoned payloads, because functions of a detached -realm can still be reachable. - -## 5. Changes inside each layer - -### V8 - -- **Agent.** `UnofficialEnvScope` grows into `napi_agent__` and absorbs: - - the isolate-keyed maps: hash seed, promise reject, promise hooks, - fatal/OOM, near-heap-limit, profiler; - - the principal env (replacing `g_env_by_isolate`); - - the foreground target; - - the `Private` keys; - - the isolate-level V8 callbacks (prepare stack trace, dynamic import, - import.meta, promise reject), as dispatchers that resolve - context → env → hook. -- **Context → env** goes through an embedder-data slot. It replaces - `FindRecordByKey`, `ResolveContextFromKey` and `GetModuleWrapEnvForIsolate`. -- **`napi_env__`** keeps the immutable context, the parent, per-realm hooks, - module records, the own microtask queue and the sandbox key. -- **Entering the realm.** The prologue of each N-API call that creates objects - enters `env->context()` only when it differs from the current context. That - keeps the same-realm path free; the enter/leave branch measured - `Context::Enter`/`Exit` at about 3 ns. -- **Deleted:** - - `g_context_records` and its scans; - - `NapiV8ApplyPromiseHooksToContextifyContexts`; - - the per-context prepare-stack-trace table; - - the context-token plumbing. - -### QuickJS - -- **Agent.** `napi_agent__` owns: - - the `JSRuntime`; - - class ids, made per runtime instead of static; - - the rejection tracker, promise hook and module loader as dispatchers via - `JS_GetContextOpaque(ctx)` → env; - - the job queue; - - the scope stack and value slots; - - the pending exception; - - `external_memory_` and the embedder hooks. -- **`napi_env__`** owns one `JSContext`. -- **Deleted:** `current_context_`, `napi_env_context_scope__` (23 sites), - `napi_value__::context_` tags and `last_exception_context_`. -- **The trampoline takes its env from `func_data`** (the creating env). This - is a deliberate behaviour change to match V8 and Node. -- **`module_wrap` and `compile_function`** honour the env's realm. - -### host-JS - -- **Split `HostJsEnv`** into: - - `HostJsAgent`, per worker: values, frames, refs, `object_ids`, - finalizers; - - `HostJsEnv`: `global_context`, instance data, modules. -- **`create_realm`** builds a new `global_context`, optionally over a sandbox. - This deletes the anonymous `wasmerNapiGlobalScopes` fallback and the - `evaluation_scope(parsing_context)` branch. -- **Pass the env's context explicitly** to `context_eval`, `is_buffer` and - `buffer_view`. That lets `wasmerNapiActiveGlobalContext` and the - `activate()` switch go. -- **Limit.** These realms stay virtual (`with`/`Proxy` over one host realm), - so intrinsics are shared. The API becomes uniform; real isolation would need - host ShadowRealm, iframes or `node:vm`, which is out of scope. - -### Bridge (`napi_bridge_init.cc`) - -- **Split `SnapiEnvState`:** - - `SnapiAgentState`: owner, value slots, scope frames, refs, deferreds, - handle tables (module_wrap, bytecode, profile, buffer lease), - `active_callback_ctx`, `value_limit`, the list of envs; - - `SnapiEnvState`: agent pointer, `napi_env`, callback registry. -- **Guest value ids become agent-scoped**, so they stay valid across that - agent's realms. -- **`g_envs` validation** maps env → agent. -- **Lock scope (side benefit).** With an agent object it is natural to replace - the process-global `g_mu`, taken on every `unofficial_*` call, with a - per-agent lock. - -### Rust (`src/env.rs`, `src/guest/napi.rs`) - -- **Agents get their own table.** `napi_scopes: scope_id → env_id` becomes - `agents: agent_id → { principal env, heap charge, registry entry }`. -- **Budget is per agent.** Isolate reservation and heap charges stay on - `create_env` only; `create_realm` charges no isolate, because a context - counts against its isolate's heap. -- **`env_registry` and `terminate_all`** hold agents instead of envs. -- **The bridge reports realm death** so the env id and its leases can be - dropped. -- **New guest imports** `unofficial_napi_create_realm` and - `unofficial_napi_get_realm`. -- **Changed signatures get new import names.** The old ones stay as shims for - one release; see §8. - -## 6. EdgeJS migration - -| Area | Change | -|---|---| -| `makeContext` | `create_realm`. Keep the `contextify_context_private_symbol` tag on the returned object. | -| `runInContext` | `get_realm(sandbox)`, then run on that env. | -| `compileFunction` | `get_realm(parsing_context)`, then compile on that env. | -| `ModuleWrap` | Create on `get_realm(context)`. Drop the "context given → skip bytecode cache" special case; the cache is per agent now. | -| Hooks | No change for vm contexts, because realm envs fall back to the principal env. A ShadowRealm later gets its own Edge `Realm` object holding the module loader state, binding registry and hooks, sharing the `edge::Environment`. | -| Isolate operations, workers | No change. | -| `attach_env` | No change: it is already called once, on the principal env. | -| Context-token handlers | Delete. | -| `process.dlopen` | Optional later: one addon env per addon. | - -What must not change: callbacks keep receiving their creating env, and values -stay usable across envs. Both are invariants in §3. - -## 7. Pitfalls - -- **Envs held past their realm.** An embedder that keeps a realm env must - also keep its realm reachable, for example by holding a ref to the global or - sandbox, or by listening on that env's cleanup hook. EdgeJS stores what it - needs on the sandbox, which satisfies this. -- **Cross-agent values remain invalid.** Workers still exchange values through - `unofficial_napi_message`. A cheap agent check on value-taking calls would - catch misuse in debug builds. -- **QuickJS behaviour change.** Callbacks called from vm code will see their - creating realm, as on V8. Any QuickJS-only test that expects the vm global - inside a callback will change. -- **Hook fallback is a policy.** It makes vm contexts behave like Node. Code - that wants isolation (ShadowRealm) must set hooks on its realm env. -- **Teardown order.** The agent tears down after all of its realm envs. The - principal env tears down last, then the isolate or runtime. - -## 8. Phased plan - -Every phase leaves the tests passing on V8, QuickJS and host-JS. - -**Phase 0: internal split, no ABI change.** -- Introduce agent structs in V8, QuickJS, host-JS and the bridge, and move the - isolate-level state into them. -- Make `env->context()` immutable everywhere. -- Fix the QuickJS trampoline. - -**Phase 1: realm envs, additive ABI.** -- Add `create_realm` and `get_realm`. -- `contextify_make_context` becomes a shim over `create_realm`. The old - context arguments resolve through `get_realm` and forward to the realm env. -- Dispatch hooks per realm with fallback to the parent. -- Collect realm envs. -- Make bridge value tables agent-scoped. -- Add the guest imports. - -**Phase 2: EdgeJS moves to realm envs** (§6). - -**Phase 3: remove the old surface.** -- Drop the context arguments, `make_context` and the context-token hooks. -- Bump the options structs (module create v2). -- Delete the records, scans and fallbacks listed in §5. - -**Phase 4, optional:** per-addon envs, and ShadowRealm in EdgeJS. - -## 9. Unmerged branches - -| Branch | Recommendation | -|---|---| -| `feat/contextify-enter-leave` | Superseded: "one realm per document or frame" becomes `create_realm` plus that env. Its commits are a list of the costs of a selectable context, which this design avoids: root vs selected context, the microtask queue split, finalizers and interrupts running in the wrong realm, the handle leak, and callback cost going from 5.9 to 11 ns. | -| `feat/concurrent-stores`, `perf/concurrent-envs` | Land first. "Ids never reused" and "scope id = env id" become "agent id = principal env id". Terminate and interrupt then target the agent. | -| `fix/contextify-weak-records`, `fix/quickjs-contextify-collect` | Land first. Their lifetime model is the realm-env lifetime in §4.5. | -| `feat/trusted-script` | No conflict. Its hook is installed once per isolate, which is agent-level. | - -## 10. Decisions to make - -1. **Hook fallback to the parent** (recommended, matches Node) or explicit - hooks per realm? -2. **Realm teardown:** GC only at first (recommended), or explicit detach from - the start? -3. **Per-addon envs:** now, or after realm envs (recommended)? -4. **Guest ABI:** additive imports plus shims, then removal (recommended), or - a `napi_extension_wasmer_v1` module? - -## 11. Phase 0: what landed - -Every engine now has an agent next to its env. Each agent still has exactly one -env, its principal env. There is no ABI change: public headers, guest imports -and the Rust↔C++ signatures are untouched. The one deliberate behaviour change -is the QuickJS trampoline. - -### V8 (`v8/src`) - -- **New `napi_agent__`** (`internal/napi_v8_agent.h`). It is owned by the owner - handle (`UnofficialEnvScope`) and found from an isolate through isolate data - slot 0. -- **Eight process-global maps are gone**, replaced by agent fields that need no - lock: `g_env_by_isolate`, `g_hash_seeds`, `g_tracking_allocators`, - `g_fatal_error_callbacks`, `g_near_heap_limit_callbacks`, - `g_profiler_states`, `g_promise_reject_callbacks` and `g_promise_hooks`. -- **Also moved to the agent:** - - the three `Private` keys; - - the embedder hooks (context tokens, foreground task, fatal and OOM); - - the microtask policy; - - the default dynamic-import hook. -- **Moved to the env (realm):** the promise-reject callback and the four - promise hooks. Dispatch goes isolate → agent → principal env; Phase 1 - resolves context → env instead. -- **`GetModuleWrapEnvForIsolate`** is an O(1) agent lookup instead of a scan. -- **`napi_agent__::Shutdown()`** now also removes the near-heap-limit - trampoline. Before, it stayed registered with the env pointer as data after - the env was freed. -- **Unchanged:** the env-keyed realm maps (`g_prepare_stack_trace_callbacks`, - `g_error_formatting_states`, `g_context_records`, `g_module_wrap_states`) and - `g_runtime_mu` around the platform. - -### QuickJS (`quickjs/src`) - -- **New `napi_agent__`** (`internal/napi_agent.{h,cc}`) holds: - - the runtime; - - the handle-scope stack; - - the pending exception; - - external memory and the embedder hooks; - - continuation data and promise context frames; - - the runtime-wide promise, rejection, import.meta and dynamic-import hooks, - installed with the agent as opaque. -- **The env has one immutable `JSContext`.** -- **Deleted:** - - `current_context_` and `napi_env_context_scope__` (16 sites); - - `main_context()` / `current_context()`; - - `last_exception_context_`; - - the per-value, per-ref and per-deferred context tags. Values hold only the - runtime. -- **Trampoline:** the env now comes from the function's own data, not the - caller's context. A native function called from a vm script now sees its - creating realm, as on V8 and Node. -- **New shared test:** `NativeFunctionCalledFromContextKeepsItsRealm`. -- **Teardown:** native callbacks are refused once teardown starts. Before, only - calls from the main context were refused. -- **Not done:** class ids are still process-static. - -### Bridge (`src/napi_bridge_init.cc`) - -- **`SnapiAgentState` holds:** the owner, value slots, scope frames, refs, - deferreds, handle tables, cbinfo invocations, `active_callback_ctx` and - `value_limit`. -- **`SnapiEnvState` holds:** the agent pointer, the `napi_env`, and the - callback registry and bindings. -- **Scope frames remember the env that opened them.** -- **The value cap counts across the agent's envs.** -- **Unchanged:** `g_mu` and `g_envs`. - -### host-JS (`src/snapi_js.rs`) - -- **`HostJsAgent` holds:** the handle tables and frames, `object_ids`, wraps, - references, deferreds, finalizers, pending callbacks and - `active_callback_ctx`. -- **`HostJsEnv` keeps:** its global context, `last_exception`, callbacks, - closures, instance data and modules. -- **No implicit active context any more.** The module-global - `wasmerNapiActiveGlobalContext`, `activate()` and the `ACTIVE_HOST_JS_ENV` - thread-local are gone. The JS helpers take the env's context explicitly. -- **Bug fix:** buffer views made by `create_bytes_value` and - `create_guest_buffer_view` used whichever env had been active last. -- **Unchanged:** vm sandbox semantics, including the fallback scope WeakMap. - -### Tests - -All counts are compared with `main`. - -| Suite | Before | After | -|---|---|---| -| V8 (native) | 97 | 99 | -| QuickJS (native, at the recorded submodule commit) | 96 | 97 | -| Rust lib / `v8_host_control` | 48 / 3 | 48 / 3 | -| Manifest, native + WASIX | 36 | 36 | -| host-JS node / bun | 15 / — | 16 / 13 passed, 3 skipped | -| host-JS wasm-bindgen | 15 | 15 | - -The new tests: - -- V8 `NearHeapLimitCallbackReceivesItsEnvironment`; -- shared `NativeFunctionCalledFromContextKeepsItsRealm`; -- a host-JS test that two contexts each evaluate in their own global. - -`make test-wasix-napi` does not work in standalone mode: the harness looks for -`./cargo-standalone.sh` under the temporary crate root. The manifest was run -with an equivalent script instead. - -### Notes for Phase 1 - -- Callback, finalizer and interrupt paths in the bridge and host-JS still - carry their env. Pending callbacks and finalizer drains read the exception of - the env passed to the drain. -- The per-env callback registry and the opener env on frames exist, but - nothing exercises them yet. -- `Box` needs a shared handle once several envs share an agent. diff --git a/docs/realms.md b/docs/realms.md new file mode 100644 index 0000000000..6144f7d470 --- /dev/null +++ b/docs/realms.md @@ -0,0 +1,108 @@ +# Realms and envs + +## The model + +- **An env is one engine instance's view from its main realm.** Every N-API + call through it creates objects in that realm, and the native functions it + makes run there. It never switches realms. This is Node's model: a + `napi_env` belongs to the principal realm, and vm contexts get none. +- **A vm context is another realm of the same engine instance, but not an + env.** `unofficial_napi_create_realm` makes one and returns an + `unofficial_napi_realm`. Only the calls that run code take a realm: + `unofficial_napi_run_script`, `unofficial_napi_compile_function`, module + creation and `unofficial_napi_bytecode_open`. A NULL realm means the env's + own. +- **Hooks, instance data and cleanup hooks stay on the env.** A hook fires + for code running in any of its realms, as Node's hooks do for vm contexts. +- **Realms are collected.** A realm lives while its global (its sandbox, when + it has one) or anything made in it is reachable. A realm handle is valid + only while the handle scope it was obtained in is open, like a + `napi_value`, and two handles for one realm may differ; + `unofficial_napi_get_realm` finds the realm again from its global. + +## API + +```c +typedef struct unofficial_napi_realm__* unofficial_napi_realm; + +napi_status unofficial_napi_create_realm(napi_env env, + const unofficial_napi_realm_options* options_or_null, + unofficial_napi_realm* realm_out, + napi_value* global_out); +napi_status unofficial_napi_get_realm(napi_env env, napi_value global_or_sandbox, + unofficial_napi_realm* realm_out); + +napi_status unofficial_napi_run_script(napi_env env, unofficial_napi_realm realm_or_null, …); +napi_status unofficial_napi_compile_function(napi_env env, unofficial_napi_realm realm_or_null, …); +// unofficial_napi_module_create_options.realm_or_null (options version 2) +// unofficial_napi_bytecode_open_options.realm_or_null (options version 2) +``` + +- **`create_realm`:** + - With a sandbox, global property access in the realm reads and writes the + sandbox, as with `vm.createContext(sandbox)`. + - A sandbox belongs to at most one realm. The env's own global may still be + one. + - Options: sandbox, name, origin, host-defined option id, the + code-generation flags and an own microtask queue (V8 only). +- **`get_realm`** returns NULL for any object that isn't a realm's global or + sandbox, the env's own global included. +- **Changed from `main`:** + - `unofficial_napi_contextify_make_context` is replaced by `create_realm`. + - `unofficial_napi_contextify_run_script` and + `unofficial_napi_contextify_compile_function` become `run_script` and + `compile_function`. They take a realm instead of a sandbox or parsing + context. + - The module options' `context_or_undefined` becomes `realm_or_null`. + - The context-token hooks are gone (env hooks are version 2). +- **Guest ABI:** a realm id is the value id of the realm's global or sandbox, + and 0 is the env's realm. The bridge keeps no realm table: it resolves the + id again with `get_realm` on each call, so the id lives exactly as long as + its value id. Version 1 structs are rejected and the old imports are gone. + +## How each provider does it + +| Provider | A realm is | `get_realm` | Collection | +|---|---|---|---| +| V8 | a record with a weak `v8::Global` and its own microtask queue, owned by the env | creation context of the global, then context embedder-data slot 33 | The context is weak. The next `create_realm` frees records whose context is gone, and only then their microtask queues (from #109). | +| QuickJS | a record with a `JSContext` on the env's runtime; a sandbox realm copies the sandbox's properties in and out around each call | a map from global or sandbox to record | The key (the sandbox, or the realm's global) holds a function of the realm under a private symbol, and a sandbox realm's global holds the sandbox, so the collector frees the cycle with its key. The record holds the key weakly, and the next `create_realm` frees collected records (from #110). | +| host-JS | a virtual global context (a `with`/Proxy scope over one host realm) | a per-env `WeakMap` from global or sandbox to context | Nothing holds a realm strongly; the host GC collects it with its key. | + +## How EdgeJS uses it + +- `vm.createContext` → `create_realm`. +- `runInContext`, `compileFunction`, `moveMessagePortToContext` and + `ModuleWrap` → `get_realm` on the contextified object, then the call with + that realm. +- Everything else, hooks included, goes through the env. + +## Not done + +- **QuickJS needs engine commit 7ddf9e3**, which makes a pending job hold its + context. Without it, a job queued in a realm that is then collected runs on + a freed context. With it, a realm's pending jobs keep the realm alive until + they run. +- **ShadowRealm.** A realm with its own bindings and hooks, and no fallback + to the main realm, would be a separate concept, closer to Node's `Realm`. +- **Native objects inside a vm realm.** Native functions always belong to the + env's realm. EdgeJS creates the objects `moveMessagePortToContext` needs by + running a script in the realm. +- **Sandboxes work differently per engine.** + - V8 turns the sandbox itself into the realm's global, which goes against + V8's API contract and breaks `vm.createContext(globalThis)`. + - QuickJS copies sandbox properties in and out around scripts. + - host-JS evaluates against the sandbox with `with`. + +## History + +- **#111** moved what is shared by an isolate or runtime into an agent, + apart from the env. +- **#112 and #114** made every vm context a full env, with fallback to its + parent env for hooks and state and shims for older guests. +- **#115** made an env a realm that owns nothing, with all state on the + engine instance. + +Both kept an env per vm context. That means native code has to know which +env it holds, and every hook, scope and reference has to work across envs. +Here, vm contexts are realm handles and only the four calls that run code +take one, so the rest of N-API keeps a single env per engine instance. From 247d0175d9f13f742f41e3564f3bddbaa74fa568 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Sun, 25 Oct 2026 10:41:22 +0100 Subject: [PATCH 016/150] Test that a pending job outlives the realm that queued it Code in a realm can resolve a promise whose reaction belongs to the env's realm. The job is queued from the realm, and nothing else need keep that realm alive until the job runs. On QuickJS this needs engine commit 7ddf9e3, which makes a job hold its context; without it ASan reports a use-after-free in promise_reaction_job. Co-Authored-By: Claude Opus 5.5 --- tests/runners/test_66_unofficial_realm.cc | 47 +++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/tests/runners/test_66_unofficial_realm.cc b/tests/runners/test_66_unofficial_realm.cc index 8353e05330..ba922f9efb 100644 --- a/tests/runners/test_66_unofficial_realm.cc +++ b/tests/runners/test_66_unofficial_realm.cc @@ -547,6 +547,53 @@ TEST_F(Test66UnofficialRealm, RealmOutlivesItsGlobalHandleWhileReachable) { ASSERT_EQ(napi_delete_reference(s.env, weak_sandbox), napi_ok); } +// A job queued by code in a realm can still run after nothing else refers to +// that realm, even when the job's functions belong to the env's realm. +TEST_F(Test66UnofficialRealm, PendingJobRunsAfterItsRealmIsUnreachable) { + EnvScope s(runtime_.get()); + + napi_ref weak_global = nullptr; + { + napi_handle_scope scope = nullptr; + ASSERT_EQ(napi_open_handle_scope(s.env, &scope), napi_ok); + napi_value resolve = Eval(s.env, + "(() => {" + " let resolve;" + " new Promise((r) => { resolve = r; })" + " .then((value) => { globalThis.got = value; });" + " return resolve;" + "})()"); + ASSERT_NE(resolve, nullptr); + napi_value global = nullptr; + unofficial_napi_realm realm = CreateRealm(s.env, &global); + ASSERT_NE(realm, nullptr); + ASSERT_EQ(napi_set_named_property(s.env, global, "resolve", resolve), napi_ok); + // Resolving from the realm queues the reaction job there. + ASSERT_NE(RunIn(s.env, realm, "resolve(5); 0"), nullptr); + ASSERT_EQ(napi_create_reference(s.env, global, 0, &weak_global), napi_ok); + ASSERT_EQ(napi_close_handle_scope(s.env, scope), napi_ok); + } + + ASSERT_EQ(unofficial_napi_collect_garbage(s.env), napi_ok); + for (int i = 0; i < 4; ++i) { + napi_handle_scope scope = nullptr; + ASSERT_EQ(napi_open_handle_scope(s.env, &scope), napi_ok); + ASSERT_NE(CreateRealm(s.env), nullptr); + ASSERT_EQ(napi_close_handle_scope(s.env, scope), napi_ok); + } + ASSERT_EQ(unofficial_napi_collect_garbage(s.env), napi_ok); + + ASSERT_EQ(unofficial_napi_event_loop_checkpoint( + s.env, unofficial_napi_event_loop_checkpoint_microtasks, true, nullptr), + napi_ok); + EXPECT_EQ(Int32(s.env, Eval(s.env, "globalThis.got")), 5); + + // Once the job has run, the realm is collected. + ASSERT_EQ(unofficial_napi_collect_garbage(s.env), napi_ok); + EXPECT_TRUE(IsCollected(s.env, weak_global)); + ASSERT_EQ(napi_delete_reference(s.env, weak_global), napi_ok); +} + #if defined(NAPI_TEST_ENGINE_V8) namespace { From 1f7a337ae2e9bc10b7a10b08dcaedc6ceb612f07 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Sun, 25 Oct 2026 10:43:23 +0100 Subject: [PATCH 017/150] Pin QuickJS to 7ddf9e3 (a job holds its context) Realms are now collected with their global or sandbox. A promise job queued from a realm took no reference to that realm's context, so if the realm was collected before the job ran, the job used a freed context. Engine commit 7ddf9e3 (wasmerio/quickjs#10) makes a job hold its context until it runs. PendingJobRunsAfterItsRealmIsUnreachable covers this. Co-Authored-By: Claude Opus 5.5 --- quickjs/deps/quickjs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/quickjs/deps/quickjs b/quickjs/deps/quickjs index 89fb17a82b..7ddf9e3cf4 160000 --- a/quickjs/deps/quickjs +++ b/quickjs/deps/quickjs @@ -1 +1 @@ -Subproject commit 89fb17a82ba1d38f605e01558c3928aacc4ffd54 +Subproject commit 7ddf9e3cf411033ea5d65b729953163cbe9c4878 From eaeb1cd8f567651aaf1d3841e0f2f1e4156162b7 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Sun, 25 Oct 2026 12:21:18 +0100 Subject: [PATCH 018/150] Pin QuickJS to wasmerio/quickjs#10's current head wasmerio/quickjs#10 now ports all of bellard/quickjs 458c34d: besides a job holding its context, a module can outlive the context that loaded it (a module whose top-level await is pending when its context is freed was used after it was freed) and a FinalizationRegistry holds its constructor's context. Co-Authored-By: Claude Opus 5.5 --- quickjs/deps/quickjs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/quickjs/deps/quickjs b/quickjs/deps/quickjs index 7ddf9e3cf4..55415c67fe 160000 --- a/quickjs/deps/quickjs +++ b/quickjs/deps/quickjs @@ -1 +1 @@ -Subproject commit 7ddf9e3cf411033ea5d65b729953163cbe9c4878 +Subproject commit 55415c67fea820901565cd40f91d1e5040ff6369 From 7f09bc731bc89d6eb69bc421e93b68d78b231a6d Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Sun, 25 Oct 2026 13:49:50 +0100 Subject: [PATCH 019/150] Pin QuickJS to merged master wasmerio/quickjs#10 is merged as 870aa7b, with the same tree as the commit pinned before. Co-Authored-By: Claude Opus 5.5 --- quickjs/deps/quickjs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/quickjs/deps/quickjs b/quickjs/deps/quickjs index 55415c67fe..870aa7b604 160000 --- a/quickjs/deps/quickjs +++ b/quickjs/deps/quickjs @@ -1 +1 @@ -Subproject commit 55415c67fea820901565cd40f91d1e5040ff6369 +Subproject commit 870aa7b604792cf38c597e9f8d57c19b3c05afea From fef14553a4ca6e532e7a18d3992b6615cd4f1583 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Tue, 27 Oct 2026 11:29:49 -0700 Subject: [PATCH 020/150] Add entering realms to the realm API N-API acts in one realm at a time, the current realm, as an ECMAScript engine runs code in the realm of its running execution context. What N-API creates comes from that realm, and a native function belongs to the realm current when it was made, like a built-in function's [[Realm]], and runs there. unofficial_napi_enter_realm makes a realm current until unofficial_napi_leave_realm. An embedder that never enters a realm acts only in the env's realm, as before. Co-Authored-By: Claude Opus 5.5 --- docs/realms.md | 110 ++++++++++++++++++++++++++++++-------- include/unofficial_napi.h | 77 ++++++++++++++++++++++---- 2 files changed, 156 insertions(+), 31 deletions(-) diff --git a/docs/realms.md b/docs/realms.md index 6144f7d470..4ee17e522c 100644 --- a/docs/realms.md +++ b/docs/realms.md @@ -2,18 +2,31 @@ ## The model -- **An env is one engine instance's view from its main realm.** Every N-API - call through it creates objects in that realm, and the native functions it - makes run there. It never switches realms. This is Node's model: a - `napi_env` belongs to the principal realm, and vm contexts get none. -- **A vm context is another realm of the same engine instance, but not an - env.** `unofficial_napi_create_realm` makes one and returns an - `unofficial_napi_realm`. Only the calls that run code take a realm: +- **An env serves one engine instance and all its realms.** Its own realm is + the engine instance's main realm. `unofficial_napi_create_realm` makes more + (vm contexts, or a browser's documents) and returns an + `unofficial_napi_realm`. A realm is not an env. +- **N-API acts in one realm at a time, the current realm**, as an ECMAScript + engine runs code in the realm of its running execution context: + - what N-API creates comes from the current realm, with its intrinsics, and + `napi_get_global` returns its global; + - a native function belongs to the realm current when it was made (its + `[[Realm]]`, as for an ECMAScript built-in function) and its callback + runs in that realm, whichever realm calls it; + - `unofficial_napi_enter_realm` makes a realm current until + `unofficial_napi_leave_realm`; + - otherwise the current realm is the env's own. +- **An embedder that never enters a realm acts only in the env's realm.** + Every native function it makes belongs to the env's realm, so it runs there + even when a vm context calls it. That is Node's model, and EdgeJS's. +- **The calls that run code take their realm explicitly:** `unofficial_napi_run_script`, `unofficial_napi_compile_function`, module - creation and `unofficial_napi_bytecode_open`. A NULL realm means the env's - own. + creation and `unofficial_napi_bytecode_open`. A NULL realm there means the + env's own, also while another realm is current. - **Hooks, instance data and cleanup hooks stay on the env.** A hook fires for code running in any of its realms, as Node's hooks do for vm contexts. + Hooks, finalizers, cleanup hooks and interrupt callbacks run in the env's + realm. - **Realms are collected.** A realm lives while its global (its sandbox, when it has one) or anything made in it is reachable. A realm handle is valid only while the handle scope it was obtained in is open, like a @@ -32,6 +45,11 @@ napi_status unofficial_napi_create_realm(napi_env env, napi_status unofficial_napi_get_realm(napi_env env, napi_value global_or_sandbox, unofficial_napi_realm* realm_out); +typedef uint64_t unofficial_napi_realm_scope; +napi_status unofficial_napi_enter_realm(napi_env env, unofficial_napi_realm realm_or_null, + unofficial_napi_realm_scope* scope_out); +napi_status unofficial_napi_leave_realm(napi_env env, unofficial_napi_realm_scope scope); + napi_status unofficial_napi_run_script(napi_env env, unofficial_napi_realm realm_or_null, …); napi_status unofficial_napi_compile_function(napi_env env, unofficial_napi_realm realm_or_null, …); // unofficial_napi_module_create_options.realm_or_null (options version 2) @@ -47,6 +65,26 @@ napi_status unofficial_napi_compile_function(napi_env env, unofficial_napi_realm code-generation flags and an own microtask queue (V8 only). - **`get_realm`** returns NULL for any object that isn't a realm's global or sandbox, the env's own global included. +- **`enter_realm` / `leave_realm`:** + - Scopes nest and close in LIFO order. A token is nonzero and never reused + within its env. Leaving any token but the innermost scope's fails with + `napi_invalid_arg` and changes nothing. + - A native callback's frame sits on the same stack, so a callback can't + leave a scope its caller opened, and scopes it leaves open close when it + returns. Releasing the env closes every scope. + - A scope keeps its realm alive until it is left. Entering a realm of + another env, or a collected one, fails with `napi_invalid_arg`. + - No JavaScript runs, so both work while execution is terminating. A + pending exception stays pending. + - NULL enters the env's own realm, for example to reach its global from + inside another realm. +- **Promises:** a promise from `napi_create_promise` belongs to the current + realm, and `napi_resolve_deferred` and `napi_reject_deferred` settle it + there. +- **Threadsafe functions and async work** are the embedder's, not napi's. To + run their callbacks in the realm that made them, the embedder keeps a + reference to the global `napi_get_global` returns when they are made, and + enters `get_realm` of that global around each callback. - **Changed from `main`:** - `unofficial_napi_contextify_make_context` is replaced by `create_realm`. - `unofficial_napi_contextify_run_script` and @@ -59,6 +97,24 @@ napi_status unofficial_napi_compile_function(napi_env env, unofficial_napi_realm and 0 is the env's realm. The bridge keeps no realm table: it resolves the id again with `get_realm` on each call, so the id lives exactly as long as its value id. Version 1 structs are rejected and the old imports are gone. + The scope imports are `unofficial_napi_enter_realm(env, realm_id, + scope_out_ptr) -> status` and `unofficial_napi_leave_realm(env, scope: i64) + -> status`; the token is the provider's, passed through as a u64. + +## How the current realm works + +Each env keeps a stack of realm frames, innermost last: the scopes +`enter_realm` opened and the native callbacks that are running. The innermost +frame is the current realm; an empty stack means the env's own. A callback +pushes its function's realm on entry and pops back to where it started on +return, closing the scopes it left open. Finalizers, cleanup hooks, env hooks +and interrupt callbacks push the env's realm. + +| Provider | Current realm | A native function's realm | Keeping the realm alive | +|---|---|---|---| +| V8 | `env->context()` returns the innermost frame's context. A scope also enters the context (`v8::Context::Enter`), so what V8 makes in the isolate's current context is made there too. | The function is made in the realm's context. V8 already makes a function's creation context current while it runs; the callback payload names the realm for N-API's frame. | A scope holds its context in a strong handle until it is left. A function holds its creation context, as any V8 function does. | +| QuickJS | `env->context()` returns the innermost frame's `JSContext`. | QuickJS calls C functions with data in the caller's context: it doesn't switch realms for them as it does for its own built-ins. A function of another realm carries that realm's context and anchor (a function of the realm) in its data, and its trampoline pushes them. | A scope owns a reference to the realm's anchor. A function's data holds it, so the collector sees the edge and frees the realm with its last function. | +| host-JS | The env's stack of virtual contexts. | The JS wrapper of a callback holds its context and passes it to the Rust dispatch. | The wrapper, not the Rust closure the env keeps, holds the context, so the realm goes with the function. | ## How each provider does it @@ -78,15 +134,22 @@ napi_status unofficial_napi_compile_function(napi_env env, unofficial_napi_realm ## Not done -- **QuickJS needs engine commit 7ddf9e3**, which makes a pending job hold its - context. Without it, a job queued in a realm that is then collected runs on - a freed context. With it, a realm's pending jobs keep the realm alive until - they run. +- **QuickJS needs engine commit 870aa7b** (wasmerio/quickjs#10), which makes + a pending job hold its context. Without it, a job queued in a realm that is + then collected runs on a freed context. With it, a realm's pending jobs keep + the realm alive until they run. - **ShadowRealm.** A realm with its own bindings and hooks, and no fallback to the main realm, would be a separate concept, closer to Node's `Realm`. -- **Native objects inside a vm realm.** Native functions always belong to the - env's realm. EdgeJS creates the objects `moveMessagePortToContext` needs by - running a script in the realm. +- **host-JS realms have no intrinsics of their own.** A Worker can't create a + JavaScript realm, so objects and errors made there come from the host + realm. Entering a realm selects its global, and functions keep their + realm. +- **The realm of a value** (`get_value_realm`). ECMAScript defines a realm + only for functions (`GetFunctionRealm`), and QuickJS and host-JS record + none for other objects. A callback already knows the realm it runs in: + `napi_get_global` returns that realm's global. +- **Per-realm embedder data.** An embedder keeps its own map from a realm's + global to its state. - **Sandboxes work differently per engine.** - V8 turns the sandbox itself into the realm's global, which goes against V8's API contract and breaks `vm.createContext(globalThis)`. @@ -101,8 +164,13 @@ napi_status unofficial_napi_compile_function(napi_env env, unofficial_napi_realm parent env for hooks and state and shims for older guests. - **#115** made an env a realm that owns nothing, with all state on the engine instance. - -Both kept an env per vm context. That means native code has to know which -env it holds, and every hook, scope and reference has to work across envs. -Here, vm contexts are realm handles and only the four calls that run code -take one, so the rest of N-API keeps a single env per engine instance. +- **#116** made vm contexts realm handles. Both earlier designs kept an env + per vm context, so native code had to know which env it held, and every + hook, scope and reference had to work across envs. With realm handles, + only the four calls that run code take a realm, and the rest of N-API + keeps a single env per engine instance. Native code acted only in the + env's realm. +- **Entering realms** followed WebkitWasm's feedback on #116: a browser runs + one realm per document, and its bindings must create objects in the + document's realm and run there. Native code now acts in a current realm, + with ECMAScript's rules. diff --git a/include/unofficial_napi.h b/include/unofficial_napi.h index 9d493f1fe0..ef88c3ccfb 100644 --- a/include/unofficial_napi.h +++ b/include/unofficial_napi.h @@ -145,17 +145,47 @@ NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_release_env( unofficial_napi_env_owner owner, struct uv_loop_s* loop_or_null); -// Realms. An env acts in one realm, its engine instance's main realm, for its -// whole life: every N-API call through it creates objects there, and the -// native functions it makes run there. +// Realms. An engine instance holds realms, each with its own global and +// intrinsics: the env's own realm (the engine instance's main realm) and the +// realms unofficial_napi_create_realm makes, such as vm contexts. A realm is +// not an env: one env serves all of them, and its hooks, instance data and +// cleanup hooks are shared by all of them. A hook fires for code running in +// any realm. // -// A vm context is another realm of the same engine instance. It is not an env: -// unofficial_napi_create_realm makes one and returns an unofficial_napi_realm, -// and only the calls that run code take one (unofficial_napi_run_script, -// unofficial_napi_compile_function, module creation and -// unofficial_napi_bytecode_open). A NULL realm means the env's own realm. -// Hooks, instance data and cleanup hooks stay on the env: a hook fires for -// code running in any of its realms. +// N-API acts in one realm at a time, the current realm, as an ECMAScript +// engine runs code in the realm of its running execution context: +// +// - A call that creates something creates it in the current realm, with that +// realm's intrinsics: objects, arrays, functions, classes, errors (also the +// ones napi_throw_* makes), promises, dates, typed arrays and buffers. +// napi_get_global returns the current realm's global (a sandbox realm's +// sandbox), and napi_run_script runs there. +// - A native function belongs to the realm that was current when it was made, +// as an ECMAScript built-in function has a [[Realm]]. That covers +// napi_create_function, and the constructors, methods and accessors of +// napi_define_class and napi_define_properties. Its callback runs with that +// realm current, whichever realm calls it. +// - A promise from napi_create_promise belongs to the current realm, and +// napi_resolve_deferred and napi_reject_deferred settle it in that realm. +// - unofficial_napi_enter_realm makes a realm current until the matching +// unofficial_napi_leave_realm. +// - Otherwise the current realm is the env's own. An embedder that never +// enters a realm only ever acts in the env's realm. +// - Finalizers, cleanup hooks, env hooks and interrupt callbacks run in the +// env's realm. +// +// The calls that run code in a realm take it explicitly +// (unofficial_napi_run_script, unofficial_napi_compile_function, module +// creation and unofficial_napi_bytecode_open). There a NULL realm means the +// env's own realm, also while another realm is current. +// +// N-API's threadsafe functions and async work belong to the embedder. To run +// their callbacks in the realm that made them, it keeps a reference to the +// global napi_get_global returns when they are made, and enters the realm +// unofficial_napi_get_realm finds for that global around each callback. +// +// The host-JS provider's realms share the host realm's intrinsics: there, +// entering a realm selects its global, and objects still come from the host. // // A realm lives while its global (the sandbox, when it has one) or anything // made in it is reachable, and is then collected. A realm handle, like a @@ -215,6 +245,33 @@ NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_get_realm( napi_value value, unofficial_napi_realm* realm_out); +// A scope opened by unofficial_napi_enter_realm. A token is never 0 and never +// reused within its env. +typedef uint64_t unofficial_napi_realm_scope; + +// Makes `realm_or_null` the current realm (NULL: the env's own) until +// unofficial_napi_leave_realm closes the returned scope. Scopes nest and close +// in LIFO order, and a scope keeps its realm alive until it is closed. A scope +// that a native callback leaves open closes when that callback returns, and +// every scope closes when the env is released. +// +// No JavaScript runs, so entering also succeeds while execution is +// terminating. Fails with napi_invalid_arg for a realm of another env or one +// that was collected. +NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_enter_realm( + napi_env env, + unofficial_napi_realm realm_or_null, + unofficial_napi_realm_scope* scope_out); + +// Closes `scope`, which must be the innermost scope opened in the running +// native callback (or outside any callback). A pending exception stays +// pending. Any other token fails with napi_invalid_arg and changes nothing: +// one already closed, one opened by an outer callback, or one with a scope +// nested inside it still open. +NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_leave_realm( + napi_env env, + unofficial_napi_realm_scope scope); + NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_collect_garbage( napi_env env); NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_set_prepare_stack_trace_callback( From 2bac018905f8998a55fbd8bbf94567e4fdd6726e Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Tue, 27 Oct 2026 11:29:49 -0700 Subject: [PATCH 021/150] V8: act in the current realm The env keeps a stack of realm frames: scopes opened with enter_realm, which also enter the realm's context, and the native callbacks that are running. napi_env__::context() is the innermost frame's context. A function made in a realm names it in its payload; V8 already runs it in its creation context. Promises settle in their creation context. Finalizers, env hooks and interrupt callbacks run in the env's realm, and the calls that take a NULL realm use the env's own context. Co-Authored-By: Claude Opus 5.5 --- v8/src/internal/napi_callback_payload.h | 4 ++ v8/src/internal/napi_v8_env.h | 46 +++++++++++++++++++- v8/src/js_native_api_v8.cc | 58 ++++++++++++++++++++++--- v8/src/unofficial_napi.cc | 15 ++++--- v8/src/unofficial_napi_contextify.cc | 44 ++++++++++++++++++- 5 files changed, 153 insertions(+), 14 deletions(-) diff --git a/v8/src/internal/napi_callback_payload.h b/v8/src/internal/napi_callback_payload.h index 5bdff4d9e3..95f17370b8 100644 --- a/v8/src/internal/napi_callback_payload.h +++ b/v8/src/internal/napi_callback_payload.h @@ -2,11 +2,15 @@ #define NAPI_V8_CALLBACK_PAYLOAD_H_ #include "js_native_api.h" +#include "unofficial_napi.h" struct napi_callback_payload__ { napi_env env; napi_callback cb; void* data; + // The realm the function belongs to (null: the env's own). The function + // keeps its creation context, and so the realm, alive. + unofficial_napi_realm realm = nullptr; }; struct napi_accessor_payload__ { diff --git a/v8/src/internal/napi_v8_env.h b/v8/src/internal/napi_v8_env.h index 270776e5d0..98e5048761 100644 --- a/v8/src/internal/napi_v8_env.h +++ b/v8/src/internal/napi_v8_env.h @@ -68,11 +68,36 @@ struct unofficial_napi_realm__ { std::unique_ptr own_microtask_queue; }; +// A realm N-API acts in: a scope opened with unofficial_napi_enter_realm, or +// a native callback that is running. The innermost frame is the current +// realm. +struct napi_realm_frame__ { + // The scope's token; 0 for a callback. + uint64_t scope = 0; + // The realm; null for the env's own. + unofficial_napi_realm__* realm = nullptr; + // A scope enters its realm's context and holds it until it is left. A + // callback's realm is V8's current context already, and its function keeps + // it alive. + v8::Global entered; +}; + struct napi_env__ { explicit napi_env__(v8::Local context, int32_t module_api_version); ~napi_env__(); + // The current realm's context: the innermost realm frame's, else the env's + // own. N-API calls create what they make there. v8::Local context() const; + // The env's own realm. + v8::Local main_context() const; + // The current realm; null for the env's own. + unofficial_napi_realm__* current_realm() const; + // Pushes the frame of a callback running in `realm` (null: the env's own) + // and returns the depth PopRealmFrames restores. + size_t PushRealmFrame(unofficial_napi_realm__* realm); + // Pops the frames above `depth`, leaving the contexts their scopes entered. + void PopRealmFrames(size_t depth); void CallFinalizer(node_api_basic_finalize cb, void* data, void* hint); void InvokeFinalizerFromGC(napi_ref_tracker__* finalizer); void EnqueueFinalizer(napi_ref_tracker__* finalizer); @@ -101,8 +126,12 @@ struct napi_env__ { // Set only when the env had to create its own agent (an isolate the // provider did not set up). std::unique_ptr owned_agent; - // The env's realm. Never changes. + // The env's own realm. Never changes. v8::Global context_ref; + // The realms N-API acts in, innermost last. Empty means the env's own. + std::vector realm_frames; + // The last scope token unofficial_napi_enter_realm handed out. + uint64_t last_realm_scope = 0; napi::error_state__ error_state; std::vector open_handle_scope_stack; v8::Global last_exception; @@ -137,6 +166,21 @@ struct napi_env__ { v8impl::detail::napi_factory__ factory_; }; +// Runs the enclosing code in a realm (null: the env's own) and closes any +// scope it leaves open. +class napi_realm_frame_scope__ { + public: + napi_realm_frame_scope__(napi_env env, unofficial_napi_realm__* realm) + : env_(env), depth_(env->PushRealmFrame(realm)) {} + ~napi_realm_frame_scope__() { env_->PopRealmFrames(depth_); } + napi_realm_frame_scope__(const napi_realm_frame_scope__&) = delete; + napi_realm_frame_scope__& operator=(const napi_realm_frame_scope__&) = delete; + + private: + napi_env env_; + size_t depth_; +}; + napi_status napi_v8_set_last_error(napi_env env, napi_status status, const char* message); diff --git a/v8/src/js_native_api_v8.cc b/v8/src/js_native_api_v8.cc index 9d2565fc51..75eeb4fd82 100644 --- a/v8/src/js_native_api_v8.cc +++ b/v8/src/js_native_api_v8.cc @@ -474,6 +474,13 @@ bool HandleCallbackException(napi_env env) { return true; } +// A promise settles in its own realm, the one it was made in. +v8::Local PromiseContext(napi_env env, v8::Local resolver) { + v8::Local context; + if (!resolver->GetCreationContext().ToLocal(&context)) context = env->main_context(); + return context; +} + void FunctionTrampoline(const v8::FunctionCallbackInfo& info) { auto* payload = static_cast(info.Data().As()->Value()); @@ -482,6 +489,9 @@ void FunctionTrampoline(const v8::FunctionCallbackInfo& info) { } napi_env env = payload->env; + // V8 already runs the callback in the function's creation context; N-API + // acts in that realm too, and closes the scopes the callback leaves open. + napi_realm_frame_scope__ realm_frame(env, payload->realm); napi_function_callback_info__ cbinfo(info, payload); napi_value ret = payload->cb(env, &cbinfo); @@ -535,10 +545,12 @@ napi_handle_scope__::napi_handle_scope__(napi_env env) napi_escapable_handle_scope__::napi_escapable_handle_scope__(napi_env env) : env(env), wrapper(env->isolate) {} +// Finalizers run in the env's own realm. void napi_env__::CallFinalizer(node_api_basic_finalize cb, void* data, void* hint) { if (cb == nullptr) return; v8::HandleScope handle_scope(isolate); - v8::Context::Scope context_scope(context()); + v8::Context::Scope context_scope(main_context()); + napi_realm_frame_scope__ realm_frame(this, nullptr); cb(this, data, hint); } @@ -564,6 +576,10 @@ void napi_env__::DequeueFinalizer(napi_ref_tracker__* finalizer) { void napi_env__::DrainFinalizerQueue() { finalization_scheduled = false; + if (pending_finalizers.empty() && pending_buffer_finalizers.empty()) return; + v8::HandleScope handle_scope(isolate); + v8::Context::Scope context_scope(main_context()); + napi_realm_frame_scope__ realm_frame(this, nullptr); while (!pending_finalizers.empty() || !pending_buffer_finalizers.empty()) { while (!pending_finalizers.empty()) { napi_ref_tracker__* ref_tracker = *pending_finalizers.begin(); @@ -636,6 +652,8 @@ napi_env__::napi_env__(v8::Local context, int32_t module_api_versio napi_env__::~napi_env__() { NAPI_V8_LIFETIME_DUMP(this, "napi_env__ teardown begin"); + // Every scope closes; cleanup hooks and finalizers run in the env's realm. + PopRealmFrames(0); RunEnvCleanupHooks(this); napi_ref_tracker__::FinalizeAll(&finalizing_reflist); napi_ref_tracker__::FinalizeAll(&reflist); @@ -655,9 +673,36 @@ napi_env__::~napi_env__() { } v8::Local napi_env__::context() const { + unofficial_napi_realm__* realm = current_realm(); + return realm != nullptr ? realm->context.Get(isolate) : context_ref.Get(isolate); +} + +v8::Local napi_env__::main_context() const { return context_ref.Get(isolate); } +unofficial_napi_realm__* napi_env__::current_realm() const { + return realm_frames.empty() ? nullptr : realm_frames.back().realm; +} + +size_t napi_env__::PushRealmFrame(unofficial_napi_realm__* realm) { + size_t depth = realm_frames.size(); + realm_frames.emplace_back(); + realm_frames.back().realm = realm; + return depth; +} + +void napi_env__::PopRealmFrames(size_t depth) { + while (realm_frames.size() > depth) { + napi_realm_frame__& frame = realm_frames.back(); + if (!frame.entered.IsEmpty()) { + v8::HandleScope handle_scope(isolate); + frame.entered.Get(isolate)->Exit(); + } + realm_frames.pop_back(); + } +} + #if defined(NAPI_ENABLE_LIFETIME_TRACKER) && defined(NAPI_ENABLE_LIFETIME_PERIODIC_STATS) bool napi_env__::should_dump_lifetime_stats(int64_t now_ms) { return lifetime_stats_gate_.should_fire(now_ms); @@ -1766,7 +1811,7 @@ napi_status NAPI_CDECL napi_create_function(napi_env env, if (cb == nullptr || result == nullptr) { return napi_v8_set_last_error(env, napi_invalid_arg, "Invalid argument"); } - auto* payload = env->allocate(env, cb, data); + auto* payload = env->allocate(env, cb, data, env->current_realm()); if (payload == nullptr) return napi_generic_failure; v8::Local payloadValue = v8::External::New(env->isolate, payload); @@ -1811,7 +1856,8 @@ napi_status NAPI_CDECL napi_define_class(napi_env env, } v8::Local context = env->context(); - auto* payload = env->allocate(env, constructor, data); + auto* payload = + env->allocate(env, constructor, data, env->current_realm()); if (payload == nullptr) return napi_generic_failure; const int v8_length = (length == NAPI_AUTO_LENGTH) ? -1 : static_cast(length); @@ -2110,7 +2156,8 @@ napi_status NAPI_CDECL napi_resolve_deferred(napi_env env, } v8::TryCatch tc(env->isolate); v8::Local resolver = deferred->resolver.Get(env->isolate); - if (!resolver->Resolve(env->context(), napi_v8_unwrap_value(resolution)).FromMaybe(false)) { + if (!resolver->Resolve(PromiseContext(env, resolver), napi_v8_unwrap_value(resolution)) + .FromMaybe(false)) { return ReturnPendingIfCaught(env, tc, "Failed to resolve promise"); } env->release(deferred); @@ -2126,7 +2173,8 @@ napi_status NAPI_CDECL napi_reject_deferred(napi_env env, } v8::TryCatch tc(env->isolate); v8::Local resolver = deferred->resolver.Get(env->isolate); - if (!resolver->Reject(env->context(), napi_v8_unwrap_value(rejection)).FromMaybe(false)) { + if (!resolver->Reject(PromiseContext(env, resolver), napi_v8_unwrap_value(rejection)) + .FromMaybe(false)) { return ReturnPendingIfCaught(env, tc, "Failed to reject promise"); } env->release(deferred); diff --git a/v8/src/unofficial_napi.cc b/v8/src/unofficial_napi.cc index 613bbd0b34..6bd1c5198f 100644 --- a/v8/src/unofficial_napi.cc +++ b/v8/src/unofficial_napi.cc @@ -325,7 +325,7 @@ v8::Local LookupPrepareStackTraceCallback(napi_env env, } PrepareStackTraceState& state = state_it->second; - v8::Local principal_context = env->context(); + v8::Local principal_context = env->main_context(); const bool use_principal_callback = !principal_context.IsEmpty() && (context == principal_context || NapiV8IsContextifyContext(env, context)); @@ -687,8 +687,9 @@ void PromiseRejectCallback(v8::PromiseRejectMessage message) { std::getenv("EDGE_DEBUG_EXCEPTIONS")[0] != '\0' && std::getenv("EDGE_DEBUG_EXCEPTIONS")[0] != '0'; + // Env hooks run in the env's own realm. v8::HandleScope handle_scope(isolate); - v8::Local context = env->context(); + v8::Local context = env->main_context(); v8::Context::Scope context_scope(context); v8::TryCatch tc(isolate); if (debug_promise_reject) { @@ -1918,7 +1919,7 @@ napi_status NAPI_CDECL unofficial_napi_set_prepare_stack_trace_callback( { std::lock_guard lock(g_runtime_mu); PrepareStackTraceState& state = g_prepare_stack_trace_callbacks[env]; - v8::Local principal_context = env->context(); + v8::Local principal_context = env->main_context(); const bool use_principal_callback = current_context.IsEmpty() || (!principal_context.IsEmpty() && @@ -1990,7 +1991,7 @@ bool PumpPlatformForegroundTasks(napi_env env) { bool DrainMicrotasksForEnv(napi_env env) { if (env == nullptr || env->isolate == nullptr) return false; env->DrainFinalizerQueue(); - v8::Local context = env->context(); + v8::Local context = env->main_context(); if (!context.IsEmpty()) { v8::MicrotaskQueue* queue = context->GetMicrotaskQueue(); if (queue != nullptr) { @@ -2090,10 +2091,12 @@ napi_status NAPI_CDECL unofficial_napi_request_interrupt( request->env->isolate != isolate) { return; } + // Interrupt callbacks run in the env's own realm. v8::HandleScope handle_scope(isolate); - v8::Local context = request->env->context(); + v8::Local context = request->env->main_context(); if (context.IsEmpty()) return; v8::Context::Scope context_scope(context); + napi_realm_frame_scope__ realm_frame(request->env, nullptr); request->callback(request->env, request->data); }, request); @@ -2226,7 +2229,7 @@ napi_status NAPI_CDECL unofficial_napi_set_promise_hooks(napi_env env, #endif #ifdef V8_ENABLE_JAVASCRIPT_PROMISE_HOOKS - NapiV8ApplyPromiseHooksToContext(env, env->context()); + NapiV8ApplyPromiseHooksToContext(env, env->main_context()); NapiV8ApplyPromiseHooksToContextifyContexts(env); #else env->isolate->SetPromiseHook(has_hooks ? PromiseHookCallback : nullptr); diff --git a/v8/src/unofficial_napi_contextify.cc b/v8/src/unofficial_napi_contextify.cc index 240f775ae9..ef27c3d810 100644 --- a/v8/src/unofficial_napi_contextify.cc +++ b/v8/src/unofficial_napi_contextify.cc @@ -1274,7 +1274,7 @@ unofficial_napi_realm RealmForContext(v8::Local context) { // The context code for `realm` runs in: the env's own for a null realm. // Empty when the realm is not one of `env`'s or was collected. v8::Local RealmContext(napi_env env, unofficial_napi_realm realm) { - if (realm == nullptr) return env->context(); + if (realm == nullptr) return env->main_context(); if (realm->env != env) return v8::Local(); return realm->context.Get(env->isolate); } @@ -1713,6 +1713,46 @@ napi_status NAPI_CDECL unofficial_napi_get_realm(napi_env env, return napi_ok; } +napi_status NAPI_CDECL unofficial_napi_enter_realm(napi_env env, + unofficial_napi_realm realm_or_null, + unofficial_napi_realm_scope* scope_out) { + if (env == nullptr || scope_out == nullptr) return napi_invalid_arg; + *scope_out = 0; + // Only a realm this env made and still holds; the handle is not read + // before that is known. + if (realm_or_null != nullptr && + std::none_of(env->realms.begin(), env->realms.end(), + [&](const auto& realm) { return realm.get() == realm_or_null; })) { + return napi_invalid_arg; + } + v8::HandleScope handle_scope(env->isolate); + v8::Local context = RealmContext(env, realm_or_null); + if (context.IsEmpty()) return napi_invalid_arg; + + // The scope enters the realm's context, as v8::Context::Scope does, so + // that what V8 makes in the current context is made there too. + napi_realm_frame__ frame; + frame.scope = ++env->last_realm_scope; + frame.realm = realm_or_null; + frame.entered.Reset(env->isolate, context); + context->Enter(); + env->realm_frames.push_back(std::move(frame)); + *scope_out = env->last_realm_scope; + return napi_ok; +} + +napi_status NAPI_CDECL unofficial_napi_leave_realm(napi_env env, + unofficial_napi_realm_scope scope) { + if (env == nullptr || scope == 0) return napi_invalid_arg; + // A callback's frame has token 0, so a scope of an outer callback is never + // the innermost one. + if (env->realm_frames.empty() || env->realm_frames.back().scope != scope) { + return napi_invalid_arg; + } + env->PopRealmFrames(env->realm_frames.size() - 1); + return napi_ok; +} + static napi_status BytecodeCompile( napi_env env, v8::Local context, @@ -2352,7 +2392,7 @@ static napi_status CreateSourceTextModule( v8::Local module; const bool artifact_reusable = bytecode_record != nullptr && !bytecode_record->module.IsEmpty() && - context == env->context() && !host_id_symbol.IsEmpty() && + context == env->main_context() && !host_id_symbol.IsEmpty() && !bytecode_record->host_symbol.IsEmpty() && bytecode_record->host_symbol.Get(isolate) == host_id_symbol; if (artifact_reusable) { From 851384cd5311201dad861da088927cb9df57e456 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Tue, 27 Oct 2026 11:29:49 -0700 Subject: [PATCH 022/150] QuickJS: act in the current realm QuickJS calls C functions with data in the caller's context; it switches realms only for its own built-ins. A native function of another realm now carries that realm's context and anchor in its data, and its trampoline makes the realm current. The env keeps the same stack of realm frames as on V8, and deferreds settle in their realm. Finalizers and interrupt callbacks run in the env's realm. Co-Authored-By: Claude Opus 5.5 --- quickjs/src/internal/napi_contextify.cc | 47 ++++++++++- quickjs/src/internal/napi_contextify.h | 9 +++ quickjs/src/internal/napi_deferred.cc | 24 ++++-- quickjs/src/internal/napi_deferred.h | 6 ++ quickjs/src/internal/napi_env.cc | 60 ++++++++++++++ quickjs/src/internal/napi_env.h | 59 +++++++++++++- .../napi_external_backing_store_hint.cc | 11 ++- quickjs/src/internal/napi_function.cc | 81 +++++++++++++++---- quickjs/src/internal/napi_function.h | 9 +++ quickjs/src/js_native_api_quickjs.cc | 3 +- quickjs/src/unofficial_napi.cc | 33 +++++++- 11 files changed, 313 insertions(+), 29 deletions(-) diff --git a/quickjs/src/internal/napi_contextify.cc b/quickjs/src/internal/napi_contextify.cc index 10ba901074..e6447f0f74 100644 --- a/quickjs/src/internal/napi_contextify.cc +++ b/quickjs/src/internal/napi_contextify.cc @@ -162,6 +162,9 @@ namespace quickjs::detail disposed = true; JSRuntime *rt = JS_GetRuntime(parent_ctx); JS_DeleteNativeWeakRefLink(rt, &key_link); + if (owns_anchor) + JS_FreeValueRT(rt, anchor); + anchor = JS_UNDEFINED; if (owns_context && ctx != nullptr) JS_FreeContext(ctx); for (JSAtom atom : baseline_atoms) @@ -184,6 +187,10 @@ namespace quickjs::detail JSContext *ctx = nullptr; // Borrowed; valid while live(). JSValueConst sandbox = JS_UNDEFINED; // Borrowed; undefined without one. JSValueConst global = JS_UNDEFINED; // Borrowed; valid while live(). + // A function of the realm, which keeps its context alive. The key + // holds it, or the record when the key cannot. + JSValue anchor = JS_UNDEFINED; + bool owns_anchor = false; JSValue host_defined_option_id = JS_UNDEFINED; std::vector baseline_atoms; JSNativeWeakRefLink key_link{}; @@ -414,15 +421,25 @@ namespace quickjs::detail JSValue anchor = JS_NewCFunction(child_ctx, contextify_anchor, "contextify", 0); if (!JS_IsException(anchor)) { - int stored = JS_DefinePropertyValue(ctx_, key, context_link_atom_, anchor, k_contextify_link_flags); + int stored = JS_DefinePropertyValue(ctx_, key, context_link_atom_, + JS_DupValue(child_ctx, anchor), k_contextify_link_flags); raw->anchored = stored > 0; + raw->anchor = anchor; if (stored > 0) + { + // The key holds the anchor; the record borrows it. + JS_FreeValue(child_ctx, anchor); linked = !raw->has_sandbox() || JS_DefinePropertyValue(child_ctx, raw->global, sandbox_link_atom_, JS_DupValue(child_ctx, raw->sandbox), k_contextify_link_flags) > 0; - else if (stored == 0) - linked = raw->owns_context = true; + } + else + { + raw->owns_anchor = true; + if (stored == 0) + linked = raw->owns_context = true; + } } linked = linked && JS_AddNativeWeakRefLink(ctx_, key, &raw->key_link, context_record::key_collected, raw) >= 0; @@ -872,6 +889,30 @@ namespace quickjs::detail return napi_ok; } + napi_status napi_contextify__::realm_to_enter(unofficial_napi_realm realm, + JSContext **ctx_out, + JSValue *anchor_out) const + { + // Only a realm this env made and still holds; the handle is not read + // before that is known. + auto *record = reinterpret_cast(realm); + const bool known = std::any_of(contexts_.begin(), contexts_.end(), [&](const auto &entry) + { return entry.get() == record; }); + if (!known || !record->live()) + return napi_invalid_arg; + *ctx_out = record->ctx; + *anchor_out = JS_DupValue(record->ctx, record->anchor); + return napi_ok; + } + + JSValue napi_contextify__::realm_key_for_global(JSValueConst global) const + { + context_record *record = find_live_record(global); + if (record == nullptr || !is_same_object(record->global, global)) + return JS_UNDEFINED; + return JS_DupValue(ctx_, record->key()); + } + JSContext *napi_contextify__::realm_context(unofficial_napi_realm realm) const { if (realm == nullptr) diff --git a/quickjs/src/internal/napi_contextify.h b/quickjs/src/internal/napi_contextify.h index 94eaa9e809..244c0aa00f 100644 --- a/quickjs/src/internal/napi_contextify.h +++ b/quickjs/src/internal/napi_contextify.h @@ -38,6 +38,15 @@ namespace quickjs::detail unofficial_napi_realm *realm_out, napi_value *global_out); napi_status get_realm(napi_value value, unofficial_napi_realm *realm_out) const; + // The context of a live realm of this env and, as a new reference, a + // function of the realm that keeps it alive. + napi_status realm_to_enter(unofficial_napi_realm realm, + JSContext **ctx_out, + JSValue *anchor_out) const; + // The key of the realm whose own global is `global` (its sandbox, or + // the global itself), as a new reference; undefined for any other + // object. + JSValue realm_key_for_global(JSValueConst global) const; // The context code for `realm` runs in: the realm's, or the env's // for NULL. JSContext *realm_context(unofficial_napi_realm realm) const; diff --git a/quickjs/src/internal/napi_deferred.cc b/quickjs/src/internal/napi_deferred.cc index f5a6a7cb44..3b6452f3dc 100644 --- a/quickjs/src/internal/napi_deferred.cc +++ b/quickjs/src/internal/napi_deferred.cc @@ -6,7 +6,9 @@ napi_deferred__::napi_deferred__(napi_env env, JSValue resolve, JSValue reject) : env_{env}, resolve_{resolve}, - reject_{reject} + reject_{reject}, + realm_ctx_{env->context()}, + realm_anchor_{JS_DupValue(env->context(), env->current_realm_anchor())} { } @@ -15,17 +17,21 @@ napi_deferred__::~napi_deferred__() if (env_ == nullptr) return; - JSContext *context = env_->context(); + JSContext *context = env_->main_context(); JSValue resolve = resolve_; JSValue reject = reject_; + JSValue anchor = realm_anchor_; env_ = nullptr; resolve_ = JS_UNDEFINED; reject_ = JS_UNDEFINED; + realm_anchor_ = JS_UNDEFINED; + realm_ctx_ = nullptr; if (context != nullptr) { JS_FreeValue(context, resolve); JS_FreeValue(context, reject); + JS_FreeValue(context, anchor); } } @@ -51,14 +57,20 @@ void napi_deferred__::destroy(napi_deferred__ *deferred) env->destroy_deferred(deferred); } +// The promise settles in its own realm. +JSValue napi_deferred__::call(JSValueConst function, napi_value argument) +{ + napi_realm_frame_scope__ realm_frame{env_, realm_ctx_, realm_anchor_}; + JSValue arg = napi_quickjs_value_inner(env_, argument); + return JS_Call(realm_ctx_, function, JS_UNDEFINED, 1, &arg); +} + JSValue napi_deferred__::call_resolve(napi_value resolution) { - JSValue arg = napi_quickjs_value_inner(env_, resolution); - return JS_Call(env_->context(), resolve_, JS_UNDEFINED, 1, &arg); + return call(resolve_, resolution); } JSValue napi_deferred__::call_reject(napi_value rejection) { - JSValue arg = napi_quickjs_value_inner(env_, rejection); - return JS_Call(env_->context(), reject_, JS_UNDEFINED, 1, &arg); + return call(reject_, rejection); } diff --git a/quickjs/src/internal/napi_deferred.h b/quickjs/src/internal/napi_deferred.h index d354833b18..17a55e12da 100644 --- a/quickjs/src/internal/napi_deferred.h +++ b/quickjs/src/internal/napi_deferred.h @@ -22,10 +22,16 @@ struct napi_deferred__ JSValue call_reject(napi_value rejection); private: + JSValue call(JSValueConst function, napi_value argument); + // Owning environment and stored promise callbacks. napi_env env_ = nullptr; JSValue resolve_ = JS_UNDEFINED; JSValue reject_ = JS_UNDEFINED; + // The promise's realm, where it settles, and an anchor that keeps it alive + // until then (undefined for the env's own realm). + JSContext *realm_ctx_ = nullptr; + JSValue realm_anchor_ = JS_UNDEFINED; }; #endif // NAPI_QUICKJS_DEFERRED_H_ diff --git a/quickjs/src/internal/napi_env.cc b/quickjs/src/internal/napi_env.cc index 2f5c1afb3d..25f77f8e0b 100644 --- a/quickjs/src/internal/napi_env.cc +++ b/quickjs/src/internal/napi_env.cc @@ -122,6 +122,8 @@ void napi_env__::prepare_teardown() closing_ = true; NAPI_QUICKJS_LIFETIME_DUMP(this, "napi_env__ teardown begin"); + // Every scope closes; cleanup hooks and finalizers run in the env's realm. + pop_realm_frames(0); while (!env_cleanup_hooks_.empty()) { auto *entry = env_cleanup_hooks_.back(); @@ -209,10 +211,68 @@ bool napi_env__::is_principal() const } JSContext *napi_env__::context() const +{ + return realm_frames_.empty() ? context_ : realm_frames_.back().ctx; +} + +JSContext *napi_env__::main_context() const { return context_; } +JSValueConst napi_env__::current_realm_anchor() const +{ + return realm_frames_.empty() ? JS_UNDEFINED : realm_frames_.back().anchor; +} + +JSValue napi_env__::current_global() +{ + JSContext *ctx = context(); + JSValue global = JS_GetGlobalObject(ctx); + if (ctx == context_) + return global; + // A sandbox realm reports its sandbox as its global. + JSValue key = contextify_.realm_key_for_global(global); + if (JS_IsUndefined(key)) + return global; + JS_FreeValue(ctx, global); + return key; +} + +size_t napi_env__::push_realm_frame(JSContext *ctx, JSValueConst anchor) +{ + const size_t depth = realm_frames_.size(); + realm_frames_.push_back({0, ctx != nullptr ? ctx : context_, anchor}); + return depth; +} + +void napi_env__::pop_realm_frames(size_t depth) +{ + while (realm_frames_.size() > depth) + { + napi_realm_frame__ frame = realm_frames_.back(); + realm_frames_.pop_back(); + if (frame.scope != 0) + JS_FreeValue(context_, frame.anchor); + } +} + +uint64_t napi_env__::enter_realm(JSContext *ctx, JSValue anchor) +{ + realm_frames_.push_back({++last_realm_scope_, ctx, anchor}); + return last_realm_scope_; +} + +bool napi_env__::leave_realm(uint64_t scope) +{ + // A callback's frame has token 0, so a scope of an outer callback is never + // the innermost one. + if (scope == 0 || realm_frames_.empty() || realm_frames_.back().scope != scope) + return false; + pop_realm_frames(realm_frames_.size() - 1); + return true; +} + int32_t napi_env__::module_api_version() const { return module_api_version_; diff --git a/quickjs/src/internal/napi_env.h b/quickjs/src/internal/napi_env.h index d592e13957..93a17aaa67 100644 --- a/quickjs/src/internal/napi_env.h +++ b/quickjs/src/internal/napi_env.h @@ -30,7 +30,22 @@ struct napi_external_backing_store_hint__; struct napi_runtime_interrupts__; -// One realm (JSContext) of an agent. The context never changes. +// A realm N-API acts in: a scope opened with unofficial_napi_enter_realm, or +// a native callback that is running. The innermost frame is the current +// realm. +struct napi_realm_frame__ +{ + // The scope's token; 0 for a callback. + uint64_t scope = 0; + JSContext *ctx = nullptr; + // A function of the realm, which keeps its context alive; undefined for the + // env's own realm. A scope owns it until it is left; a callback borrows its + // function's. + JSValue anchor = JS_UNDEFINED; +}; + +// One env of an agent. Its own realm (JSContext) never changes; the realm it +// acts in is the innermost realm frame's. struct napi_env__ { napi_env__(napi_agent__ *agent, JSContext *context, int32_t module_api_version); @@ -45,7 +60,26 @@ struct napi_env__ // Makes this env own its agent (an env made from an embedder's context). void adopt_agent(std::unique_ptr agent); bool is_principal() const; + // The current realm's context: the innermost realm frame's, else the env's + // own. N-API calls create what they make there. JSContext *context() const; + // The env's own realm. + JSContext *main_context() const; + // A function of the current realm that keeps it alive; undefined for the + // env's own realm. + JSValueConst current_realm_anchor() const; + // The current realm's global as unofficial_napi_create_realm reports it: + // a sandbox realm's sandbox. A new reference. + JSValue current_global(); + // Pushes the frame of a callback running in `ctx` (borrowing `anchor`) and + // returns the depth pop_realm_frames restores. + size_t push_realm_frame(JSContext *ctx, JSValueConst anchor); + // Pops the frames above `depth`. + void pop_realm_frames(size_t depth); + // unofficial_napi_enter_realm and unofficial_napi_leave_realm. The scope + // takes `anchor`. + uint64_t enter_realm(JSContext *ctx, JSValue anchor); + bool leave_realm(uint64_t scope); int32_t module_api_version() const; napi_handle_scope root_scope() const; @@ -140,6 +174,11 @@ struct napi_env__ JSContext *context_; int32_t module_api_version_ = 8; + // The realms N-API acts in, innermost last. Empty means the env's own. + std::vector realm_frames_; + // The last scope token enter_realm handed out. + uint64_t last_realm_scope_ = 0; + // Last native error state. napi::error_state__ error_state_; @@ -180,6 +219,24 @@ struct napi_env__ bool clearing_refs_for_teardown_ = false; }; +// Runs the enclosing code in a realm (null: the env's own) and closes any +// scope it leaves open. +class napi_realm_frame_scope__ +{ +public: + napi_realm_frame_scope__(napi_env env, JSContext *ctx, JSValueConst anchor) + : env_{env}, depth_{env->push_realm_frame(ctx, anchor)} + { + } + ~napi_realm_frame_scope__() { env_->pop_realm_frames(depth_); } + napi_realm_frame_scope__(const napi_realm_frame_scope__ &) = delete; + napi_realm_frame_scope__ &operator=(const napi_realm_frame_scope__ &) = delete; + +private: + napi_env env_; + size_t depth_; +}; + napi_status napi_quickjs_set_last_error(napi_env env, napi_status status, const char *message); diff --git a/quickjs/src/internal/napi_external_backing_store_hint.cc b/quickjs/src/internal/napi_external_backing_store_hint.cc index d578ba9112..2e925f6594 100644 --- a/quickjs/src/internal/napi_external_backing_store_hint.cc +++ b/quickjs/src/internal/napi_external_backing_store_hint.cc @@ -63,8 +63,17 @@ void napi_external_backing_store_hint__::invoke_finalizer() if (finalize_invoked_) return; finalize_invoked_ = true; - if (finalize_cb_ != nullptr) + if (finalize_cb_ == nullptr) + return; + if (env_ == nullptr) + { finalize_cb_(env_, external_data_, finalize_hint_); + return; + } + // Finalizers run in the env's own realm, also when the collector runs + // inside another realm. + napi_realm_frame_scope__ realm_frame{env_, nullptr, JS_UNDEFINED}; + finalize_cb_(env_, external_data_, finalize_hint_); } napi_env napi_external_backing_store_hint__::env() const diff --git a/quickjs/src/internal/napi_function.cc b/quickjs/src/internal/napi_function.cc index 4ecac56499..d011148953 100644 --- a/quickjs/src/internal/napi_function.cc +++ b/quickjs/src/internal/napi_function.cc @@ -57,19 +57,26 @@ JSValue napi_function__::create_internal(napi_env env, return JS_DupValue(env->context(), napi_quickjs_value_inner(env, fn_val)); } -// QuickJS passes the caller's realm as `ctx` for C function data (it does not -// switch realms). The callback runs in the realm of the env that created the -// function instead, as in V8 and Node. -JSValue napi_function__::trampoline(JSContext *caller_ctx, - JSValueConst this_val, - int argc, - JSValueConst *argv, - int magic, - JSValue *func_data) +namespace +{ +// QuickJS passes the caller's realm as `ctx` for C function data: it does not +// switch realms as it does for its own built-in functions. The callback runs +// in the function's realm instead (`realm_ctx`, or the env's own when null), +// as in V8, and N-API acts in that realm while it runs. +JSValue invoke_callback(JSContext *caller_ctx, + JSContext *realm_ctx, + JSValueConst realm_anchor, + JSValueConst this_val, + int argc, + JSValueConst *argv, + int magic, + JSValue *func_data) { auto env = napi_external__::get_env(func_data[0]); if (!napi_util__::check_env(env) || env->is_closing()) return JS_ThrowReferenceError(caller_ctx, "Null NAPI env"); + // Closes the scopes the callback leaves open once everything below is done. + napi_realm_frame_scope__ realm_frame{env, realm_ctx, realm_anchor}; JSContext *ctx = env->context(); auto cb_ptr = napi_external__::get_value(func_data[0]); @@ -148,6 +155,28 @@ JSValue napi_function__::trampoline(JSContext *caller_ctx, return returned; } +} // namespace + +JSValue napi_function__::trampoline(JSContext *caller_ctx, + JSValueConst this_val, + int argc, + JSValueConst *argv, + int magic, + JSValue *func_data) +{ + return invoke_callback(caller_ctx, nullptr, JS_UNDEFINED, this_val, argc, argv, magic, func_data); +} + +JSValue napi_function__::realm_trampoline(JSContext *caller_ctx, + JSValueConst this_val, + int argc, + JSValueConst *argv, + int magic, + JSValue *func_data) +{ + auto *realm_ctx = static_cast(napi_external__::get_value(func_data[3])); + return invoke_callback(caller_ctx, realm_ctx, func_data[2], this_val, argc, argv, magic, func_data); +} napi_status napi_function__::make_constructible(napi_env env, JSValue fn) { @@ -172,7 +201,19 @@ napi_status napi_function__::create(napi_env env, if (!napi_util__::check_env(env) || cb == nullptr || result == nullptr) return napi_util__::invalid_arg(env); - JSValue data_values[2]; + // The function belongs to the current realm. One of another realm also + // holds that realm's anchor, which keeps the realm alive exactly as long as + // the function and lets the collector see the edge. + JSContext *ctx = env->context(); + JSValueConst realm_anchor = env->current_realm_anchor(); + const bool own_realm = JS_IsUndefined(realm_anchor); + JSValue data_values[4] = {JS_UNDEFINED, JS_UNDEFINED, JS_UNDEFINED, JS_UNDEFINED}; + const int data_count = own_realm ? 2 : 4; + auto free_data = [&]() + { + for (JSValue &value : data_values) + JS_FreeValue(ctx, value); + }; data_values[0] = env->wrap_external_data(reinterpret_cast(cb)); if (JS_IsException(data_values[0])) { @@ -181,13 +222,25 @@ napi_status napi_function__::create(napi_env env, data_values[1] = env->wrap_external_data(data); if (JS_IsException(data_values[1])) { - JS_FreeValue(env->context(), data_values[0]); + data_values[1] = JS_UNDEFINED; + free_data(); return napi_util__::return_pending_if_caught(env, "Failed to create function data"); } + if (!own_realm) + { + data_values[2] = JS_DupValue(ctx, realm_anchor); + data_values[3] = env->wrap_external_data(ctx); + if (JS_IsException(data_values[3])) + { + data_values[3] = JS_UNDEFINED; + free_data(); + return napi_util__::return_pending_if_caught(env, "Failed to create function data"); + } + } - JSValue fn = JS_NewCFunctionData(env->context(), trampoline, 0, magic, 2, data_values); - JS_FreeValue(env->context(), data_values[0]); - JS_FreeValue(env->context(), data_values[1]); + JSValue fn = JS_NewCFunctionData(ctx, own_realm ? trampoline : realm_trampoline, 0, magic, + data_count, data_values); + free_data(); if (JS_IsException(fn)) return napi_util__::return_pending_if_caught(env, "Failed to create function"); diff --git a/quickjs/src/internal/napi_function.h b/quickjs/src/internal/napi_function.h index ea6ebf607f..6ae809a18e 100644 --- a/quickjs/src/internal/napi_function.h +++ b/quickjs/src/internal/napi_function.h @@ -13,12 +13,21 @@ class napi_function__ napi_callback cb, void *data); + // A function of the env's own realm: data is [callback, data]. static JSValue trampoline(JSContext *ctx, JSValueConst this_val, int argc, JSValueConst *argv, int magic, JSValue *func_data); + // A function of another realm: data is [callback, data, realm anchor, + // realm context]. + static JSValue realm_trampoline(JSContext *ctx, + JSValueConst this_val, + int argc, + JSValueConst *argv, + int magic, + JSValue *func_data); static napi_status make_constructible(napi_env env, JSValue fn); diff --git a/quickjs/src/js_native_api_quickjs.cc b/quickjs/src/js_native_api_quickjs.cc index e226509ea9..3c67425f66 100644 --- a/quickjs/src/js_native_api_quickjs.cc +++ b/quickjs/src/js_native_api_quickjs.cc @@ -179,8 +179,7 @@ extern "C" { if (!napi_util__::check_env(env) || result == nullptr) return napi_invalid_arg; - auto context = env->context(); - *result = env->wrap_value_in_current_scope(JS_GetGlobalObject(context), true); + *result = env->wrap_value_in_current_scope(env->current_global(), true); return (*result == nullptr) ? napi_generic_failure : napi_ok; } diff --git a/quickjs/src/unofficial_napi.cc b/quickjs/src/unofficial_napi.cc index de37284347..58350a59f1 100644 --- a/quickjs/src/unofficial_napi.cc +++ b/quickjs/src/unofficial_napi.cc @@ -50,7 +50,7 @@ namespace if (env == nullptr) return napi_invalid_arg; - JSContext *ctx = env->context(); + JSContext *ctx = env->main_context(); env->agent()->clear_promise_hooks(); JS_SetContextOpaque(ctx, nullptr); env->prepare_teardown(); @@ -478,6 +478,8 @@ extern "C" { if (!napi_util__::check_env(env) || callback == nullptr) return napi_invalid_arg; + // Interrupt callbacks run in the env's own realm. + napi_realm_frame_scope__ realm_frame{env, nullptr, JS_UNDEFINED}; callback(env, data); return napi_ok; } @@ -1168,6 +1170,33 @@ extern "C" : napi_invalid_arg; } + napi_status NAPI_CDECL unofficial_napi_enter_realm(napi_env env, + unofficial_napi_realm realm_or_null, + unofficial_napi_realm_scope *scope_out) + { + if (!napi_util__::check_env(env) || scope_out == nullptr) + return napi_invalid_arg; + *scope_out = 0; + JSContext *ctx = env->main_context(); + JSValue anchor = JS_UNDEFINED; + if (realm_or_null != nullptr) + { + napi_status status = env->contextify().realm_to_enter(realm_or_null, &ctx, &anchor); + if (status != napi_ok) + return status; + } + *scope_out = env->enter_realm(ctx, anchor); + return napi_ok; + } + + napi_status NAPI_CDECL unofficial_napi_leave_realm(napi_env env, + unofficial_napi_realm_scope scope) + { + if (!napi_util__::check_env(env)) + return napi_invalid_arg; + return env->leave_realm(scope) ? napi_ok : napi_invalid_arg; + } + napi_status NAPI_CDECL unofficial_napi_run_script( napi_env env, unofficial_napi_realm realm_or_null, @@ -1534,7 +1563,7 @@ extern "C" { if (env == nullptr) return napi_invalid_arg; - JSContext *ctx = env->context(); + JSContext *ctx = env->main_context(); napi_status status = DestroyEnvInstance(env); JS_FreeContext(ctx); return status; From d0204030dbe089172b16eb3220ed135c546ce730 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Tue, 27 Oct 2026 11:29:49 -0700 Subject: [PATCH 023/150] Bridge: enter and leave realms through the guest ABI The guest imports unofficial_napi_enter_realm(env, realm_id, scope_out_ptr) and unofficial_napi_leave_realm(env, scope). A realm id is the value id of the realm's global, 0 for the env's own; the scope token is the provider's. Co-Authored-By: Claude Opus 5.5 --- src/guest/napi.rs | 32 ++++++++++++++++++++++++++++++++ src/napi_bridge_init.cc | 23 +++++++++++++++++++++++ src/snapi.rs | 9 +++++++++ 3 files changed, 64 insertions(+) diff --git a/src/guest/napi.rs b/src/guest/napi.rs index d52a370234..c230f19f6d 100644 --- a/src/guest/napi.rs +++ b/src/guest/napi.rs @@ -1172,6 +1172,36 @@ fn guest_unofficial_napi_get_realm( status } +/// `realm` is a guest realm id (0 for the env's own realm). The scope token is +/// the provider's, written as a u64. +fn guest_unofficial_napi_enter_realm( + mut env: FunctionEnvMut, + napi_env: u32, + realm: u32, + scope_out_ptr: u32, +) -> i32 { + if scope_out_ptr == 0 { + return 1; + } + let env_handle = snapi_env(&env, napi_env); + let mut scope = 0u64; + let status = unsafe { snapi_bridge_unofficial_enter_realm(env_handle, realm, &mut scope) }; + if status == 0 && !write_guest_u64(&mut env, scope_out_ptr, scope) { + // The guest never learns the token, so close the scope again. + unsafe { snapi_bridge_unofficial_leave_realm(env_handle, scope) }; + return 1; + } + status +} + +fn guest_unofficial_napi_leave_realm( + env: FunctionEnvMut, + napi_env: u32, + scope: i64, +) -> i32 { + unsafe { snapi_bridge_unofficial_leave_realm(snapi_env(&env, napi_env), scope as u64) } +} + #[allow(clippy::too_many_arguments)] #[allow(clippy::result_large_err)] fn guest_unofficial_napi_run_script( @@ -4939,6 +4969,8 @@ pub fn register_napi_imports( "unofficial_napi_contextify_contains_module_syntax" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_contextify_contains_module_syntax), "unofficial_napi_create_realm" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_create_realm), "unofficial_napi_get_realm" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_get_realm), + "unofficial_napi_enter_realm" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_enter_realm), + "unofficial_napi_leave_realm" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_leave_realm), "unofficial_napi_run_script" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_run_script), "unofficial_napi_compile_function" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_compile_function), "unofficial_napi_bytecode_open" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_bytecode_open), diff --git a/src/napi_bridge_init.cc b/src/napi_bridge_init.cc index e5bf06eb21..894b2d3589 100644 --- a/src/napi_bridge_init.cc +++ b/src/napi_bridge_init.cc @@ -3853,6 +3853,29 @@ extern "C" int snapi_bridge_unofficial_get_realm(SnapiEnvState* env_state, return napi_ok; } +// The scope token is the provider's; the bridge keeps no scope table. +extern "C" int snapi_bridge_unofficial_enter_realm(SnapiEnvState* env_state, + uint32_t realm_id, + uint64_t* scope_out) { + auto* bridge_state = RequireEnvState(env_state); + if (bridge_state == nullptr || scope_out == nullptr) return napi_invalid_arg; + std::lock_guard lock(g_mu); + unofficial_napi_realm realm = nullptr; + if (!ResolveRealm(*bridge_state, realm_id, &realm)) return napi_invalid_arg; + unofficial_napi_realm_scope scope = 0; + napi_status s = unofficial_napi_enter_realm(bridge_state->env, realm, &scope); + if (s != napi_ok) return s; + *scope_out = scope; + return napi_ok; +} + +extern "C" int snapi_bridge_unofficial_leave_realm(SnapiEnvState* env_state, uint64_t scope) { + auto* bridge_state = RequireEnvState(env_state); + if (bridge_state == nullptr) return napi_invalid_arg; + std::lock_guard lock(g_mu); + return unofficial_napi_leave_realm(bridge_state->env, scope); +} + extern "C" int snapi_bridge_unofficial_run_script( SnapiEnvState* env_state, uint32_t realm_id, diff --git a/src/snapi.rs b/src/snapi.rs index 0abb021253..9620b51c59 100644 --- a/src/snapi.rs +++ b/src/snapi.rs @@ -298,6 +298,15 @@ unsafe extern "C" { ) -> i32; pub fn snapi_bridge_unofficial_get_realm(env: SnapiEnv, value_id: u32, realm_out: *mut u32) -> i32; + // Makes the realm `realm_id` (0: the env's own) current until + // snapi_bridge_unofficial_leave_realm closes the scope written to + // `scope_out`, as unofficial_napi_enter_realm does. + pub fn snapi_bridge_unofficial_enter_realm( + env: SnapiEnv, + realm_id: u32, + scope_out: *mut u64, + ) -> i32; + pub fn snapi_bridge_unofficial_leave_realm(env: SnapiEnv, scope: u64) -> i32; pub fn snapi_bridge_unofficial_run_script( env: SnapiEnv, realm_id: u32, From d496fa72fde0a856e2e1cf078fdef7485c82b006 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Tue, 27 Oct 2026 11:29:49 -0700 Subject: [PATCH 024/150] host-JS: act in the current realm Implement snapi_bridge_unofficial_enter_realm and snapi_bridge_unofficial_leave_realm for the host-JS provider, and the unofficial_napi_enter_realm / unofficial_napi_leave_realm guest imports of the in-tab build. The env keeps a realm stack: scopes opened with enter_realm and the native callbacks and finalizers running, innermost last. The current realm is the innermost entry's, else the env's own. napi_get_global returns the current realm's key (its sandbox, else its global), so unofficial_napi_get_realm finds the realm again. A native function belongs to the realm current when it was made. Its JS wrapper holds that realm's context and passes it to dispatch on every call; the Rust closure, which the env keeps for its whole life, does not capture it, so a realm is collected with the last function made in it. A callback runs with its function's realm current, including a deferred callback when it is drained, and the scopes it leaves open close when it returns. napi_run_script runs in the current realm. Finalizers run in the env's realm. Functions made with no scope open belong to the env's realm, as before. Co-Authored-By: Claude Opus 5.5 --- src/guest/napi_js.rs | 32 ++ src/snapi_js.rs | 660 ++++++++++++++++++++++++-- tests/host-js/README.md | 3 +- tests/host-js/global-context.test.mjs | 44 ++ 4 files changed, 698 insertions(+), 41 deletions(-) diff --git a/src/guest/napi_js.rs b/src/guest/napi_js.rs index 3568606ff2..e9c8a9963a 100644 --- a/src/guest/napi_js.rs +++ b/src/guest/napi_js.rs @@ -1615,6 +1615,36 @@ fn guest_unofficial_napi_get_realm( status } +/// `realm` is a guest realm id (0 for the env's own realm). The scope token is +/// the provider's, written as a u64. +fn guest_unofficial_napi_enter_realm( + mut env: FunctionEnvMut, + napi_env: u32, + realm: u32, + scope_out_ptr: u32, +) -> i32 { + if scope_out_ptr == 0 { + return 1; + } + let env_handle = snapi_env(&env, napi_env); + let mut scope = 0u64; + let status = unsafe { snapi_bridge_unofficial_enter_realm(env_handle, realm, &mut scope) }; + if status == 0 && !write_guest_u64(&mut env, scope_out_ptr, scope) { + // The guest never learns the token, so close the scope again. + unsafe { snapi_bridge_unofficial_leave_realm(env_handle, scope) }; + return 1; + } + status +} + +fn guest_unofficial_napi_leave_realm( + env: FunctionEnvMut, + napi_env: u32, + scope: i64, +) -> i32 { + unsafe { snapi_bridge_unofficial_leave_realm(snapi_env(&env, napi_env), scope as u64) } +} + #[allow(clippy::too_many_arguments)] fn guest_unofficial_napi_run_script( mut env: FunctionEnvMut, @@ -5690,6 +5720,8 @@ pub fn register_napi_imports( "unofficial_napi_contextify_contains_module_syntax" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_contextify_contains_module_syntax), "unofficial_napi_create_realm" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_create_realm), "unofficial_napi_get_realm" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_get_realm), + "unofficial_napi_enter_realm" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_enter_realm), + "unofficial_napi_leave_realm" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_leave_realm), "unofficial_napi_run_script" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_run_script), "unofficial_napi_compile_function" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_compile_function), "unofficial_napi_bytecode_open" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_bytecode_open), diff --git a/src/snapi_js.rs b/src/snapi_js.rs index b756635a77..177d27c04a 100644 --- a/src/snapi_js.rs +++ b/src/snapi_js.rs @@ -456,13 +456,16 @@ function wasmerNapiSyncGlobalScope(context, snapshot) { }); return context.scope; } -export function wasmer_napi_make_callback(context, dispatch) { +// `realm` is the context of the realm the function belongs to, undefined for +// the env's own. Only the returned function holds it, so a realm whose only +// remaining reference is one of its functions is collected with that function. +export function wasmer_napi_make_callback(context, dispatch, realm) { const callbacks = context.callbacks; const index = callbacks.dispatches.push(dispatch) - 1; return function (...args) { const dispatch = callbacks.dispatches?.[index]; // new.target lets napi_get_new_target tell construction from a call. - return dispatch?.(this, args, new.target); + return dispatch?.(this, args, new.target, realm); }; } function wasmerNapiCreateGlobalScope(scopeTarget, fallback = globalThis) { @@ -551,6 +554,11 @@ export function wasmer_napi_realm_context(registry, value) { typeof value === 'function'; return isObject ? registry.get(value) : undefined; } +// The global napi_get_global returns in `context`'s realm: the realm's key +// (its sandbox, when it has one, else its global). +export function wasmer_napi_realm_global(context) { + return context.sandbox ?? context.scope; +} // Evaluates `source` in `context`. The context's scope exposes builtins as // bare identifiers and keeps its own defaults, so writes to process and Error // hooks cannot reach the worker global; a sandbox realm resolves identifiers @@ -1137,7 +1145,11 @@ export function wasmer_napi_create_serdes_binding() { } "#)] extern "C" { - fn wasmer_napi_make_callback(context: &JsValue, dispatch: &Function) -> Function; + fn wasmer_napi_make_callback( + context: &JsValue, + dispatch: &Function, + realm: &JsValue, + ) -> Function; fn wasmer_napi_enqueue_microtask(callback: &Function); fn wasmer_napi_event_loop_checkpoint( allow_host_tasks: bool, @@ -1160,6 +1172,7 @@ extern "C" { fn wasmer_napi_create_realm_registry() -> JsValue; fn wasmer_napi_create_realm_context(registry: &JsValue, sandbox: &JsValue) -> JsValue; fn wasmer_napi_realm_context(registry: &JsValue, value: &JsValue) -> JsValue; + fn wasmer_napi_realm_global(context: &JsValue) -> JsValue; #[wasm_bindgen(catch)] fn wasmer_napi_context_eval(context: &JsValue, source: &str) -> Result; #[wasm_bindgen(catch)] @@ -1304,8 +1317,10 @@ struct CallbackReg { data: u64, } -/// A guest callback trampoline: receives `this`, the arguments and `new.target`. -type CallbackClosure = Closure JsValue>; +/// A guest callback trampoline: receives `this`, the arguments, `new.target` +/// and the context of the function's realm (undefined for the env's own). +type CallbackFn = dyn Fn(JsValue, Array, JsValue, JsValue) -> JsValue; +type CallbackClosure = Closure; struct CallbackInfo { args: Vec, @@ -1318,10 +1333,22 @@ struct PendingCallback { registration: CallbackReg, cbinfo: u32, value_frame: u32, + /// The context of the function's realm, None for the env's own. + realm: Option, resolve: Function, reject: Function, } +/// An entry of an env's realm stack: a scope opened with enter_realm, or a +/// running native callback or finalizer. +struct RealmEntry { + /// The scope's token; 0 for a callback, which leave_realm never closes. + token: u64, + /// The context of the realm current while this is the innermost entry, + /// None for the env's own. + realm: Option, +} + struct ValueFrame { id: u32, handles: Vec, @@ -1402,14 +1429,18 @@ struct HostJsAgent { embedder_hooks_attached: bool, } -/// One N-API environment: its realm (the virtual global context, fixed for -/// the environment's life), the callbacks and modules created through it, -/// and addon state. +/// One N-API environment: its own realm (a virtual global context), the +/// realms it made and which of them is current, the callbacks and modules +/// created through it, and addon state. struct HostJsEnv { agent: Box, global_context: JsValue, /// The realms made with create_realm, by global and sandbox (a WeakMap). realms: JsValue, + /// Open realm scopes and running callbacks, innermost last. The current + /// realm is the innermost entry's, else the env's own. + realm_stack: Vec, + next_realm_scope: u64, live_env_addr: Rc>, /// Pending exception of calls made through this environment. last_exception: Option, @@ -1458,6 +1489,8 @@ impl HostJsEnv { agent: Box::new(HostJsAgent::new()), global_context: wasmer_napi_create_global_context(), realms: wasmer_napi_create_realm_registry(), + realm_stack: Vec::new(), + next_realm_scope: 1, live_env_addr: Rc::new(Cell::new(0)), last_exception: None, next_callback: 1, @@ -1471,6 +1504,28 @@ impl HostJsEnv { source_text_modules: IdHashMap::default(), } } + + /// The context of the current realm, None for the env's own. + fn current_realm(&self) -> Option<&JsValue> { + self.realm_stack.last()?.realm.as_ref() + } + + /// Makes `realm` (None: the env's own) current for a native callback or + /// finalizer about to run. Returns the depth to pass to `leave_callback`. + fn enter_callback(&mut self, realm: Option) -> usize { + self.realm_stack.push(RealmEntry { token: 0, realm }); + self.realm_stack.len() - 1 + } + + /// Ends the callback `enter_callback` started at `depth`, closing the + /// scopes it left open, and returns the realm it ran in. + fn leave_callback(&mut self, depth: usize) -> Option { + if depth >= self.realm_stack.len() { + return None; + } + self.realm_stack.truncate(depth + 1); + self.realm_stack.pop()?.realm + } } impl HostJsAgent { @@ -2256,7 +2311,11 @@ pub unsafe extern "C" fn snapi_bridge_get_global(env: SnapiEnv, out: *mut u32) - let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let global = wasmer_napi_global_context_scope(&state.global_context); + // The current realm's key, so get_realm finds that realm again. + let global = match state.current_realm() { + Some(realm) => wasmer_napi_realm_global(realm), + None => wasmer_napi_global_context_scope(&state.global_context), + }; let id = state.agent.insert(global); unsafe { write(out, id) }.map_or_else(|error| error, |()| NAPI_OK) } @@ -2907,12 +2966,16 @@ pub unsafe extern "C" fn snapi_bridge_run_script(env: SnapiEnv, script: u32, out let Some(source) = state.agent.get(script).and_then(JsValue::as_string) else { return NAPI_STRING_EXPECTED; }; - // napi_run_script executes in the environment's context. Evaluating with - // js_sys::eval here would instead target the Wasmer worker's real global - // realm, allowing Node bootstrap code from one N-API environment to mutate - // the SDK scheduler and leak state into every other environment hosted by - // that worker. - match wasmer_napi_context_eval(&state.global_context, &source) { + // napi_run_script executes in the current realm's context, the env's own + // when none is entered. Evaluating with js_sys::eval here would instead + // target the Wasmer worker's real global realm, allowing Node bootstrap + // code from one N-API environment to mutate the SDK scheduler and leak + // state into every other environment hosted by that worker. + let context = state + .current_realm() + .cloned() + .unwrap_or_else(|| state.global_context.clone()); + match wasmer_napi_context_eval(&context, &source) { Ok(value) => { let id = state.agent.insert(value); unsafe { write(out, id) }.map_or_else(|e| e, |_| NAPI_OK) @@ -3305,6 +3368,7 @@ pub unsafe extern "C" fn snapi_bridge_overwrite_reference_bytes( NAPI_OK } +#[cfg(not(test))] unsafe extern "C" { fn snapi_host_invoke_wasm_callback( ctx: *mut c_void, @@ -3320,10 +3384,13 @@ unsafe extern "C" { hint: u32, ) -> u32; } +// Tests run Rust closures in place of guest callbacks and finalizers. +#[cfg(test)] +use tests::{snapi_host_invoke_wasm_callback, snapi_host_invoke_wasm_finalizer}; unsafe fn drain_guest_finalizers(env: SnapiEnv, force: bool) -> i32 { loop { - let (record, callback_ctx, value_frame) = { + let (record, callback_ctx, value_frame, realm_depth) = { let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; @@ -3331,7 +3398,14 @@ unsafe fn drain_guest_finalizers(env: SnapiEnv, force: bool) -> i32 { return NAPI_OK; }; let value_frame = state.agent.open_value_frame(); - (record, state.agent.active_callback_ctx, value_frame) + // Finalizers run in the env's own realm. + let realm_depth = state.enter_callback(None); + ( + record, + state.agent.active_callback_ctx, + value_frame, + realm_depth, + ) }; let result = unsafe { snapi_host_invoke_wasm_finalizer( @@ -3345,6 +3419,7 @@ unsafe fn drain_guest_finalizers(env: SnapiEnv, force: bool) -> i32 { let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; + state.leave_callback(realm_depth); state.agent.close_value_frame(value_frame); if result == CALLBACK_DEFERRED { state.agent.guest_finalizers.push(record); @@ -3417,8 +3492,11 @@ pub unsafe extern "C" fn snapi_bridge_create_function( }; let live_env_addr = s.live_env_addr.clone(); let callback_name = function_name.clone(); + // The function belongs to the current realm. Its JS wrapper holds that + // realm's context and passes it in on every call; the closure must not + // capture it, since the env keeps every closure for its whole life. let closure = Closure::wrap(Box::new( - move |this: JsValue, args: Array, new_target: JsValue| -> JsValue { + move |this: JsValue, args: Array, new_target: JsValue, realm: JsValue| -> JsValue { let env_addr = live_env_addr.get(); if env_addr == 0 { wasmer_napi_console_error(&format!( @@ -3430,7 +3508,7 @@ pub unsafe extern "C" fn snapi_bridge_create_function( // Do not keep a mutable environment borrow across the guest callback: // invoking JavaScript from that callback may recursively enter this // same trampoline. - let (value_frame, cb, callback_ctx) = { + let (value_frame, cb, callback_ctx, realm_depth) = { let Ok(state) = (unsafe { env_mut(env) }) else { wasmer_napi_console_error(&format!( "[wasmer-napi-callback] invalid env callback={callback_name}" @@ -3459,7 +3537,14 @@ pub unsafe extern "C" fn snapi_bridge_create_function( data: registration.data, }, ); - (value_frame, cb, state.agent.active_callback_ctx) + let realm = (!realm.is_undefined()).then_some(realm); + let realm_depth = state.enter_callback(realm); + ( + value_frame, + cb, + state.agent.active_callback_ctx, + realm_depth, + ) }; if callback_ctx.is_null() { wasmer_napi_console_error(&format!( @@ -3474,7 +3559,11 @@ pub unsafe extern "C" fn snapi_bridge_create_function( cb, ) }; + let Ok(state) = (unsafe { env_mut(env) }) else { + return JsValue::UNDEFINED; + }; if result == CALLBACK_DEFERRED { + let realm = state.leave_callback(realm_depth); let resolve_slot = Rc::new(RefCell::new(None)); let reject_slot = Rc::new(RefCell::new(None)); let rs = resolve_slot.clone(); @@ -3483,21 +3572,18 @@ pub unsafe extern "C" fn snapi_bridge_create_function( *rs.borrow_mut() = Some(resolve); *rj.borrow_mut() = Some(reject); }); - let Ok(state) = (unsafe { env_mut(env) }) else { - return JsValue::UNDEFINED; - }; state.agent.pending_callbacks.push_back(PendingCallback { registration, cbinfo: cb, value_frame, + realm, resolve: resolve_slot.borrow_mut().take().unwrap(), reject: reject_slot.borrow_mut().take().unwrap(), }); return promise.into(); } - let Ok(state) = (unsafe { env_mut(env) }) else { - return JsValue::UNDEFINED; - }; + // Not kept in a local: throw_val below skips Rust destructors. + state.leave_callback(realm_depth); let error = state.last_exception.take(); let result_value = state.agent.get(result).cloned(); if result_value.is_none() && result != 0 { @@ -3518,8 +3604,11 @@ pub unsafe extern "C" fn snapi_bridge_create_function( } result }, - ) as Box JsValue>); - let function = wasmer_napi_make_callback(&s.global_context, closure.as_ref().unchecked_ref()); + ) as Box); + let undefined = JsValue::UNDEFINED; + let realm = s.current_realm().unwrap_or(&undefined); + let function = + wasmer_napi_make_callback(&s.global_context, closure.as_ref().unchecked_ref(), realm); if !name.is_null() { let _ = Reflect::set( &function, @@ -3535,14 +3624,16 @@ pub unsafe extern "C" fn snapi_bridge_create_function( #[unsafe(no_mangle)] pub unsafe extern "C" fn snapi_bridge_drain_pending_callbacks(env: SnapiEnv) -> i32 { loop { - let (pending, callback_ctx) = { + let (mut pending, callback_ctx, realm_depth) = { let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; - let Some(pending) = state.agent.pending_callbacks.pop_front() else { + let Some(mut pending) = state.agent.pending_callbacks.pop_front() else { return unsafe { drain_guest_finalizers(env, false) }; }; - (pending, state.agent.active_callback_ctx) + // A deferred callback still runs in its function's realm. + let realm_depth = state.enter_callback(pending.realm.take()); + (pending, state.agent.active_callback_ctx, realm_depth) }; let result = unsafe { @@ -3553,18 +3644,16 @@ pub unsafe extern "C" fn snapi_bridge_drain_pending_callbacks(env: SnapiEnv) -> pending.cbinfo, ) }; - if result == CALLBACK_DEFERRED { - let Ok(state) = (unsafe { env_mut(env) }) else { - return NAPI_INVALID_ARG; - }; - state.agent.pending_callbacks.push_front(pending); - return NAPI_OK; - } - let (error, result) = { let Ok(state) = (unsafe { env_mut(env) }) else { return NAPI_INVALID_ARG; }; + if result == CALLBACK_DEFERRED { + pending.realm = state.leave_callback(realm_depth); + state.agent.pending_callbacks.push_front(pending); + return NAPI_OK; + } + state.leave_callback(realm_depth); let error = state.last_exception.take(); let result = state .agent @@ -4538,6 +4627,50 @@ pub unsafe extern "C" fn snapi_bridge_unofficial_get_realm( unsafe { write(realm_out, if is_realm { value_id } else { 0 }) } .map_or_else(|err| err, |()| NAPI_OK) } +/// Makes the realm `realm_id` (0: the env's own) current until +/// snapi_bridge_unofficial_leave_realm closes the scope written to +/// `scope_out`. The scope holds the realm's context, which keeps it alive. +#[unsafe(no_mangle)] +pub unsafe extern "C" fn snapi_bridge_unofficial_enter_realm( + env: SnapiEnv, + realm_id: u32, + scope_out: *mut u64, +) -> i32 { + let Ok(state) = (unsafe { env_mut(env) }) else { + return NAPI_INVALID_ARG; + }; + if scope_out.is_null() { + return NAPI_INVALID_ARG; + } + let realm = if realm_id == 0 { + None + } else { + match realm_context(state, realm_id) { + Ok(context) => Some(context), + Err(status) => return status, + } + }; + let token = state.next_realm_scope; + state.next_realm_scope += 1; + state.realm_stack.push(RealmEntry { token, realm }); + unsafe { scope_out.write(token) }; + NAPI_OK +} +/// Closes `scope` when it is the innermost entry of the realm stack: a scope +/// opened in the running callback (or outside any callback) with none nested +/// in it still open. Anything else changes nothing. +#[unsafe(no_mangle)] +pub unsafe extern "C" fn snapi_bridge_unofficial_leave_realm(env: SnapiEnv, scope: u64) -> i32 { + let Ok(state) = (unsafe { env_mut(env) }) else { + return NAPI_INVALID_ARG; + }; + // Callback entries have token 0, which no scope gets. + if scope == 0 || state.realm_stack.last().map(|entry| entry.token) != Some(scope) { + return NAPI_INVALID_ARG; + } + state.realm_stack.pop(); + NAPI_OK +} #[unsafe(no_mangle)] pub unsafe extern "C" fn snapi_bridge_unofficial_run_script( env: SnapiEnv, @@ -6962,14 +7095,127 @@ mod tests { use super::*; use wasm_bindgen_test::wasm_bindgen_test; + /// A fresh environment, live as snapi_bridge_unofficial_create_env makes it. + fn new_env() -> SnapiEnv { + let state = Box::new(HostJsEnv::new()); + state + .live_env_addr + .set((&*state as *const HostJsEnv) as usize); + Box::into_raw(state).cast::() + } + /// Runs `test` on a fresh environment and releases it afterwards, so its /// global context does not outlive the test. fn with_env(test: impl FnOnce(SnapiEnv, &mut HostJsEnv)) { - let env = Box::into_raw(Box::new(HostJsEnv::new())).cast::(); + let env = new_env(); test(env, unsafe { env_mut(env) }.unwrap()); assert_eq!(unsafe { snapi_bridge_unofficial_release_env(env) }, NAPI_OK); } + /// A guest callback or finalizer body: takes the cbinfo id or the + /// finalizer's data, returns what the guest function would. + type GuestFunction = Rc u32>; + + thread_local! { + /// The guest functions tests make, by their `wasm_fn_ptr`. + static GUEST_FUNCTIONS: RefCell> = RefCell::default(); + } + + /// Registers `body` as a guest function and returns its `wasm_fn_ptr`. + fn guest_function(body: impl Fn(u32) -> u32 + 'static) -> u32 { + GUEST_FUNCTIONS.with(|functions| { + let mut functions = functions.borrow_mut(); + functions.push(Rc::new(body)); + functions.len() as u32 - 1 + }) + } + + fn run_guest_function(wasm_fn: u32, arg: u32) -> u32 { + let body = GUEST_FUNCTIONS.with(|functions| functions.borrow()[wasm_fn as usize].clone()); + body(arg) + } + + /// Runs the guest function `wasm_fn` with the callback's cbinfo id. + pub(super) unsafe fn snapi_host_invoke_wasm_callback( + _ctx: *mut c_void, + _guest_env: u32, + wasm_fn: u32, + cbinfo: u32, + ) -> u32 { + run_guest_function(wasm_fn, cbinfo) + } + + /// Runs the guest function `wasm_fn` with the finalizer's data. + pub(super) unsafe fn snapi_host_invoke_wasm_finalizer( + _ctx: *mut c_void, + _guest_env: u32, + wasm_fn: u32, + data: u32, + _hint: u32, + ) -> u32 { + run_guest_function(wasm_fn, data) + } + + /// Makes a native function whose callback runs `body` with its cbinfo id, + /// and returns the function's value id. + fn native_function(env: SnapiEnv, body: impl Fn(u32) -> u32 + 'static) -> u32 { + // Any non-null context: the guest functions above do not read it. + unsafe { env_mut(env) }.unwrap().agent.active_callback_ctx = env.cast(); + let reg = unsafe { snapi_bridge_alloc_cb_reg_id(env) }; + unsafe { snapi_bridge_register_callback(env, reg, 0, guest_function(body), 0) }; + let mut function = 0; + assert_eq!( + unsafe { snapi_bridge_create_function(env, ptr::null(), 0, reg, &mut function) }, + NAPI_OK + ); + function + } + + /// Calls the function `function` with no arguments. + fn call(env: SnapiEnv, function: u32) { + let mut out = 0; + assert_eq!( + unsafe { snapi_bridge_call_function(env, 0, function, 0, ptr::null(), &mut out) }, + NAPI_OK + ); + } + + fn value(env: SnapiEnv, id: u32) -> JsValue { + unsafe { env_mut(env) } + .unwrap() + .agent + .get(id) + .unwrap() + .clone() + } + + /// The value id of what napi_get_global returns now. + fn global_id(env: SnapiEnv) -> u32 { + let mut global = 0; + assert_eq!( + unsafe { snapi_bridge_get_global(env, &mut global) }, + NAPI_OK + ); + global + } + + /// The realm whose global napi_get_global returns now (0: the env's own). + fn current_realm(env: SnapiEnv) -> u32 { + realm_of(env, global_id(env)).unwrap() + } + + fn enter(env: SnapiEnv, realm: u32) -> Result { + let mut scope = 0; + match unsafe { snapi_bridge_unofficial_enter_realm(env, realm, &mut scope) } { + NAPI_OK => Ok(scope), + status => Err(status), + } + } + + fn leave(env: SnapiEnv, scope: u64) -> i32 { + unsafe { snapi_bridge_unofficial_leave_realm(env, scope) } + } + #[wasm_bindgen_test] fn get_new_target_reports_the_constructor_or_null() { with_env(|env, state| { @@ -7279,6 +7525,340 @@ mod tests { }); } + #[wasm_bindgen_test] + fn get_global_returns_the_global_of_the_entered_realm() { + with_env(|env, state| { + let sandbox = state.agent.insert(Object::new().into()); + let sandboxed = new_realm(env, sandbox).unwrap(); + let fresh = new_realm(env, 0).unwrap(); + let own = value(env, global_id(env)); + + let outer = enter(env, fresh).unwrap(); + assert!(Object::is(&value(env, global_id(env)), &value(env, fresh))); + assert_eq!(current_realm(env), fresh); + // napi_run_script runs in the current realm. + let script = state.agent.insert_primitive("globalThis".into()); + let mut evaluated = 0; + assert_eq!( + unsafe { snapi_bridge_run_script(env, script, &mut evaluated) }, + NAPI_OK + ); + assert!(Object::is(&value(env, evaluated), &value(env, fresh))); + let inner = enter(env, sandboxed).unwrap(); + // A sandbox realm's global is its sandbox. + assert!(Object::is( + &value(env, global_id(env)), + &value(env, sandbox) + )); + assert_eq!(current_realm(env), sandboxed); + // Realm id 0 is the env's own realm, also from inside another. + let own_scope = enter(env, 0).unwrap(); + assert!(Object::is(&value(env, global_id(env)), &own)); + assert_eq!(current_realm(env), 0); + + assert_eq!(leave(env, own_scope), NAPI_OK); + assert_eq!(current_realm(env), sandboxed); + assert_eq!(leave(env, inner), NAPI_OK); + assert_eq!(current_realm(env), fresh); + assert_eq!(leave(env, outer), NAPI_OK); + assert!(Object::is(&value(env, global_id(env)), &own)); + }); + } + + #[wasm_bindgen_test] + fn realm_scopes_close_innermost_first() { + with_env(|env, state| { + let error = state.agent.insert(Error::new("pending").into()); + let a = new_realm(env, 0).unwrap(); + let b = new_realm(env, 0).unwrap(); + let outer = enter(env, a).unwrap(); + let inner = enter(env, b).unwrap(); + assert!(outer != 0 && inner != 0 && outer != inner); + // An outer, a null or an unknown token is refused and changes nothing. + for token in [outer, 0, inner + 100] { + assert_eq!(leave(env, token), NAPI_INVALID_ARG); + assert_eq!(current_realm(env), b); + } + // Leaving keeps a pending exception pending. + assert_eq!(unsafe { snapi_bridge_throw(env, error) }, NAPI_OK); + assert_eq!(leave(env, inner), NAPI_OK); + let mut pending = 0; + assert_eq!( + unsafe { snapi_bridge_is_exception_pending(env, &mut pending) }, + NAPI_OK + ); + assert_eq!(pending, 1); + // A scope closes once. + assert_eq!(leave(env, inner), NAPI_INVALID_ARG); + assert_eq!(current_realm(env), a); + assert_eq!(leave(env, outer), NAPI_OK); + assert_eq!(leave(env, outer), NAPI_INVALID_ARG); + assert_eq!(current_realm(env), 0); + // Tokens are not reused. + let again = enter(env, b).unwrap(); + assert!(again != outer && again != inner); + assert_eq!(leave(env, again), NAPI_OK); + }); + } + + #[wasm_bindgen_test] + fn only_realms_of_the_env_can_be_entered() { + with_env(|env, state| { + let object = state.agent.insert(Object::new().into()); + let number = state.agent.insert_primitive(JsValue::from_f64(1.0)); + // A realm of another env, also when this env has a handle to it. + let other = new_env(); + let foreign = new_realm(other, 0).unwrap(); + let foreign = state.agent.insert(value(other, foreign)); + assert_eq!( + unsafe { snapi_bridge_unofficial_release_env(other) }, + NAPI_OK + ); + let own_global = global_id(env); + for id in [object, number, own_global, foreign, u32::MAX - 1] { + assert_eq!(enter(env, id), Err(NAPI_INVALID_ARG)); + } + let realm = new_realm(env, 0).unwrap(); + assert_eq!( + unsafe { snapi_bridge_unofficial_enter_realm(env, realm, ptr::null_mut()) }, + NAPI_INVALID_ARG + ); + // Nothing was entered. + assert_eq!(current_realm(env), 0); + assert_eq!(leave(env, 1), NAPI_INVALID_ARG); + }); + } + + #[wasm_bindgen_test] + fn native_functions_run_in_the_realm_they_were_made_in() { + with_env(|env, state| { + let sandbox = state.agent.insert(Object::new().into()); + let a = new_realm(env, sandbox).unwrap(); + let b = new_realm(env, 0).unwrap(); + let seen = Rc::new(RefCell::new(Vec::new())); + // A callback that records the realm it runs in. + let record = move |seen: &Rc>>| { + let seen = seen.clone(); + move |_: u32| -> u32 { + seen.borrow_mut().push(current_realm(env)); + 0 + } + }; + // A function made inside a callback, with no scope open, belongs to + // the callback's realm. + let made_inside = Rc::new(RefCell::new(None)); + + let scope = enter(env, a).unwrap(); + let in_a = native_function(env, record(&seen)); + let maker = native_function(env, { + let (seen, made_inside) = (seen.clone(), made_inside.clone()); + move |_| { + let function = native_function(env, record(&seen)); + *made_inside.borrow_mut() = Some(value(env, function)); + 0 + } + }); + assert_eq!(leave(env, scope), NAPI_OK); + let in_env = native_function(env, record(&seen)); + + call(env, in_a); + let scope = enter(env, b).unwrap(); + call(env, in_a); + call(env, in_env); + call(env, maker); + assert_eq!(leave(env, scope), NAPI_OK); + let made_inside: Function = made_inside.borrow_mut().take().unwrap().unchecked_into(); + made_inside.call0(&JsValue::UNDEFINED).unwrap(); + assert_eq!(*seen.borrow(), [a, a, 0, a]); + // The callbacks left the realm stack as they found it. + assert_eq!(current_realm(env), 0); + }); + } + + #[wasm_bindgen_test] + fn a_callback_closes_the_scopes_it_leaves_open() { + with_env(|env, _| { + let a = new_realm(env, 0).unwrap(); + let b = new_realm(env, 0).unwrap(); + let outer = enter(env, a).unwrap(); + let statuses = Rc::new(RefCell::new(Vec::new())); + let (left_open, realm_inside) = (Rc::new(Cell::new(0)), Rc::new(Cell::new(0))); + let function = native_function(env, { + let (statuses, left_open, realm_inside) = + (statuses.clone(), left_open.clone(), realm_inside.clone()); + move |_| { + let mut statuses = statuses.borrow_mut(); + // A scope opened outside the callback is not its to close. + statuses.push(leave(env, outer)); + let nested = enter(env, b).unwrap(); + let inner = enter(env, a).unwrap(); + statuses.push(leave(env, nested)); + statuses.push(leave(env, inner)); + realm_inside.set(current_realm(env)); + left_open.set(nested); + 0 + } + }); + call(env, function); + assert_eq!( + *statuses.borrow(), + [NAPI_INVALID_ARG, NAPI_INVALID_ARG, NAPI_OK] + ); + assert_eq!(realm_inside.get(), b); + assert_eq!(current_realm(env), a); + assert_eq!(leave(env, left_open.get()), NAPI_INVALID_ARG); + assert_eq!(leave(env, outer), NAPI_OK); + }); + } + + #[wasm_bindgen_test] + fn deferred_callbacks_run_in_their_realm_when_drained() { + with_env(|env, _| { + let a = new_realm(env, 0).unwrap(); + let b = new_realm(env, 0).unwrap(); + let deferred = Rc::new(Cell::new(false)); + let seen = Rc::new(RefCell::new(Vec::new())); + let scope = enter(env, a).unwrap(); + let function = native_function(env, { + let (deferred, seen) = (deferred.clone(), seen.clone()); + move |_| { + // The first call does not run, as while JSPI holds the + // guest suspended. + if !deferred.replace(true) { + return CALLBACK_DEFERRED; + } + seen.borrow_mut().push(current_realm(env)); + 0 + } + }); + assert_eq!(leave(env, scope), NAPI_OK); + + let outer = enter(env, b).unwrap(); + call(env, function); + assert!(seen.borrow().is_empty()); + assert_eq!(current_realm(env), b); + assert_eq!( + unsafe { snapi_bridge_drain_pending_callbacks(env) }, + NAPI_OK + ); + assert_eq!(*seen.borrow(), [a]); + assert_eq!(current_realm(env), b); + assert_eq!(leave(env, outer), NAPI_OK); + }); + } + + #[wasm_bindgen_test] + fn finalizers_run_in_the_env_realm() { + with_env(|env, state| { + let seen = Rc::new(Cell::new(u32::MAX)); + let finalizer = guest_function({ + let seen = seen.clone(); + move |_| { + seen.set(current_realm(env)); + 0 + } + }); + let target = state.agent.insert(Object::new().into()); + assert!( + state + .agent + .register_guest_finalizer(target, 0, finalizer, 0, 0, None) + ); + let realm = new_realm(env, 0).unwrap(); + let scope = enter(env, realm).unwrap(); + assert_eq!(unsafe { drain_guest_finalizers(env, true) }, NAPI_OK); + assert_eq!(seen.get(), 0); + assert_eq!(current_realm(env), realm); + assert_eq!(leave(env, scope), NAPI_OK); + }); + } + + // The env keeps every callback closure for its whole life, so a realm a + // closure referred to would live as long as the env. Only the function's + // JS wrapper refers to it; tests/host-js checks that the realm is + // collected with the wrapper. (Collection is not observable here: these + // tests cannot await, which the atomics build needs shared memory for.) + #[wasm_bindgen_test] + fn only_the_js_wrapper_of_a_native_function_refers_to_its_realm() { + with_env(|env, _| { + let roots = wasm_bindgen::externref_heap_live_count; + let before = roots(); + native_function(env, |_| 0); + let per_function = roots() - before; + + let ran_in_realm = Rc::new(Cell::new(false)); + for sandboxed in [false, true] { + let state = unsafe { env_mut(env) }.unwrap(); + let frame = state.agent.open_value_frame(); + let sandbox = if sandboxed { + state.agent.insert(Object::new().into()) + } else { + 0 + }; + let realm = new_realm(env, sandbox).unwrap(); + let scope = enter(env, realm).unwrap(); + let before = roots(); + let function = native_function(env, { + let ran_in_realm = ran_in_realm.clone(); + move |_| { + ran_in_realm.set(current_realm(env) != 0); + 0 + } + }); + // The same roots as for a function of the env's own realm. + assert_eq!(roots() - before, per_function); + let function: Function = value(env, function).unchecked_into(); + assert_eq!(leave(env, scope), NAPI_OK); + // With the realm's handles and scope gone, the function still + // runs in it. + assert!( + unsafe { env_mut(env) } + .unwrap() + .agent + .close_value_frame(frame) + ); + ran_in_realm.set(false); + function.call0(&JsValue::UNDEFINED).unwrap(); + assert!(ran_in_realm.get()); + } + }); + } + + #[wasm_bindgen_test] + fn a_callback_that_throws_keeps_no_root_for_its_realm() { + with_env(|env, state| { + let error = state.agent.insert(Error::new("thrown").into()); + let throwing = move |_: u32| -> u32 { + assert_eq!(unsafe { snapi_bridge_throw(env, error) }, NAPI_OK); + 0 + }; + let in_env = native_function(env, throwing); + let realm = new_realm(env, 0).unwrap(); + let scope = enter(env, realm).unwrap(); + let in_realm = native_function(env, throwing); + assert_eq!(leave(env, scope), NAPI_OK); + // The roots a throwing call leaves behind, its exception cleared. + let left_behind = |function: u32| { + let before = wasm_bindgen::externref_heap_live_count(); + let mut out = 0; + assert_eq!( + unsafe { + snapi_bridge_call_function(env, 0, function, 0, ptr::null(), &mut out) + }, + NAPI_PENDING_EXCEPTION + ); + assert_eq!( + unsafe { snapi_bridge_get_and_clear_last_exception(env, &mut out) }, + NAPI_OK + ); + assert_eq!(out, error); + wasm_bindgen::externref_heap_live_count() - before + }; + assert_eq!(left_behind(in_realm), left_behind(in_env)); + assert_eq!(current_realm(env), 0); + }); + } + #[wasm_bindgen_test] fn released_callbacks_do_not_keep_externref_roots_and_remain_callable() { let before = wasm_bindgen::externref_heap_live_count(); diff --git a/tests/host-js/README.md b/tests/host-js/README.md index db64b93e54..e32192273a 100644 --- a/tests/host-js/README.md +++ b/tests/host-js/README.md @@ -13,7 +13,8 @@ context-owned writes, Error constructor/prototype ownership, native error compatibility, causes/subclasses, stack formatting and collection of released contexts and their shared WebAssembly buffers. Retained callback wrappers must become inert on release and allow collection of their contexts and dispatch -captures. The shared-object registry and +captures. A callback wrapper passes the realm it was made in to its dispatch, +and is all that keeps that realm alive. The shared-object registry and module loader are outside this isolated test. Custom `Error.prepareStackTrace` tests detect whether the engine honors the diff --git a/tests/host-js/global-context.test.mjs b/tests/host-js/global-context.test.mjs index 7cab133910..5acbcc340c 100644 --- a/tests/host-js/global-context.test.mjs +++ b/tests/host-js/global-context.test.mjs @@ -353,6 +353,50 @@ test('realms nothing refers to are collected, also while their registry lives', assert.equal(evaluate(realmOf(own,kept),'typeof payload'),'undefined'); }); +// Callbacks made in realms of `own`, each realm referred to only by its +// callback; `dispatch` is the env's. +function realmCallbacks(context,own,dispatch) { + const callbacks=[], references=[]; + for(let i=0;i<12;i++) { + const key=createRealm(own,i%2 ? {i} : null); + const realm=realmOf(own,key); + evaluate(realm,'globalThis.payload=new Array(1024).fill(1)'); + callbacks.push(callback(context,dispatch,realm)); + references.push(new WeakRef(key),new WeakRef(realm),new WeakRef(realm.scope)); + } + return {callbacks,references}; +} + +test('a callback passes its realm to dispatch and alone keeps that realm alive', async () => { + const gc=globalThis.gc ?? (globalThis.Bun ? ()=>Bun.gc(true) : undefined); + const context=create(), own=createRegistry(), seen=[]; + const dispatch=(_receiver,_args,_target,realm)=>{seen.push(realm);}; + callback(context,dispatch)(); + assert.deepEqual(seen,[undefined]); + seen.length=0; + // Only `made` refers to the callbacks: the suspended async frame must not. + const made=realmCallbacks(context,own,dispatch), references=made.references; + for(let i=0;i<4;i++) { await setTimeout(0); gc(); } + assert.equal(references.filter(reference=>reference.deref()).length,references.length); + made.callbacks.forEach(fn=>fn()); + assert.ok(seen.every((realm,i)=>realm===references[3*i+1].deref())); + // The env's dispatch table and the registry do not keep them alive. + seen.length=0; + made.callbacks=undefined; + await assertCollected(references); + runtime.wasmer_napi_release_global_context(context); +}); + +test('a realm\'s global is its sandbox, else its own global', () => { + const own=createRegistry(), sandbox={}; + const sandboxed=realmOf(own,createRealm(own,sandbox)); + const fresh=realmOf(own,createRealm(own,null)); + assert.equal(runtime.wasmer_napi_realm_global(sandboxed),sandbox); + assert.equal(runtime.wasmer_napi_realm_global(fresh),fresh.scope); + assert.equal(realmOf(own,runtime.wasmer_napi_realm_global(fresh)),fresh); + assert.equal(runtime.wasmer_napi_realm_global(host),host.scope); +}); + test('realms are found by their global or sandbox only', () => { const own=createRegistry(); const sandbox={x:1}; From b101c3511d8c2be151c183430286069f6bef470f Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Tue, 27 Oct 2026 11:29:49 -0700 Subject: [PATCH 025/150] Test entering realms test_69 covers, on V8 and QuickJS: values made in an entered realm, the global per realm, nesting and refused leaves, native functions, classes and properties running in their realm, deferreds, scopes a callback leaves open, a pending exception, unknown and collected realms, realms kept alive by their functions, and finalizers. test_realm covers entering a realm through the guest ABI. Co-Authored-By: Claude Opus 5.5 --- tests/CMakeLists.txt | 3 + tests/programs/manifest.json | 4 +- tests/programs/test_realm.c | 44 ++ .../runners/test_69_unofficial_realm_entry.cc | 655 ++++++++++++++++++ 4 files changed, 704 insertions(+), 2 deletions(-) create mode 100644 tests/runners/test_69_unofficial_realm_entry.cc diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt index ba26b80c3a..5a521af36e 100644 --- a/tests/CMakeLists.txt +++ b/tests/CMakeLists.txt @@ -330,6 +330,9 @@ add_fixture_test(${_napi_test_prefix}_test_67_terminate_execution add_fixture_test(${_napi_test_prefix}_test_68_napi_calls_keep_termination runners/test_68_napi_calls_keep_termination.cc ) +add_fixture_test(${_napi_test_prefix}_test_69_unofficial_realm_entry + runners/test_69_unofficial_realm_entry.cc +) if(_napi_test_engine STREQUAL "v8") # Only the V8 provider posts engine tasks through the enqueue hook. add_fixture_test(${_napi_test_prefix}_test_66_foreground_task_handoff diff --git a/tests/programs/manifest.json b/tests/programs/manifest.json index 1597fa785c..6716b6277b 100644 --- a/tests/programs/manifest.json +++ b/tests/programs/manifest.json @@ -182,8 +182,8 @@ }, { "name": "test_realm", - "description": "Realms: own globals, shared values, native functions in the env's realm, get_realm, sandbox realms, scripts, functions, modules and bytecode in a realm, collection of dropped realms, release with live realms", - "expected_stdout": "realm has its own global\nvalues cross realms: x=7\nnative function stays in the env's realm\nget_realm finds the realm by its global\nsandbox realm: input=5 output=10\nvm results: run=4 function=30 module=5 bytecode=6\ncollected 6 of 6 dropped realms\nreleased an env with live realms\nTEST_REALM_OK=1\n" + "description": "Realms: own globals, shared values, native functions in the env's realm, get_realm, sandbox realms, scripts, functions, modules and bytecode in a realm, entering a realm, collection of dropped realms, release with live realms", + "expected_stdout": "realm has its own global\nvalues cross realms: x=7\nnative function stays in the env's realm\nget_realm finds the realm by its global\nsandbox realm: input=5 output=10\nvm results: run=4 function=30 module=5 bytecode=6\nentered realm: its global, objects and functions\ncollected 6 of 6 dropped realms\nreleased an env with live realms\nTEST_REALM_OK=1\n" } ] } diff --git a/tests/programs/test_realm.c b/tests/programs/test_realm.c index cf5aecea76..f27942c3d6 100644 --- a/tests/programs/test_realm.c +++ b/tests/programs/test_realm.c @@ -249,6 +249,50 @@ int main(void) { printf("vm results: run=%d function=%d module=%d bytecode=%d\n", ran, called, exported, from_bytecode); + // While a realm is entered, N-API creates in it and napi_get_global returns + // its global. Scopes nest, NULL enters the env's realm, and only the + // innermost scope can be left, once. + unofficial_napi_realm_scope outer = 0; + unofficial_napi_realm_scope inner = 0; + napi_value current = NULL; + napi_value made = NULL; + NAPI_CALL(env, unofficial_napi_enter_realm(env, realm, &outer)); + CHECK_OR_FAIL(outer != 0, "enter_realm returned no scope"); + NAPI_CALL(env, napi_get_global(env, ¤t)); + CHECK_OR_FAIL(StrictEquals(env, current, realm_global), + "napi_get_global did not return the entered realm's global"); + NAPI_CALL(env, napi_create_object(env, &made)); + NAPI_CALL(env, unofficial_napi_enter_realm(env, NULL, &inner)); + NAPI_CALL(env, napi_get_global(env, ¤t)); + CHECK_OR_FAIL(StrictEquals(env, current, env_global), "NULL did not enter the env's realm"); + CHECK_OR_FAIL(unofficial_napi_leave_realm(env, outer) == napi_invalid_arg, + "an outer scope was left before an inner one"); + NAPI_CALL(env, unofficial_napi_leave_realm(env, inner)); + // A native function made while the realm is entered runs in it. + callback_record realm_record = {realm_global, NULL, false, 0}; + napi_value realm_fn = NULL; + NAPI_CALL(env, napi_create_function(env, "realmProbe", NAPI_AUTO_LENGTH, RecordCallback, + &realm_record, &realm_fn)); + NAPI_CALL(env, unofficial_napi_leave_realm(env, outer)); + CHECK_OR_FAIL(unofficial_napi_leave_realm(env, outer) == napi_invalid_arg, + "a scope was left twice"); + NAPI_CALL(env, napi_get_global(env, ¤t)); + CHECK_OR_FAIL(StrictEquals(env, current, env_global), + "leaving did not make the env's realm current again"); + napi_value made_by_fn = NULL; + NAPI_CALL(env, napi_call_function(env, undefined, realm_fn, 0, NULL, &made_by_fn)); + CHECK_OR_FAIL(realm_record.calls == 1 && realm_record.saw_expected_global, + "a function made in the realm did not run in it"); + NAPI_CALL(env, napi_set_named_property(env, realm_global, "made", made)); + NAPI_CALL(env, napi_set_named_property(env, realm_global, "madeByFn", made_by_fn)); + int32_t own = 0; + NAPI_CALL(env, RunInInt32(env, realm, + "(Object.getPrototypeOf(made) === Object.prototype) +" + " (Object.getPrototypeOf(madeByFn) === Object.prototype)", + &own)); + CHECK_OR_FAIL(own == 2, "an object made in the realm has another realm's prototype"); + printf("entered realm: its global, objects and functions\n"); + // Realms nothing refers to any more are collected. enum { kDropped = 6 }; napi_ref dropped[kDropped]; diff --git a/tests/runners/test_69_unofficial_realm_entry.cc b/tests/runners/test_69_unofficial_realm_entry.cc new file mode 100644 index 0000000000..97cbbcc311 --- /dev/null +++ b/tests/runners/test_69_unofficial_realm_entry.cc @@ -0,0 +1,655 @@ +#ifdef NAPI_MODULE +#undef NAPI_MODULE +#endif +#include "node_api.h" + +#include "test_env.h" + +#include "unofficial_napi.h" + +#include +#include +#include +#include + +// The current realm: what N-API creates while a realm is entered or one of +// its native functions runs, and how long realms entered or used that way +// live. +class Test69UnofficialRealmEntry : public FixtureTestBase {}; + +namespace { + +napi_value Str(napi_env env, const char* value) { + napi_value out = nullptr; + if (napi_create_string_utf8(env, value, NAPI_AUTO_LENGTH, &out) != napi_ok) return nullptr; + return out; +} + +// Runs `source` with napi_run_script, in the current realm. +napi_value Eval(napi_env env, const char* source) { + napi_value result = nullptr; + if (napi_run_script(env, Str(env, source), &result) != napi_ok) return nullptr; + return result; +} + +// Runs `source` in `realm` (the env's own realm when null). +napi_value RunIn(napi_env env, unofficial_napi_realm realm, const char* source) { + const unofficial_napi_js_source script = unofficial_napi_js_source_from_text(Str(env, source)); + napi_value result = nullptr; + if (unofficial_napi_run_script(env, realm, &script, Str(env, "realm.js"), 0, 0, -1, true, false, + false, nullptr, &result) != napi_ok) { + return nullptr; + } + return result; +} + +bool StrictEquals(napi_env env, napi_value a, napi_value b) { + bool same = false; + return a != nullptr && b != nullptr && napi_strict_equals(env, a, b, &same) == napi_ok && same; +} + +napi_value Global(napi_env env) { + napi_value global = nullptr; + if (napi_get_global(env, &global) != napi_ok) return nullptr; + return global; +} + +napi_value Undefined(napi_env env) { + napi_value undefined = nullptr; + if (napi_get_undefined(env, &undefined) != napi_ok) return nullptr; + return undefined; +} + +std::string Utf8(napi_env env, napi_value value) { + char buffer[512] = {}; + size_t length = 0; + if (value == nullptr || + napi_get_value_string_utf8(env, value, buffer, sizeof(buffer), &length) != napi_ok) { + return ""; + } + return std::string(buffer, length); +} + +unofficial_napi_realm CreateRealm(napi_env env, + napi_value* global_out = nullptr, + napi_value sandbox = nullptr) { + unofficial_napi_realm_options options; + unofficial_napi_realm_options_init(&options); + options.sandbox_or_null = sandbox; + unofficial_napi_realm realm = nullptr; + if (unofficial_napi_create_realm(env, &options, &realm, global_out) != napi_ok) return nullptr; + return realm; +} + +unofficial_napi_realm_scope Enter(napi_env env, unofficial_napi_realm realm) { + unofficial_napi_realm_scope scope = 0; + EXPECT_EQ(unofficial_napi_enter_realm(env, realm, &scope), napi_ok); + EXPECT_NE(scope, 0u); + return scope; +} + +void Leave(napi_env env, unofficial_napi_realm_scope scope) { + EXPECT_EQ(unofficial_napi_leave_realm(env, scope), napi_ok); +} + +bool IsCollected(napi_env env, napi_ref ref) { + napi_value value = nullptr; + return napi_get_reference_value(env, ref, &value) == napi_ok && value == nullptr; +} + +napi_value ReturnUndefined(napi_env env, napi_callback_info) { + return Undefined(env); +} + +// Makes one of each kind of value N-API creates, in the current realm: +// [global, object, array, function, error, type error, promise, date, +// array buffer, typed array]. A thrown error is checked on its own, since a +// throw from a callback reaches its caller. +napi_value MakeValues(napi_env env) { + napi_value values[10] = {}; + napi_deferred deferred = nullptr; + napi_value buffer = nullptr; + // Reports the first call that fails. + int step = 0; + auto ok = [&](napi_status status) { + ++step; + if (status == napi_ok) return true; + std::fprintf(stderr, "MakeValues: call %d failed with status %d\n", step, status); + return false; + }; + if (!ok(napi_get_global(env, &values[0])) || !ok(napi_create_object(env, &values[1])) || + !ok(napi_create_array(env, &values[2])) || + !ok(napi_create_function(env, "made", NAPI_AUTO_LENGTH, ReturnUndefined, nullptr, + &values[3])) || + !ok(napi_create_error(env, nullptr, Str(env, "error"), &values[4])) || + !ok(napi_create_type_error(env, nullptr, Str(env, "type error"), &values[5])) || + !ok(napi_create_promise(env, &deferred, &values[6])) || + !ok(napi_resolve_deferred(env, deferred, Undefined(env))) || + !ok(napi_create_date(env, 0, &values[7])) || + !ok(napi_create_arraybuffer(env, 8, nullptr, &buffer)) || + !ok(napi_create_typedarray(env, napi_uint8_array, 8, buffer, 0, &values[9]))) { + return nullptr; + } + values[8] = buffer; + napi_value array = nullptr; + if (napi_create_array_with_length(env, 10, &array) != napi_ok) return nullptr; + for (uint32_t i = 0; i < 10; ++i) { + if (napi_set_element(env, array, i, values[i]) != napi_ok) return nullptr; + } + return array; +} + +napi_value MakeValuesCallback(napi_env env, napi_callback_info) { + return MakeValues(env); +} + +// Lists what in `values` (from MakeValues) does not come from the realm whose +// global is `realm_global`; empty when everything does. Runs in the env's +// realm, so call it with no realm entered. +std::string ValuesNotFrom(napi_env env, napi_value values, napi_value realm_global) { + napi_value global = Global(env); + if (values == nullptr || realm_global == nullptr || + napi_set_named_property(env, global, "__values", values) != napi_ok || + napi_set_named_property(env, global, "__realm", realm_global) != napi_ok) { + return ""; + } + napi_value report = Eval(env, + "(() => {" + " const [g, o, a, f, e, te, p, d, ab, ta] = __values;" + " const R = __realm;" + " const proto = Object.getPrototypeOf;" + " const wrong = [];" + " const check = (name, ok) => { if (!ok) wrong.push(name); };" + " check('global', g === R);" + " check('object', proto(o) === R.Object.prototype);" + " check('array', proto(a) === R.Array.prototype);" + " check('function', proto(f) === R.Function.prototype);" + " check('error', proto(e) === R.Error.prototype);" + " check('type error', proto(te) === R.TypeError.prototype);" + " check('promise', proto(p) === R.Promise.prototype);" + " check('date', proto(d) === R.Date.prototype);" + " check('array buffer', proto(ab) === R.ArrayBuffer.prototype);" + " check('typed array', proto(ta) === R.Uint8Array.prototype);" + " delete globalThis.__values;" + " delete globalThis.__realm;" + " return wrong.join(', ');" + "})()"); + return Utf8(env, report); +} + +} // namespace + +TEST_F(Test69UnofficialRealmEntry, EnteredRealmMakesValuesWithItsIntrinsics) { + EnvScope s(runtime_.get()); + napi_value env_global = Global(s.env); + napi_value realm_global = nullptr; + unofficial_napi_realm realm = CreateRealm(s.env, &realm_global); + ASSERT_NE(realm, nullptr); + + unofficial_napi_realm_scope scope = Enter(s.env, realm); + napi_value in_realm = MakeValues(s.env); + Leave(s.env, scope); + ASSERT_NE(in_realm, nullptr); + EXPECT_EQ(ValuesNotFrom(s.env, in_realm, realm_global), ""); + + // Without a scope, values come from the env's realm again. + napi_value in_env = MakeValues(s.env); + ASSERT_NE(in_env, nullptr); + EXPECT_EQ(ValuesNotFrom(s.env, in_env, env_global), ""); +} + +TEST_F(Test69UnofficialRealmEntry, GetGlobalFollowsTheCurrentRealm) { + EnvScope s(runtime_.get()); + napi_value env_global = Global(s.env); + napi_value realm_global = nullptr; + unofficial_napi_realm realm = CreateRealm(s.env, &realm_global); + ASSERT_NE(realm, nullptr); + napi_value sandbox = nullptr; + ASSERT_EQ(napi_create_object(s.env, &sandbox), napi_ok); + unofficial_napi_realm sandbox_realm = CreateRealm(s.env, nullptr, sandbox); + ASSERT_NE(sandbox_realm, nullptr); + + unofficial_napi_realm_scope scope = Enter(s.env, realm); + EXPECT_TRUE(StrictEquals(s.env, Global(s.env), realm_global)); + // The current realm's global names the realm. + unofficial_napi_realm found = nullptr; + ASSERT_EQ(unofficial_napi_get_realm(s.env, Global(s.env), &found), napi_ok); + EXPECT_TRUE(StrictEquals(s.env, RunIn(s.env, found, "globalThis"), realm_global)); + // napi_run_script runs in the current realm; a NULL realm still means the + // env's own. + EXPECT_TRUE(StrictEquals(s.env, Eval(s.env, "globalThis"), realm_global)); + EXPECT_TRUE(StrictEquals(s.env, RunIn(s.env, nullptr, "globalThis"), env_global)); + + // A sandbox realm's global is its sandbox, as create_realm reported. + unofficial_napi_realm_scope sandbox_scope = Enter(s.env, sandbox_realm); + EXPECT_TRUE(StrictEquals(s.env, Global(s.env), sandbox)); + found = nullptr; + ASSERT_EQ(unofficial_napi_get_realm(s.env, Global(s.env), &found), napi_ok); + EXPECT_NE(found, nullptr); + Leave(s.env, sandbox_scope); + + // NULL enters the env's realm from inside another. + unofficial_napi_realm_scope env_scope = Enter(s.env, nullptr); + EXPECT_TRUE(StrictEquals(s.env, Global(s.env), env_global)); + Leave(s.env, env_scope); + + EXPECT_TRUE(StrictEquals(s.env, Global(s.env), realm_global)); + Leave(s.env, scope); + EXPECT_TRUE(StrictEquals(s.env, Global(s.env), env_global)); +} + +TEST_F(Test69UnofficialRealmEntry, ScopesNestAndCloseInOrder) { + EnvScope s(runtime_.get()); + napi_value env_global = Global(s.env); + napi_value a_global = nullptr, b_global = nullptr; + unofficial_napi_realm a = CreateRealm(s.env, &a_global); + unofficial_napi_realm b = CreateRealm(s.env, &b_global); + ASSERT_NE(a, nullptr); + ASSERT_NE(b, nullptr); + + EXPECT_EQ(unofficial_napi_enter_realm(nullptr, a, nullptr), napi_invalid_arg); + EXPECT_EQ(unofficial_napi_enter_realm(s.env, a, nullptr), napi_invalid_arg); + EXPECT_EQ(unofficial_napi_leave_realm(s.env, 0), napi_invalid_arg); + EXPECT_EQ(unofficial_napi_leave_realm(s.env, 12345), napi_invalid_arg); + + unofficial_napi_realm_scope in_a = Enter(s.env, a); + unofficial_napi_realm_scope in_b = Enter(s.env, b); + unofficial_napi_realm_scope in_env = Enter(s.env, nullptr); + EXPECT_EQ(std::set({in_a, in_b, in_env}).size(), 3u); + EXPECT_TRUE(StrictEquals(s.env, Global(s.env), env_global)); + + // Only the innermost scope can be left; a refused leave changes nothing. + EXPECT_EQ(unofficial_napi_leave_realm(s.env, in_b), napi_invalid_arg); + EXPECT_EQ(unofficial_napi_leave_realm(s.env, in_a), napi_invalid_arg); + EXPECT_TRUE(StrictEquals(s.env, Global(s.env), env_global)); + + Leave(s.env, in_env); + EXPECT_EQ(unofficial_napi_leave_realm(s.env, in_env), napi_invalid_arg); + EXPECT_TRUE(StrictEquals(s.env, Global(s.env), b_global)); + Leave(s.env, in_b); + EXPECT_TRUE(StrictEquals(s.env, Global(s.env), a_global)); + Leave(s.env, in_a); + EXPECT_TRUE(StrictEquals(s.env, Global(s.env), env_global)); + EXPECT_EQ(unofficial_napi_leave_realm(s.env, in_a), napi_invalid_arg); + + // A token is never reused. + unofficial_napi_realm_scope again = Enter(s.env, a); + EXPECT_EQ(std::set({in_a, in_b, in_env, again}).size(), 4u); + Leave(s.env, again); +} + +TEST_F(Test69UnofficialRealmEntry, NativeFunctionRunsInTheRealmThatMadeIt) { + EnvScope s(runtime_.get()); + napi_value a_global = nullptr, b_global = nullptr; + unofficial_napi_realm a = CreateRealm(s.env, &a_global); + unofficial_napi_realm b = CreateRealm(s.env, &b_global); + ASSERT_NE(a, nullptr); + ASSERT_NE(b, nullptr); + + napi_value probe = nullptr; + unofficial_napi_realm_scope scope = Enter(s.env, a); + ASSERT_EQ(napi_create_function(s.env, "probe", NAPI_AUTO_LENGTH, MakeValuesCallback, nullptr, + &probe), + napi_ok); + Leave(s.env, scope); + ASSERT_EQ(napi_set_named_property(s.env, b_global, "probe", probe), napi_ok); + ASSERT_EQ(napi_set_named_property(s.env, a_global, "probe", probe), napi_ok); + + // The function is one of A's. + EXPECT_TRUE(StrictEquals(s.env, RunIn(s.env, a, "Object.getPrototypeOf(probe)"), + RunIn(s.env, a, "Function.prototype"))); + + // Called from B, from A and from the env's realm, it runs in A. + EXPECT_EQ(ValuesNotFrom(s.env, RunIn(s.env, b, "probe()"), a_global), ""); + EXPECT_EQ(ValuesNotFrom(s.env, RunIn(s.env, a, "probe()"), a_global), ""); + napi_value result = nullptr; + ASSERT_EQ(napi_call_function(s.env, Undefined(s.env), probe, 0, nullptr, &result), napi_ok); + EXPECT_EQ(ValuesNotFrom(s.env, result, a_global), ""); + + // Also while B is entered, and B is current again afterwards. + scope = Enter(s.env, b); + result = nullptr; + ASSERT_EQ(napi_call_function(s.env, Undefined(s.env), probe, 0, nullptr, &result), napi_ok); + EXPECT_TRUE(StrictEquals(s.env, Global(s.env), b_global)); + Leave(s.env, scope); + EXPECT_EQ(ValuesNotFrom(s.env, result, a_global), ""); +} + +// EdgeJS never enters a realm: its functions run in the env's realm wherever +// they are called from. +TEST_F(Test69UnofficialRealmEntry, FunctionMadeOutsideAScopeRunsInTheEnvsRealm) { + EnvScope s(runtime_.get()); + napi_value env_global = Global(s.env); + napi_value a_global = nullptr; + unofficial_napi_realm a = CreateRealm(s.env, &a_global); + ASSERT_NE(a, nullptr); + + napi_value probe = nullptr; + ASSERT_EQ(napi_create_function(s.env, "probe", NAPI_AUTO_LENGTH, MakeValuesCallback, nullptr, + &probe), + napi_ok); + ASSERT_EQ(napi_set_named_property(s.env, a_global, "probe", probe), napi_ok); + EXPECT_EQ(ValuesNotFrom(s.env, RunIn(s.env, a, "probe()"), env_global), ""); + + unofficial_napi_realm_scope scope = Enter(s.env, a); + napi_value result = nullptr; + ASSERT_EQ(napi_call_function(s.env, Undefined(s.env), probe, 0, nullptr, &result), napi_ok); + // A function made with the env's realm entered from inside A is the env's. + unofficial_napi_realm_scope env_scope = Enter(s.env, nullptr); + napi_value env_probe = nullptr; + ASSERT_EQ(napi_create_function(s.env, "envProbe", NAPI_AUTO_LENGTH, MakeValuesCallback, nullptr, + &env_probe), + napi_ok); + Leave(s.env, env_scope); + Leave(s.env, scope); + EXPECT_EQ(ValuesNotFrom(s.env, result, env_global), ""); + + ASSERT_EQ(napi_set_named_property(s.env, a_global, "envProbe", env_probe), napi_ok); + EXPECT_EQ(ValuesNotFrom(s.env, RunIn(s.env, a, "envProbe()"), env_global), ""); +} + +namespace { + +napi_value ReturnThis(napi_env env, napi_callback_info info) { + napi_value self = nullptr; + if (napi_get_cb_info(env, info, nullptr, nullptr, &self, nullptr) != napi_ok) return nullptr; + return self; +} + +napi_value GetGlobalCallback(napi_env env, napi_callback_info) { + return Global(env); +} + +} // namespace + +TEST_F(Test69UnofficialRealmEntry, ClassesAndPropertiesBelongToTheirRealm) { + EnvScope s(runtime_.get()); + napi_value a_global = nullptr, b_global = nullptr; + unofficial_napi_realm a = CreateRealm(s.env, &a_global); + unofficial_napi_realm b = CreateRealm(s.env, &b_global); + ASSERT_NE(a, nullptr); + ASSERT_NE(b, nullptr); + + const napi_property_descriptor properties[] = { + {"values", nullptr, MakeValuesCallback, nullptr, nullptr, nullptr, napi_default, nullptr}, + {"global", nullptr, nullptr, GetGlobalCallback, nullptr, nullptr, napi_default, nullptr}, + {"staticValues", nullptr, MakeValuesCallback, nullptr, nullptr, nullptr, napi_static, + nullptr}, + }; + napi_value thing = nullptr; + napi_value object = nullptr; + unofficial_napi_realm_scope scope = Enter(s.env, a); + ASSERT_EQ(napi_define_class(s.env, "Thing", NAPI_AUTO_LENGTH, ReturnThis, nullptr, 3, properties, + &thing), + napi_ok); + ASSERT_EQ(napi_create_object(s.env, &object), napi_ok); + ASSERT_EQ(napi_define_properties(s.env, object, 2, properties), napi_ok); + Leave(s.env, scope); + ASSERT_EQ(napi_set_named_property(s.env, b_global, "Thing", thing), napi_ok); + ASSERT_EQ(napi_set_named_property(s.env, b_global, "object", object), napi_ok); + ASSERT_EQ(napi_set_named_property(s.env, a_global, "Thing", thing), napi_ok); + + EXPECT_EQ(Utf8(s.env, RunIn(s.env, a, + "[Object.getPrototypeOf(Thing) === Function.prototype," + " Object.getPrototypeOf(Thing.prototype) === Object.prototype," + " Object.getPrototypeOf(new Thing()) === Thing.prototype].join()")), + "true,true,true"); + // Constructed, called and read from B, everything runs in A. + EXPECT_TRUE(StrictEquals(s.env, RunIn(s.env, b, "new Thing().global"), a_global)); + EXPECT_EQ(ValuesNotFrom(s.env, RunIn(s.env, b, "new Thing().values()"), a_global), ""); + EXPECT_EQ(ValuesNotFrom(s.env, RunIn(s.env, b, "Thing.staticValues()"), a_global), ""); + EXPECT_TRUE(StrictEquals(s.env, RunIn(s.env, b, "object.global"), a_global)); + EXPECT_EQ(ValuesNotFrom(s.env, RunIn(s.env, b, "object.values()"), a_global), ""); +} + +TEST_F(Test69UnofficialRealmEntry, DeferredBelongsToItsRealm) { + EnvScope s(runtime_.get()); + napi_value a_global = nullptr; + unofficial_napi_realm a = CreateRealm(s.env, &a_global); + ASSERT_NE(a, nullptr); + + napi_deferred deferred = nullptr; + napi_value promise = nullptr; + unofficial_napi_realm_scope scope = Enter(s.env, a); + ASSERT_EQ(napi_create_promise(s.env, &deferred, &promise), napi_ok); + Leave(s.env, scope); + ASSERT_EQ(napi_set_named_property(s.env, a_global, "promise", promise), napi_ok); + EXPECT_EQ(Utf8(s.env, RunIn(s.env, a, + "promise.then((v) => { globalThis.got = v; });" + "String(Object.getPrototypeOf(promise) === Promise.prototype)")), + "true"); + + // Settled later from the env's realm. + napi_value value = nullptr; + ASSERT_EQ(napi_create_int32(s.env, 9, &value), napi_ok); + ASSERT_EQ(napi_resolve_deferred(s.env, deferred, value), napi_ok); + ASSERT_EQ(unofficial_napi_event_loop_checkpoint( + s.env, unofficial_napi_event_loop_checkpoint_microtasks, true, nullptr), + napi_ok); + EXPECT_EQ(Utf8(s.env, RunIn(s.env, a, "String(globalThis.got)")), "9"); +} + +namespace { + +struct LeakyScope { + unofficial_napi_realm realm = nullptr; + unofficial_napi_realm_scope outer = 0; + unofficial_napi_realm_scope leaked = 0; + napi_status leave_outer = napi_ok; +}; + +// Enters a realm and returns without leaving it, after trying to leave a +// scope its caller opened. +napi_value EnterAndReturn(napi_env env, napi_callback_info info) { + void* data = nullptr; + if (napi_get_cb_info(env, info, nullptr, nullptr, nullptr, &data) != napi_ok) return nullptr; + auto* record = static_cast(data); + if (record->outer != 0) record->leave_outer = unofficial_napi_leave_realm(env, record->outer); + if (unofficial_napi_enter_realm(env, record->realm, &record->leaked) != napi_ok) return nullptr; + return Global(env); +} + +} // namespace + +TEST_F(Test69UnofficialRealmEntry, ScopeLeftOpenClosesWhenTheCallbackReturns) { + EnvScope s(runtime_.get()); + napi_value env_global = Global(s.env); + napi_value a_global = nullptr, b_global = nullptr; + unofficial_napi_realm a = CreateRealm(s.env, &a_global); + unofficial_napi_realm b = CreateRealm(s.env, &b_global); + ASSERT_NE(a, nullptr); + ASSERT_NE(b, nullptr); + + LeakyScope record; + record.realm = b; + napi_value leaky = nullptr; + ASSERT_EQ(napi_create_function(s.env, "leaky", NAPI_AUTO_LENGTH, EnterAndReturn, &record, + &leaky), + napi_ok); + + napi_value result = nullptr; + ASSERT_EQ(napi_call_function(s.env, Undefined(s.env), leaky, 0, nullptr, &result), napi_ok); + EXPECT_TRUE(StrictEquals(s.env, result, b_global)); + EXPECT_TRUE(StrictEquals(s.env, Global(s.env), env_global)); + EXPECT_EQ(unofficial_napi_leave_realm(s.env, record.leaked), napi_invalid_arg); + + // A callback cannot leave a scope its caller opened. + record.outer = Enter(s.env, a); + ASSERT_EQ(napi_call_function(s.env, Undefined(s.env), leaky, 0, nullptr, &result), napi_ok); + EXPECT_EQ(record.leave_outer, napi_invalid_arg); + EXPECT_TRUE(StrictEquals(s.env, Global(s.env), a_global)); + Leave(s.env, record.outer); + + // Called from script, too. + record.outer = 0; + ASSERT_EQ(napi_set_named_property(s.env, a_global, "leaky", leaky), napi_ok); + EXPECT_TRUE(StrictEquals(s.env, RunIn(s.env, a, "leaky()"), b_global)); + EXPECT_TRUE(StrictEquals(s.env, Global(s.env), env_global)); +} + +TEST_F(Test69UnofficialRealmEntry, PendingExceptionSurvivesLeavingARealm) { + EnvScope s(runtime_.get()); + napi_value a_global = nullptr; + unofficial_napi_realm a = CreateRealm(s.env, &a_global); + ASSERT_NE(a, nullptr); + + unofficial_napi_realm_scope scope = Enter(s.env, a); + const napi_status thrown = napi_throw_type_error(s.env, nullptr, "boom"); + EXPECT_TRUE(thrown == napi_ok || thrown == napi_pending_exception); + Leave(s.env, scope); + bool pending = false; + ASSERT_EQ(napi_is_exception_pending(s.env, &pending), napi_ok); + EXPECT_TRUE(pending); + napi_value error = nullptr; + ASSERT_EQ(napi_get_and_clear_last_exception(s.env, &error), napi_ok); + ASSERT_EQ(napi_set_named_property(s.env, a_global, "error", error), napi_ok); + EXPECT_EQ(Utf8(s.env, RunIn(s.env, a, + "String(Object.getPrototypeOf(error) === TypeError.prototype &&" + " error.message === 'boom')")), + "true"); +} + +TEST_F(Test69UnofficialRealmEntry, EnteringAnUnknownOrCollectedRealmFails) { + EnvScope s(runtime_.get()); + unofficial_napi_realm_scope scope = 0; + + // Anything but one of this env's realms is refused without being read. + int not_a_realm = 0; + EXPECT_EQ(unofficial_napi_enter_realm( + s.env, reinterpret_cast(¬_a_realm), &scope), + napi_invalid_arg); + EXPECT_EQ(scope, 0u); + + // A handle that outlived its handle scope, once the realm is collected. + unofficial_napi_realm stale = nullptr; + napi_ref weak_global = nullptr; + { + napi_handle_scope handles = nullptr; + ASSERT_EQ(napi_open_handle_scope(s.env, &handles), napi_ok); + napi_value global = nullptr; + stale = CreateRealm(s.env, &global); + ASSERT_NE(stale, nullptr); + ASSERT_EQ(napi_create_reference(s.env, global, 0, &weak_global), napi_ok); + ASSERT_EQ(napi_close_handle_scope(s.env, handles), napi_ok); + } + ASSERT_EQ(unofficial_napi_collect_garbage(s.env), napi_ok); + ASSERT_TRUE(IsCollected(s.env, weak_global)); + EXPECT_EQ(unofficial_napi_enter_realm(s.env, stale, &scope), napi_invalid_arg); + EXPECT_EQ(scope, 0u); + ASSERT_EQ(napi_delete_reference(s.env, weak_global), napi_ok); + + // No JavaScript runs on entering or leaving, so both work while + // terminating. + unofficial_napi_realm live = CreateRealm(s.env); + ASSERT_NE(live, nullptr); + ASSERT_EQ(unofficial_napi_terminate_execution(s.env), napi_ok); + ASSERT_EQ(unofficial_napi_enter_realm(s.env, live, &scope), napi_ok); + EXPECT_EQ(unofficial_napi_leave_realm(s.env, scope), napi_ok); + ASSERT_EQ(unofficial_napi_cancel_terminate_execution(s.env), napi_ok); +} + +TEST_F(Test69UnofficialRealmEntry, RealmLivesWhileItsNativeFunctionIsReachable) { + EnvScope s(runtime_.get()); + + // Many realms, each reachable only through a native function made in it. + constexpr int kRealms = 64; + napi_ref functions[kRealms] = {}; + napi_ref globals[kRealms] = {}; + for (int i = 0; i < kRealms; ++i) { + napi_handle_scope handles = nullptr; + ASSERT_EQ(napi_open_handle_scope(s.env, &handles), napi_ok); + napi_value global = nullptr; + unofficial_napi_realm realm = CreateRealm(s.env, &global); + ASSERT_NE(realm, nullptr); + ASSERT_NE(RunIn(s.env, realm, "globalThis.payload = new Array(4096).fill(1); 1"), nullptr); + unofficial_napi_realm_scope scope = Enter(s.env, realm); + napi_value probe = nullptr; + ASSERT_EQ(napi_create_function(s.env, "probe", NAPI_AUTO_LENGTH, MakeValuesCallback, nullptr, + &probe), + napi_ok); + Leave(s.env, scope); + ASSERT_EQ(napi_create_reference(s.env, probe, 1, &functions[i]), napi_ok); + ASSERT_EQ(napi_create_reference(s.env, global, 0, &globals[i]), napi_ok); + ASSERT_EQ(napi_close_handle_scope(s.env, handles), napi_ok); + } + + // Making more realms releases what collected realms left behind; the + // reachable ones stay. + ASSERT_EQ(unofficial_napi_collect_garbage(s.env), napi_ok); + for (int i = 0; i < 4; ++i) { + napi_handle_scope handles = nullptr; + ASSERT_EQ(napi_open_handle_scope(s.env, &handles), napi_ok); + ASSERT_NE(CreateRealm(s.env), nullptr); + ASSERT_EQ(napi_close_handle_scope(s.env, handles), napi_ok); + } + ASSERT_EQ(unofficial_napi_collect_garbage(s.env), napi_ok); + + for (int i = 0; i < kRealms; ++i) { + napi_handle_scope handles = nullptr; + ASSERT_EQ(napi_open_handle_scope(s.env, &handles), napi_ok); + napi_value global = nullptr, probe = nullptr, result = nullptr; + ASSERT_EQ(napi_get_reference_value(s.env, globals[i], &global), napi_ok); + ASSERT_NE(global, nullptr); + ASSERT_EQ(napi_get_reference_value(s.env, functions[i], &probe), napi_ok); + ASSERT_EQ(napi_call_function(s.env, Undefined(s.env), probe, 0, nullptr, &result), napi_ok); + EXPECT_EQ(ValuesNotFrom(s.env, result, global), ""); + ASSERT_EQ(napi_close_handle_scope(s.env, handles), napi_ok); + } + + // Once its function is unreachable, each realm is collected. + for (napi_ref function : functions) ASSERT_EQ(napi_delete_reference(s.env, function), napi_ok); + ASSERT_EQ(unofficial_napi_collect_garbage(s.env), napi_ok); + for (napi_ref global : globals) { + EXPECT_TRUE(IsCollected(s.env, global)); + ASSERT_EQ(napi_delete_reference(s.env, global), napi_ok); + } +} + +namespace { + +struct FinalizerRecord { + napi_ref env_global = nullptr; + bool ran = false; + bool saw_env_global = false; +}; + +void RecordFinalizerRealm(node_api_basic_env basic_env, void*, void* hint) { + auto env = const_cast(basic_env); + auto* record = static_cast(hint); + record->ran = true; + napi_value env_global = nullptr; + if (napi_get_reference_value(env, record->env_global, &env_global) != napi_ok) return; + record->saw_env_global = StrictEquals(env, Global(env), env_global); +} + +} // namespace + +TEST_F(Test69UnofficialRealmEntry, FinalizersRunInTheEnvsRealm) { + EnvScope s(runtime_.get()); + unofficial_napi_realm a = CreateRealm(s.env); + ASSERT_NE(a, nullptr); + FinalizerRecord record; + ASSERT_EQ(napi_create_reference(s.env, Global(s.env), 1, &record.env_global), napi_ok); + + // The object becomes unreachable, and is collected and finalized, with A + // entered. + unofficial_napi_realm_scope scope = Enter(s.env, a); + { + napi_handle_scope handles = nullptr; + ASSERT_EQ(napi_open_handle_scope(s.env, &handles), napi_ok); + napi_value object = nullptr; + ASSERT_EQ(napi_create_object(s.env, &object), napi_ok); + ASSERT_EQ(napi_add_finalizer(s.env, object, nullptr, RecordFinalizerRealm, &record, nullptr), + napi_ok); + ASSERT_EQ(napi_close_handle_scope(s.env, handles), napi_ok); + } + ASSERT_EQ(unofficial_napi_collect_garbage(s.env), napi_ok); + ASSERT_EQ(unofficial_napi_event_loop_checkpoint( + s.env, unofficial_napi_event_loop_checkpoint_microtasks, true, nullptr), + napi_ok); + Leave(s.env, scope); + + EXPECT_TRUE(record.ran); + EXPECT_TRUE(record.saw_env_global); + ASSERT_EQ(napi_delete_reference(s.env, record.env_global), napi_ok); +} From 80f821956572b834802d540098e886c00af8b949 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Tue, 27 Oct 2026 11:59:36 -0700 Subject: [PATCH 026/150] host-JS: free a throwing callback's values before it throws The callback trampoline ended with wasm_bindgen::throw_val when the guest left an exception pending. throw_val unwinds without running Rust destructors, so the closure's arguments (the arguments array, an undefined new.target) were never dropped and every throwing call kept two externref slots for good. The trampoline now returns Result. wasm-bindgen throws an Err only after the closure has returned and dropped what it owns. throw_val was the file's only call that throws. The tests run Rust closures in place of guest callbacks, as on realm-entry, and count the roots a native function leaves behind when JavaScript calls it: 0 for one that returns, 2 for one that throws before this change, 0 after. Co-Authored-By: Claude Opus 5.5 --- src/snapi_js.rs | 59 +++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 47 insertions(+), 12 deletions(-) diff --git a/src/snapi_js.rs b/src/snapi_js.rs index 177d27c04a..183dcdfa9d 100644 --- a/src/snapi_js.rs +++ b/src/snapi_js.rs @@ -1318,8 +1318,9 @@ struct CallbackReg { } /// A guest callback trampoline: receives `this`, the arguments, `new.target` -/// and the context of the function's realm (undefined for the env's own). -type CallbackFn = dyn Fn(JsValue, Array, JsValue, JsValue) -> JsValue; +/// and the context of the function's realm (undefined for the env's own), and +/// returns the result or the exception to throw. +type CallbackFn = dyn Fn(JsValue, Array, JsValue, JsValue) -> Result; type CallbackClosure = Closure; struct CallbackInfo { @@ -3496,13 +3497,17 @@ pub unsafe extern "C" fn snapi_bridge_create_function( // realm's context and passes it in on every call; the closure must not // capture it, since the env keeps every closure for its whole life. let closure = Closure::wrap(Box::new( - move |this: JsValue, args: Array, new_target: JsValue, realm: JsValue| -> JsValue { + move |this: JsValue, + args: Array, + new_target: JsValue, + realm: JsValue| + -> Result { let env_addr = live_env_addr.get(); if env_addr == 0 { wasmer_napi_console_error(&format!( "[wasmer-napi-callback] released env callback={callback_name}" )); - return JsValue::UNDEFINED; + return Ok(JsValue::UNDEFINED); } let env = env_addr as SnapiEnv; // Do not keep a mutable environment borrow across the guest callback: @@ -3513,7 +3518,7 @@ pub unsafe extern "C" fn snapi_bridge_create_function( wasmer_napi_console_error(&format!( "[wasmer-napi-callback] invalid env callback={callback_name}" )); - return JsValue::UNDEFINED; + return Ok(JsValue::UNDEFINED); }; let value_frame = state.agent.open_value_frame(); let mut ids = Vec::with_capacity(args.length() as usize); @@ -3560,7 +3565,7 @@ pub unsafe extern "C" fn snapi_bridge_create_function( ) }; let Ok(state) = (unsafe { env_mut(env) }) else { - return JsValue::UNDEFINED; + return Ok(JsValue::UNDEFINED); }; if result == CALLBACK_DEFERRED { let realm = state.leave_callback(realm_depth); @@ -3580,9 +3585,8 @@ pub unsafe extern "C" fn snapi_bridge_create_function( resolve: resolve_slot.borrow_mut().take().unwrap(), reject: reject_slot.borrow_mut().take().unwrap(), }); - return promise.into(); + return Ok(promise.into()); } - // Not kept in a local: throw_val below skips Rust destructors. state.leave_callback(realm_depth); let error = state.last_exception.take(); let result_value = state.agent.get(result).cloned(); @@ -3599,10 +3603,10 @@ pub unsafe extern "C" fn snapi_bridge_create_function( let result = result_value.unwrap_or(JsValue::UNDEFINED); state.agent.callback_infos.remove(&cb); state.agent.close_value_frame(value_frame); - if let Some(error) = error { - wasm_bindgen::throw_val(error); - } - result + // wasm-bindgen throws an Err once this closure has returned and + // dropped what it owns. throw_val here would skip those + // destructors and leak the arguments' externref slots. + error.map_or(Ok(result), Err) }, ) as Box); let undefined = JsValue::UNDEFINED; @@ -7216,6 +7220,37 @@ mod tests { unsafe { snapi_bridge_unofficial_leave_realm(env, scope) } } + // throw_val unwinds without running Rust destructors, so a callback must + // not throw while it still owns its arguments or its result. + #[wasm_bindgen_test] + fn a_callback_that_throws_keeps_no_more_roots_than_one_that_returns() { + with_env(|env, state| { + let error = state.agent.insert(Error::new("thrown").into()); + let throwing = native_function(env, move |_| { + assert_eq!(unsafe { snapi_bridge_throw(env, error) }, NAPI_OK); + 0 + }); + let returning = native_function(env, |_| 0); + // JavaScript catches the exception: one caught by a wasm-bindgen + // catch import, as napi_call_function's is, costs a root of its own. + let call = + Function::new_with_args("f", "try { return f(1, {}); } catch (e) { return e; }"); + let error = value(env, error); + // The roots a call leaves behind, and whether it threw `error`. + let left_behind = |function: u32| { + let function = value(env, function); + let before = wasm_bindgen::externref_heap_live_count(); + let result = call.call1(&JsValue::UNDEFINED, &function).unwrap(); + let threw = Object::is(&result, &error); + drop(result); + let after = wasm_bindgen::externref_heap_live_count(); + (i64::from(after) - i64::from(before), threw) + }; + assert_eq!(left_behind(returning), (0, false)); + assert_eq!(left_behind(throwing), (0, true)); + }); + } + #[wasm_bindgen_test] fn get_new_target_reports_the_constructor_or_null() { with_env(|env, state| { From a6da1251f574d2ce4f6990048131616908dfc32a Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 13:27:03 -0800 Subject: [PATCH 027/150] Close realm scopes opened while the env is released The env popped its realm frames once, before running the cleanup hooks and the teardown finalizers, and those then ran with no frame of their own. A scope a cleanup hook or the instance-data finalizer opened and left open was never closed: on V8 its context stayed entered and the embedder's next Context::Exit aborted with "Cannot exit non-entered context", and on QuickJS the scope's anchor leaked past teardown (the Debug leak assert in JS_FreeRuntime fired). Either way a later cleanup hook ran in the leftover realm instead of the env's. V8 now runs each cleanup hook in its own handle scope, context scope and env-realm frame, and routes the instance-data finalizer, the teardown external backing-store finalizers and buffer finalizers through CallFinalizer, which does the same. QuickJS runs each cleanup hook in an env-realm frame, and the instance-data finalizer (at release and when set_instance_data replaces the data) in one too. Both keep a final pop of every frame as a backstop. On QuickJS the instance-data finalizer runs after the runtime is freed, and JS_FreeValue reads ctx->rt even for undefined, so popping a scope of the env's own realm there read freed memory. Such a scope holds no anchor, so it is no longer freed. test_69 covers a cleanup hook that leaves a scope open (a later hook checks napi_get_global is the env's global), an instance-data finalizer that leaves scopes open at release, and replaced instance data finalized in the env's realm. They pass on V8, QuickJS and a QuickJS Debug+ASan build. Co-Authored-By: Claude Opus 5.5 --- quickjs/src/internal/napi_env.cc | 34 ++++- quickjs/src/internal/napi_env.h | 1 + .../runners/test_69_unofficial_realm_entry.cc | 120 ++++++++++++++++++ v8/src/js_native_api_v8.cc | 27 ++-- 4 files changed, 167 insertions(+), 15 deletions(-) diff --git a/quickjs/src/internal/napi_env.cc b/quickjs/src/internal/napi_env.cc index 25f77f8e0b..c1b01f4d58 100644 --- a/quickjs/src/internal/napi_env.cc +++ b/quickjs/src/internal/napi_env.cc @@ -122,7 +122,8 @@ void napi_env__::prepare_teardown() closing_ = true; NAPI_QUICKJS_LIFETIME_DUMP(this, "napi_env__ teardown begin"); - // Every scope closes; cleanup hooks and finalizers run in the env's realm. + // Every scope closes. Cleanup hooks and finalizers each run in the env's + // realm, and a scope one leaves open closes when it returns. pop_realm_frames(0); while (!env_cleanup_hooks_.empty()) { @@ -130,7 +131,10 @@ void napi_env__::prepare_teardown() env_cleanup_hooks_.pop_back(); if (entry != nullptr) { - entry->run(); + { + napi_realm_frame_scope__ realm_frame{this, nullptr, JS_UNDEFINED}; + entry->run(); + } napi_env_cleanup_hook__::destroy(entry); } } @@ -151,6 +155,9 @@ void napi_env__::prepare_teardown() agent_->close_scopes(); agent_->clear_module_hooks(); } + // Backstop: nothing above should leave a scope open, and a scope's anchor + // must be freed while the runtime lives. + pop_realm_frames(0); module_wrap_.teardown(); contextify_.teardown(); buffers_.teardown(); @@ -186,8 +193,20 @@ void napi_env__::finalize_instance_data() instance_data_finalize_cb_ = nullptr; instance_data_finalize_hint_ = nullptr; - if (data != nullptr && finalize_cb != nullptr) - finalize_cb(this, data, finalize_hint); + call_instance_data_finalizer(data, finalize_cb, finalize_hint); +} + +void napi_env__::call_instance_data_finalizer(void *data, + napi_finalize finalize_cb, + void *finalize_hint) +{ + if (data == nullptr || finalize_cb == nullptr) + return; + // In the env's realm, as any finalizer. At release this runs after the + // runtime is freed; the realms are gone by then, so no scope it opens holds + // an anchor and popping the frame touches nothing. + napi_realm_frame_scope__ realm_frame{this, nullptr, JS_UNDEFINED}; + finalize_cb(this, data, finalize_hint); } bool napi_env__::is_closing() const @@ -252,7 +271,9 @@ void napi_env__::pop_realm_frames(size_t depth) { napi_realm_frame__ frame = realm_frames_.back(); realm_frames_.pop_back(); - if (frame.scope != 0) + // A scope of the env's own realm holds no anchor, and may close after + // the runtime is freed (in the instance-data finalizer). + if (frame.scope != 0 && JS_VALUE_HAS_REF_COUNT(frame.anchor)) JS_FreeValue(context_, frame.anchor); } } @@ -505,8 +526,7 @@ void napi_env__::set_instance_data(void *data, napi_finalize finalize_cb, void * instance_data_finalize_cb_ = nullptr; instance_data_finalize_hint_ = nullptr; - if (old_data != nullptr && old_finalize_cb != nullptr) - old_finalize_cb(this, old_data, old_finalize_hint); + call_instance_data_finalizer(old_data, old_finalize_cb, old_finalize_hint); instance_data_ = data; instance_data_finalize_cb_ = finalize_cb; diff --git a/quickjs/src/internal/napi_env.h b/quickjs/src/internal/napi_env.h index 93a17aaa67..5f1fbd7da0 100644 --- a/quickjs/src/internal/napi_env.h +++ b/quickjs/src/internal/napi_env.h @@ -165,6 +165,7 @@ struct napi_env__ private: void clear_refs_for_teardown(); + void call_instance_data_finalizer(void *data, napi_finalize finalize_cb, void *finalize_hint); // Set only when this env owns its agent; destroyed last. std::unique_ptr owned_agent_; diff --git a/tests/runners/test_69_unofficial_realm_entry.cc b/tests/runners/test_69_unofficial_realm_entry.cc index 97cbbcc311..83dd2a9306 100644 --- a/tests/runners/test_69_unofficial_realm_entry.cc +++ b/tests/runners/test_69_unofficial_realm_entry.cc @@ -653,3 +653,123 @@ TEST_F(Test69UnofficialRealmEntry, FinalizersRunInTheEnvsRealm) { EXPECT_TRUE(record.saw_env_global); ASSERT_EQ(napi_delete_reference(s.env, record.env_global), napi_ok); } + +// Scopes opened while the env is released. + +namespace { + +// Releases the env before the test ends. +void Release(EnvScope& s) { + ASSERT_EQ(unofficial_napi_release_env(s.scope, nullptr), napi_ok); + s.scope = nullptr; + s.env = nullptr; +} + +struct ReleaseRecord { + napi_env env = nullptr; + napi_ref env_global = nullptr; + napi_ref realm_global = nullptr; + unofficial_napi_realm realm = nullptr; + napi_status enter_status = napi_generic_failure; + napi_status enter_env_realm_status = napi_generic_failure; + bool checked = false; + bool saw_env_global = false; +}; + +// A cleanup hook that enters a realm, makes an object there and returns +// without leaving it. +void EnterRealmFromCleanupHook(void* arg) { + auto* record = static_cast(arg); + napi_value global = nullptr; + unofficial_napi_realm realm = nullptr; + if (napi_get_reference_value(record->env, record->realm_global, &global) != napi_ok || + unofficial_napi_get_realm(record->env, global, &realm) != napi_ok) { + return; + } + unofficial_napi_realm_scope scope = 0; + record->enter_status = unofficial_napi_enter_realm(record->env, realm, &scope); + napi_value object = nullptr; + (void)napi_create_object(record->env, &object); +} + +// A cleanup hook that records whether it acts in the env's realm. +void CheckEnvRealmFromCleanupHook(void* arg) { + auto* record = static_cast(arg); + record->checked = true; + napi_value env_global = nullptr; + if (napi_get_reference_value(record->env, record->env_global, &env_global) == napi_ok) { + record->saw_env_global = StrictEquals(record->env, Global(record->env), env_global); + } + (void)napi_delete_reference(record->env, record->env_global); + (void)napi_delete_reference(record->env, record->realm_global); +} + +// An instance-data finalizer that enters a realm, then the env's own, and +// returns without leaving either. +void EnterRealmFromInstanceDataFinalizer(napi_env env, void* data, void*) { + auto* record = static_cast(data); + record->checked = true; + unofficial_napi_realm_scope scope = 0; + record->enter_status = unofficial_napi_enter_realm(env, record->realm, &scope); + unofficial_napi_realm_scope env_scope = 0; + record->enter_env_realm_status = unofficial_napi_enter_realm(env, nullptr, &env_scope); +} + +} // namespace + +TEST_F(Test69UnofficialRealmEntry, ScopeACleanupHookLeavesOpenClosesWhenItReturns) { + EnvScope s(runtime_.get()); + napi_value realm_global = nullptr; + ASSERT_NE(CreateRealm(s.env, &realm_global), nullptr); + ReleaseRecord record; + record.env = s.env; + ASSERT_EQ(napi_create_reference(s.env, Global(s.env), 1, &record.env_global), napi_ok); + ASSERT_EQ(napi_create_reference(s.env, realm_global, 1, &record.realm_global), napi_ok); + // Hooks run in reverse order of registration: the one that enters runs + // first. + ASSERT_EQ(napi_add_env_cleanup_hook(s.env, CheckEnvRealmFromCleanupHook, &record), napi_ok); + ASSERT_EQ(napi_add_env_cleanup_hook(s.env, EnterRealmFromCleanupHook, &record), napi_ok); + + Release(s); + EXPECT_EQ(record.enter_status, napi_ok); + EXPECT_TRUE(record.checked); + EXPECT_TRUE(record.saw_env_global); +} + +TEST_F(Test69UnofficialRealmEntry, ScopeTheInstanceDataFinalizerLeavesOpenCloses) { + EnvScope s(runtime_.get()); + napi_value realm_global = nullptr; + ReleaseRecord record; + record.realm = CreateRealm(s.env, &realm_global); + ASSERT_NE(record.realm, nullptr); + // The env's global keeps the realm alive until the env is released. + ASSERT_EQ(napi_set_named_property(s.env, Global(s.env), "realm", realm_global), napi_ok); + ASSERT_EQ(napi_set_instance_data(s.env, &record, EnterRealmFromInstanceDataFinalizer, nullptr), + napi_ok); + + Release(s); + EXPECT_TRUE(record.checked); + // The finalizer runs last, and a provider may have let go of its realms by + // then. + EXPECT_TRUE(record.enter_status == napi_ok || record.enter_status == napi_invalid_arg) + << record.enter_status; + EXPECT_EQ(record.enter_env_realm_status, napi_ok); +} + +TEST_F(Test69UnofficialRealmEntry, ReplacedInstanceDataIsFinalizedInTheEnvsRealm) { + EnvScope s(runtime_.get()); + napi_value env_global = Global(s.env); + ReleaseRecord record; + record.realm = CreateRealm(s.env); + ASSERT_NE(record.realm, nullptr); + ASSERT_EQ(napi_set_instance_data(s.env, &record, EnterRealmFromInstanceDataFinalizer, nullptr), + napi_ok); + ASSERT_EQ(napi_set_instance_data(s.env, nullptr, nullptr, nullptr), napi_ok); + // A provider that finalizes replaced data does it in the env's realm, and + // closes the scope the finalizer left open. + if (record.checked) { + EXPECT_EQ(record.enter_status, napi_ok); + EXPECT_EQ(record.enter_env_realm_status, napi_ok); + } + EXPECT_TRUE(StrictEquals(s.env, Global(s.env), env_global)); +} diff --git a/v8/src/js_native_api_v8.cc b/v8/src/js_native_api_v8.cc index 75eeb4fd82..778f343f64 100644 --- a/v8/src/js_native_api_v8.cc +++ b/v8/src/js_native_api_v8.cc @@ -156,7 +156,14 @@ void RunEnvCleanupHooks(napi_env env) { continue; } - snapshot.hook(snapshot.arg); + { + // Each hook runs in the env's realm, and a scope it leaves open + // closes when it returns. + v8::HandleScope handle_scope(env->isolate); + v8::Context::Scope context_scope(env->main_context()); + napi_realm_frame_scope__ realm_frame(env, nullptr); + snapshot.hook(snapshot.arg); + } it = find_hook(env->env_cleanup_hooks, snapshot); if (it != env->env_cleanup_hooks.end()) { @@ -182,7 +189,10 @@ napi_buffer_record* TakeBufferRecord(napi_env env, napi_buffer_record* record) { void FinalizeBufferRecord(napi_buffer_record* record) { if (record == nullptr || record->finalized) return; record->finalized = true; - if (record->finalize_cb != nullptr) { + if (record->finalize_cb == nullptr) return; + if (CheckEnv(record->env)) { + record->env->CallFinalizer(record->finalize_cb, record->external_data, record->finalize_hint); + } else { record->finalize_cb(record->env, record->external_data, record->finalize_hint); } } @@ -286,7 +296,7 @@ void FinalizeExternalBackingStoreHints(napi_env env) { } for (auto& [finalize_cb, external_data, finalize_hint] : pending) { - finalize_cb(env, external_data, finalize_hint); + env->CallFinalizer(finalize_cb, external_data, finalize_hint); } } @@ -652,7 +662,8 @@ napi_env__::napi_env__(v8::Local context, int32_t module_api_versio napi_env__::~napi_env__() { NAPI_V8_LIFETIME_DUMP(this, "napi_env__ teardown begin"); - // Every scope closes; cleanup hooks and finalizers run in the env's realm. + // Every scope closes. Cleanup hooks and finalizers each run in the env's + // realm, and a scope one leaves open closes when it returns. PopRealmFrames(0); RunEnvCleanupHooks(this); napi_ref_tracker__::FinalizeAll(&finalizing_reflist); @@ -662,10 +673,10 @@ napi_env__::~napi_env__() { finalization_scheduled = false; FinalizeExternalBackingStoreHints(this); napi_v8_finalize_buffer_records(this); - - if (instance_data_finalize_cb != nullptr) { - instance_data_finalize_cb(this, instance_data, instance_data_finalize_hint); - } + CallFinalizer(instance_data_finalize_cb, instance_data, instance_data_finalize_hint); + // Backstop: nothing above should leave a scope open, and a context still + // entered here would abort V8 at the embedder's next Context::Exit. + PopRealmFrames(0); if (agent != nullptr && agent->principal_env == this) { agent->principal_env = nullptr; } From d76db7b905f4b5982add87550f3f20c27ee83609 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 13:34:19 -0800 Subject: [PATCH 028/150] Make errors and DataViews from the current realm's intrinsics Since N-API can act in page realms, a realm's global is page-controlled, but three calls still looked constructors up on it by name. QuickJS made plain errors (napi_create_error, napi_throw_error and the module loader's errors) by calling globalThis.Error of the current realm, and never checked the result. A page with its own Error ran during the call and chose the object; with Error = 1 the JS_EXCEPTION sentinel was returned with napi_ok, or stored as the thrown value, so the page could not catch the throw. Plain errors now use JS_NewPlainError, like the typed errors, through create_error_object, which keeps messages longer than QuickJS's 256-byte format buffer in full. napi_create_error goes through the same create_error_common as the typed errors. A failed creation now returns napi_pending_exception with the real exception instead of wrapping or throwing the sentinel, in every napi_throw_* too. Both providers made DataViews with globalThis.DataView. V8 now uses v8::DataView::New (the ArrayBuffer or the SharedArrayBuffer overload) in the current realm. QuickJS has no public DataView constructor: the env reads its realm's DataView when it is made, before any script runs, and a view made for another realm then takes that realm's own DataView.prototype (JS_GetClassProto), so neither reads a realm's global. Both first check byte_offset + length against the buffer as Node does and throw a RangeError with code ERR_NAPI_INVALID_DATAVIEW_ARGS. test_69 replaces Error and DataView in a realm, and in the env's realm, with counting getters, and checks on both engines that what N-API makes there has the original prototypes, that a 300-byte message is kept, that the range check throws the realm's RangeError, that a realm function's napi_throw_error is caught by the page as its original Error, and that no page code ran. Co-Authored-By: Claude Opus 5.5 --- quickjs/src/internal/napi_env.cc | 19 +++ quickjs/src/internal/napi_env.h | 4 + quickjs/src/internal/napi_util.cc | 42 ++----- quickjs/src/internal/napi_util.h | 6 +- quickjs/src/js_native_api_quickjs.cc | 76 ++++++++---- .../runners/test_69_unofficial_realm_entry.cc | 114 ++++++++++++++++++ v8/src/js_native_api_v8.cc | 40 +++--- 7 files changed, 214 insertions(+), 87 deletions(-) diff --git a/quickjs/src/internal/napi_env.cc b/quickjs/src/internal/napi_env.cc index c1b01f4d58..44b8c1e6ea 100644 --- a/quickjs/src/internal/napi_env.cc +++ b/quickjs/src/internal/napi_env.cc @@ -104,7 +104,18 @@ napi_env__::napi_env__(napi_agent__ *agent, JSContext *context, int32_t module_a if (agent_->principal_env() == nullptr) agent_->set_principal_env(this); if (context_ != nullptr) + { agent_->open_root_scope(this); + JSValue global = JS_GetGlobalObject(context_); + JSValue data_view = JS_GetPropertyStr(context_, global, "DataView"); + JS_FreeValue(context_, global); + if (JS_IsConstructor(context_, data_view)) + data_view_constructor_ = data_view; + else if (JS_IsException(data_view)) + JS_FreeValue(context_, JS_GetException(context_)); + else + JS_FreeValue(context_, data_view); + } clear_last_error(); runtime_interrupts_ = attach_runtime_interrupts(JS_GetRuntime(context), this); } @@ -161,6 +172,9 @@ void napi_env__::prepare_teardown() module_wrap_.teardown(); contextify_.teardown(); buffers_.teardown(); + if (context_ != nullptr) + JS_FreeValue(context_, data_view_constructor_); + data_view_constructor_ = JS_UNDEFINED; if (principal) agent_->clear_promise_hooks(); promises_.teardown(); @@ -239,6 +253,11 @@ JSContext *napi_env__::main_context() const return context_; } +JSValueConst napi_env__::data_view_constructor() const +{ + return data_view_constructor_; +} + JSValueConst napi_env__::current_realm_anchor() const { return realm_frames_.empty() ? JS_UNDEFINED : realm_frames_.back().anchor; diff --git a/quickjs/src/internal/napi_env.h b/quickjs/src/internal/napi_env.h index 5f1fbd7da0..2f81f85d62 100644 --- a/quickjs/src/internal/napi_env.h +++ b/quickjs/src/internal/napi_env.h @@ -65,6 +65,9 @@ struct napi_env__ JSContext *context() const; // The env's own realm. JSContext *main_context() const; + // The env realm's DataView constructor, read when the env was made, before + // any script could replace it; undefined if there was none. + JSValueConst data_view_constructor() const; // A function of the current realm that keeps it alive; undefined for the // env's own realm. JSValueConst current_realm_anchor() const; @@ -174,6 +177,7 @@ struct napi_env__ napi_agent__ *agent_; JSContext *context_; int32_t module_api_version_ = 8; + JSValue data_view_constructor_ = JS_UNDEFINED; // The realms N-API acts in, innermost last. Empty means the env's own. std::vector realm_frames_; diff --git a/quickjs/src/internal/napi_util.cc b/quickjs/src/internal/napi_util.cc index c5e08f6a85..05aee1c17f 100644 --- a/quickjs/src/internal/napi_util.cc +++ b/quickjs/src/internal/napi_util.cc @@ -751,41 +751,8 @@ napi_status napi_util__::get_property_names(napi_env env, JSValue napi_util__::create_plain_error(JSContext *ctx, const char *msg) { - JSValue global = JS_GetGlobalObject(ctx); - JSValue error_ctor = JS_GetPropertyStr(ctx, global, "Error"); - JSValue msg_str = JS_NewString(ctx, msg ? msg : ""); - JSValue error = JS_CallConstructor(ctx, error_ctor, 1, &msg_str); - JS_FreeValue(ctx, msg_str); - JS_FreeValue(ctx, error_ctor); - JS_FreeValue(ctx, global); - return error; -} - -napi_status napi_util__::create_plain_error_common(napi_env env, - napi_value code, - napi_value msg, - napi_value *result) -{ - if (!check_env(env) || msg == nullptr || result == nullptr) - return napi_invalid_arg; - - JSValue msg_val = napi_quickjs_value_inner(env, msg); - if (!JS_IsString(msg_val)) - return napi_string_expected; - - const char *msg_str = JS_ToCString(env->context(), msg_val); - JSValue error = create_plain_error(env->context(), msg_str); - JS_FreeCString(env->context(), msg_str); - - if (code != nullptr && !JS_IsUndefined(napi_quickjs_value_inner(env, code)) && !JS_IsNull(napi_quickjs_value_inner(env, code))) - { - const char *code_str = JS_ToCString(env->context(), napi_quickjs_value_inner(env, code)); - JS_SetPropertyStr(env->context(), error, "code", JS_NewString(env->context(), code_str)); - JS_FreeCString(env->context(), code_str); - } - - *result = env->wrap_value_in_current_scope(error, true); - return (*result == nullptr) ? napi_generic_failure : napi_ok; + // The realm's own Error, not whatever its global now calls Error. + return create_error_object(ctx, JS_NewPlainError, nullptr, msg); } JSValue napi_util__::create_error_object(JSContext *ctx, @@ -794,6 +761,9 @@ JSValue napi_util__::create_error_object(JSContext *ctx, const char *msg) { JSValue error = factory(ctx, "%s", msg ? msg : ""); + if (JS_IsException(error)) + return error; + // The factory cuts the formatted message at 256 bytes; keep all of it. JS_SetPropertyStr(ctx, error, "message", JS_NewString(ctx, msg ? msg : "")); if (code != nullptr) JS_SetPropertyStr(ctx, error, "code", JS_NewString(ctx, code)); @@ -823,6 +793,8 @@ napi_status napi_util__::create_error_common(napi_env env, JS_FreeCString(env->context(), msg_str); if (code_str != nullptr) JS_FreeCString(env->context(), code_str); + if (JS_IsException(error)) + return return_pending_if_caught(env, "Failed to create error"); *result = env->wrap_value_in_current_scope(error, true); return (*result == nullptr) ? napi_generic_failure : napi_ok; diff --git a/quickjs/src/internal/napi_util.h b/quickjs/src/internal/napi_util.h index 80d2955ee9..527a9ac130 100644 --- a/quickjs/src/internal/napi_util.h +++ b/quickjs/src/internal/napi_util.h @@ -76,11 +76,9 @@ class napi_util__ napi_key_conversion key_conversion, napi_value *result); + // Errors from the realm's intrinsics. On failure the error is JS_EXCEPTION + // and the exception is pending. static JSValue create_plain_error(JSContext *ctx, const char *msg); - static napi_status create_plain_error_common(napi_env env, - napi_value code, - napi_value msg, - napi_value *result); static JSValue create_error_object(JSContext *ctx, JSValue (*factory)(JSContext *, const char *, ...), const char *code, diff --git a/quickjs/src/js_native_api_quickjs.cc b/quickjs/src/js_native_api_quickjs.cc index 3c67425f66..05a5fbd081 100644 --- a/quickjs/src/js_native_api_quickjs.cc +++ b/quickjs/src/js_native_api_quickjs.cc @@ -1373,27 +1373,46 @@ extern "C" if (!napi_util__::check_value(env, arraybuffer) || result == nullptr) return napi_util__::invalid_arg(env); + JSContext *ctx = env->context(); + JSValueConst buffer = napi_quickjs_value_inner(env, arraybuffer); size_t ab_len = 0; - uint8_t *ab_data = JS_GetArrayBuffer(env->context(), &ab_len, napi_quickjs_value_inner(env, arraybuffer)); - if (ab_data == nullptr && ab_len == 0 && JS_HasException(env->context())) + uint8_t *ab_data = JS_GetArrayBuffer(ctx, &ab_len, buffer); + if (ab_data == nullptr && ab_len == 0 && JS_HasException(ctx)) return napi_util__::return_pending_if_caught(env, "ArrayBuffer expected"); + if (byte_offset > ab_len || length > ab_len - byte_offset) + { + napi_throw_range_error(env, "ERR_NAPI_INVALID_DATAVIEW_ARGS", + "byte_offset + byte_length should be less than or equal to the size in " + "bytes of the array passed in"); + return napi_quickjs_set_last_error(env, napi_pending_exception, "Invalid DataView range"); + } - JSValue global = JS_GetGlobalObject(env->context()); - JSValue ctor = JS_GetPropertyStr(env->context(), global, "DataView"); - JS_FreeValue(env->context(), global); - if (JS_IsException(ctor)) - return napi_util__::return_pending_if_caught(env, "Failed to get DataView constructor"); - + // The env realm's DataView, read before any script ran, makes the view; + // a view for another realm then takes that realm's own DataView.prototype. + // Neither step reads the realm's global, which its scripts control. + JSValueConst ctor = env->data_view_constructor(); + if (!JS_IsConstructor(ctx, ctor)) + return napi_quickjs_set_last_error(env, napi_generic_failure, "No DataView constructor"); JSValue args[] = { - napi_quickjs_value_inner(env, arraybuffer), - JS_NewInt64(env->context(), static_cast(byte_offset)), - JS_NewInt64(env->context(), static_cast(length))}; - JSValue view = JS_CallConstructor(env->context(), ctor, 3, args); - JS_FreeValue(env->context(), args[1]); - JS_FreeValue(env->context(), args[2]); - JS_FreeValue(env->context(), ctor); + JS_DupValue(ctx, buffer), + JS_NewInt64(ctx, static_cast(byte_offset)), + JS_NewInt64(ctx, static_cast(length))}; + JSValue view = JS_CallConstructor(ctx, ctor, 3, args); + for (JSValue arg : args) + JS_FreeValue(ctx, arg); if (JS_IsException(view)) return napi_util__::return_pending_if_caught(env, "DataView construction threw"); + if (ctx != env->main_context()) + { + JSValue proto = JS_GetClassProto(ctx, JS_GetClassID(view)); + const int set = JS_SetPrototype(ctx, view, proto); + JS_FreeValue(ctx, proto); + if (set < 0) + { + JS_FreeValue(ctx, view); + return napi_util__::return_pending_if_caught(env, "Failed to create DataView"); + } + } *result = env->wrap_value_in_current_scope(view, true); return (*result == nullptr) ? napi_generic_failure : napi_quickjs_clear_last_error(env); @@ -3033,13 +3052,9 @@ extern "C" return napi_invalid_arg; } - JSValue error = napi_util__::create_plain_error(env->context(), msg); - if (code != nullptr) - { - JS_SetPropertyStr(env->context(), error, "code", - JS_NewString(env->context(), code)); - } - + JSValue error = napi_util__::create_error_object(env->context(), JS_NewPlainError, code, msg); + if (JS_IsException(error)) + return napi_util__::return_pending_if_caught(env, "Failed to create error"); napi_util__::set_last_exception(env, error); return napi_ok; @@ -3074,7 +3089,10 @@ extern "C" NAPI_QUICKJS_RETURN_IF_TERMINATING(env); if (!napi_util__::check_env(env)) return napi_invalid_arg; - napi_util__::set_last_exception(env, napi_util__::create_error_object(env->context(), JS_NewTypeError, code, msg)); + JSValue error = napi_util__::create_error_object(env->context(), JS_NewTypeError, code, msg); + if (JS_IsException(error)) + return napi_util__::return_pending_if_caught(env, "Failed to create error"); + napi_util__::set_last_exception(env, error); return napi_pending_exception; } @@ -3083,7 +3101,10 @@ extern "C" NAPI_QUICKJS_RETURN_IF_TERMINATING(env); if (!napi_util__::check_env(env)) return napi_invalid_arg; - napi_util__::set_last_exception(env, napi_util__::create_error_object(env->context(), JS_NewRangeError, code, msg)); + JSValue error = napi_util__::create_error_object(env->context(), JS_NewRangeError, code, msg); + if (JS_IsException(error)) + return napi_util__::return_pending_if_caught(env, "Failed to create error"); + napi_util__::set_last_exception(env, error); return napi_pending_exception; } @@ -3092,7 +3113,10 @@ extern "C" NAPI_QUICKJS_RETURN_IF_TERMINATING(env); if (!napi_util__::check_env(env)) return napi_invalid_arg; - napi_util__::set_last_exception(env, napi_util__::create_error_object(env->context(), JS_NewSyntaxError, code, msg)); + JSValue error = napi_util__::create_error_object(env->context(), JS_NewSyntaxError, code, msg); + if (JS_IsException(error)) + return napi_util__::return_pending_if_caught(env, "Failed to create error"); + napi_util__::set_last_exception(env, error); return napi_pending_exception; } @@ -3107,7 +3131,7 @@ extern "C" napi_status NAPI_CDECL napi_create_error(napi_env env, napi_value code, napi_value msg, napi_value *result) { - return napi_util__::create_plain_error_common(env, code, msg, result); + return napi_util__::create_error_common(env, JS_NewPlainError, code, msg, result); } napi_status NAPI_CDECL napi_create_type_error(napi_env env, napi_value code, napi_value msg, napi_value *result) diff --git a/tests/runners/test_69_unofficial_realm_entry.cc b/tests/runners/test_69_unofficial_realm_entry.cc index 83dd2a9306..c7acf759c6 100644 --- a/tests/runners/test_69_unofficial_realm_entry.cc +++ b/tests/runners/test_69_unofficial_realm_entry.cc @@ -773,3 +773,117 @@ TEST_F(Test69UnofficialRealmEntry, ReplacedInstanceDataIsFinalizedInTheEnvsRealm } EXPECT_TRUE(StrictEquals(s.env, Global(s.env), env_global)); } +// Intrinsics in an entered realm: what N-API makes there comes from the +// realm's own intrinsics, never from whatever its global now holds, which its +// scripts control. + +namespace { + +// Saves the realm's Error, RangeError and DataView, then hides Error and +// DataView behind getters that count every read: Error reads as 1, and +// DataView as a fake constructor that counts its calls too. +constexpr char kReplaceErrorAndDataView[] = + "globalThis.saved = { Error, RangeError, DataView };" + "globalThis.pageCalls = 0;" + "Object.defineProperty(globalThis, 'Error', {" + " configurable: true, get() { pageCalls++; return 1; } });" + "Object.defineProperty(globalThis, 'DataView', {" + " configurable: true," + " get() { pageCalls++; return function DataView() { pageCalls++; return {}; }; } });" + "0"; + +// In `realm` (the env's own when null): makes an error, one with a message +// longer than 256 bytes, a DataView and an out-of-range DataView, and reports +// how they relate to the intrinsics the realm saved. +std::string MadeFromSavedIntrinsics(napi_env env, unofficial_napi_realm realm) { + const std::string long_message(300, 'm'); + napi_value made[4] = {}; + napi_value buffer = nullptr; + napi_status range_status = napi_ok; + bool pending = false; + unofficial_napi_realm_scope scope = Enter(env, realm); + const bool ok = + napi_create_error(env, nullptr, Str(env, "made"), &made[0]) == napi_ok && + napi_create_error(env, nullptr, Str(env, long_message.c_str()), &made[1]) == napi_ok && + napi_create_arraybuffer(env, 8, nullptr, &buffer) == napi_ok && + napi_create_dataview(env, 4, buffer, 2, &made[2]) == napi_ok && + napi_is_exception_pending(env, &pending) == napi_ok && !pending && + (range_status = napi_create_dataview(env, 200, buffer, 10, &made[3])) == + napi_pending_exception && + napi_get_and_clear_last_exception(env, &made[3]) == napi_ok; + napi_value array = nullptr; + const bool stored = ok && napi_create_array_with_length(env, 4, &array) == napi_ok && + napi_set_element(env, array, 0, made[0]) == napi_ok && + napi_set_element(env, array, 1, made[1]) == napi_ok && + napi_set_element(env, array, 2, made[2]) == napi_ok && + napi_set_element(env, array, 3, made[3]) == napi_ok && + napi_set_named_property(env, Global(env), "made", array) == napi_ok; + Leave(env, scope); + if (!stored) { + return ""; + } + return Utf8(env, RunIn(env, realm, + "(() => {" + " const [e, long, view, range] = made;" + " const proto = Object.getPrototypeOf;" + " return [" + " proto(e) === saved.Error.prototype, e instanceof saved.Error," + " e.message, long.message.length," + " proto(view) === saved.DataView.prototype, view.byteOffset," + " view.byteLength," + " proto(range) === saved.RangeError.prototype, range.code," + " pageCalls].join();" + "})()")); +} + +napi_value ThrowBindingFailed(napi_env env, napi_callback_info) { + const napi_status status = napi_throw_error(env, nullptr, "binding failed"); + if (status != napi_ok && status != napi_pending_exception) return Str(env, "not thrown"); + return nullptr; +} + +} // namespace + +TEST_F(Test69UnofficialRealmEntry, ErrorsAndDataViewsComeFromTheRealmsIntrinsics) { + EnvScope s(runtime_.get()); + unofficial_napi_realm realm = CreateRealm(s.env); + ASSERT_NE(realm, nullptr); + ASSERT_NE(RunIn(s.env, realm, kReplaceErrorAndDataView), nullptr); + const std::string expected = + "true,true,made,300,true,2,4,true,ERR_NAPI_INVALID_DATAVIEW_ARGS,0"; + EXPECT_EQ(MadeFromSavedIntrinsics(s.env, realm), expected); + + // The env's own realm, too. + ASSERT_NE(RunIn(s.env, nullptr, kReplaceErrorAndDataView), nullptr); + EXPECT_EQ(MadeFromSavedIntrinsics(s.env, nullptr), expected); +} + +TEST_F(Test69UnofficialRealmEntry, ThrowFromARealmsFunctionIsCaughtAsItsError) { + EnvScope s(runtime_.get()); + napi_value realm_global = nullptr; + unofficial_napi_realm realm = CreateRealm(s.env, &realm_global); + ASSERT_NE(realm, nullptr); + ASSERT_NE(RunIn(s.env, realm, kReplaceErrorAndDataView), nullptr); + + napi_value fail = nullptr; + unofficial_napi_realm_scope scope = Enter(s.env, realm); + ASSERT_EQ(napi_create_function(s.env, "fail", NAPI_AUTO_LENGTH, ThrowBindingFailed, nullptr, + &fail), + napi_ok); + Leave(s.env, scope); + ASSERT_EQ(napi_set_named_property(s.env, realm_global, "fail", fail), napi_ok); + + EXPECT_EQ(Utf8(s.env, RunIn(s.env, realm, + "(() => {" + " try { return String(fail()); } catch (e) {" + " return [e instanceof saved.Error," + " Object.getPrototypeOf(e) === saved.Error.prototype," + " e.message, pageCalls].join();" + " }" + "})()")), + "true,true,binding failed,0"); + bool pending = true; + ASSERT_EQ(napi_is_exception_pending(s.env, &pending), napi_ok); + EXPECT_FALSE(pending); +} diff --git a/v8/src/js_native_api_v8.cc b/v8/src/js_native_api_v8.cc index 778f343f64..93facc30b0 100644 --- a/v8/src/js_native_api_v8.cc +++ b/v8/src/js_native_api_v8.cc @@ -1541,28 +1541,24 @@ napi_status NAPI_CDECL napi_create_dataview(napi_env env, return napi_v8_set_last_error(env, napi_arraybuffer_expected, "ArrayBuffer expected"); } - v8::TryCatch tc(env->isolate); - auto context = env->context(); - v8::Local ctor_name = v8::String::NewFromUtf8Literal(env->isolate, "DataView"); - v8::Local ctor_val; - if (!context->Global()->Get(context, ctor_name).ToLocal(&ctor_val) || !ctor_val->IsFunction()) { - return napi_generic_failure; - } - v8::Local ctor = ctor_val.As(); - v8::Local args[3] = { - ab, - v8::Integer::NewFromUnsigned(env->isolate, static_cast(byte_offset)), - v8::Integer::NewFromUnsigned(env->isolate, static_cast(length)), - }; - v8::Local out; - if (!ctor->NewInstance(context, 3, args).ToLocal(&out)) { - if (tc.HasCaught()) { - SetLastException(env, tc.Exception(), tc.Message()); - return napi_v8_set_last_error(env, napi_pending_exception, "DataView construction threw"); - } - return napi_generic_failure; - } - *result = napi_v8_wrap_value(env, out); + const size_t buffer_length = ab->IsArrayBuffer() ? ab.As()->ByteLength() + : ab.As()->ByteLength(); + if (byte_offset > buffer_length || length > buffer_length - byte_offset) { + napi_throw_range_error(env, + "ERR_NAPI_INVALID_DATAVIEW_ARGS", + "byte_offset + byte_length should be less than or equal to the size in " + "bytes of the array passed in"); + return napi_v8_set_last_error(env, napi_pending_exception, "Invalid DataView range"); + } + + // The current realm's own DataView, never its global's (scripts can + // replace that). + v8::Context::Scope context_scope(env->context()); + v8::Local view = + ab->IsArrayBuffer() + ? v8::DataView::New(ab.As(), byte_offset, length) + : v8::DataView::New(ab.As(), byte_offset, length); + *result = napi_v8_wrap_value(env, view); return (*result == nullptr) ? napi_generic_failure : napi_ok; } From b18cc85a2179c137e189e8901377c9309f21a5f5 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 13:34:19 -0800 Subject: [PATCH 029/150] V8: read Buffer from the env's realm CreateBufferObject (napi_create_buffer*) read Buffer and Buffer.prototype from the current realm's global, and CreateNodeBufferFromBytes (unofficial_napi_bytecode_serialize and module cached data) also called its Buffer.from. With a page realm current, a page getter ran during the call and chose the result. Both now read Buffer from the env's own realm, as QuickJS already does: a buffer made in a realm is that realm's Uint8Array with the env realm's Buffer.prototype. With no realm entered nothing changes. The test defines Buffer in the env's realm and a counting Buffer getter in a realm, then makes a buffer and serializes bytecode with the realm entered: the buffer has the env's Buffer.prototype and the getter never runs, on both engines. Co-Authored-By: Claude Opus 5.5 --- .../runners/test_69_unofficial_realm_entry.cc | 54 +++++++++++++++++++ v8/src/js_native_api_v8.cc | 4 +- v8/src/unofficial_napi_contextify.cc | 4 +- 3 files changed, 60 insertions(+), 2 deletions(-) diff --git a/tests/runners/test_69_unofficial_realm_entry.cc b/tests/runners/test_69_unofficial_realm_entry.cc index c7acf759c6..c682c8e27a 100644 --- a/tests/runners/test_69_unofficial_realm_entry.cc +++ b/tests/runners/test_69_unofficial_realm_entry.cc @@ -887,3 +887,57 @@ TEST_F(Test69UnofficialRealmEntry, ThrowFromARealmsFunctionIsCaughtAsItsError) { ASSERT_EQ(napi_is_exception_pending(s.env, &pending), napi_ok); EXPECT_FALSE(pending); } + +// Buffer is the env's, as in Node: a buffer made in a realm takes the env +// realm's Buffer.prototype, and nothing reads the realm's Buffer. +TEST_F(Test69UnofficialRealmEntry, BuffersNeverReadTheRealmsBuffer) { + EnvScope s(runtime_.get()); + ASSERT_NE(RunIn(s.env, nullptr, + "globalThis.Buffer = class Buffer extends Uint8Array {" + " static from(view) { return new Buffer(view); } };" + "0"), + nullptr); + unofficial_napi_realm realm = CreateRealm(s.env); + ASSERT_NE(realm, nullptr); + ASSERT_NE(RunIn(s.env, realm, + "globalThis.pageCalls = 0;" + "Object.defineProperty(globalThis, 'Buffer', { get() {" + " pageCalls++;" + " return { prototype: {}, from() { pageCalls++; return {}; } }; } });" + "0"), + nullptr); + + unofficial_napi_bytecode_open_options options{}; + options.size = sizeof(options); + options.version = UNOFFICIAL_NAPI_BYTECODE_OPEN_OPTIONS_VERSION; + options.source_text = Str(s.env, "1 + 1"); + options.filename = Str(s.env, "script.js"); + options.shape = unofficial_napi_bytecode_shape_script; + options.params_or_undefined = Undefined(s.env); + ASSERT_EQ(napi_create_symbol(s.env, Str(s.env, "hdo"), &options.host_defined_option_id), + napi_ok); + unofficial_napi_bytecode_open_result opened{}; + ASSERT_EQ(unofficial_napi_bytecode_open(s.env, &options, &opened), napi_ok); + ASSERT_NE(opened.bytecode, nullptr); + + napi_value buffer = nullptr; + napi_value serialized = nullptr; + void* data = nullptr; + unofficial_napi_realm_scope scope = Enter(s.env, realm); + EXPECT_EQ(napi_create_buffer(s.env, 4, &data, &buffer), napi_ok); + EXPECT_EQ(unofficial_napi_bytecode_serialize(s.env, opened.bytecode, &serialized), napi_ok); + Leave(s.env, scope); + ASSERT_EQ(unofficial_napi_bytecode_release(s.env, opened.bytecode), napi_ok); + ASSERT_NE(buffer, nullptr); + ASSERT_NE(serialized, nullptr); + bool is_typedarray = false; + ASSERT_EQ(napi_is_typedarray(s.env, serialized, &is_typedarray), napi_ok); + EXPECT_TRUE(is_typedarray); + + // The buffer is a Buffer of the env's realm, and the realm's getter never + // ran. + ASSERT_EQ(napi_set_named_property(s.env, Global(s.env), "made", buffer), napi_ok); + EXPECT_EQ(Utf8(s.env, Eval(s.env, "String(Object.getPrototypeOf(made) === Buffer.prototype)")), + "true"); + EXPECT_EQ(Utf8(s.env, RunIn(s.env, realm, "String(pageCalls)")), "0"); +} diff --git a/v8/src/js_native_api_v8.cc b/v8/src/js_native_api_v8.cc index 93facc30b0..3f76707e19 100644 --- a/v8/src/js_native_api_v8.cc +++ b/v8/src/js_native_api_v8.cc @@ -320,7 +320,9 @@ v8::Local CreateBufferObject(napi_env env, size_t offset, size_t length) { v8::Local ab = v8::ArrayBuffer::New(env->isolate, backing_store); - v8::Local context = env->context(); + // Buffer is the env's: read it from the env's realm, never from the current + // one, whose global its scripts control. + v8::Local context = env->main_context(); v8::Local global = context->Global(); // Node's napi_create_buffer* APIs produce Buffer instances, not plain diff --git a/v8/src/unofficial_napi_contextify.cc b/v8/src/unofficial_napi_contextify.cc index 290621b894..b6e3a4c79d 100644 --- a/v8/src/unofficial_napi_contextify.cc +++ b/v8/src/unofficial_napi_contextify.cc @@ -703,7 +703,9 @@ bool CreateNodeBufferFromBytes(napi_env env, const uint8_t* data, size_t size, n *out = nullptr; v8::Isolate* isolate = env->isolate; - v8::Local context = env->context(); + // Buffer is the env's: read and call it in the env's realm, never in the + // current one, whose global its scripts control. + v8::Local context = env->main_context(); std::unique_ptr store = v8::ArrayBuffer::NewBackingStore(isolate, size); if (!store) return false; From 0a50296963a753b286d72d8620ee219afe171c17 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 13:34:19 -0800 Subject: [PATCH 030/150] V8: run module hooks in the env's realm The dynamic-import and import.meta hooks pushed no realm frame, so the hook's receiver (napi_get_global) and the import-attributes object came from whichever realm happened to be current: the env's for a plain run_script in a realm, the realm's when it was entered, another realm's when one of its callbacks was on the stack. The docs say env hooks run in the env's realm. Both hooks now run with the env's realm current and its context entered, as finalizers do; their arguments still describe the importing script, and the import() promise is still the importing realm's. GetSymbolsBindingProperty, which reads the env's internalBinding for module compilation, now reads it from the env's realm too. The test (V8 only, like test_66's import test) calls import() in a realm with nothing entered, with that realm entered, and with another realm entered, and checks that the hook's receiver and napi_get_global are the env's global each time. Co-Authored-By: Claude Opus 5.5 --- .../runners/test_69_unofficial_realm_entry.cc | 62 +++++++++++++++++++ v8/src/unofficial_napi_contextify.cc | 52 ++++++++++------ 2 files changed, 95 insertions(+), 19 deletions(-) diff --git a/tests/runners/test_69_unofficial_realm_entry.cc b/tests/runners/test_69_unofficial_realm_entry.cc index c682c8e27a..550c089ffb 100644 --- a/tests/runners/test_69_unofficial_realm_entry.cc +++ b/tests/runners/test_69_unofficial_realm_entry.cc @@ -941,3 +941,65 @@ TEST_F(Test69UnofficialRealmEntry, BuffersNeverReadTheRealmsBuffer) { "true"); EXPECT_EQ(Utf8(s.env, RunIn(s.env, realm, "String(pageCalls)")), "0"); } + +#if defined(NAPI_TEST_ENGINE_V8) +namespace { + +struct ImportHookRealms { + napi_ref env_global = nullptr; + int calls = 0; + int this_is_env_global = 0; + int global_is_env_global = 0; +}; + +napi_value RecordImportHookRealm(napi_env env, napi_callback_info info) { + napi_value self = nullptr; + void* data = nullptr; + if (napi_get_cb_info(env, info, nullptr, nullptr, &self, &data) != napi_ok) return nullptr; + auto* record = static_cast(data); + napi_value env_global = nullptr; + if (napi_get_reference_value(env, record->env_global, &env_global) != napi_ok) return nullptr; + ++record->calls; + if (StrictEquals(env, self, env_global)) ++record->this_is_env_global; + if (StrictEquals(env, Global(env), env_global)) ++record->global_is_env_global; + napi_value result = nullptr; + napi_create_object(env, &result); + return result; +} + +} // namespace + +// Env hooks run in the env's realm: the dynamic-import hook's receiver and +// current realm are the env's, whichever realm imports and is current. +TEST_F(Test69UnofficialRealmEntry, DynamicImportHookRunsInTheEnvsRealm) { + EnvScope s(runtime_.get()); + unofficial_napi_realm a = CreateRealm(s.env); + unofficial_napi_realm b = CreateRealm(s.env); + ASSERT_NE(a, nullptr); + ASSERT_NE(b, nullptr); + + ImportHookRealms record; + ASSERT_EQ(napi_create_reference(s.env, Global(s.env), 1, &record.env_global), napi_ok); + napi_value hook = nullptr; + ASSERT_EQ(napi_create_function(s.env, "importHook", NAPI_AUTO_LENGTH, RecordImportHookRealm, + &record, &hook), + napi_ok); + const unofficial_napi_module_hooks hooks = { + sizeof(unofficial_napi_module_hooks), UNOFFICIAL_NAPI_MODULE_HOOKS_VERSION, hook, nullptr}; + ASSERT_EQ(unofficial_napi_module_wrap_set_hooks(s.env, &hooks), napi_ok); + + // import() in A: with nothing entered, with A entered, and with B entered. + ASSERT_NE(RunIn(s.env, a, "import('one'); 0"), nullptr); + unofficial_napi_realm_scope scope = Enter(s.env, a); + ASSERT_NE(Eval(s.env, "import('two'); 0"), nullptr); + Leave(s.env, scope); + scope = Enter(s.env, b); + ASSERT_NE(RunIn(s.env, a, "import('three'); 0"), nullptr); + Leave(s.env, scope); + + EXPECT_EQ(record.calls, 3); + EXPECT_EQ(record.this_is_env_global, 3); + EXPECT_EQ(record.global_is_env_global, 3); + ASSERT_EQ(napi_delete_reference(s.env, record.env_global), napi_ok); +} +#endif diff --git a/v8/src/unofficial_napi_contextify.cc b/v8/src/unofficial_napi_contextify.cc index b6e3a4c79d..0b40d22c7c 100644 --- a/v8/src/unofficial_napi_contextify.cc +++ b/v8/src/unofficial_napi_contextify.cc @@ -939,6 +939,10 @@ napi_value GetVmDynamicImportDefaultInternalSymbol(napi_env env) { napi_value GetSymbolsBindingProperty(napi_env env, const char* property_name) { if (env == nullptr || property_name == nullptr) return nullptr; + // The bindings are the env's: look them up in its realm, whichever is + // current. + v8::Context::Scope context_scope(env->main_context()); + napi_realm_frame_scope__ realm_frame(env, nullptr); napi_value global = nullptr; napi_get_global(env, &global); if (global == nullptr) return nullptr; @@ -1190,30 +1194,37 @@ v8::MaybeLocal ImportModuleDynamicallyWithPhase( } } - napi_value phase_value = nullptr; - napi_create_int32(env, phase == v8::ModuleImportPhase::kSource ? 1 : 2, &phase_value); - napi_value argv[5] = { - napi_v8_wrap_value(env, id), - napi_v8_wrap_value(env, specifier), - phase_value, - napi_v8_wrap_value(env, CreateDynamicImportAttributesObject(env, import_attributes)), - napi_v8_wrap_value(env, resource_name), - }; - - napi_value global = nullptr; - napi_get_global(env, &global); napi_value result = nullptr; - if (napi_call_function(env, global, callback, 5, argv, &result) != napi_ok) { - bool pending = false; - if (napi_is_exception_pending(env, &pending) == napi_ok && pending) { - napi_value error = nullptr; - if (napi_get_and_clear_last_exception(env, &error) == napi_ok && error != nullptr) { - isolate->ThrowException(napi_v8_unwrap_value(error)); + { + // Env hooks run in the env's realm, whichever realm imports; the + // arguments still name the importing script. + v8::Context::Scope env_context_scope(env->main_context()); + napi_realm_frame_scope__ realm_frame(env, nullptr); + napi_value phase_value = nullptr; + napi_create_int32(env, phase == v8::ModuleImportPhase::kSource ? 1 : 2, &phase_value); + napi_value argv[5] = { + napi_v8_wrap_value(env, id), + napi_v8_wrap_value(env, specifier), + phase_value, + napi_v8_wrap_value(env, CreateDynamicImportAttributesObject(env, import_attributes)), + napi_v8_wrap_value(env, resource_name), + }; + + napi_value global = nullptr; + napi_get_global(env, &global); + if (napi_call_function(env, global, callback, 5, argv, &result) != napi_ok) { + bool pending = false; + if (napi_is_exception_pending(env, &pending) == napi_ok && pending) { + napi_value error = nullptr; + if (napi_get_and_clear_last_exception(env, &error) == napi_ok && error != nullptr) { + isolate->ThrowException(napi_v8_unwrap_value(error)); + } } + return v8::MaybeLocal(); } - return v8::MaybeLocal(); } + // The promise is the importing realm's. v8::Local resolver; if (!v8::Promise::Resolver::New(context).ToLocal(&resolver)) { return v8::MaybeLocal(); @@ -1256,6 +1267,9 @@ void HostInitializeImportMetaObject(v8::Local context, napi_value id_value = GetRefValue(env, record->host_defined_option_ref); if (callback == nullptr || wrapper == nullptr || id_value == nullptr) return; + // Env hooks run in the env's realm, whichever realm the module is in. + v8::Context::Scope env_context_scope(env->main_context()); + napi_realm_frame_scope__ realm_frame(env, nullptr); napi_value meta_value = napi_v8_wrap_value(env, meta); napi_value argv[3] = {id_value, meta_value, wrapper}; napi_value ignored = nullptr; From 8f9d93454f57fb6053b5df82d12c9ea45e53b831 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 13:27:23 -0800 Subject: [PATCH 031/150] Realms: don't promise to refuse a stale realm handle The header and docs/realms.md said that entering a collected realm fails with napi_invalid_arg. Both providers only check that the handle is one of the env's realm records, and the next create_realm frees collected records and can reuse one, so a stale handle can enter a newer, unrelated realm. A realm handle is already valid only while its handle scope is open. The header now says what happens after that: using the handle is undefined behavior that the provider may not detect, and a newer realm can get the same handle. Entering a realm of another env still fails with napi_invalid_arg. An embedder that uses a realm later keeps its global and calls unofficial_napi_get_realm on it each time. test_69's case no longer enters a stale handle. It keeps a realm by its global across a collection and finds it again with get_realm, which only makes deterministic assertions. Co-Authored-By: Claude Opus 5.5 --- docs/realms.md | 12 ++++++- include/unofficial_napi.h | 12 +++++-- .../runners/test_69_unofficial_realm_entry.cc | 32 ++++++++++++------- 3 files changed, 41 insertions(+), 15 deletions(-) diff --git a/docs/realms.md b/docs/realms.md index 0f6caf13ad..99b784c79e 100644 --- a/docs/realms.md +++ b/docs/realms.md @@ -32,6 +32,11 @@ only while the handle scope it was obtained in is open, like a `napi_value`, and two handles for one realm may differ; `unofficial_napi_get_realm` finds the realm again from its global. +- **Don't keep realm handles.** Using one after its handle scope has closed + is undefined behavior that the provider may not detect: once the realm is + collected, a newer realm can get the same handle. An embedder that uses a + realm later (a browser, per document) keeps its global in a `napi_ref` and + calls `get_realm` on it each time. ## API @@ -73,7 +78,12 @@ napi_status unofficial_napi_compile_function(napi_env env, unofficial_napi_realm leave a scope its caller opened, and scopes it leaves open close when it returns. Releasing the env closes every scope. - A scope keeps its realm alive until it is left. Entering a realm of - another env, or a collected one, fails with `napi_invalid_arg`. + another env fails with `napi_invalid_arg`. + - A handle used after its handle scope has closed is undefined behavior. + V8 and QuickJS only check that the handle is one of the env's realm + records before reading it, so entering it does not crash. But the next + `create_realm` frees the records of collected realms and can reuse one, + and the stale handle then enters that newer realm. - No JavaScript runs, so both work while execution is terminating. A pending exception stays pending. - NULL enters the env's own realm, for example to reach its global from diff --git a/include/unofficial_napi.h b/include/unofficial_napi.h index ef88c3ccfb..01cbb82b07 100644 --- a/include/unofficial_napi.h +++ b/include/unofficial_napi.h @@ -191,7 +191,11 @@ NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_release_env( // made in it is reachable, and is then collected. A realm handle, like a // napi_value, is valid only while the handle scope it was obtained in is open, // and two handles for one realm may differ; unofficial_napi_get_realm finds -// the realm again from its global. +// the realm again from its global. Using a handle after its handle scope has +// closed is undefined behavior that the provider may not detect: once the +// realm is collected, a newer realm can get the same handle. To use a realm +// later, keep its global (in a napi_ref, say) and call +// unofficial_napi_get_realm on it each time. typedef struct unofficial_napi_realm__* unofficial_napi_realm; enum { UNOFFICIAL_NAPI_REALM_OPTIONS_VERSION = 1 }; @@ -256,8 +260,10 @@ typedef uint64_t unofficial_napi_realm_scope; // every scope closes when the env is released. // // No JavaScript runs, so entering also succeeds while execution is -// terminating. Fails with napi_invalid_arg for a realm of another env or one -// that was collected. +// terminating. Fails with napi_invalid_arg for a realm of another env. A +// handle used after its handle scope has closed is undefined behavior (see +// unofficial_napi_realm): it may fail, or enter a newer realm that got the +// same handle. NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_enter_realm( napi_env env, unofficial_napi_realm realm_or_null, diff --git a/tests/runners/test_69_unofficial_realm_entry.cc b/tests/runners/test_69_unofficial_realm_entry.cc index 550c089ffb..06e8ddad13 100644 --- a/tests/runners/test_69_unofficial_realm_entry.cc +++ b/tests/runners/test_69_unofficial_realm_entry.cc @@ -509,7 +509,7 @@ TEST_F(Test69UnofficialRealmEntry, PendingExceptionSurvivesLeavingARealm) { "true"); } -TEST_F(Test69UnofficialRealmEntry, EnteringAnUnknownOrCollectedRealmFails) { +TEST_F(Test69UnofficialRealmEntry, EnteringAnUnknownRealmFails) { EnvScope s(runtime_.get()); unofficial_napi_realm_scope scope = 0; @@ -520,23 +520,33 @@ TEST_F(Test69UnofficialRealmEntry, EnteringAnUnknownOrCollectedRealmFails) { napi_invalid_arg); EXPECT_EQ(scope, 0u); - // A handle that outlived its handle scope, once the realm is collected. - unofficial_napi_realm stale = nullptr; - napi_ref weak_global = nullptr; + // A handle that outlived its handle scope is not tried: using it is + // undefined behavior, and a newer realm may have the same handle. A realm + // used later is kept by its global and found again from it. + napi_ref kept_global = nullptr; { napi_handle_scope handles = nullptr; ASSERT_EQ(napi_open_handle_scope(s.env, &handles), napi_ok); napi_value global = nullptr; - stale = CreateRealm(s.env, &global); - ASSERT_NE(stale, nullptr); - ASSERT_EQ(napi_create_reference(s.env, global, 0, &weak_global), napi_ok); + ASSERT_NE(CreateRealm(s.env, &global), nullptr); + ASSERT_EQ(napi_create_reference(s.env, global, 1, &kept_global), napi_ok); ASSERT_EQ(napi_close_handle_scope(s.env, handles), napi_ok); } ASSERT_EQ(unofficial_napi_collect_garbage(s.env), napi_ok); - ASSERT_TRUE(IsCollected(s.env, weak_global)); - EXPECT_EQ(unofficial_napi_enter_realm(s.env, stale, &scope), napi_invalid_arg); - EXPECT_EQ(scope, 0u); - ASSERT_EQ(napi_delete_reference(s.env, weak_global), napi_ok); + { + napi_handle_scope handles = nullptr; + ASSERT_EQ(napi_open_handle_scope(s.env, &handles), napi_ok); + napi_value global = nullptr; + ASSERT_EQ(napi_get_reference_value(s.env, kept_global, &global), napi_ok); + unofficial_napi_realm found = nullptr; + ASSERT_EQ(unofficial_napi_get_realm(s.env, global, &found), napi_ok); + ASSERT_NE(found, nullptr); + scope = Enter(s.env, found); + EXPECT_TRUE(StrictEquals(s.env, Global(s.env), global)); + Leave(s.env, scope); + ASSERT_EQ(napi_close_handle_scope(s.env, handles), napi_ok); + } + ASSERT_EQ(napi_delete_reference(s.env, kept_global), napi_ok); // No JavaScript runs on entering or leaving, so both work while // terminating. From e37dbdeba7bb4ea827f6d0c54ffddad1d0c0512e Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 13:27:41 -0800 Subject: [PATCH 032/150] QuickJS: copy a sandbox realm's sandbox around napi_run_script While a sandbox realm is current, napi_get_global returns its sandbox, and the header says napi_run_script runs there. QuickJS evaluated against the realm's real global without copying the sandbox in or out, so the script saw none of the sandbox's properties and its global writes never reached the sandbox. V8, where the sandbox is the global, behaved as documented. napi_run_script now copies the sandbox into the realm's global before the script and back after it, as unofficial_napi_run_script already does for sandbox realms. The contextify layer finds the realm from the current context's global and does nothing for other contexts. docs/realms.md describes when QuickJS copies, and what native code that runs during a script sees in between. test_69 checks, on both engines, that napi_run_script in an entered sandbox realm reads the sandbox and writes to it. Co-Authored-By: Claude Opus 5.5 --- docs/realms.md | 10 ++++- include/unofficial_napi.h | 3 +- quickjs/src/internal/napi_contextify.cc | 23 +++++++++++ quickjs/src/internal/napi_contextify.h | 6 +++ quickjs/src/js_native_api_quickjs.cc | 17 ++++++++ .../runners/test_69_unofficial_realm_entry.cc | 41 +++++++++++++++++++ 6 files changed, 97 insertions(+), 3 deletions(-) diff --git a/docs/realms.md b/docs/realms.md index 99b784c79e..b538cfa591 100644 --- a/docs/realms.md +++ b/docs/realms.md @@ -131,7 +131,7 @@ and interrupt callbacks push the env's realm. | Provider | A realm is | `get_realm` | Collection | |---|---|---|---| | V8 | a record with a weak `v8::Global` and its own microtask queue, owned by the env | creation context of the global, then context embedder-data slot 33 | The context is weak. The next `create_realm` frees records whose context is gone, and only then their microtask queues (from #109). | -| QuickJS | a record with a `JSContext` on the env's runtime; a sandbox realm copies the sandbox's properties in and out around each call | a map from global or sandbox to record | The key (the sandbox, or the realm's global) holds a function of the realm under a private symbol, and a sandbox realm's global holds the sandbox, so the collector frees the cycle with its key. The record holds the key weakly, and the next `create_realm` frees collected records (from #110). | +| QuickJS | a record with a `JSContext` on the env's runtime; a sandbox realm copies the sandbox's properties in and out around each script | a map from global or sandbox to record | The key (the sandbox, or the realm's global) holds a function of the realm under a private symbol, and a sandbox realm's global holds the sandbox, so the collector frees the cycle with its key. The record holds the key weakly, and the next `create_realm` frees collected records (from #110). | | host-JS | a virtual global context (a `with`/Proxy scope over one host realm) | a per-env `WeakMap` from global or sandbox to context | Nothing holds a realm strongly; the host GC collects it with its key. | - **host-JS with a native Worker realm (#125).** The env's realm is the @@ -172,7 +172,13 @@ and interrupt callbacks push the env's realm. - **Sandboxes work differently per engine.** - V8 turns the sandbox itself into the realm's global, which goes against V8's API contract and breaks `vm.createContext(globalThis)`. - - QuickJS copies sandbox properties in and out around scripts. + - QuickJS copies the sandbox's properties into the realm's global before + each script and back after a script that completes: + `unofficial_napi_run_script`, and `napi_run_script` while the realm is + current. `compile_function` only copies them in. In between, the two can + differ. Native code that runs during a script sees the sandbox as of the + last copy, and a script it starts in the realm copies the sandbox in + again, over the running script's global writes to the same names. - host-JS evaluates against the sandbox with `with`. ## History diff --git a/include/unofficial_napi.h b/include/unofficial_napi.h index 01cbb82b07..e199725a96 100644 --- a/include/unofficial_napi.h +++ b/include/unofficial_napi.h @@ -159,7 +159,8 @@ NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_release_env( // realm's intrinsics: objects, arrays, functions, classes, errors (also the // ones napi_throw_* makes), promises, dates, typed arrays and buffers. // napi_get_global returns the current realm's global (a sandbox realm's -// sandbox), and napi_run_script runs there. +// sandbox), and napi_run_script runs there. (QuickJS copies a sandbox in +// and out around each script; see docs/realms.md.) // - A native function belongs to the realm that was current when it was made, // as an ECMAScript built-in function has a [[Realm]]. That covers // napi_create_function, and the constructors, methods and accessors of diff --git a/quickjs/src/internal/napi_contextify.cc b/quickjs/src/internal/napi_contextify.cc index e6447f0f74..32522454a6 100644 --- a/quickjs/src/internal/napi_contextify.cc +++ b/quickjs/src/internal/napi_contextify.cc @@ -921,6 +921,29 @@ namespace quickjs::detail return record->live() ? record->ctx : nullptr; } + // The live sandbox realm whose context is `ctx`, or null. + napi_contextify__::context_record *napi_contextify__::sandbox_record_for(JSContext *ctx) const + { + if (ctx == nullptr || ctx == ctx_) + return nullptr; + JSValue global = JS_GetGlobalObject(ctx); + context_record *record = find_live_record(global); + JS_FreeValue(ctx, global); + return record != nullptr && record->ctx == ctx && record->has_sandbox() ? record : nullptr; + } + + napi_status napi_contextify__::sync_sandbox_in(JSContext *ctx) const + { + context_record *record = sandbox_record_for(ctx); + return record != nullptr ? sync_sandbox_to_context(record) : napi_ok; + } + + napi_status napi_contextify__::sync_sandbox_out(JSContext *ctx) const + { + context_record *record = sandbox_record_for(ctx); + return record != nullptr ? sync_context_to_sandbox(record) : napi_ok; + } + napi_status napi_contextify__::run_script(unofficial_napi_realm realm, const unofficial_napi_js_source *source, napi_value filename, diff --git a/quickjs/src/internal/napi_contextify.h b/quickjs/src/internal/napi_contextify.h index 244c0aa00f..44e411ee77 100644 --- a/quickjs/src/internal/napi_contextify.h +++ b/quickjs/src/internal/napi_contextify.h @@ -50,6 +50,11 @@ namespace quickjs::detail // The context code for `realm` runs in: the realm's, or the env's // for NULL. JSContext *realm_context(unofficial_napi_realm realm) const; + // For napi_run_script in a sandbox realm: copy the sandbox into the + // realm's global before the script and back after it, as run_script + // does. No-ops for a context without a sandbox. + napi_status sync_sandbox_in(JSContext *ctx) const; + napi_status sync_sandbox_out(JSContext *ctx) const; napi_status run_script(unofficial_napi_realm realm, const unofficial_napi_js_source *source, @@ -125,6 +130,7 @@ namespace quickjs::detail int32_t line_offset, int32_t column_offset); context_record *find_live_record(JSValueConst global_or_sandbox) const; + context_record *sandbox_record_for(JSContext *ctx) const; context_record *create_context_record(JSValueConst sandbox_or_undefined, JSValueConst host_defined_option_id, napi_value *key_out); diff --git a/quickjs/src/js_native_api_quickjs.cc b/quickjs/src/js_native_api_quickjs.cc index 05a5fbd081..e123dfe62f 100644 --- a/quickjs/src/js_native_api_quickjs.cc +++ b/quickjs/src/js_native_api_quickjs.cc @@ -3220,6 +3220,16 @@ extern "C" if (str == nullptr) return napi_util__::return_pending_if_caught(env, "Failed to convert script to string"); + // A sandbox realm's global is its sandbox (napi_get_global), so the + // sandbox is copied into the realm's real global and back, as + // unofficial_napi_run_script does. + napi_status sync_status = env->contextify().sync_sandbox_in(env->context()); + if (sync_status != napi_ok) + { + JS_FreeCString(env->context(), str); + return sync_status; + } + JSValue out = JS_Eval(env->context(), str, len, "", JS_EVAL_TYPE_GLOBAL); if (JS_IsException(out)) @@ -3242,6 +3252,13 @@ extern "C" JS_FreeCString(env->context(), str); + sync_status = env->contextify().sync_sandbox_out(env->context()); + if (sync_status != napi_ok) + { + JS_FreeValue(env->context(), out); + return sync_status; + } + *result = env->wrap_value_in_current_scope(out, true); return (*result == nullptr) ? napi_generic_failure : napi_ok; } diff --git a/tests/runners/test_69_unofficial_realm_entry.cc b/tests/runners/test_69_unofficial_realm_entry.cc index 06e8ddad13..1381e5490a 100644 --- a/tests/runners/test_69_unofficial_realm_entry.cc +++ b/tests/runners/test_69_unofficial_realm_entry.cc @@ -1013,3 +1013,44 @@ TEST_F(Test69UnofficialRealmEntry, DynamicImportHookRunsInTheEnvsRealm) { ASSERT_EQ(napi_delete_reference(s.env, record.env_global), napi_ok); } #endif +// napi_run_script in an entered sandbox realm. + +namespace { + +int32_t Int32Property(napi_env env, napi_value object, const char* name) { + napi_value value = nullptr; + int32_t out = -1; + if (napi_get_named_property(env, object, name, &value) != napi_ok || + napi_get_value_int32(env, value, &out) != napi_ok) { + return -1; + } + return out; +} + +} // namespace + +// A sandbox realm's global is its sandbox, so napi_run_script there reads the +// sandbox, and its global writes reach the sandbox. +TEST_F(Test69UnofficialRealmEntry, NapiRunScriptInAnEnteredSandboxRealmUsesTheSandbox) { + EnvScope s(runtime_.get()); + napi_value sandbox = nullptr; + napi_value x = nullptr; + ASSERT_EQ(napi_create_object(s.env, &sandbox), napi_ok); + ASSERT_EQ(napi_create_int32(s.env, 42, &x), napi_ok); + ASSERT_EQ(napi_set_named_property(s.env, sandbox, "x", x), napi_ok); + unofficial_napi_realm realm = CreateRealm(s.env, nullptr, sandbox); + ASSERT_NE(realm, nullptr); + + unofficial_napi_realm_scope scope = Enter(s.env, realm); + ASSERT_TRUE(StrictEquals(s.env, Global(s.env), sandbox)); + ASSERT_EQ(napi_set_named_property(s.env, Global(s.env), "fromNative", Str(s.env, "native")), + napi_ok); + EXPECT_EQ(Utf8(s.env, Eval(s.env, "`${typeof x} ${x} ${fromNative}`")), "number 42 native"); + EXPECT_NE(Eval(s.env, "globalThis.written = 7; var declared = 8; x = 43"), nullptr); + Leave(s.env, scope); + + EXPECT_EQ(Int32Property(s.env, sandbox, "written"), 7); + EXPECT_EQ(Int32Property(s.env, sandbox, "declared"), 8); + EXPECT_EQ(Int32Property(s.env, sandbox, "x"), 43); + EXPECT_EQ(Utf8(s.env, Eval(s.env, "typeof written")), "undefined"); +} From c7bb1d6f3c126225b3796e2a8d1563b8b1255e08 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 13:27:49 -0800 Subject: [PATCH 033/150] Realms: document which realm options each provider honors unofficial_napi_realm_options has fields some providers ignore, while create_realm still returns napi_ok, and nothing said which. Checked on each provider: the sandbox works everywhere; host_defined_option_id on V8 and QuickJS; allow_code_gen_strings and own_microtask_queue on V8 only. allow_code_gen_wasm, name and origin are used by no provider. On V8 a realm created with both code-generation flags false still compiles WebAssembly. The header and docs/realms.md now list this next to the options. QuickJS's create_realm comment said that name and origin label V8 inspector contexts, but the V8 provider ignores them too, so it now says no provider uses them. V8's create_realm says why allow_code_gen_wasm is ignored: it would need an isolate-wide AllowWasmCodeGenerationCallback, which the provider does not install. docs/realms.md lists that, and the missing call to change a realm's code-generation policy after creation, under Not done. test_69 checks on V8 that allow_code_gen_strings holds for napi_run_script while the realm is entered. Co-Authored-By: Claude Opus 5.5 --- docs/realms.md | 24 +++++++++++++++++-- include/unofficial_napi.h | 10 ++++++++ quickjs/src/internal/napi_contextify.cc | 3 ++- .../runners/test_69_unofficial_realm_entry.cc | 23 +++++++++++++++++- v8/src/unofficial_napi_contextify.cc | 3 +++ 5 files changed, 59 insertions(+), 4 deletions(-) diff --git a/docs/realms.md b/docs/realms.md index b538cfa591..4295022fe6 100644 --- a/docs/realms.md +++ b/docs/realms.md @@ -66,8 +66,22 @@ napi_status unofficial_napi_compile_function(napi_env env, unofficial_napi_realm sandbox, as with `vm.createContext(sandbox)`. - A sandbox belongs to at most one realm. The env's own global may still be one. - - Options: sandbox, name, origin, host-defined option id, the - code-generation flags and an own microtask queue (V8 only). + - Options: sandbox, name, origin, host-defined option id, the two + code-generation flags and an own microtask queue. Each provider honors + only some of them, and accepts and ignores the rest: + + | Option | V8 | QuickJS | host-JS | + |---|---|---|---| + | `sandbox_or_null` | yes | yes | yes | + | `host_defined_option_id` | yes | yes | no | + | `allow_code_gen_strings` | yes | no | no | + | `own_microtask_queue` | yes | no | no | + | `allow_code_gen_wasm` | no | no | no | + | `name`, `origin` | no | no | no | + + With `allow_code_gen_strings` false, V8 makes `eval` and the `Function` + constructors throw an `EvalError` in the realm. WebAssembly code + generation stays allowed on V8 (QuickJS has no WebAssembly). - **`get_realm`** returns NULL for any object that isn't a realm's global or sandbox, the env's own global included. - **`enter_realm` / `leave_realm`:** @@ -180,6 +194,12 @@ and interrupt callbacks push the env's realm. last copy, and a script it starts in the realm copies the sandbox in again, over the running script's global writes to the same names. - host-JS evaluates against the sandbox with `with`. +- **Code generation per realm.** No provider enforces + `allow_code_gen_wasm`. V8 would need an isolate-wide + `AllowWasmCodeGenerationCallback` that reads a per-realm flag, as Node + does. There is also no call to change a realm's code-generation policy + after it is created, which a browser needs because CSP arrives with the + response. ## History diff --git a/include/unofficial_napi.h b/include/unofficial_napi.h index e199725a96..8050bbede1 100644 --- a/include/unofficial_napi.h +++ b/include/unofficial_napi.h @@ -205,6 +205,16 @@ enum { UNOFFICIAL_NAPI_REALM_OPTIONS_VERSION = 1 }; // writes the sandbox, as with vm.createContext(sandbox). Otherwise the realm // gets a fresh global. `name`, `origin` and `host_defined_option_id` may be // NULL. The descriptor is observed only for the duration of the call. +// +// Each provider honors only some fields. It accepts the rest, ignores them +// and still returns napi_ok: +// - `sandbox_or_null`: every provider. +// - `host_defined_option_id`: V8 and QuickJS. +// - `allow_code_gen_strings`: V8 only. When false, eval and the Function +// constructors throw an EvalError in the realm. +// - `own_microtask_queue`: V8 only. +// - `allow_code_gen_wasm`, `name` and `origin`: no provider. WebAssembly code +// generation stays allowed wherever the engine has WebAssembly. typedef struct { uint32_t size; uint32_t version; diff --git a/quickjs/src/internal/napi_contextify.cc b/quickjs/src/internal/napi_contextify.cc index 32522454a6..c7fd624bef 100644 --- a/quickjs/src/internal/napi_contextify.cc +++ b/quickjs/src/internal/napi_contextify.cc @@ -836,7 +836,8 @@ namespace quickjs::detail napi_value *global_out) { // QuickJS has no per-realm code-generation switches or microtask - // queues; name and origin only label V8 inspector contexts. + // queues, so those options are ignored. No provider uses name or + // origin either. if (!napi_util__::check_env(env_) || realm_out == nullptr) return napi_invalid_arg; JSValueConst sandbox = JS_UNDEFINED; diff --git a/tests/runners/test_69_unofficial_realm_entry.cc b/tests/runners/test_69_unofficial_realm_entry.cc index 1381e5490a..cb71099b3f 100644 --- a/tests/runners/test_69_unofficial_realm_entry.cc +++ b/tests/runners/test_69_unofficial_realm_entry.cc @@ -1013,7 +1013,8 @@ TEST_F(Test69UnofficialRealmEntry, DynamicImportHookRunsInTheEnvsRealm) { ASSERT_EQ(napi_delete_reference(s.env, record.env_global), napi_ok); } #endif -// napi_run_script in an entered sandbox realm. +// napi_run_script in an entered sandbox realm, and the realm options each +// provider honors. namespace { @@ -1054,3 +1055,23 @@ TEST_F(Test69UnofficialRealmEntry, NapiRunScriptInAnEnteredSandboxRealmUsesTheSa EXPECT_EQ(Int32Property(s.env, sandbox, "x"), 43); EXPECT_EQ(Utf8(s.env, Eval(s.env, "typeof written")), "undefined"); } + +#if defined(NAPI_TEST_ENGINE_V8) +// Only V8 honors allow_code_gen_strings. The switch belongs to the realm, so +// it holds for napi_run_script while the realm is entered. +TEST_F(Test69UnofficialRealmEntry, EnteredRealmKeepsItsStringCodeGenerationSwitch) { + EnvScope s(runtime_.get()); + unofficial_napi_realm_options options; + unofficial_napi_realm_options_init(&options); + options.allow_code_gen_strings = false; + unofficial_napi_realm realm = nullptr; + ASSERT_EQ(unofficial_napi_create_realm(s.env, &options, &realm, nullptr), napi_ok); + + const char* probe = + "(() => { try { return String(eval('1 + 1')); } catch (e) { return e.name; } })()"; + unofficial_napi_realm_scope scope = Enter(s.env, realm); + EXPECT_EQ(Utf8(s.env, Eval(s.env, probe)), "EvalError"); + Leave(s.env, scope); + EXPECT_EQ(Utf8(s.env, Eval(s.env, probe)), "2"); +} +#endif diff --git a/v8/src/unofficial_napi_contextify.cc b/v8/src/unofficial_napi_contextify.cc index 0b40d22c7c..f76ada45a5 100644 --- a/v8/src/unofficial_napi_contextify.cc +++ b/v8/src/unofficial_napi_contextify.cc @@ -1697,6 +1697,9 @@ napi_status NAPI_CDECL unofficial_napi_create_realm( if (context.IsEmpty()) return napi_pending_exception; context->SetSecurityToken(current->GetSecurityToken()); + // allow_code_gen_wasm is ignored: honoring it per realm needs an isolate + // AllowWasmCodeGenerationCallback, which this provider does not install. + // name and origin are ignored too. context->AllowCodeGenerationFromStrings(options.allow_code_gen_strings); context->SetAlignedPointerInEmbedderData(kRealmContextSlot, realm.get()); NapiV8ApplyPromiseHooksToContext(env, context); From adf36734124b71054a02d7e67c07e621e86a169f Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 13:27:13 -0800 Subject: [PATCH 034/150] Test realm entry against errors, scopes, collection and teardown test_69 covers the realm model; these 20 tests push on the paths an embedder hits once it runs pages in real realms. They cover script errors thrown in an entered realm, handle and escapable scopes opened in either order around realm scopes, three-realm nesting with a throw from the innermost native function, classes and subclasses used across realms, a function or deferred that is the only thing keeping its realm alive, compile_function with an explicit realm, growth over many entries, termination and env release with scopes open, microtasks and interrupts while entered, more value kinds, a sandbox realm's callback, recursion through two realms, tokens that stay in their env, and create_realm while another realm is current. They come from the review of this PR, minus the cases that test something else: the stale-handle case, the QuickJS sandbox two-globals case, and two engine behaviours that predate realm entry. The recursion depth is 8 so it fits QuickJS's stack limit in a Debug+ASan build, and the termination case makes a call after terminating, since V8 only notices a termination at its next interrupt check. All 20 pass on V8, QuickJS and QuickJS Debug+ASan. Co-Authored-By: Claude Opus 5.5 --- tests/CMakeLists.txt | 3 + tests/runners/test_70_realm_entry_attack.cc | 1341 +++++++++++++++++++ 2 files changed, 1344 insertions(+) create mode 100644 tests/runners/test_70_realm_entry_attack.cc diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt index 5a521af36e..cf543b9fcb 100644 --- a/tests/CMakeLists.txt +++ b/tests/CMakeLists.txt @@ -333,6 +333,9 @@ add_fixture_test(${_napi_test_prefix}_test_68_napi_calls_keep_termination add_fixture_test(${_napi_test_prefix}_test_69_unofficial_realm_entry runners/test_69_unofficial_realm_entry.cc ) +add_fixture_test(${_napi_test_prefix}_test_70_realm_entry_attack + runners/test_70_realm_entry_attack.cc +) if(_napi_test_engine STREQUAL "v8") # Only the V8 provider posts engine tasks through the enqueue hook. add_fixture_test(${_napi_test_prefix}_test_66_foreground_task_handoff diff --git a/tests/runners/test_70_realm_entry_attack.cc b/tests/runners/test_70_realm_entry_attack.cc new file mode 100644 index 0000000000..c04d106350 --- /dev/null +++ b/tests/runners/test_70_realm_entry_attack.cc @@ -0,0 +1,1341 @@ +#ifdef NAPI_MODULE +#undef NAPI_MODULE +#endif +#include "node_api.h" + +#include "test_env.h" + +#include "unofficial_napi.h" + +#include +#include + +// Realm entry under pressure: script errors, handle scopes, nesting, classes, +// realms only a function or a deferred keeps alive, termination, env release +// with scopes open, and recursion. +class Test70RealmEntryAttack : public FixtureTestBase {}; + +namespace { + +napi_value Str(napi_env env, const char* value) { + napi_value out = nullptr; + if (napi_create_string_utf8(env, value, NAPI_AUTO_LENGTH, &out) != napi_ok) return nullptr; + return out; +} + +// Runs `source` with napi_run_script, in the current realm. +napi_status EvalStatus(napi_env env, const char* source, napi_value* result) { + return napi_run_script(env, Str(env, source), result); +} + +napi_value Eval(napi_env env, const char* source) { + napi_value result = nullptr; + if (EvalStatus(env, source, &result) != napi_ok) return nullptr; + return result; +} + +// Runs `source` in `realm` (the env's own realm when null). +napi_status RunInStatus(napi_env env, + unofficial_napi_realm realm, + const char* source, + napi_value* result) { + const unofficial_napi_js_source script = unofficial_napi_js_source_from_text(Str(env, source)); + return unofficial_napi_run_script(env, realm, &script, Str(env, "realm.js"), 0, 0, -1, true, + false, false, nullptr, result); +} + +napi_value RunIn(napi_env env, unofficial_napi_realm realm, const char* source) { + napi_value result = nullptr; + if (RunInStatus(env, realm, source, &result) != napi_ok) return nullptr; + return result; +} + +bool StrictEquals(napi_env env, napi_value a, napi_value b) { + bool same = false; + return a != nullptr && b != nullptr && napi_strict_equals(env, a, b, &same) == napi_ok && same; +} + +napi_value Global(napi_env env) { + napi_value global = nullptr; + if (napi_get_global(env, &global) != napi_ok) return nullptr; + return global; +} + +napi_value Undefined(napi_env env) { + napi_value undefined = nullptr; + if (napi_get_undefined(env, &undefined) != napi_ok) return nullptr; + return undefined; +} + +std::string Utf8(napi_env env, napi_value value) { + char buffer[512] = {}; + size_t length = 0; + if (value == nullptr || + napi_get_value_string_utf8(env, value, buffer, sizeof(buffer), &length) != napi_ok) { + return ""; + } + return std::string(buffer, length); +} + +unofficial_napi_realm CreateRealm(napi_env env, + napi_value* global_out = nullptr, + napi_value sandbox = nullptr) { + unofficial_napi_realm_options options; + unofficial_napi_realm_options_init(&options); + options.sandbox_or_null = sandbox; + unofficial_napi_realm realm = nullptr; + if (unofficial_napi_create_realm(env, &options, &realm, global_out) != napi_ok) return nullptr; + return realm; +} + +unofficial_napi_realm_scope Enter(napi_env env, unofficial_napi_realm realm) { + unofficial_napi_realm_scope scope = 0; + EXPECT_EQ(unofficial_napi_enter_realm(env, realm, &scope), napi_ok); + EXPECT_NE(scope, 0u); + return scope; +} + +void Leave(napi_env env, unofficial_napi_realm_scope scope) { + EXPECT_EQ(unofficial_napi_leave_realm(env, scope), napi_ok); +} + +napi_value RefValue(napi_env env, napi_ref ref) { + napi_value value = nullptr; + napi_get_reference_value(env, ref, &value); + return value; +} + +// Checks in its own handle scope, so the check does not keep the value alive. +bool IsCollected(napi_env env, napi_ref ref) { + napi_handle_scope handles = nullptr; + if (napi_open_handle_scope(env, &handles) != napi_ok) return false; + napi_value value = nullptr; + bool collected = napi_get_reference_value(env, ref, &value) == napi_ok && value == nullptr; + napi_close_handle_scope(env, handles); + return collected; +} + +// Whether `value`'s prototype is `global[ctor].prototype`. Runs no script, so +// it works in any realm and inside callbacks. +bool ProtoIs(napi_env env, napi_value value, napi_value global, const char* ctor) { + napi_value proto = nullptr, constructor = nullptr, ctor_proto = nullptr; + if (value == nullptr || global == nullptr) return false; + if (napi_get_prototype(env, value, &proto) != napi_ok) return false; + if (napi_get_named_property(env, global, ctor, &constructor) != napi_ok) return false; + if (napi_get_named_property(env, constructor, "prototype", &ctor_proto) != napi_ok) return false; + return StrictEquals(env, proto, ctor_proto); +} + +// Takes the pending exception; null when there is none. +napi_value ClearException(napi_env env) { + napi_value error = nullptr; + bool pending = false; + if (napi_is_exception_pending(env, &pending) != napi_ok || !pending) return nullptr; + if (napi_get_and_clear_last_exception(env, &error) != napi_ok) return nullptr; + return error; +} + +napi_value ReturnUndefined(napi_env env, napi_callback_info) { + return Undefined(env); +} + +napi_value ReturnGlobal(napi_env env, napi_callback_info) { + return Global(env); +} + +void* CallbackData(napi_env env, napi_callback_info info) { + void* data = nullptr; + napi_get_cb_info(env, info, nullptr, nullptr, nullptr, &data); + return data; +} + +} // namespace + +// A script error thrown in an entered realm is still pending after leaving +// it, and is made by the realm whose code threw. +TEST_F(Test70RealmEntryAttack, JsThrowInEnteredRealmIsPendingAfterLeave) { + EnvScope s(runtime_.get()); + napi_value a_global = nullptr, b_global = nullptr; + unofficial_napi_realm a = CreateRealm(s.env, &a_global); + unofficial_napi_realm b = CreateRealm(s.env, &b_global); + ASSERT_NE(a, nullptr); + ASSERT_NE(b, nullptr); + + unofficial_napi_realm_scope scope = Enter(s.env, a); + napi_value result = nullptr; + EXPECT_EQ(EvalStatus(s.env, "throw new TypeError('t')", &result), napi_pending_exception); + Leave(s.env, scope); + napi_value error = ClearException(s.env); + ASSERT_NE(error, nullptr); + EXPECT_TRUE(ProtoIs(s.env, error, a_global, "TypeError")); + + // An error the engine makes. + scope = Enter(s.env, a); + EXPECT_EQ(EvalStatus(s.env, "null.x", &result), napi_pending_exception); + Leave(s.env, scope); + error = ClearException(s.env); + ASSERT_NE(error, nullptr); + EXPECT_TRUE(ProtoIs(s.env, error, a_global, "TypeError")); + + // Script run in B while A is entered throws B's error, and A stays current. + scope = Enter(s.env, a); + EXPECT_EQ(RunInStatus(s.env, b, "undefinedName", &result), napi_pending_exception); + EXPECT_TRUE(StrictEquals(s.env, Global(s.env), a_global)); + napi_value b_error = ClearException(s.env); + Leave(s.env, scope); + ASSERT_NE(b_error, nullptr); + EXPECT_TRUE(ProtoIs(s.env, b_error, b_global, "ReferenceError")); + + // A function of A called from the env's realm throws A's error. + napi_value thrower = RunIn(s.env, a, "(function () { return null.y; })"); + ASSERT_NE(thrower, nullptr); + EXPECT_EQ(napi_call_function(s.env, Undefined(s.env), thrower, 0, nullptr, &result), + napi_pending_exception); + error = ClearException(s.env); + ASSERT_NE(error, nullptr); + EXPECT_TRUE(ProtoIs(s.env, error, a_global, "TypeError")); +} + +// Handle scopes and realm scopes can be opened in either order, and values +// escape from inside a realm. +TEST_F(Test70RealmEntryAttack, HandleScopesInterleaveWithRealmScopes) { + EnvScope s(runtime_.get()); + napi_value env_global = Global(s.env); + napi_value a_global = nullptr, b_global = nullptr; + unofficial_napi_realm a = CreateRealm(s.env, &a_global); + unofficial_napi_realm b = CreateRealm(s.env, &b_global); + ASSERT_NE(a, nullptr); + ASSERT_NE(b, nullptr); + + // Handle scope outside, realm scope inside. + napi_handle_scope handles = nullptr; + ASSERT_EQ(napi_open_handle_scope(s.env, &handles), napi_ok); + unofficial_napi_realm_scope scope = Enter(s.env, a); + napi_value object = nullptr; + ASSERT_EQ(napi_create_object(s.env, &object), napi_ok); + Leave(s.env, scope); + EXPECT_TRUE(ProtoIs(s.env, object, a_global, "Object")); + ASSERT_EQ(napi_close_handle_scope(s.env, handles), napi_ok); + + // A value escapes from two realms deep. + napi_value escaped = nullptr; + { + napi_escapable_handle_scope esc = nullptr; + ASSERT_EQ(napi_open_escapable_handle_scope(s.env, &esc), napi_ok); + unofficial_napi_realm_scope in_a = Enter(s.env, a); + unofficial_napi_realm_scope in_b = Enter(s.env, b); + napi_value array = nullptr; + ASSERT_EQ(napi_create_array(s.env, &array), napi_ok); + ASSERT_EQ(napi_escape_handle(s.env, esc, array, &escaped), napi_ok); + Leave(s.env, in_b); + Leave(s.env, in_a); + ASSERT_EQ(napi_close_escapable_handle_scope(s.env, esc), napi_ok); + } + ASSERT_NE(escaped, nullptr); + EXPECT_TRUE(ProtoIs(s.env, escaped, b_global, "Array")); + + // Realm scope outside, handle scope opened inside and closed after leaving. + scope = Enter(s.env, a); + ASSERT_EQ(napi_open_handle_scope(s.env, &handles), napi_ok); + napi_value in_a_object = nullptr; + ASSERT_EQ(napi_create_object(s.env, &in_a_object), napi_ok); + Leave(s.env, scope); + napi_value env_object = nullptr; + ASSERT_EQ(napi_create_object(s.env, &env_object), napi_ok); + EXPECT_TRUE(ProtoIs(s.env, in_a_object, a_global, "Object")); + EXPECT_TRUE(ProtoIs(s.env, env_object, env_global, "Object")); + ASSERT_EQ(napi_close_handle_scope(s.env, handles), napi_ok); + + // An escapable scope opened inside the realm scope, escaped after leaving. + napi_value escaped_date = nullptr; + { + napi_escapable_handle_scope esc = nullptr; + scope = Enter(s.env, a); + ASSERT_EQ(napi_open_escapable_handle_scope(s.env, &esc), napi_ok); + napi_value date = nullptr; + ASSERT_EQ(napi_create_date(s.env, 1, &date), napi_ok); + Leave(s.env, scope); + ASSERT_EQ(napi_escape_handle(s.env, esc, date, &escaped_date), napi_ok); + ASSERT_EQ(napi_close_escapable_handle_scope(s.env, esc), napi_ok); + } + EXPECT_TRUE(ProtoIs(s.env, escaped_date, a_global, "Date")); + EXPECT_TRUE(StrictEquals(s.env, Global(s.env), env_global)); +} + +namespace { + +struct ThreeRealms { + napi_ref a_global = nullptr, b_global = nullptr, c_global = nullptr; + unofficial_napi_realm b = nullptr; + napi_ref js_b = nullptr; + std::vector log; +}; + +std::string WhichGlobal(napi_env env, ThreeRealms* t) { + napi_value global = Global(env); + if (StrictEquals(env, global, RefValue(env, t->a_global))) return "A"; + if (StrictEquals(env, global, RefValue(env, t->b_global))) return "B"; + if (StrictEquals(env, global, RefValue(env, t->c_global))) return "C"; + return "env"; +} + +napi_value ThrowInC(napi_env env, napi_callback_info info) { + auto* t = static_cast(CallbackData(env, info)); + t->log.push_back("C:" + WhichGlobal(env, t)); + napi_throw_error(env, "ECODE", "thrown in C"); + return nullptr; +} + +// Enters B, calls B's function (which calls C's ThrowInC), leaves B and +// rethrows C's error. +napi_value CallFromA(napi_env env, napi_callback_info info) { + auto* t = static_cast(CallbackData(env, info)); + t->log.push_back("A:" + WhichGlobal(env, t)); + unofficial_napi_realm_scope scope = 0; + if (unofficial_napi_enter_realm(env, t->b, &scope) != napi_ok) return nullptr; + t->log.push_back("A-entered:" + WhichGlobal(env, t)); + napi_value result = nullptr; + napi_status status = + napi_call_function(env, Undefined(env), RefValue(env, t->js_b), 0, nullptr, &result); + t->log.push_back("A-after-call:" + WhichGlobal(env, t) + + (status == napi_pending_exception ? ":pending" + : ":status" + std::to_string(status))); + napi_value error = ClearException(env); + t->log.push_back(std::string("A-error-from-C:") + + (ProtoIs(env, error, RefValue(env, t->c_global), "Error") ? "yes" : "no")); + if (unofficial_napi_leave_realm(env, scope) != napi_ok) t->log.push_back("A-leave-failed"); + t->log.push_back("A-left:" + WhichGlobal(env, t)); + napi_throw(env, error); + return nullptr; +} + +} // namespace + +// A's callback enters B and calls B's script, which calls C's native function +// that throws. Each frame sees its own realm, and the error is C's. +TEST_F(Test70RealmEntryAttack, NestedCallbacksAcrossThreeRealms) { + EnvScope s(runtime_.get()); + napi_value env_global = Global(s.env); + napi_value a_global = nullptr, b_global = nullptr, c_global = nullptr; + unofficial_napi_realm a = CreateRealm(s.env, &a_global); + unofficial_napi_realm b = CreateRealm(s.env, &b_global); + unofficial_napi_realm c = CreateRealm(s.env, &c_global); + ASSERT_NE(a, nullptr); + ASSERT_NE(b, nullptr); + ASSERT_NE(c, nullptr); + ThreeRealms t; + t.b = b; + ASSERT_EQ(napi_create_reference(s.env, a_global, 1, &t.a_global), napi_ok); + ASSERT_EQ(napi_create_reference(s.env, b_global, 1, &t.b_global), napi_ok); + ASSERT_EQ(napi_create_reference(s.env, c_global, 1, &t.c_global), napi_ok); + + napi_value throw_in_c = nullptr, call_from_a = nullptr; + unofficial_napi_realm_scope scope = Enter(s.env, c); + ASSERT_EQ(napi_create_function(s.env, "throwInC", NAPI_AUTO_LENGTH, ThrowInC, &t, &throw_in_c), + napi_ok); + Leave(s.env, scope); + scope = Enter(s.env, a); + ASSERT_EQ(napi_create_function(s.env, "callFromA", NAPI_AUTO_LENGTH, CallFromA, &t, &call_from_a), + napi_ok); + Leave(s.env, scope); + ASSERT_EQ(napi_set_named_property(s.env, b_global, "throwInC", throw_in_c), napi_ok); + napi_value js_b = RunIn(s.env, b, "(function jsB() { return throwInC(); })"); + ASSERT_NE(js_b, nullptr); + ASSERT_EQ(napi_create_reference(s.env, js_b, 1, &t.js_b), napi_ok); + + // Called from the env's realm. + napi_value result = nullptr; + EXPECT_EQ(napi_call_function(s.env, Undefined(s.env), call_from_a, 0, nullptr, &result), + napi_pending_exception); + EXPECT_TRUE(StrictEquals(s.env, Global(s.env), env_global)); + napi_value error = ClearException(s.env); + EXPECT_TRUE(ProtoIs(s.env, error, c_global, "Error")); + std::string joined; + for (auto& line : t.log) joined += line + ";"; + EXPECT_EQ(joined, + "A:A;A-entered:B;C:C;A-after-call:B:pending;A-error-from-C:yes;A-left:A;"); + + // Called from the env's script, which catches the error. + t.log.clear(); + ASSERT_EQ(napi_set_named_property(s.env, env_global, "callFromA", call_from_a), napi_ok); + napi_value caught = Eval(s.env, + "(() => { try { callFromA(); return 'no throw'; }" + " catch (e) { return e.message + '|' + e.code; } })()"); + EXPECT_EQ(Utf8(s.env, caught), "thrown in C|ECODE"); + EXPECT_TRUE(StrictEquals(s.env, Global(s.env), env_global)); + + for (napi_ref ref : {t.a_global, t.b_global, t.c_global, t.js_b}) + ASSERT_EQ(napi_delete_reference(s.env, ref), napi_ok); +} + +namespace { + +struct ClassRecord { + napi_ref a_global = nullptr; + bool ctor_ran_in_a = false; + int native = 1234; +}; + +void NoopFinalize(node_api_basic_env, void*, void*) {} + +napi_value WrappingCtor(napi_env env, napi_callback_info info) { + void* data = nullptr; + napi_value self = nullptr; + napi_get_cb_info(env, info, nullptr, nullptr, &self, &data); + auto* record = static_cast(data); + record->ctor_ran_in_a = StrictEquals(env, Global(env), RefValue(env, record->a_global)); + if (napi_wrap(env, self, &record->native, NoopFinalize, nullptr, nullptr) != napi_ok) { + return nullptr; + } + return self; +} + +napi_value UnwrapMethod(napi_env env, napi_callback_info info) { + napi_value self = nullptr; + napi_get_cb_info(env, info, nullptr, nullptr, &self, nullptr); + void* native = nullptr; + if (napi_unwrap(env, self, &native) != napi_ok) return nullptr; + napi_value out = nullptr; + napi_create_int32(env, *static_cast(native), &out); + return out; +} + +} // namespace + +// A class of A constructed while B is current: the constructor runs in A, +// wrap/unwrap and instanceof work across realms, and so does a subclass made +// in B. +TEST_F(Test70RealmEntryAttack, ClassOfAConstructedWhileBIsCurrent) { + EnvScope s(runtime_.get()); + napi_value a_global = nullptr, b_global = nullptr; + unofficial_napi_realm a = CreateRealm(s.env, &a_global); + unofficial_napi_realm b = CreateRealm(s.env, &b_global); + ASSERT_NE(a, nullptr); + ASSERT_NE(b, nullptr); + ClassRecord record; + ASSERT_EQ(napi_create_reference(s.env, a_global, 1, &record.a_global), napi_ok); + + const napi_property_descriptor properties[] = { + {"unwrap", nullptr, UnwrapMethod, nullptr, nullptr, nullptr, napi_default, nullptr}, + }; + napi_value thing = nullptr; + unofficial_napi_realm_scope scope = Enter(s.env, a); + ASSERT_EQ(napi_define_class(s.env, "Thing", NAPI_AUTO_LENGTH, WrappingCtor, &record, 1, + properties, &thing), + napi_ok); + Leave(s.env, scope); + napi_value thing_proto = nullptr; + ASSERT_EQ(napi_get_named_property(s.env, thing, "prototype", &thing_proto), napi_ok); + + scope = Enter(s.env, b); + napi_value instance = nullptr; + ASSERT_EQ(napi_new_instance(s.env, thing, 0, nullptr, &instance), napi_ok); + EXPECT_TRUE(record.ctor_ran_in_a); + EXPECT_TRUE(StrictEquals(s.env, Global(s.env), b_global)); + napi_value proto = nullptr; + ASSERT_EQ(napi_get_prototype(s.env, instance, &proto), napi_ok); + EXPECT_TRUE(StrictEquals(s.env, proto, thing_proto)); + void* native = nullptr; + ASSERT_EQ(napi_unwrap(s.env, instance, &native), napi_ok); + EXPECT_EQ(native, &record.native); + bool is_instance = false; + ASSERT_EQ(napi_instanceof(s.env, instance, thing, &is_instance), napi_ok); + EXPECT_TRUE(is_instance); + napi_value b_object_ctor = nullptr, a_object_ctor = nullptr; + ASSERT_EQ(napi_get_named_property(s.env, b_global, "Object", &b_object_ctor), napi_ok); + ASSERT_EQ(napi_get_named_property(s.env, a_global, "Object", &a_object_ctor), napi_ok); + ASSERT_EQ(napi_instanceof(s.env, instance, b_object_ctor, &is_instance), napi_ok); + EXPECT_FALSE(is_instance); + ASSERT_EQ(napi_instanceof(s.env, instance, a_object_ctor, &is_instance), napi_ok); + EXPECT_TRUE(is_instance); + Leave(s.env, scope); + + // A subclass made in B: the instance gets the subclass's prototype, the + // native constructor still runs in A, and the inherited method unwraps. + ASSERT_EQ(napi_set_named_property(s.env, b_global, "Thing", thing), napi_ok); + record.ctor_ran_in_a = false; + napi_value out = RunIn(s.env, b, + "class Sub extends Thing { constructor() { super(); this.sub = 1; } }" + "const x = new Sub();" + "[Object.getPrototypeOf(x) === Sub.prototype, x instanceof Thing," + " x.sub === 1, x.unwrap()].join()"); + EXPECT_EQ(Utf8(s.env, out), "true,true,true,1234"); + EXPECT_TRUE(record.ctor_ran_in_a); + ASSERT_EQ(napi_delete_reference(s.env, record.a_global), napi_ok); +} + +namespace { + +struct Rediscover { + bool got_realm = false; + bool ran_in_it = false; + bool new_function_in_it = false; +}; + +// Finds the callback's realm from its global, runs script in it and makes a +// function with it entered. +napi_value RediscoverRealm(napi_env env, napi_callback_info info) { + auto* r = static_cast(CallbackData(env, info)); + napi_value global = Global(env); + unofficial_napi_realm realm = nullptr; + if (unofficial_napi_get_realm(env, global, &realm) != napi_ok || realm == nullptr) return nullptr; + r->got_realm = true; + r->ran_in_it = StrictEquals(env, RunIn(env, realm, "globalThis"), global); + unofficial_napi_realm_scope scope = 0; + if (unofficial_napi_enter_realm(env, realm, &scope) != napi_ok) return nullptr; + napi_value fn = nullptr; + napi_create_function(env, "inner", NAPI_AUTO_LENGTH, ReturnUndefined, nullptr, &fn); + r->new_function_in_it = ProtoIs(env, fn, global, "Function"); + unofficial_napi_leave_realm(env, scope); + return global; +} + +} // namespace + +// A function whose realm is reachable only through it finds that realm again +// with get_realm, after collections and new realms, and can use it. +TEST_F(Test70RealmEntryAttack, FunctionFindsItsRealmAfterItsGlobalIsUnreachable) { + EnvScope s(runtime_.get()); + Rediscover r; + napi_ref fn_ref = nullptr; + napi_ref weak_global = nullptr; + { + napi_handle_scope handles = nullptr; + ASSERT_EQ(napi_open_handle_scope(s.env, &handles), napi_ok); + napi_value global = nullptr; + unofficial_napi_realm realm = CreateRealm(s.env, &global); + ASSERT_NE(realm, nullptr); + unofficial_napi_realm_scope scope = Enter(s.env, realm); + napi_value fn = nullptr; + ASSERT_EQ(napi_create_function(s.env, "rediscover", NAPI_AUTO_LENGTH, RediscoverRealm, &r, &fn), + napi_ok); + Leave(s.env, scope); + ASSERT_EQ(napi_create_reference(s.env, fn, 1, &fn_ref), napi_ok); + ASSERT_EQ(napi_create_reference(s.env, global, 0, &weak_global), napi_ok); + ASSERT_EQ(napi_close_handle_scope(s.env, handles), napi_ok); + } + // New realms release what collected realms left behind. + ASSERT_EQ(unofficial_napi_collect_garbage(s.env), napi_ok); + for (int i = 0; i < 4; ++i) { + napi_handle_scope handles = nullptr; + ASSERT_EQ(napi_open_handle_scope(s.env, &handles), napi_ok); + ASSERT_NE(CreateRealm(s.env), nullptr); + ASSERT_EQ(napi_close_handle_scope(s.env, handles), napi_ok); + } + ASSERT_EQ(unofficial_napi_collect_garbage(s.env), napi_ok); + + { + napi_handle_scope handles = nullptr; + ASSERT_EQ(napi_open_handle_scope(s.env, &handles), napi_ok); + napi_value fn = RefValue(s.env, fn_ref); + ASSERT_NE(fn, nullptr); + napi_value result = nullptr; + ASSERT_EQ(napi_call_function(s.env, Undefined(s.env), fn, 0, nullptr, &result), napi_ok); + EXPECT_TRUE(r.got_realm); + EXPECT_TRUE(r.ran_in_it); + EXPECT_TRUE(r.new_function_in_it); + EXPECT_TRUE(StrictEquals(s.env, result, RefValue(s.env, weak_global))); + ASSERT_EQ(napi_close_handle_scope(s.env, handles), napi_ok); + } + ASSERT_EQ(napi_delete_reference(s.env, fn_ref), napi_ok); + ASSERT_EQ(unofficial_napi_collect_garbage(s.env), napi_ok); + EXPECT_TRUE(IsCollected(s.env, weak_global)); + ASSERT_EQ(napi_delete_reference(s.env, weak_global), napi_ok); +} + +namespace { + +struct Settled { + int calls = 0; + int32_t value = 0; + bool in_env_realm = false; + napi_ref env_global = nullptr; +}; + +napi_value RecordSettled(napi_env env, napi_callback_info info) { + size_t argc = 1; + napi_value argv[1] = {}; + void* data = nullptr; + napi_get_cb_info(env, info, &argc, argv, nullptr, &data); + auto* r = static_cast(data); + r->calls++; + napi_get_value_int32(env, argv[0], &r->value); + r->in_env_realm = StrictEquals(env, Global(env), RefValue(env, r->env_global)); + return Undefined(env); +} + +} // namespace + +// A deferred of A, whose global and promise nothing else holds, is resolved +// later with B's thenable while B is entered; A is collected once settled. +TEST_F(Test70RealmEntryAttack, DeferredOfAnUnreachableRealmSettlesWithAThenable) { + EnvScope s(runtime_.get()); + Settled settled; + ASSERT_EQ(napi_create_reference(s.env, Global(s.env), 1, &settled.env_global), napi_ok); + napi_value recorder = nullptr; + ASSERT_EQ(napi_create_function(s.env, "recorder", NAPI_AUTO_LENGTH, RecordSettled, &settled, + &recorder), + napi_ok); + napi_ref recorder_ref = nullptr; + ASSERT_EQ(napi_create_reference(s.env, recorder, 1, &recorder_ref), napi_ok); + + napi_value b_global = nullptr; + unofficial_napi_realm b = CreateRealm(s.env, &b_global); + ASSERT_NE(b, nullptr); + + napi_deferred deferred = nullptr; + napi_ref weak_global = nullptr; + { + napi_handle_scope handles = nullptr; + ASSERT_EQ(napi_open_handle_scope(s.env, &handles), napi_ok); + napi_value a_global = nullptr; + unofficial_napi_realm a = CreateRealm(s.env, &a_global); + ASSERT_NE(a, nullptr); + unofficial_napi_realm_scope scope = Enter(s.env, a); + napi_value promise = nullptr; + ASSERT_EQ(napi_create_promise(s.env, &deferred, &promise), napi_ok); + napi_value then = nullptr, ignored = nullptr; + ASSERT_EQ(napi_get_named_property(s.env, promise, "then", &then), napi_ok); + napi_value reaction = RefValue(s.env, recorder_ref); + ASSERT_EQ(napi_call_function(s.env, promise, then, 1, &reaction, &ignored), napi_ok); + Leave(s.env, scope); + ASSERT_EQ(napi_create_reference(s.env, a_global, 0, &weak_global), napi_ok); + ASSERT_EQ(napi_close_handle_scope(s.env, handles), napi_ok); + } + ASSERT_EQ(unofficial_napi_collect_garbage(s.env), napi_ok); + for (int i = 0; i < 4; ++i) { + napi_handle_scope handles = nullptr; + ASSERT_EQ(napi_open_handle_scope(s.env, &handles), napi_ok); + ASSERT_NE(CreateRealm(s.env), nullptr); + ASSERT_EQ(napi_close_handle_scope(s.env, handles), napi_ok); + } + ASSERT_EQ(unofficial_napi_collect_garbage(s.env), napi_ok); + + napi_handle_scope resolve_handles = nullptr; + ASSERT_EQ(napi_open_handle_scope(s.env, &resolve_handles), napi_ok); + unofficial_napi_realm_scope scope = Enter(s.env, b); + napi_value thenable = RunIn(s.env, b, "({ then(resolve) { resolve(42); } })"); + ASSERT_NE(thenable, nullptr); + ASSERT_EQ(napi_resolve_deferred(s.env, deferred, thenable), napi_ok); + ASSERT_EQ(unofficial_napi_event_loop_checkpoint( + s.env, unofficial_napi_event_loop_checkpoint_microtasks, true, nullptr), + napi_ok); + EXPECT_TRUE(StrictEquals(s.env, Global(s.env), b_global)); + Leave(s.env, scope); + EXPECT_EQ(settled.calls, 1); + EXPECT_EQ(settled.value, 42); + EXPECT_TRUE(settled.in_env_realm); + ASSERT_EQ(napi_close_handle_scope(s.env, resolve_handles), napi_ok); + + ASSERT_EQ(napi_delete_reference(s.env, recorder_ref), napi_ok); + ASSERT_EQ(unofficial_napi_collect_garbage(s.env), napi_ok); + ASSERT_EQ(unofficial_napi_event_loop_checkpoint( + s.env, unofficial_napi_event_loop_checkpoint_microtasks, true, nullptr), + napi_ok); + ASSERT_EQ(unofficial_napi_collect_garbage(s.env), napi_ok); + EXPECT_TRUE(IsCollected(s.env, weak_global)); + ASSERT_EQ(napi_delete_reference(s.env, weak_global), napi_ok); + ASSERT_EQ(napi_delete_reference(s.env, settled.env_global), napi_ok); +} + +// compile_function compiles in the realm it is given, not the current one: a +// NULL realm is the env's even while B is entered. +TEST_F(Test70RealmEntryAttack, CompileFunctionTakesItsRealmExplicitly) { + EnvScope s(runtime_.get()); + napi_value env_global = Global(s.env); + napi_value a_global = nullptr, b_global = nullptr; + unofficial_napi_realm a = CreateRealm(s.env, &a_global); + unofficial_napi_realm b = CreateRealm(s.env, &b_global); + ASSERT_NE(a, nullptr); + ASSERT_NE(b, nullptr); + + unofficial_napi_realm_scope scope = Enter(s.env, b); + // Compiles `return globalThis;` in `realm` and returns what calling it gives. + auto compile = [&](unofficial_napi_realm realm) { + const unofficial_napi_js_source source = + unofficial_napi_js_source_from_text(Str(s.env, "return globalThis;")); + napi_value fn = nullptr; + EXPECT_EQ(unofficial_napi_compile_function(s.env, realm, &source, Str(s.env, "f.js"), 0, 0, + Undefined(s.env), Undefined(s.env), nullptr, &fn), + napi_ok); + napi_value out = nullptr; + if (fn == nullptr) return out; + // The result may be the function or a record holding it. + napi_valuetype type = napi_undefined; + napi_typeof(s.env, fn, &type); + if (type != napi_function) napi_get_named_property(s.env, fn, "function", &fn); + EXPECT_EQ(napi_call_function(s.env, Undefined(s.env), fn, 0, nullptr, &out), napi_ok); + return out; + }; + EXPECT_TRUE(StrictEquals(s.env, compile(nullptr), env_global)); + EXPECT_TRUE(StrictEquals(s.env, compile(a), a_global)); + EXPECT_TRUE(StrictEquals(s.env, Global(s.env), b_global)); + Leave(s.env, scope); +} + +namespace { + +struct LoopRecord { + unofficial_napi_realm b = nullptr; + int calls = 0; +}; + +// Enters B and returns without leaving it. +napi_value EnterBAndReturn(napi_env env, napi_callback_info info) { + auto* r = static_cast(CallbackData(env, info)); + r->calls++; + unofficial_napi_realm_scope scope = 0; + unofficial_napi_enter_realm(env, r->b, &scope); + napi_value object = nullptr; + napi_create_object(env, &object); + return object; +} + +unofficial_napi_heap_statistics Stats(napi_env env) { + unofficial_napi_heap_statistics stats; + unofficial_napi_heap_statistics_init(&stats); + EXPECT_EQ(unofficial_napi_get_heap_statistics(env, &stats), napi_ok); + return stats; +} + +} // namespace + +// Many enter/leave cycles and calls of a callback that leaves its scope open +// keep no frames, handles or heap behind. +TEST_F(Test70RealmEntryAttack, ManyEntriesAndCallsDoNotGrow) { + EnvScope s(runtime_.get()); + napi_value a_global = nullptr, b_global = nullptr; + unofficial_napi_realm a = CreateRealm(s.env, &a_global); + unofficial_napi_realm b = CreateRealm(s.env, &b_global); + ASSERT_NE(a, nullptr); + ASSERT_NE(b, nullptr); + LoopRecord record; + record.b = b; + napi_value fn = nullptr; + unofficial_napi_realm_scope scope = Enter(s.env, a); + ASSERT_EQ(napi_create_function(s.env, "enterB", NAPI_AUTO_LENGTH, EnterBAndReturn, &record, &fn), + napi_ok); + Leave(s.env, scope); + ASSERT_EQ(napi_set_named_property(s.env, b_global, "enterB", fn), napi_ok); + napi_value loop_in_b = + RunIn(s.env, b, "(function (n) { for (let i = 0; i < n; i++) enterB(); })"); + ASSERT_NE(loop_in_b, nullptr); + + // n cycles from native code, then n calls from B's script. + auto round = [&](int n) { + for (int i = 0; i < n; ++i) { + napi_handle_scope handles = nullptr; + ASSERT_EQ(napi_open_handle_scope(s.env, &handles), napi_ok); + unofficial_napi_realm_scope in_a = Enter(s.env, a); + napi_value object = nullptr; + ASSERT_EQ(napi_create_object(s.env, &object), napi_ok); + unofficial_napi_realm_scope in_b = Enter(s.env, b); + napi_value result = nullptr; + ASSERT_EQ(napi_call_function(s.env, Undefined(s.env), fn, 0, nullptr, &result), napi_ok); + Leave(s.env, in_b); + Leave(s.env, in_a); + ASSERT_EQ(napi_close_handle_scope(s.env, handles), napi_ok); + } + napi_handle_scope handles = nullptr; + ASSERT_EQ(napi_open_handle_scope(s.env, &handles), napi_ok); + napi_value count = nullptr, result = nullptr; + ASSERT_EQ(napi_create_int32(s.env, n, &count), napi_ok); + ASSERT_EQ(napi_call_function(s.env, Undefined(s.env), loop_in_b, 1, &count, &result), napi_ok); + ASSERT_EQ(napi_close_handle_scope(s.env, handles), napi_ok); + }; + + round(2000); + ASSERT_EQ(unofficial_napi_collect_garbage(s.env), napi_ok); + const unofficial_napi_heap_statistics before = Stats(s.env); + round(50000); + ASSERT_EQ(unofficial_napi_collect_garbage(s.env), napi_ok); + const unofficial_napi_heap_statistics after = Stats(s.env); + EXPECT_EQ(record.calls, 2 * (2000 + 50000)); + // 256 KiB of noise; 100,000 leaked frames would be far more. + EXPECT_LT(after.used_heap_size, before.used_heap_size + 256 * 1024); + if (after.valid_fields & unofficial_napi_heap_stat_used_global_handles_size) { + EXPECT_LE(after.used_global_handles_size, before.used_global_handles_size + 4096); + } +} + +namespace { + +struct TerminateRecord { + unofficial_napi_realm b = nullptr; + napi_status enter = napi_generic_failure; +}; + +// Enters B, terminates, and returns with B still entered. +napi_value EnterBAndTerminate(napi_env env, napi_callback_info info) { + auto* r = static_cast(CallbackData(env, info)); + unofficial_napi_realm_scope scope = 0; + r->enter = unofficial_napi_enter_realm(env, r->b, &scope); + unofficial_napi_terminate_execution(env); + return nullptr; +} + +} // namespace + +// Termination with a realm entered: leaving still works, the env's realm is +// current again, and entering works once termination is cancelled. +TEST_F(Test70RealmEntryAttack, TerminationWithARealmScopeOpen) { + EnvScope s(runtime_.get()); + napi_value env_global = Global(s.env); + napi_value a_global = nullptr, b_global = nullptr; + unofficial_napi_realm a = CreateRealm(s.env, &a_global); + unofficial_napi_realm b = CreateRealm(s.env, &b_global); + ASSERT_NE(a, nullptr); + ASSERT_NE(b, nullptr); + + unofficial_napi_realm_scope scope = Enter(s.env, a); + ASSERT_EQ(unofficial_napi_terminate_execution(s.env), napi_ok); + napi_value result = nullptr; + EXPECT_NE(EvalStatus(s.env, "1", &result), napi_ok); + Leave(s.env, scope); + ASSERT_EQ(unofficial_napi_cancel_terminate_execution(s.env), napi_ok); + ClearException(s.env); + EXPECT_TRUE(StrictEquals(s.env, Global(s.env), env_global)); + EXPECT_TRUE(StrictEquals(s.env, Eval(s.env, "globalThis"), env_global)); + scope = Enter(s.env, a); + EXPECT_TRUE(StrictEquals(s.env, Eval(s.env, "globalThis"), a_global)); + Leave(s.env, scope); + + // A callback of A, called from A's script, enters B and terminates. + TerminateRecord record; + record.b = b; + napi_value fn = nullptr; + scope = Enter(s.env, a); + ASSERT_EQ(napi_create_function(s.env, "term", NAPI_AUTO_LENGTH, EnterBAndTerminate, &record, + &fn), + napi_ok); + Leave(s.env, scope); + ASSERT_EQ(napi_set_named_property(s.env, a_global, "term", fn), napi_ok); + // V8 notices a termination at its next interrupt check, such as a call. + EXPECT_NE(RunInStatus(s.env, a, "term(); (() => {})(); globalThis.after = 1;", &result), + napi_ok); + EXPECT_EQ(record.enter, napi_ok); + EXPECT_TRUE(StrictEquals(s.env, Global(s.env), env_global)); + ASSERT_EQ(unofficial_napi_cancel_terminate_execution(s.env), napi_ok); + ClearException(s.env); + EXPECT_EQ(Utf8(s.env, RunIn(s.env, a, "String(globalThis.after)")), "undefined"); + scope = Enter(s.env, b); + EXPECT_TRUE(StrictEquals(s.env, Eval(s.env, "globalThis"), b_global)); + Leave(s.env, scope); +} + +// Releasing the env, outside any callback, with realm scopes still open; then +// also a deferred, a pending exception and a handle scope. +TEST_F(Test70RealmEntryAttack, EnvReleasedWithScopesOpen) { + for (int variant = 0; variant < 4; ++variant) { + SCOPED_TRACE(variant); + EnvScope s(runtime_.get()); + napi_value a_global = nullptr, b_global = nullptr; + unofficial_napi_realm a = CreateRealm(s.env, &a_global); + unofficial_napi_realm b = CreateRealm(s.env, &b_global); + ASSERT_NE(a, nullptr); + ASSERT_NE(b, nullptr); + Enter(s.env, a); + Enter(s.env, b); + if (variant >= 1) Enter(s.env, nullptr); + if (variant >= 2) { + Enter(s.env, b); + napi_deferred deferred = nullptr; + napi_value promise = nullptr; + ASSERT_EQ(napi_create_promise(s.env, &deferred, &promise), napi_ok); + napi_throw_error(s.env, nullptr, "left pending"); + } + if (variant >= 3) { + napi_handle_scope handles = nullptr; + ASSERT_EQ(napi_open_handle_scope(s.env, &handles), napi_ok); + napi_value object = nullptr; + ASSERT_EQ(napi_create_object(s.env, &object), napi_ok); + } + // ~EnvScope releases the env. + } +} + +namespace { + +struct ReactionRecord { + napi_ref b_global = nullptr; + bool ran_in_b = false; + int calls = 0; +}; + +napi_value ReactionInB(napi_env env, napi_callback_info info) { + auto* r = static_cast(CallbackData(env, info)); + r->calls++; + r->ran_in_b = StrictEquals(env, Global(env), RefValue(env, r->b_global)); + return Undefined(env); +} + +int g_interrupt_calls = 0; +bool g_interrupt_in_env = false; +napi_ref g_env_global = nullptr; + +void InterruptProbe(napi_env env, void*) { + g_interrupt_calls++; + g_interrupt_in_env = StrictEquals(env, Global(env), RefValue(env, g_env_global)); +} + +} // namespace + +// Microtasks drained while A is entered run native reactions in their own +// realm, interrupts run in the env's realm, and A is current afterwards. +TEST_F(Test70RealmEntryAttack, MicrotasksAndInterruptsWhileEntered) { + EnvScope s(runtime_.get()); + napi_value env_global = Global(s.env); + napi_value a_global = nullptr, b_global = nullptr; + unofficial_napi_realm a = CreateRealm(s.env, &a_global); + unofficial_napi_realm b = CreateRealm(s.env, &b_global); + ASSERT_NE(a, nullptr); + ASSERT_NE(b, nullptr); + ReactionRecord record; + ASSERT_EQ(napi_create_reference(s.env, b_global, 1, &record.b_global), napi_ok); + napi_value reaction = nullptr; + unofficial_napi_realm_scope scope = Enter(s.env, b); + ASSERT_EQ(napi_create_function(s.env, "reaction", NAPI_AUTO_LENGTH, ReactionInB, &record, + &reaction), + napi_ok); + Leave(s.env, scope); + + scope = Enter(s.env, a); + napi_deferred deferred = nullptr; + napi_value promise = nullptr; + ASSERT_EQ(napi_create_promise(s.env, &deferred, &promise), napi_ok); + napi_value then = nullptr, ignored = nullptr; + ASSERT_EQ(napi_get_named_property(s.env, promise, "then", &then), napi_ok); + ASSERT_EQ(napi_call_function(s.env, promise, then, 1, &reaction, &ignored), napi_ok); + ASSERT_EQ(napi_resolve_deferred(s.env, deferred, Undefined(s.env)), napi_ok); + ASSERT_EQ(unofficial_napi_event_loop_checkpoint( + s.env, unofficial_napi_event_loop_checkpoint_microtasks, true, nullptr), + napi_ok); + EXPECT_EQ(record.calls, 1); + EXPECT_TRUE(record.ran_in_b); + EXPECT_TRUE(StrictEquals(s.env, Global(s.env), a_global)); + + ASSERT_EQ(napi_create_reference(s.env, env_global, 1, &g_env_global), napi_ok); + g_interrupt_calls = 0; + g_interrupt_in_env = false; + ASSERT_EQ(unofficial_napi_request_interrupt(s.env, InterruptProbe, nullptr), napi_ok); + napi_value result = nullptr; + ASSERT_EQ(EvalStatus(s.env, "let n = 0; for (let i = 0; i < 2e6; i++) n += i; n", &result), + napi_ok); + EXPECT_EQ(g_interrupt_calls, 1); + EXPECT_TRUE(g_interrupt_in_env); + EXPECT_TRUE(StrictEquals(s.env, Global(s.env), a_global)); + Leave(s.env, scope); + ASSERT_EQ(napi_delete_reference(s.env, g_env_global), napi_ok); + g_env_global = nullptr; + ASSERT_EQ(napi_delete_reference(s.env, record.b_global), napi_ok); +} + +// An open scope keeps its realm alive after every handle and reference to it +// is gone; the realm is collected once the scope is left. +TEST_F(Test70RealmEntryAttack, OpenScopeKeepsItsRealmAlive) { + EnvScope s(runtime_.get()); + napi_value env_global = Global(s.env); + napi_ref weak_global = nullptr; + unofficial_napi_realm_scope scope = 0; + { + napi_handle_scope handles = nullptr; + ASSERT_EQ(napi_open_handle_scope(s.env, &handles), napi_ok); + napi_value global = nullptr; + unofficial_napi_realm realm = CreateRealm(s.env, &global); + ASSERT_NE(realm, nullptr); + ASSERT_NE(RunIn(s.env, realm, "globalThis.marker = 'alive'; 1"), nullptr); + ASSERT_EQ(napi_create_reference(s.env, global, 0, &weak_global), napi_ok); + scope = Enter(s.env, realm); + ASSERT_EQ(napi_close_handle_scope(s.env, handles), napi_ok); + } + ASSERT_EQ(unofficial_napi_collect_garbage(s.env), napi_ok); + for (int i = 0; i < 4; ++i) { + napi_handle_scope handles = nullptr; + ASSERT_EQ(napi_open_handle_scope(s.env, &handles), napi_ok); + unofficial_napi_realm_scope env_scope = Enter(s.env, nullptr); + ASSERT_NE(CreateRealm(s.env), nullptr); + Leave(s.env, env_scope); + ASSERT_EQ(napi_close_handle_scope(s.env, handles), napi_ok); + } + ASSERT_EQ(unofficial_napi_collect_garbage(s.env), napi_ok); + EXPECT_FALSE(IsCollected(s.env, weak_global)); + { + napi_handle_scope handles = nullptr; + ASSERT_EQ(napi_open_handle_scope(s.env, &handles), napi_ok); + EXPECT_EQ(Utf8(s.env, Eval(s.env, "globalThis.marker")), "alive"); + unofficial_napi_realm found = nullptr; + ASSERT_EQ(unofficial_napi_get_realm(s.env, Global(s.env), &found), napi_ok); + EXPECT_NE(found, nullptr); + ASSERT_EQ(napi_close_handle_scope(s.env, handles), napi_ok); + } + Leave(s.env, scope); + EXPECT_TRUE(StrictEquals(s.env, Global(s.env), env_global)); + ASSERT_EQ(unofficial_napi_collect_garbage(s.env), napi_ok); + EXPECT_TRUE(IsCollected(s.env, weak_global)); + ASSERT_EQ(napi_delete_reference(s.env, weak_global), napi_ok); +} + +// More values made with a realm entered come from it: objects from coercion, +// property name arrays, DataView, typed arrays, an external ArrayBuffer, a +// Buffer and range errors, made or thrown. +TEST_F(Test70RealmEntryAttack, MoreValuesComeFromTheEnteredRealm) { + EnvScope s(runtime_.get()); + napi_value a_global = nullptr; + unofficial_napi_realm a = CreateRealm(s.env, &a_global); + ASSERT_NE(a, nullptr); + napi_value env_object = nullptr; + ASSERT_EQ(napi_create_object(s.env, &env_object), napi_ok); + ASSERT_EQ(napi_set_named_property(s.env, env_object, "k", Str(s.env, "v")), napi_ok); + + unofficial_napi_realm_scope scope = Enter(s.env, a); + // Names what failed or is not from A. + std::vector wrong; + auto check = [&](const char* name, napi_status status, napi_value value, const char* ctor) { + if (status != napi_ok) { + wrong.push_back(std::string(name) + ":status" + std::to_string(status)); + ClearException(s.env); + return; + } + if (!ProtoIs(s.env, value, a_global, ctor)) wrong.push_back(name); + }; + napi_value v = nullptr, number = nullptr; + ASSERT_EQ(napi_create_int32(s.env, 3, &number), napi_ok); + check("coerce number", napi_coerce_to_object(s.env, number, &v), v, "Number"); + v = nullptr; + check("coerce string", napi_coerce_to_object(s.env, Str(s.env, "x"), &v), v, "String"); + v = nullptr; + check("property names", napi_get_property_names(s.env, env_object, &v), v, "Array"); + v = nullptr; + check("all property names", + napi_get_all_property_names(s.env, env_object, napi_key_own_only, napi_key_enumerable, + napi_key_keep_numbers, &v), + v, "Array"); + napi_value ab = nullptr; + ASSERT_EQ(napi_create_arraybuffer(s.env, 16, nullptr, &ab), napi_ok); + v = nullptr; + check("dataview", napi_create_dataview(s.env, 8, ab, 0, &v), v, "DataView"); + v = nullptr; + check("bigint64array", napi_create_typedarray(s.env, napi_bigint64_array, 1, ab, 0, &v), v, + "BigInt64Array"); + v = nullptr; + check("float64array", napi_create_typedarray(s.env, napi_float64_array, 1, ab, 0, &v), v, + "Float64Array"); + static char external_bytes[16]; + v = nullptr; + napi_status status = napi_create_external_arraybuffer(s.env, external_bytes, + sizeof(external_bytes), nullptr, nullptr, + &v); + // Providers may refuse external buffers. + if (status != napi_no_external_buffers_allowed) { + check("external arraybuffer", status, v, "ArrayBuffer"); + } + v = nullptr; + check("range error", napi_create_range_error(s.env, nullptr, Str(s.env, "r"), &v), v, + "RangeError"); + // Whatever a Buffer's prototype chain, it ends in A's Uint8Array. + void* data = nullptr; + v = nullptr; + status = napi_create_buffer(s.env, 4, &data, &v); + if (status == napi_ok) { + napi_value uint8_array = nullptr; + bool is_instance = false; + napi_get_named_property(s.env, a_global, "Uint8Array", &uint8_array); + napi_instanceof(s.env, v, uint8_array, &is_instance); + if (!is_instance) wrong.push_back("buffer"); + } else { + wrong.push_back("buffer:status" + std::to_string(status)); + } + napi_throw_range_error(s.env, nullptr, "thrown"); + napi_value thrown = ClearException(s.env); + if (!ProtoIs(s.env, thrown, a_global, "RangeError")) wrong.push_back("thrown range error"); + Leave(s.env, scope); + std::string joined; + for (auto& name : wrong) joined += name + ","; + EXPECT_EQ(joined, ""); +} + +namespace { + +struct SandboxProbe { + napi_ref sandbox = nullptr; + bool global_is_sandbox = false; + bool found_realm = false; +}; + +napi_value ProbeSandbox(napi_env env, napi_callback_info info) { + auto* p = static_cast(CallbackData(env, info)); + napi_value global = Global(env); + p->global_is_sandbox = StrictEquals(env, global, RefValue(env, p->sandbox)); + unofficial_napi_realm realm = nullptr; + p->found_realm = unofficial_napi_get_realm(env, global, &realm) == napi_ok && realm != nullptr; + return global; +} + +} // namespace + +// A native function of a sandbox realm sees the sandbox as its global, and +// get_realm finds the realm from it. +TEST_F(Test70RealmEntryAttack, SandboxRealmCallbackSeesItsSandbox) { + EnvScope s(runtime_.get()); + napi_value sandbox = nullptr; + ASSERT_EQ(napi_create_object(s.env, &sandbox), napi_ok); + unofficial_napi_realm realm = CreateRealm(s.env, nullptr, sandbox); + ASSERT_NE(realm, nullptr); + SandboxProbe probe; + ASSERT_EQ(napi_create_reference(s.env, sandbox, 1, &probe.sandbox), napi_ok); + unofficial_napi_realm_scope scope = Enter(s.env, realm); + napi_value fn = nullptr; + ASSERT_EQ(napi_create_function(s.env, "probe", NAPI_AUTO_LENGTH, ProbeSandbox, &probe, &fn), + napi_ok); + Leave(s.env, scope); + napi_value result = nullptr; + ASSERT_EQ(napi_call_function(s.env, Undefined(s.env), fn, 0, nullptr, &result), napi_ok); + EXPECT_TRUE(probe.global_is_sandbox); + EXPECT_TRUE(probe.found_realm); + ASSERT_EQ(napi_delete_reference(s.env, probe.sandbox), napi_ok); +} + +namespace { + +// QuickJS's 1 MiB stack limit fits about 11 levels in a Debug+ASan build. +constexpr int32_t kRecursionDepth = 8; + +struct Recur { + unofficial_napi_realm b = nullptr; + napi_ref a_global = nullptr, b_global = nullptr, js_b = nullptr; + int bad = 0; + int32_t deepest = kRecursionDepth + 1; +}; + +// Enters B and calls B's script, which calls this again with depth - 1. +// Leaves every other level's scope open for the callback's return to close. +napi_value RecurseA(napi_env env, napi_callback_info info) { + size_t argc = 1; + napi_value argv[1] = {}; + void* data = nullptr; + napi_get_cb_info(env, info, &argc, argv, nullptr, &data); + auto* r = static_cast(data); + int32_t depth = 0; + napi_get_value_int32(env, argv[0], &depth); + if (depth < r->deepest) r->deepest = depth; + if (!StrictEquals(env, Global(env), RefValue(env, r->a_global))) r->bad++; + if (depth == 0) return Undefined(env); + unofficial_napi_realm_scope scope = 0; + unofficial_napi_enter_realm(env, r->b, &scope); + if (!StrictEquals(env, Global(env), RefValue(env, r->b_global))) r->bad++; + napi_value next = nullptr, out = nullptr; + napi_create_int32(env, depth - 1, &next); + napi_call_function(env, Undefined(env), RefValue(env, r->js_b), 1, &next, &out); + if (!StrictEquals(env, Global(env), RefValue(env, r->b_global))) r->bad++; + if (depth % 2 == 0) { + if (unofficial_napi_leave_realm(env, scope) != napi_ok) r->bad++; + if (!StrictEquals(env, Global(env), RefValue(env, r->a_global))) r->bad++; + } + return out; +} + +} // namespace + +// Recursion through two realms: every level sees the right realm, and the +// env's realm is current at the end. +TEST_F(Test70RealmEntryAttack, RecursionThroughRealms) { + EnvScope s(runtime_.get()); + napi_value env_global = Global(s.env); + napi_value a_global = nullptr, b_global = nullptr; + unofficial_napi_realm a = CreateRealm(s.env, &a_global); + unofficial_napi_realm b = CreateRealm(s.env, &b_global); + ASSERT_NE(a, nullptr); + ASSERT_NE(b, nullptr); + Recur r; + r.b = b; + ASSERT_EQ(napi_create_reference(s.env, a_global, 1, &r.a_global), napi_ok); + ASSERT_EQ(napi_create_reference(s.env, b_global, 1, &r.b_global), napi_ok); + napi_value fn = nullptr; + unofficial_napi_realm_scope scope = Enter(s.env, a); + ASSERT_EQ(napi_create_function(s.env, "recurse", NAPI_AUTO_LENGTH, RecurseA, &r, &fn), napi_ok); + Leave(s.env, scope); + ASSERT_EQ(napi_set_named_property(s.env, b_global, "recurse", fn), napi_ok); + napi_value js_b = RunIn(s.env, b, "(function (n) { return recurse(n); })"); + ASSERT_NE(js_b, nullptr); + ASSERT_EQ(napi_create_reference(s.env, js_b, 1, &r.js_b), napi_ok); + napi_value start = nullptr, out = nullptr; + ASSERT_EQ(napi_create_int32(s.env, kRecursionDepth, &start), napi_ok); + EXPECT_EQ(napi_call_function(s.env, Undefined(s.env), fn, 1, &start, &out), napi_ok); + EXPECT_EQ(r.deepest, 0); + EXPECT_EQ(r.bad, 0); + EXPECT_TRUE(StrictEquals(s.env, Global(s.env), env_global)); + for (napi_ref ref : {r.a_global, r.b_global, r.js_b}) + ASSERT_EQ(napi_delete_reference(s.env, ref), napi_ok); +} + +// A realm of one env cannot be entered on another, and a scope token of one +// env cannot be left on another. +TEST_F(Test70RealmEntryAttack, RealmsAndTokensStayInTheirEnv) { + EnvScope s1(runtime_.get()); + unofficial_napi_realm r1 = CreateRealm(s1.env); + ASSERT_NE(r1, nullptr); + unofficial_napi_realm_scope t1 = Enter(s1.env, r1); + { + EnvScope s2(runtime_.get()); + unofficial_napi_realm_scope scope = 0; + EXPECT_EQ(unofficial_napi_enter_realm(s2.env, r1, &scope), napi_invalid_arg); + EXPECT_EQ(unofficial_napi_leave_realm(s2.env, t1), napi_invalid_arg); + } + Leave(s1.env, t1); +} + +namespace { + +struct MakeInB { + unofficial_napi_realm b = nullptr; + napi_ref made = nullptr; +}; + +// Makes a function with B entered and returns it. +napi_value MakeFunctionInB(napi_env env, napi_callback_info info) { + auto* m = static_cast(CallbackData(env, info)); + unofficial_napi_realm_scope scope = 0; + unofficial_napi_enter_realm(env, m->b, &scope); + napi_value fn = nullptr; + napi_create_function(env, "inB", NAPI_AUTO_LENGTH, ReturnGlobal, nullptr, &fn); + napi_create_reference(env, fn, 1, &m->made); + unofficial_napi_leave_realm(env, scope); + return fn; +} + +} // namespace + +// A function made in A's callback with B entered is B's, and runs in B +// wherever it is called from. +TEST_F(Test70RealmEntryAttack, FunctionMadeInsideACallbackWithAnotherRealmEntered) { + EnvScope s(runtime_.get()); + napi_value a_global = nullptr, b_global = nullptr; + unofficial_napi_realm a = CreateRealm(s.env, &a_global); + unofficial_napi_realm b = CreateRealm(s.env, &b_global); + ASSERT_NE(a, nullptr); + ASSERT_NE(b, nullptr); + MakeInB m; + m.b = b; + napi_value maker = nullptr; + unofficial_napi_realm_scope scope = Enter(s.env, a); + ASSERT_EQ(napi_create_function(s.env, "maker", NAPI_AUTO_LENGTH, MakeFunctionInB, &m, &maker), + napi_ok); + Leave(s.env, scope); + napi_value made = nullptr; + ASSERT_EQ(napi_call_function(s.env, Undefined(s.env), maker, 0, nullptr, &made), napi_ok); + EXPECT_TRUE(ProtoIs(s.env, made, b_global, "Function")); + napi_value got = nullptr; + ASSERT_EQ(napi_call_function(s.env, Undefined(s.env), made, 0, nullptr, &got), napi_ok); + EXPECT_TRUE(StrictEquals(s.env, got, b_global)); + ASSERT_EQ(napi_set_named_property(s.env, a_global, "inB", made), napi_ok); + EXPECT_TRUE(StrictEquals(s.env, RunIn(s.env, a, "inB()"), b_global)); + ASSERT_EQ(napi_delete_reference(s.env, m.made), napi_ok); +} + +namespace { + +struct CreateInside { + bool ok = false; +}; + +// Makes a realm and checks it has its own intrinsics and leaves the current +// realm alone. +napi_value CreateRealmInside(napi_env env, napi_callback_info info) { + auto* c = static_cast(CallbackData(env, info)); + napi_value before = Global(env); + napi_value global = nullptr; + unofficial_napi_realm realm = CreateRealm(env, &global); + napi_value own = + RunIn(env, realm, "Object.getPrototypeOf({}) === Object.prototype && globalThis"); + c->ok = realm != nullptr && StrictEquals(env, own, global) && + StrictEquals(env, Global(env), before) && !StrictEquals(env, global, before); + return global; +} + +} // namespace + +// create_realm while another realm is entered, or inside one of its +// callbacks, makes a realm with its own intrinsics and leaves the current +// realm unchanged. +TEST_F(Test70RealmEntryAttack, CreateRealmWhileAnotherIsCurrent) { + EnvScope s(runtime_.get()); + napi_value a_global = nullptr; + unofficial_napi_realm a = CreateRealm(s.env, &a_global); + ASSERT_NE(a, nullptr); + unofficial_napi_realm_scope scope = Enter(s.env, a); + napi_value c_global = nullptr; + unofficial_napi_realm c = CreateRealm(s.env, &c_global); + ASSERT_NE(c, nullptr); + EXPECT_TRUE(StrictEquals(s.env, Global(s.env), a_global)); + Leave(s.env, scope); + EXPECT_TRUE(StrictEquals(s.env, RunIn(s.env, c, "globalThis"), c_global)); + EXPECT_EQ(Utf8(s.env, RunIn(s.env, c, + "String(Object.getPrototypeOf(globalThis) !== null &&" + " Object.getPrototypeOf({}) === Object.prototype)")), + "true"); + ASSERT_EQ(napi_set_named_property(s.env, c_global, "aGlobal", a_global), napi_ok); + EXPECT_EQ(Utf8(s.env, RunIn(s.env, c, "String(aGlobal.Object !== Object)")), "true"); + + CreateInside inside; + napi_value fn = nullptr; + scope = Enter(s.env, a); + ASSERT_EQ(napi_create_function(s.env, "mk", NAPI_AUTO_LENGTH, CreateRealmInside, &inside, &fn), + napi_ok); + Leave(s.env, scope); + napi_value result = nullptr; + ASSERT_EQ(napi_call_function(s.env, Undefined(s.env), fn, 0, nullptr, &result), napi_ok); + EXPECT_TRUE(inside.ok); +} + +namespace { + +struct CleanupRecord { + napi_env env = nullptr; + napi_ref env_global = nullptr; + bool ran = false; + bool in_env_realm = false; +}; + +CleanupRecord g_cleanup; + +void CleanupHook(void* arg) { + auto* c = static_cast(arg); + c->ran = true; + napi_handle_scope handles = nullptr; + napi_open_handle_scope(c->env, &handles); + c->in_env_realm = StrictEquals(c->env, Global(c->env), RefValue(c->env, c->env_global)); + napi_close_handle_scope(c->env, handles); +} + +} // namespace + +// An env released with a realm entered runs its cleanup hooks in its own +// realm. +TEST_F(Test70RealmEntryAttack, CleanupHooksRunInTheEnvRealmWithScopesOpen) { + g_cleanup = CleanupRecord{}; + { + EnvScope s(runtime_.get()); + g_cleanup.env = s.env; + ASSERT_EQ(napi_create_reference(s.env, Global(s.env), 1, &g_cleanup.env_global), napi_ok); + ASSERT_EQ(napi_add_env_cleanup_hook(s.env, CleanupHook, &g_cleanup), napi_ok); + unofficial_napi_realm a = CreateRealm(s.env); + ASSERT_NE(a, nullptr); + Enter(s.env, a); + } + EXPECT_TRUE(g_cleanup.ran); + EXPECT_TRUE(g_cleanup.in_env_realm); +} + +// Entering and leaving keep a pending exception pending. +TEST_F(Test70RealmEntryAttack, EnterAndLeaveWithAPendingException) { + EnvScope s(runtime_.get()); + napi_value a_global = nullptr; + unofficial_napi_realm a = CreateRealm(s.env, &a_global); + ASSERT_NE(a, nullptr); + napi_throw_error(s.env, nullptr, "pending"); + unofficial_napi_realm_scope scope = 0; + ASSERT_EQ(unofficial_napi_enter_realm(s.env, a, &scope), napi_ok); + EXPECT_TRUE(StrictEquals(s.env, Global(s.env), a_global)); + Leave(s.env, scope); + EXPECT_NE(ClearException(s.env), nullptr); +} From a6d8781c7f6bd13f0d34b3f0d8c90c6b657e6224 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 13:35:20 -0800 Subject: [PATCH 035/150] host-JS: test the realm imports from a guest The bridge's enter_realm and leave_realm had tests, but the guest imports WebkitWasm calls in a tab did not: the token written to guest memory as a u64, the i64 it comes back as, and the scope closed again when the token cannot be written. A WAT guest now calls the imports through register_napi_imports, as an instantiated module does. It enters a realm by id and finds its global with napi_get_global, then leaves with the token it read from its memory. A token above 2^63 round-trips, and one differing only in the sign bit is refused. A pointer past the end of memory, or 0, leaves nothing entered. Co-Authored-By: Claude Opus 5.5 --- src/snapi_js.rs | 121 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 121 insertions(+) diff --git a/src/snapi_js.rs b/src/snapi_js.rs index 4f346f5ab7..d97bd87066 100644 --- a/src/snapi_js.rs +++ b/src/snapi_js.rs @@ -8861,4 +8861,125 @@ mod tests { drop(retained); assert_eq!(wasm_bindgen::externref_heap_live_count(), before); } + + /// A guest that uses the realm imports as a C guest does: the scope token + /// comes back through its memory as a u64 and goes out again as an i64. + const REALM_GUEST: &str = r#" + (module + (import "env" "memory" (memory 1)) + (import "napi_extension_wasmer_v0" "unofficial_napi_enter_realm" + (func $enter (param i32 i32 i32) (result i32))) + (import "napi_extension_wasmer_v0" "unofficial_napi_leave_realm" + (func $leave (param i32 i64) (result i32))) + (import "napi" "napi_get_global" (func $get_global (param i32 i32) (result i32))) + (func (export "enter") (param i32 i32 i32) (result i32) + (call $enter (local.get 0) (local.get 1) (local.get 2))) + ;; Leaves the scope whose token is stored at the pointer. + (func (export "leave") (param i32 i32) (result i32) + (call $leave (local.get 0) (i64.load (local.get 1)))) + (func (export "get_global") (param i32 i32) (result i32) + (call $get_global (local.get 0) (local.get 1)))) + "#; + + #[wasm_bindgen_test] + fn guest_imports_enter_and_leave_realms() { + use wasmer::{FunctionEnv, Imports, Instance, Memory, MemoryType, Module, Store}; + + const TOKEN: u32 = 64; + const OTHER_TOKEN: u32 = 72; + const GLOBAL: u32 = 80; + let mut store = Store::default(); + let memory = Memory::new(&mut store, MemoryType::new(1, None, false)).unwrap(); + let env = new_env(); + let mut napi_env = crate::env::NapiEnv::new( + crate::budget::ResourceBudget::unlimited(), + None, + std::sync::Arc::default(), + std::sync::Arc::default(), + ); + napi_env.memory = Some(memory.clone()); + // Dropping the store releases the env. + let (guest_env, _) = napi_env.register_napi_env(env); + let function_env = FunctionEnv::new(&mut store, napi_env); + let mut imports = Imports::new(); + crate::guest::napi::register_napi_imports(&mut store, &function_env, &mut imports); + imports.define("env", "memory", memory.clone()); + let module = Module::new(&store, wat::parse_str(REALM_GUEST).unwrap()).unwrap(); + let instance = Instance::new(&mut store, &module, &imports).unwrap(); + let enter = instance + .exports + .get_typed_function::<(u32, u32, u32), i32>(&store, "enter") + .unwrap(); + let leave = instance + .exports + .get_typed_function::<(u32, u32), i32>(&store, "leave") + .unwrap(); + let get_global = instance + .exports + .get_typed_function::<(u32, u32), i32>(&store, "get_global") + .unwrap(); + let read = |store: &Store, ptr: u32, bytes: &mut [u8]| { + memory.view(store).read(ptr.into(), bytes).unwrap(); + }; + let read_u64 = |store: &Store, ptr| { + let mut bytes = [0; 8]; + read(store, ptr, &mut bytes); + u64::from_le_bytes(bytes) + }; + let read_u32 = |store: &Store, ptr| { + let mut bytes = [0; 4]; + read(store, ptr, &mut bytes); + u32::from_le_bytes(bytes) + }; + let realm = new_realm(env, 0).unwrap(); + + // Entered by its id, the realm's global is napi_get_global's. + assert_eq!( + enter.call(&mut store, guest_env, realm, TOKEN).unwrap(), + NAPI_OK + ); + assert_ne!(read_u64(&store, TOKEN), 0); + assert_eq!(current_realm(env), realm); + assert_eq!( + get_global.call(&mut store, guest_env, GLOBAL).unwrap(), + NAPI_OK + ); + assert!(Object::is( + &value(env, read_u32(&store, GLOBAL)), + &value(env, realm) + )); + assert_eq!(leave.call(&mut store, guest_env, TOKEN).unwrap(), NAPI_OK); + assert_eq!(current_realm(env), 0); + + // A token above 2^63 reaches the guest whole and is a negative i64 on + // the way back. One that differs only in the sign bit closes nothing. + let large = 0xfedc_ba98_7654_3210_u64; + unsafe { env_mut(env) }.unwrap().next_realm_scope = large; + assert_eq!( + enter.call(&mut store, guest_env, realm, TOKEN).unwrap(), + NAPI_OK + ); + assert_eq!(read_u64(&store, TOKEN), large); + memory + .view(&store) + .write(OTHER_TOKEN.into(), &(large & !(1 << 63)).to_le_bytes()) + .unwrap(); + assert_eq!( + leave.call(&mut store, guest_env, OTHER_TOKEN).unwrap(), + NAPI_INVALID_ARG + ); + assert_eq!(current_realm(env), realm); + assert_eq!(leave.call(&mut store, guest_env, TOKEN).unwrap(), NAPI_OK); + assert_eq!(current_realm(env), 0); + + // With no room for the token, or no pointer, nothing stays entered. + for ptr in [65536 - 4, 0] { + assert_eq!( + enter.call(&mut store, guest_env, realm, ptr).unwrap(), + NAPI_INVALID_ARG + ); + assert!(unsafe { env_mut(env) }.unwrap().realm_stack.is_empty()); + } + assert_eq!(current_realm(env), 0); + } } From 883bfc9ffbc00b661f61efc981252b4907825282 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 13:39:31 -0800 Subject: [PATCH 036/150] V8: make typed arrays from the current realm's intrinsics napi_create_typedarray looked the constructor up by name on the current realm's global, which the realm's scripts control. It now makes the view with v8::Array::New in the current realm, after the checks Node makes (alignment, then length), which throw a RangeError with Node's codes instead of reaching V8's own aborts. QuickJS already used its intrinsics. The header and docs/realms.md now say which values never come from a realm's global, and what a buffer is in an entered realm. Co-Authored-By: Claude Opus 5.5 --- docs/realms.md | 5 +- include/unofficial_napi.h | 6 +- .../runners/test_69_unofficial_realm_entry.cc | 47 ++++++++ v8/src/js_native_api_v8.cc | 101 +++++++++++++----- 4 files changed, 132 insertions(+), 27 deletions(-) diff --git a/docs/realms.md b/docs/realms.md index 4295022fe6..226a4d680a 100644 --- a/docs/realms.md +++ b/docs/realms.md @@ -9,7 +9,10 @@ - **N-API acts in one realm at a time, the current realm**, as an ECMAScript engine runs code in the realm of its running execution context: - what N-API creates comes from the current realm, with its intrinsics, and - `napi_get_global` returns its global; + `napi_get_global` returns its global. Errors, typed arrays and DataViews + never come from the realm's global, which its scripts control. A buffer + is the current realm's `Uint8Array` with the env realm's + `Buffer.prototype`, since `Buffer` belongs to the env; - a native function belongs to the realm current when it was made (its `[[Realm]]`, as for an ECMAScript built-in function) and its callback runs in that realm, whichever realm calls it; diff --git a/include/unofficial_napi.h b/include/unofficial_napi.h index 8050bbede1..5925817fc6 100644 --- a/include/unofficial_napi.h +++ b/include/unofficial_napi.h @@ -157,8 +157,10 @@ NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_release_env( // // - A call that creates something creates it in the current realm, with that // realm's intrinsics: objects, arrays, functions, classes, errors (also the -// ones napi_throw_* makes), promises, dates, typed arrays and buffers. -// napi_get_global returns the current realm's global (a sandbox realm's +// ones napi_throw_* makes), promises, dates, array buffers, typed arrays and +// DataViews. Nothing reads the realm's global for them, which its scripts +// control. A buffer is the current realm's Uint8Array with the env realm's +// Buffer.prototype, since Buffer belongs to the env. napi_get_global returns the current realm's global (a sandbox realm's // sandbox), and napi_run_script runs there. (QuickJS copies a sandbox in // and out around each script; see docs/realms.md.) // - A native function belongs to the realm that was current when it was made, diff --git a/tests/runners/test_69_unofficial_realm_entry.cc b/tests/runners/test_69_unofficial_realm_entry.cc index cb71099b3f..9ccdb70183 100644 --- a/tests/runners/test_69_unofficial_realm_entry.cc +++ b/tests/runners/test_69_unofficial_realm_entry.cc @@ -1075,3 +1075,50 @@ TEST_F(Test69UnofficialRealmEntry, EnteredRealmKeepsItsStringCodeGenerationSwitc EXPECT_EQ(Utf8(s.env, Eval(s.env, probe)), "2"); } #endif + +// Typed arrays in an entered realm come from the realm's own constructors, +// and ranges that don't fit throw that realm's RangeError. +TEST_F(Test69UnofficialRealmEntry, TypedArraysComeFromTheRealmsIntrinsics) { + EnvScope s(runtime_.get()); + unofficial_napi_realm realm = CreateRealm(s.env); + ASSERT_NE(realm, nullptr); + ASSERT_NE(RunIn(s.env, realm, + "globalThis.saved = { Uint8Array, Int32Array, RangeError };" + "globalThis.pageCalls = 0;" + "for (const name of ['Uint8Array', 'Int32Array'])" + " Object.defineProperty(globalThis, name, { configurable: true," + " get() { pageCalls++; return function () { pageCalls++; return {}; }; } });" + "0"), + nullptr); + + napi_value buffer = nullptr; + napi_value made[4] = {}; + unofficial_napi_realm_scope scope = Enter(s.env, realm); + ASSERT_EQ(napi_create_arraybuffer(s.env, 16, nullptr, &buffer), napi_ok); + ASSERT_EQ(napi_create_typedarray(s.env, napi_uint8_array, 4, buffer, 1, &made[0]), napi_ok); + ASSERT_EQ(napi_create_typedarray(s.env, napi_int32_array, 2, buffer, 8, &made[1]), napi_ok); + // Misaligned, then past the end of the buffer. + EXPECT_EQ(napi_create_typedarray(s.env, napi_int32_array, 1, buffer, 2, &made[2]), + napi_pending_exception); + ASSERT_EQ(napi_get_and_clear_last_exception(s.env, &made[2]), napi_ok); + EXPECT_EQ(napi_create_typedarray(s.env, napi_int32_array, 4, buffer, 4, &made[3]), + napi_pending_exception); + ASSERT_EQ(napi_get_and_clear_last_exception(s.env, &made[3]), napi_ok); + napi_value array = nullptr; + ASSERT_EQ(napi_create_array_with_length(s.env, 4, &array), napi_ok); + for (uint32_t i = 0; i < 4; ++i) ASSERT_EQ(napi_set_element(s.env, array, i, made[i]), napi_ok); + ASSERT_EQ(napi_set_named_property(s.env, Global(s.env), "made", array), napi_ok); + Leave(s.env, scope); + + EXPECT_EQ(Utf8(s.env, RunIn(s.env, realm, + "(() => {" + " const [bytes, ints, misaligned, tooLong] = made;" + " const proto = Object.getPrototypeOf;" + " return [" + " proto(bytes) === saved.Uint8Array.prototype, bytes.byteOffset," + " bytes.length, proto(ints) === saved.Int32Array.prototype," + " ints.length, misaligned instanceof saved.RangeError," + " tooLong instanceof saved.RangeError, pageCalls].join();" + "})()")), + "true,1,4,true,2,true,true,0"); +} diff --git a/v8/src/js_native_api_v8.cc b/v8/src/js_native_api_v8.cc index 3f76707e19..f971dbd22d 100644 --- a/v8/src/js_native_api_v8.cc +++ b/v8/src/js_native_api_v8.cc @@ -13,7 +13,6 @@ #include "internal/napi_ref_with_finalizer.h" #include "internal/napi_setter_callback_info.h" #include "internal/unofficial_napi_bridge.h" -#include "napi_typedarray_metadata.h" #include "node_api_types.h" #include "unofficial_napi_error_utils.h" @@ -437,8 +436,30 @@ inline v8::PropertyAttribute ToV8PropertyAttributes(napi_property_attributes att return static_cast(v8_attrs); } -inline const char* TypedArrayConstructorName(napi_typedarray_type type) { - return napi::typedarray_constructor_name(type); +// Makes a typed array of the current realm's own intrinsic, after the checks +// Node makes, since v8::TypedArray::New aborts on an out-of-range view. +template +napi_status CreateTypedArray(napi_env env, + v8::Local buffer, + size_t element_size, + const char* type_name, + size_t byte_offset, + size_t length, + v8::Local* result) { + if (byte_offset % element_size != 0) { + std::string message = std::string("start offset of ") + type_name + + " should be a multiple of " + std::to_string(element_size); + napi_throw_range_error(env, "ERR_NAPI_INVALID_TYPEDARRAY_ALIGNMENT", message.c_str()); + return napi_v8_set_last_error(env, napi_pending_exception, "Invalid TypedArray alignment"); + } + const size_t buffer_length = buffer->ByteLength(); + if (byte_offset > buffer_length || length > T::kMaxLength || + length * element_size > buffer_length - byte_offset) { + napi_throw_range_error(env, "ERR_NAPI_INVALID_TYPEDARRAY_LENGTH", "Invalid typed array length"); + return napi_v8_set_last_error(env, napi_pending_exception, "Invalid TypedArray length"); + } + *result = T::New(buffer, byte_offset, length); + return napi_ok; } inline bool GetTypedArrayType(v8::Local value, napi_typedarray_type* out_type) { @@ -1000,29 +1021,61 @@ napi_status NAPI_CDECL napi_create_typedarray(napi_env env, if (!CheckEnv(env) || arraybuffer == nullptr || result == nullptr) return InvalidArg(env); v8::Local local = napi_v8_unwrap_value(arraybuffer); if (!local->IsArrayBuffer()) return napi_arraybuffer_expected; + v8::Local buffer = local.As(); - const char* ctor_name = TypedArrayConstructorName(type); - if (ctor_name == nullptr) return InvalidArg(env); - - v8::TryCatch tc(env->isolate); - v8::Local key; - if (!v8::String::NewFromUtf8(env->isolate, ctor_name, v8::NewStringType::kNormal).ToLocal(&key)) { - return napi_generic_failure; - } - v8::Local ctor_value; - if (!env->context()->Global()->Get(env->context(), key).ToLocal(&ctor_value) || - !ctor_value->IsFunction()) { - return napi_generic_failure; - } - v8::Local args[3] = { - local, - v8::Integer::NewFromUnsigned(env->isolate, static_cast(byte_offset)), - v8::Integer::NewFromUnsigned(env->isolate, static_cast(length)), - }; - v8::Local view; - if (!ctor_value.As()->NewInstance(env->context(), 3, args).ToLocal(&view)) { - return ReturnPendingIfCaught(env, tc, "Failed to create TypedArray"); + // The current realm's own constructors, never its global's: scripts can + // replace those. + v8::Context::Scope context_scope(env->context()); + v8::Local view; + napi_status status = napi_ok; + switch (type) { + case napi_int8_array: + status = CreateTypedArray(env, buffer, 1, "Int8Array", byte_offset, length, &view); + break; + case napi_uint8_array: + status = CreateTypedArray(env, buffer, 1, "Uint8Array", byte_offset, length, &view); + break; + case napi_uint8_clamped_array: + status = CreateTypedArray( + env, buffer, 1, "Uint8ClampedArray", byte_offset, length, &view); + break; + case napi_int16_array: + status = CreateTypedArray(env, buffer, 2, "Int16Array", byte_offset, length, &view); + break; + case napi_uint16_array: + status = CreateTypedArray(env, buffer, 2, "Uint16Array", byte_offset, length, &view); + break; + case napi_int32_array: + status = CreateTypedArray(env, buffer, 4, "Int32Array", byte_offset, length, &view); + break; + case napi_uint32_array: + status = CreateTypedArray(env, buffer, 4, "Uint32Array", byte_offset, length, &view); + break; + case napi_float16_array: + // The provider refuses --no-js-float16array, so Float16Array exists. + status = CreateTypedArray( + env, buffer, 2, "Float16Array", byte_offset, length, &view); + break; + case napi_float32_array: + status = CreateTypedArray( + env, buffer, 4, "Float32Array", byte_offset, length, &view); + break; + case napi_float64_array: + status = CreateTypedArray( + env, buffer, 8, "Float64Array", byte_offset, length, &view); + break; + case napi_bigint64_array: + status = CreateTypedArray( + env, buffer, 8, "BigInt64Array", byte_offset, length, &view); + break; + case napi_biguint64_array: + status = CreateTypedArray( + env, buffer, 8, "BigUint64Array", byte_offset, length, &view); + break; + default: + return InvalidArg(env); } + if (status != napi_ok) return status; *result = napi_v8_wrap_value(env, view); return (*result == nullptr) ? napi_generic_failure : napi_ok; } From f9288115f1789e22614917fba1c258dd231860f8 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 13:47:49 -0800 Subject: [PATCH 037/150] Test values made in a realm without relying on argument order MoreValuesComeFromTheEnteredRealm passed a value to its check helper next to the call that writes it, and C++ evaluates arguments in no fixed order. The helper now takes the value by address. Co-Authored-By: Claude Opus 5.5 --- tests/runners/test_70_realm_entry_attack.cc | 24 +++++++++++---------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/tests/runners/test_70_realm_entry_attack.cc b/tests/runners/test_70_realm_entry_attack.cc index c04d106350..c1c0bb5241 100644 --- a/tests/runners/test_70_realm_entry_attack.cc +++ b/tests/runners/test_70_realm_entry_attack.cc @@ -990,35 +990,37 @@ TEST_F(Test70RealmEntryAttack, MoreValuesComeFromTheEnteredRealm) { unofficial_napi_realm_scope scope = Enter(s.env, a); // Names what failed or is not from A. std::vector wrong; - auto check = [&](const char* name, napi_status status, napi_value value, const char* ctor) { + // Takes the value by address: the call that writes it is an argument too, + // and arguments are evaluated in no fixed order. + auto check = [&](const char* name, napi_status status, napi_value* value, const char* ctor) { if (status != napi_ok) { wrong.push_back(std::string(name) + ":status" + std::to_string(status)); ClearException(s.env); return; } - if (!ProtoIs(s.env, value, a_global, ctor)) wrong.push_back(name); + if (!ProtoIs(s.env, *value, a_global, ctor)) wrong.push_back(name); }; napi_value v = nullptr, number = nullptr; ASSERT_EQ(napi_create_int32(s.env, 3, &number), napi_ok); - check("coerce number", napi_coerce_to_object(s.env, number, &v), v, "Number"); + check("coerce number", napi_coerce_to_object(s.env, number, &v), &v, "Number"); v = nullptr; - check("coerce string", napi_coerce_to_object(s.env, Str(s.env, "x"), &v), v, "String"); + check("coerce string", napi_coerce_to_object(s.env, Str(s.env, "x"), &v), &v, "String"); v = nullptr; - check("property names", napi_get_property_names(s.env, env_object, &v), v, "Array"); + check("property names", napi_get_property_names(s.env, env_object, &v), &v, "Array"); v = nullptr; check("all property names", napi_get_all_property_names(s.env, env_object, napi_key_own_only, napi_key_enumerable, napi_key_keep_numbers, &v), - v, "Array"); + &v, "Array"); napi_value ab = nullptr; ASSERT_EQ(napi_create_arraybuffer(s.env, 16, nullptr, &ab), napi_ok); v = nullptr; - check("dataview", napi_create_dataview(s.env, 8, ab, 0, &v), v, "DataView"); + check("dataview", napi_create_dataview(s.env, 8, ab, 0, &v), &v, "DataView"); v = nullptr; - check("bigint64array", napi_create_typedarray(s.env, napi_bigint64_array, 1, ab, 0, &v), v, + check("bigint64array", napi_create_typedarray(s.env, napi_bigint64_array, 1, ab, 0, &v), &v, "BigInt64Array"); v = nullptr; - check("float64array", napi_create_typedarray(s.env, napi_float64_array, 1, ab, 0, &v), v, + check("float64array", napi_create_typedarray(s.env, napi_float64_array, 1, ab, 0, &v), &v, "Float64Array"); static char external_bytes[16]; v = nullptr; @@ -1027,10 +1029,10 @@ TEST_F(Test70RealmEntryAttack, MoreValuesComeFromTheEnteredRealm) { &v); // Providers may refuse external buffers. if (status != napi_no_external_buffers_allowed) { - check("external arraybuffer", status, v, "ArrayBuffer"); + check("external arraybuffer", status, &v, "ArrayBuffer"); } v = nullptr; - check("range error", napi_create_range_error(s.env, nullptr, Str(s.env, "r"), &v), v, + check("range error", napi_create_range_error(s.env, nullptr, Str(s.env, "r"), &v), &v, "RangeError"); // Whatever a Buffer's prototype chain, it ends in A's Uint8Array. void* data = nullptr; From f2a1878c1ba10b4b1c51d011684de2611aa6a139 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 14:26:51 -0800 Subject: [PATCH 038/150] QuickJS: run finalizers at release while the engine is alive Releasing an env freed its context and runtime first and only then called the instance-data finalizer, so a finalizer that used N-API (a handle scope, napi_get_global, napi_create_object) read a freed JSContext. Externals, wrapped objects, napi_add_finalizer objects and external buffers still alive at release fared no better: JS_FreeRuntime freed them and ran their finalizers with the context already gone. The env also kept its dangling context pointer, so check_env let such calls through. Teardown now runs, after the cleanup hooks, the finalizer of every value still alive and then the instance-data finalizer, in the env's realm and with the context, runtime and root scope alive, as Node does. A value a finalizer makes then is finalized too. After that no finalizer runs: one the runtime would call while freeing what is left is dropped, so a value the instance-data finalizer makes is never finalized, as in Node. The env lets go of its context at the end of teardown, so a later N-API call on it fails with napi_invalid_arg. test_41_instance_data now covers this on both engines. An instance-data finalizer, and the finalizers of an external, an external array buffer, an external buffer, a wrapped object and napi_add_finalizer, all alive at release, open a handle scope, read the env's global and make an object; the instance data's runs last. A value made by a finalizer at release is finalized, and one made by the instance-data finalizer is not. Before this change each new test segfaulted in the QuickJS release build, and Debug+ASan reported a heap-use-after-free in JS_GetGlobalObject (the instance-data finalizer) and a SEGV in find_own_property (finalizers called from JS_FreeRuntime). V8 already passed them. Co-Authored-By: Claude Opus 5.5 --- quickjs/src/internal/napi_env.cc | 54 ++++- quickjs/src/internal/napi_env.h | 12 +- .../napi_external_backing_store_hint.cc | 9 + .../napi_external_backing_store_hint.h | 2 + quickjs/src/unofficial_napi.cc | 8 +- tests/runners/test_41_instance_data.cc | 218 ++++++++++++++++++ 6 files changed, 291 insertions(+), 12 deletions(-) diff --git a/quickjs/src/internal/napi_env.cc b/quickjs/src/internal/napi_env.cc index 44b8c1e6ea..d84bd6de93 100644 --- a/quickjs/src/internal/napi_env.cc +++ b/quickjs/src/internal/napi_env.cc @@ -123,7 +123,6 @@ napi_env__::napi_env__(napi_agent__ *agent, JSContext *context, int32_t module_a napi_env__::~napi_env__() { prepare_teardown(); - finalize_instance_data(); } void napi_env__::prepare_teardown() @@ -149,6 +148,13 @@ void napi_env__::prepare_teardown() napi_env_cleanup_hook__::destroy(entry); } } + // As in Node, the finalizers of values still alive run next, then the + // instance data's. They run while the context and runtime are alive and + // the root scope is open, so they can use N-API; what they make is freed + // below. + finalize_external_values(); + finalize_instance_data(); + finalizers_done_ = true; cleanup_hooks_.close(); deferreds_.close(); @@ -186,6 +192,9 @@ void napi_env__::prepare_teardown() detach_runtime_interrupts(JS_GetRuntime(context_), runtime_interrupts_, this); runtime_interrupts_ = nullptr; NAPI_QUICKJS_LIFETIME_DUMP(this, "napi_env__ teardown end"); + // The context is freed after this. Without it every N-API call on the env + // fails with napi_invalid_arg instead of touching freed memory. + context_ = nullptr; torn_down_ = true; } @@ -197,6 +206,30 @@ void napi_env__::clear_refs_for_teardown() clearing_refs_for_teardown_ = false; } +void napi_env__::finalize_external_values() +{ + // Externals, wraps, napi_add_finalizer and external buffers each hold a + // hint. A finalizer may make or free values, which changes the hints, so + // look again from the start after one did. + bool changed = true; + while (changed) + { + changed = false; + for (napi_external_backing_store_hint__ &hint : external_backing_stores_) + { + if (!hint.finalizer_pending()) + continue; + const uint64_t changes = external_backing_store_changes_; + hint.invoke_finalizer(); + if (changes != external_backing_store_changes_) + { + changed = true; + break; + } + } + } +} + void napi_env__::finalize_instance_data() { void *data = instance_data_; @@ -216,9 +249,7 @@ void napi_env__::call_instance_data_finalizer(void *data, { if (data == nullptr || finalize_cb == nullptr) return; - // In the env's realm, as any finalizer. At release this runs after the - // runtime is freed; the realms are gone by then, so no scope it opens holds - // an anchor and popping the frame touches nothing. + // In the env's realm, as any finalizer. napi_realm_frame_scope__ realm_frame{this, nullptr, JS_UNDEFINED}; finalize_cb(this, data, finalize_hint); } @@ -228,6 +259,11 @@ bool napi_env__::is_closing() const return closing_; } +bool napi_env__::finalizers_done() const +{ + return finalizers_done_; +} + napi_agent__ *napi_env__::agent() const { return agent_; @@ -290,8 +326,7 @@ void napi_env__::pop_realm_frames(size_t depth) { napi_realm_frame__ frame = realm_frames_.back(); realm_frames_.pop_back(); - // A scope of the env's own realm holds no anchor, and may close after - // the runtime is freed (in the instance-data finalizer). + // A scope of the env's own realm holds no anchor. if (frame.scope != 0 && JS_VALUE_HAS_REF_COUNT(frame.anchor)) JS_FreeValue(context_, frame.anchor); } @@ -608,11 +643,16 @@ napi_external_backing_store_hint__ *napi_env__::create_external_backing_store( { if (context_ == nullptr) return nullptr; - return external_backing_stores_.allocate(this, external_data, finalize_cb, finalize_hint); + napi_external_backing_store_hint__ *hint = + external_backing_stores_.allocate(this, external_data, finalize_cb, finalize_hint); + if (hint != nullptr) + ++external_backing_store_changes_; + return hint; } void napi_env__::destroy_external_backing_store(napi_external_backing_store_hint__ *hint) { + ++external_backing_store_changes_; external_backing_stores_.destroy(hint); } diff --git a/quickjs/src/internal/napi_env.h b/quickjs/src/internal/napi_env.h index 2f81f85d62..897fe3aa8a 100644 --- a/quickjs/src/internal/napi_env.h +++ b/quickjs/src/internal/napi_env.h @@ -51,10 +51,15 @@ struct napi_env__ napi_env__(napi_agent__ *agent, JSContext *context, int32_t module_api_version); ~napi_env__(); + // Runs the cleanup hooks, then every pending finalizer and the + // instance-data finalizer last, while the context is alive, and lets go of + // the context. N-API calls on the env fail from then on. void prepare_teardown(); - void finalize_instance_data(); // Native callbacks are refused once teardown has started. bool is_closing() const; + // True once teardown has run the finalizers. A finalizer that would run + // later, as the runtime frees what was still alive, is dropped. + bool finalizers_done() const; napi_agent__ *agent() const; // Makes this env own its agent (an env made from an embedder's context). @@ -168,6 +173,8 @@ struct napi_env__ private: void clear_refs_for_teardown(); + void finalize_external_values(); + void finalize_instance_data(); void call_instance_data_finalizer(void *data, napi_finalize finalize_cb, void *finalize_hint); // Set only when this env owns its agent; destroyed last. @@ -205,6 +212,8 @@ struct napi_env__ napi_allocator__ cleanup_hooks_; napi_allocator__ deferreds_; napi_allocator__ external_backing_stores_; + // Counts hints made and destroyed, so teardown sees a finalizer change them. + uint64_t external_backing_store_changes_ = 0; #if defined(NAPI_ENABLE_LIFETIME_TRACKER) && defined(NAPI_ENABLE_LIFETIME_PERIODIC_STATS) // Periodic lifetime dump scheduling. @@ -220,6 +229,7 @@ struct napi_env__ // Env teardown state. bool closing_ = false; + bool finalizers_done_ = false; bool torn_down_ = false; bool clearing_refs_for_teardown_ = false; }; diff --git a/quickjs/src/internal/napi_external_backing_store_hint.cc b/quickjs/src/internal/napi_external_backing_store_hint.cc index 2e925f6594..a50609eee5 100644 --- a/quickjs/src/internal/napi_external_backing_store_hint.cc +++ b/quickjs/src/internal/napi_external_backing_store_hint.cc @@ -70,12 +70,21 @@ void napi_external_backing_store_hint__::invoke_finalizer() finalize_cb_(env_, external_data_, finalize_hint_); return; } + // Teardown has run every finalizer it could, and the context may be gone + // (the runtime frees what is still alive): no user code runs now. + if (env_->finalizers_done()) + return; // Finalizers run in the env's own realm, also when the collector runs // inside another realm. napi_realm_frame_scope__ realm_frame{env_, nullptr, JS_UNDEFINED}; finalize_cb_(env_, external_data_, finalize_hint_); } +bool napi_external_backing_store_hint__::finalizer_pending() const +{ + return !finalize_invoked_ && finalize_cb_ != nullptr; +} + napi_env napi_external_backing_store_hint__::env() const { return env_; diff --git a/quickjs/src/internal/napi_external_backing_store_hint.h b/quickjs/src/internal/napi_external_backing_store_hint.h index 05611313ca..eee5637aad 100644 --- a/quickjs/src/internal/napi_external_backing_store_hint.h +++ b/quickjs/src/internal/napi_external_backing_store_hint.h @@ -28,6 +28,8 @@ struct napi_external_backing_store_hint__ napi_external_backing_store_hint__ &operator=(napi_external_backing_store_hint__ &&other) = delete; void invoke_finalizer(); + // Whether invoke_finalizer would still call a finalizer. + bool finalizer_pending() const; napi_env env() const; JSRuntime *runtime() const; void *external_data() const; diff --git a/quickjs/src/unofficial_napi.cc b/quickjs/src/unofficial_napi.cc index 58350a59f1..2b9285983e 100644 --- a/quickjs/src/unofficial_napi.cc +++ b/quickjs/src/unofficial_napi.cc @@ -67,6 +67,8 @@ namespace napi_env env_to_delete = nullptr; if (scope->env != nullptr) { + // Runs every finalizer, the instance data's last, while the + // context and runtime are alive. env_to_delete = scope->env; status = DestroyEnvInstance(scope->env); scope->env = nullptr; @@ -81,10 +83,8 @@ namespace JS_FreeRuntime(scope->rt); scope->rt = nullptr; } - if (env_to_delete != nullptr) - { - env_to_delete->finalize_instance_data(); - } + // Deleted last: freeing the runtime returns the hints of the values + // still alive to the env. delete env_to_delete; delete scope; return status; diff --git a/tests/runners/test_41_instance_data.cc b/tests/runners/test_41_instance_data.cc index 944580a278..f9287e47eb 100644 --- a/tests/runners/test_41_instance_data.cc +++ b/tests/runners/test_41_instance_data.cc @@ -1,6 +1,13 @@ +#ifdef NAPI_MODULE +#undef NAPI_MODULE +#endif +#include "node_api.h" + #include "test_env.h" #include "upstream_js_test.h" +#include + extern "C" napi_value Init(napi_env env, napi_value exports); class Test41InstanceData : public FixtureTestBase {}; @@ -15,3 +22,214 @@ TEST_F(Test41InstanceData, PortedCoreFlow) { ASSERT_TRUE(RunUpstreamJsFileNoMustCallVerification( s, std::string(NAPI_TESTS_ROOT_PATH) + "/js-native-api/test_instance_data/test.js")); } + +// Finalizers at release. As in Node, every finalizer still pending when the +// env is released runs while the engine is alive, in the env's realm, and can +// use N-API; the instance-data finalizer runs last. + +namespace { + +constexpr int32_t kEnvMarker = 41; + +// What one finalizer saw. `clock` orders the finalizers of one env. +struct Seen { + explicit Seen(int* clock) : clock(clock) {} + int* clock; + int runs = 0; + int order = 0; + napi_status open_scope = napi_generic_failure; + napi_status get_global = napi_generic_failure; + napi_status create_object = napi_generic_failure; + napi_status close_scope = napi_generic_failure; + bool saw_env_global = false; +}; + +// Uses N-API as a finalizer may: opens a handle scope, reads the global's +// marker and makes an object. +void UseNapi(napi_env env, Seen* seen) { + ++seen->runs; + seen->order = ++*seen->clock; + napi_handle_scope scope = nullptr; + seen->open_scope = napi_open_handle_scope(env, &scope); + napi_value global = nullptr; + seen->get_global = napi_get_global(env, &global); + napi_value object = nullptr; + seen->create_object = napi_create_object(env, &object); + napi_value marker = nullptr; + int32_t value = 0; + seen->saw_env_global = seen->get_global == napi_ok && + napi_get_named_property(env, global, "envMarker", &marker) == napi_ok && + napi_get_value_int32(env, marker, &value) == napi_ok && + value == kEnvMarker; + if (seen->open_scope == napi_ok) seen->close_scope = napi_close_handle_scope(env, scope); +} + +void ExpectUsedNapi(const Seen& seen, const char* what) { + SCOPED_TRACE(what); + EXPECT_EQ(seen.runs, 1); + EXPECT_EQ(seen.open_scope, napi_ok); + EXPECT_EQ(seen.get_global, napi_ok); + EXPECT_EQ(seen.create_object, napi_ok); + EXPECT_EQ(seen.close_scope, napi_ok); + EXPECT_TRUE(seen.saw_env_global); +} + +void FinalizeInstanceData(napi_env env, void* data, void*) { + UseNapi(env, static_cast(data)); +} + +void FinalizeValue(node_api_basic_env env, void*, void* hint) { + UseNapi(const_cast(env), static_cast(hint)); +} + +// Sets `name` on the env's global, which keeps `value` alive until release. +void Keep(napi_env env, const char* name, napi_value value) { + napi_value global = nullptr; + ASSERT_EQ(napi_get_global(env, &global), napi_ok); + ASSERT_EQ(napi_set_named_property(env, global, name, value), napi_ok); +} + +// Marks the env's global, so a finalizer can tell it acts in the env's realm. +void MarkEnvGlobal(napi_env env) { + napi_value marker = nullptr; + ASSERT_EQ(napi_create_int32(env, kEnvMarker, &marker), napi_ok); + Keep(env, "envMarker", marker); +} + +// Makes an external whose finalizer records into `seen`, kept until release. +void KeepExternal(napi_env env, const char* name, Seen* seen) { + napi_handle_scope scope = nullptr; + ASSERT_EQ(napi_open_handle_scope(env, &scope), napi_ok); + napi_value external = nullptr; + ASSERT_EQ(napi_create_external(env, nullptr, FinalizeValue, seen, &external), napi_ok); + Keep(env, name, external); + ASSERT_EQ(napi_close_handle_scope(env, scope), napi_ok); +} + +// Releases the env before the test ends. +void Release(EnvScope& s) { + ASSERT_EQ(unofficial_napi_release_env(s.scope, nullptr), napi_ok); + s.scope = nullptr; + s.env = nullptr; +} + +} // namespace + +TEST_F(Test41InstanceData, InstanceDataFinalizerUsesNapiAtRelease) { + EnvScope s(runtime_.get()); + int clock = 0; + Seen instance_data{&clock}; + MarkEnvGlobal(s.env); + ASSERT_EQ(napi_set_instance_data(s.env, &instance_data, FinalizeInstanceData, nullptr), + napi_ok); + + Release(s); + ExpectUsedNapi(instance_data, "instance data"); +} + +TEST_F(Test41InstanceData, FinalizersOfLiveValuesRunBeforeTheInstanceDataFinalizer) { + EnvScope s(runtime_.get()); + int clock = 0; + Seen instance_data{&clock}, external{&clock}, array_buffer{&clock}, buffer{&clock}, + wrap{&clock}, finalizer{&clock}; + uint8_t array_buffer_bytes[8] = {}; + uint8_t buffer_bytes[8] = {}; + MarkEnvGlobal(s.env); + + // Each value is still reachable when the env is released. + KeepExternal(s.env, "external", &external); + napi_value value = nullptr; + ASSERT_EQ(napi_create_external_arraybuffer(s.env, array_buffer_bytes, sizeof(array_buffer_bytes), + FinalizeValue, &array_buffer, &value), + napi_ok); + Keep(s.env, "arrayBuffer", value); + ASSERT_EQ(napi_create_external_buffer(s.env, sizeof(buffer_bytes), buffer_bytes, FinalizeValue, + &buffer, &value), + napi_ok); + Keep(s.env, "buffer", value); + ASSERT_EQ(napi_create_object(s.env, &value), napi_ok); + ASSERT_EQ(napi_wrap(s.env, value, nullptr, FinalizeValue, &wrap, nullptr), napi_ok); + Keep(s.env, "wrapped", value); + ASSERT_EQ(napi_create_object(s.env, &value), napi_ok); + ASSERT_EQ(napi_add_finalizer(s.env, value, nullptr, FinalizeValue, &finalizer, nullptr), napi_ok); + Keep(s.env, "finalized", value); + ASSERT_EQ(napi_set_instance_data(s.env, &instance_data, FinalizeInstanceData, nullptr), + napi_ok); + + Release(s); + ExpectUsedNapi(external, "external"); + ExpectUsedNapi(array_buffer, "external array buffer"); + ExpectUsedNapi(buffer, "external buffer"); + ExpectUsedNapi(wrap, "wrap"); + ExpectUsedNapi(finalizer, "napi_add_finalizer"); + ExpectUsedNapi(instance_data, "instance data"); + for (const Seen* seen : {&external, &array_buffer, &buffer, &wrap, &finalizer}) { + EXPECT_LT(seen->order, instance_data.order); + } +} + +namespace { + +// A value's finalizer, and the finalizer of a value it makes at release. +struct Chain { + explicit Chain(int* clock) : first(clock), made(clock) {} + Seen first; + Seen made; +}; + +void FinalizeMakingAnother(node_api_basic_env basic_env, void*, void* hint) { + auto env = const_cast(basic_env); + auto* chain = static_cast(hint); + UseNapi(env, &chain->first); + KeepExternal(env, "made", &chain->made); +} + +// The instance-data finalizer, and a value it makes at release. +struct Late { + explicit Late(int* clock) : instance_data(clock), made(clock) {} + Seen instance_data; + Seen made; +}; + +void FinalizeInstanceDataMakingAValue(napi_env env, void* data, void*) { + auto* late = static_cast(data); + UseNapi(env, &late->instance_data); + KeepExternal(env, "made", &late->made); +} + +} // namespace + +TEST_F(Test41InstanceData, ValueAFinalizerMakesAtReleaseIsFinalizedToo) { + EnvScope s(runtime_.get()); + int clock = 0; + Chain chain{&clock}; + Seen instance_data{&clock}; + MarkEnvGlobal(s.env); + napi_value external = nullptr; + ASSERT_EQ(napi_create_external(s.env, nullptr, FinalizeMakingAnother, &chain, &external), + napi_ok); + Keep(s.env, "external", external); + ASSERT_EQ(napi_set_instance_data(s.env, &instance_data, FinalizeInstanceData, nullptr), + napi_ok); + + Release(s); + ExpectUsedNapi(chain.first, "external"); + ExpectUsedNapi(chain.made, "external its finalizer made"); + EXPECT_LT(chain.made.order, instance_data.order); + ExpectUsedNapi(instance_data, "instance data"); +} + +TEST_F(Test41InstanceData, ValueTheInstanceDataFinalizerMakesIsNeverFinalized) { + EnvScope s(runtime_.get()); + int clock = 0; + Late late{&clock}; + MarkEnvGlobal(s.env); + ASSERT_EQ(napi_set_instance_data(s.env, &late, FinalizeInstanceDataMakingAValue, nullptr), + napi_ok); + + Release(s); + ExpectUsedNapi(late.instance_data, "instance data"); + // Nothing finalizes after the instance data, as in Node: the engine is + // gone by the time the value is freed. + EXPECT_EQ(late.made.runs, 0); +} From 816ee85ce482b4f0facca653e3feeb0736a1a2ce Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 15:14:57 -0800 Subject: [PATCH 039/150] QuickJS: detach external buffers at release and finalize in linear time The release pass ran the finalizer of an external ArrayBuffer or Buffer while the buffer stayed attached to the memory the finalizer had just freed. A later finalizer, or the instance-data finalizer, could then read that memory through the buffer; ASan reported a heap-use-after-free in js_get_fast_array_element under napi_get_element. The pass also started over from the first hint whenever a finalizer made or freed a value, which made it quadratic: 40000 wrapped parents that each free a child took about 2 s to release. Cleanup hooks a finalizer added at release were dropped, and an exception one finalizer threw stayed pending for the next ones. The hints whose finalizers have yet to run now sit on a list in the env, most recent first (the order Node finalizes in), and the pass takes from it until it is empty, so it is linear. An external array buffer's hint holds the buffer through a native weak link; at release the pass detaches the buffer, which runs the finalizer, as Node's CallbackInfo::Clean does. A buffer that ArrayBuffer.prototype.transfer moved cannot be reached, by Node either, so its finalizer just runs. Cleanup hooks and pending finalizers alternate until neither is left, and hooks the instance-data finalizer adds run after it. The pending exception is cleared after each finalizer at release. The instance-data finalizer still runs last and nothing is finalized after it; comments no longer call that Node's behaviour, since current Node interleaves it with the other finalizers. test_41_instance_data adds tests for each case on both engines. Before this change on QuickJS: the external buffers were not detached in the instance-data finalizer (release build) and ASan reported the use-after-free; hooks added at release never ran; the exception was still pending in the instance-data finalizer; and releasing 40000 parents that free a child took 2046 ms against 8 ms when they free nothing. A transferred buffer and an external array buffer made by a finalizer at release are covered too. V8 does not yet detach external buffers, run late hooks, clear the exception or finalize such a buffer before the instance data, so those expectations are QuickJS-only. Co-Authored-By: Claude Opus 5.5 --- quickjs/src/internal/napi_env.cc | 83 ++-- quickjs/src/internal/napi_env.h | 16 +- quickjs/src/internal/napi_external.cc | 3 +- .../napi_external_backing_store_hint.cc | 89 +++- .../napi_external_backing_store_hint.h | 32 +- quickjs/src/js_native_api_quickjs.cc | 1 + tests/runners/test_41_instance_data.cc | 388 +++++++++++++++++- 7 files changed, 563 insertions(+), 49 deletions(-) diff --git a/quickjs/src/internal/napi_env.cc b/quickjs/src/internal/napi_env.cc index d84bd6de93..2a97e1d56c 100644 --- a/quickjs/src/internal/napi_env.cc +++ b/quickjs/src/internal/napi_env.cc @@ -135,26 +135,27 @@ void napi_env__::prepare_teardown() // Every scope closes. Cleanup hooks and finalizers each run in the env's // realm, and a scope one leaves open closes when it returns. pop_realm_frames(0); - while (!env_cleanup_hooks_.empty()) + // The cleanup hooks run, then the finalizers of the values still alive; a + // hook or value one of them adds runs too (Node also runs hooks added during + // cleanup), until neither is left. They run while the context and runtime + // are alive and the root scope is open, so they can use N-API; what they + // make is freed below. + run_cleanup_hooks(); + while (napi_external_backing_store_hint__::first_pending(pending_finalizers_) != nullptr) { - auto *entry = env_cleanup_hooks_.back(); - env_cleanup_hooks_.pop_back(); - if (entry != nullptr) - { - { - napi_realm_frame_scope__ realm_frame{this, nullptr, JS_UNDEFINED}; - entry->run(); - } - napi_env_cleanup_hook__::destroy(entry); - } + finalize_pending_values(); + run_cleanup_hooks(); } - // As in Node, the finalizers of values still alive run next, then the - // instance data's. They run while the context and runtime are alive and - // the root scope is open, so they can use N-API; what they make is freed - // below. - finalize_external_values(); + // The instance data's finalizer runs last. Nothing is finalized after it, + // but hooks it adds still run. finalize_instance_data(); + drop_finalizer_exception(); + run_cleanup_hooks(); + // A value still pending is never finalized: the runtime frees it after the + // context is gone. finalizers_done_ = true; + while (auto *hint = napi_external_backing_store_hint__::first_pending(pending_finalizers_)) + hint->abandon_finalizer(); cleanup_hooks_.close(); deferreds_.close(); @@ -206,30 +207,45 @@ void napi_env__::clear_refs_for_teardown() clearing_refs_for_teardown_ = false; } -void napi_env__::finalize_external_values() +void napi_env__::run_cleanup_hooks() { - // Externals, wraps, napi_add_finalizer and external buffers each hold a - // hint. A finalizer may make or free values, which changes the hints, so - // look again from the start after one did. - bool changed = true; - while (changed) + while (!env_cleanup_hooks_.empty()) { - changed = false; - for (napi_external_backing_store_hint__ &hint : external_backing_stores_) + auto *entry = env_cleanup_hooks_.back(); + env_cleanup_hooks_.pop_back(); + if (entry != nullptr) { - if (!hint.finalizer_pending()) - continue; - const uint64_t changes = external_backing_store_changes_; - hint.invoke_finalizer(); - if (changes != external_backing_store_changes_) { - changed = true; - break; + napi_realm_frame_scope__ realm_frame{this, nullptr, JS_UNDEFINED}; + entry->run(); } + napi_env_cleanup_hook__::destroy(entry); } } } +void napi_env__::finalize_pending_values() +{ + // Externals, wraps, napi_add_finalizer and external buffers each hold a + // hint. The ones whose finalizers have yet to run are listed most recent + // first, the order Node finalizes in. A value a finalizer makes joins the + // list, and one it frees leaves it. + while (auto *hint = napi_external_backing_store_hint__::first_pending(pending_finalizers_)) + { + hint->finalize_at_teardown(); + drop_finalizer_exception(); + } +} + +void napi_env__::drop_finalizer_exception() +{ + // Nothing can catch what a finalizer threw at release. Node also clears it + // after each finalizer. + clear_last_exception(); + if (context_ != nullptr && JS_HasException(context_)) + JS_FreeValue(context_, JS_GetException(context_)); +} + void napi_env__::finalize_instance_data() { void *data = instance_data_; @@ -645,14 +661,13 @@ napi_external_backing_store_hint__ *napi_env__::create_external_backing_store( return nullptr; napi_external_backing_store_hint__ *hint = external_backing_stores_.allocate(this, external_data, finalize_cb, finalize_hint); - if (hint != nullptr) - ++external_backing_store_changes_; + if (hint != nullptr && finalize_cb != nullptr && !finalizers_done_) + hint->link_pending(pending_finalizers_); return hint; } void napi_env__::destroy_external_backing_store(napi_external_backing_store_hint__ *hint) { - ++external_backing_store_changes_; external_backing_stores_.destroy(hint); } diff --git a/quickjs/src/internal/napi_env.h b/quickjs/src/internal/napi_env.h index 897fe3aa8a..f89345e4c7 100644 --- a/quickjs/src/internal/napi_env.h +++ b/quickjs/src/internal/napi_env.h @@ -51,9 +51,9 @@ struct napi_env__ napi_env__(napi_agent__ *agent, JSContext *context, int32_t module_api_version); ~napi_env__(); - // Runs the cleanup hooks, then every pending finalizer and the - // instance-data finalizer last, while the context is alive, and lets go of - // the context. N-API calls on the env fail from then on. + // Runs the cleanup hooks and every pending finalizer, the instance data's + // last, while the context is alive, and lets go of the context. N-API calls + // on the env fail from then on. void prepare_teardown(); // Native callbacks are refused once teardown has started. bool is_closing() const; @@ -173,7 +173,9 @@ struct napi_env__ private: void clear_refs_for_teardown(); - void finalize_external_values(); + void run_cleanup_hooks(); + void finalize_pending_values(); + void drop_finalizer_exception(); void finalize_instance_data(); void call_instance_data_finalizer(void *data, napi_finalize finalize_cb, void *finalize_hint); @@ -207,13 +209,15 @@ struct napi_env__ // Cleanup hooks in registration order. std::vector env_cleanup_hooks_; + // Hints whose finalizers have yet to run, the most recent first. Declared + // before the hints' allocator, so it is destroyed after every hint. + napi_intrinsic_link__ pending_finalizers_{}; + // Env-owned slot allocators. napi_allocator__ refs_; napi_allocator__ cleanup_hooks_; napi_allocator__ deferreds_; napi_allocator__ external_backing_stores_; - // Counts hints made and destroyed, so teardown sees a finalizer change them. - uint64_t external_backing_store_changes_ = 0; #if defined(NAPI_ENABLE_LIFETIME_TRACKER) && defined(NAPI_ENABLE_LIFETIME_PERIODIC_STATS) // Periodic lifetime dump scheduling. diff --git a/quickjs/src/internal/napi_external.cc b/quickjs/src/internal/napi_external.cc index ed7ec7b0c9..3770bf89a7 100644 --- a/quickjs/src/internal/napi_external.cc +++ b/quickjs/src/internal/napi_external.cc @@ -127,8 +127,7 @@ void *napi_external__::realloc_external_array_buffer_data(JSRuntime *rt, void *o auto *hint = reinterpret_cast(opaque); if (hint == nullptr) return nullptr; - hint->invoke_finalizer(); - napi_external_backing_store_hint__::destroy_with_runtime(rt, hint); + hint->release_array_buffer(rt); return nullptr; } diff --git a/quickjs/src/internal/napi_external_backing_store_hint.cc b/quickjs/src/internal/napi_external_backing_store_hint.cc index a50609eee5..d4696beedf 100644 --- a/quickjs/src/internal/napi_external_backing_store_hint.cc +++ b/quickjs/src/internal/napi_external_backing_store_hint.cc @@ -17,6 +17,9 @@ napi_external_backing_store_hint__::napi_external_backing_store_hint__( napi_external_backing_store_hint__::~napi_external_backing_store_hint__() { + if (pending_link_.linked()) + pending_link_.unlink(); + forget_array_buffer(); env_ = nullptr; rt_ = nullptr; external_data_ = nullptr; @@ -63,6 +66,9 @@ void napi_external_backing_store_hint__::invoke_finalizer() if (finalize_invoked_) return; finalize_invoked_ = true; + if (pending_link_.linked()) + pending_link_.unlink(); + forget_array_buffer(); if (finalize_cb_ == nullptr) return; if (env_ == nullptr) @@ -80,9 +86,88 @@ void napi_external_backing_store_hint__::invoke_finalizer() finalize_cb_(env_, external_data_, finalize_hint_); } -bool napi_external_backing_store_hint__::finalizer_pending() const +void napi_external_backing_store_hint__::release_array_buffer(JSRuntime *rt) { - return !finalize_invoked_ && finalize_cb_ != nullptr; + invoke_finalizer(); + if (!detaching_) + destroy_with_runtime(rt, this); +} + +void napi_external_backing_store_hint__::track_array_buffer(JSContext *ctx, + JSValueConst array_buffer) +{ + // Only a finalizer frees the memory, so only then must teardown detach the + // buffer first. + if (finalize_cb_ == nullptr || finalize_invoked_) + return; + if (JS_AddNativeWeakRefLink(ctx, array_buffer, &array_buffer_link_, array_buffer_freed, this) < 0) + { + // Out of memory: teardown can still run the finalizer, just not detach. + if (JS_HasException(ctx)) + JS_FreeValue(ctx, JS_GetException(ctx)); + return; + } + array_buffer_ = array_buffer; +} + +void napi_external_backing_store_hint__::link_pending(napi_intrinsic_link__ &pending) +{ + pending.link(pending_link_); +} + +napi_external_backing_store_hint__ *napi_external_backing_store_hint__::first_pending( + napi_intrinsic_link__ &pending) +{ + napi_intrinsic_link__ *link = pending.first(); + return link == nullptr + ? nullptr + : link->unsafe_get<&napi_external_backing_store_hint__::pending_link_>(); +} + +void napi_external_backing_store_hint__::finalize_at_teardown() +{ + if (JS_GetNativeWeakRefFromLink(&array_buffer_link_) != nullptr) + { + // As Node does, detach the buffer first, so nothing can reach the memory + // the finalizer frees. Detaching runs the finalizer, unless + // ArrayBuffer.prototype.transfer already moved the memory to a buffer this + // hint cannot reach (Node cannot either). The reference keeps the buffer + // alive in case the finalizer drops the last other one. + JSContext *ctx = env_->main_context(); + JSValue array_buffer = JS_DupValue(ctx, array_buffer_); + detaching_ = true; + JS_DetachArrayBuffer(ctx, array_buffer); + detaching_ = false; + JS_FreeValue(ctx, array_buffer); + if (finalize_invoked_) + { + // The buffer no longer refers to the hint. + destroy(this); + return; + } + } + invoke_finalizer(); +} + +void napi_external_backing_store_hint__::abandon_finalizer() +{ + if (pending_link_.linked()) + pending_link_.unlink(); + forget_array_buffer(); +} + +void napi_external_backing_store_hint__::array_buffer_freed(JSRuntime *rt, void *opaque) +{ + (void)rt; + // QuickJS has already cleared the link. + static_cast(opaque)->array_buffer_ = JS_UNDEFINED; +} + +void napi_external_backing_store_hint__::forget_array_buffer() +{ + if (JS_GetNativeWeakRefFromLink(&array_buffer_link_) != nullptr) + JS_DeleteNativeWeakRefLink(rt_, &array_buffer_link_); + array_buffer_ = JS_UNDEFINED; } napi_env napi_external_backing_store_hint__::env() const diff --git a/quickjs/src/internal/napi_external_backing_store_hint.h b/quickjs/src/internal/napi_external_backing_store_hint.h index eee5637aad..587fb3f12b 100644 --- a/quickjs/src/internal/napi_external_backing_store_hint.h +++ b/quickjs/src/internal/napi_external_backing_store_hint.h @@ -3,6 +3,7 @@ #include "../../../include/js_native_api.h" #include "../../../include/node_api_types.h" +#include "napi_intrinsic_link.h" #include @@ -28,8 +29,23 @@ struct napi_external_backing_store_hint__ napi_external_backing_store_hint__ &operator=(napi_external_backing_store_hint__ &&other) = delete; void invoke_finalizer(); - // Whether invoke_finalizer would still call a finalizer. - bool finalizer_pending() const; + // The external array buffer this hint backs let go of the memory: it was + // detached or freed. + void release_array_buffer(JSRuntime *rt); + // Remembers the external array buffer this hint backs, so teardown can + // detach it before running the finalizer. + void track_array_buffer(JSContext *ctx, JSValueConst array_buffer); + + // Env teardown. A hint whose finalizer has yet to run is on its env's + // pending list until it runs or the hint is destroyed. + void link_pending(napi_intrinsic_link__ &pending); + static napi_external_backing_store_hint__ *first_pending(napi_intrinsic_link__ &pending); + // Runs the finalizer, detaching the array buffer first. May destroy the + // hint. + void finalize_at_teardown(); + // Leaves the pending list for good: the finalizer will not run. + void abandon_finalizer(); + napi_env env() const; JSRuntime *runtime() const; void *external_data() const; @@ -38,6 +54,9 @@ struct napi_external_backing_store_hint__ void set_weak_target(JSValue weak_target); private: + static void array_buffer_freed(JSRuntime *rt, void *opaque); + void forget_array_buffer(); + // Owning runtime state. napi_env env_ = nullptr; JSRuntime *rt_ = nullptr; @@ -50,6 +69,15 @@ struct napi_external_backing_store_hint__ // Optional JavaScript target for wrapped-object finalizers. JSValue weak_target_ = JS_UNDEFINED; + + // On the env's pending list while the finalizer has yet to run. + napi_intrinsic_link__ pending_link_{}; + // The external array buffer made over external_data_, held weakly, while + // the finalizer has yet to run. + JSValue array_buffer_ = JS_UNDEFINED; + JSNativeWeakRefLink array_buffer_link_{}; + // Teardown is detaching array_buffer_ and destroys the hint itself. + bool detaching_ = false; }; #endif // NAPI_QUICKJS_EXTERNAL_BACKING_STORE_HINT_H_ diff --git a/quickjs/src/js_native_api_quickjs.cc b/quickjs/src/js_native_api_quickjs.cc index e123dfe62f..2065e4a6d1 100644 --- a/quickjs/src/js_native_api_quickjs.cc +++ b/quickjs/src/js_native_api_quickjs.cc @@ -450,6 +450,7 @@ extern "C" napi_external_backing_store_hint__::destroy(hint); return napi_util__::return_pending_if_caught(env, "Failed to create external array"); } + hint->track_array_buffer(env->context(), out); } *result = env->wrap_value_in_current_scope(out, true); diff --git a/tests/runners/test_41_instance_data.cc b/tests/runners/test_41_instance_data.cc index f9287e47eb..dce16adcb4 100644 --- a/tests/runners/test_41_instance_data.cc +++ b/tests/runners/test_41_instance_data.cc @@ -6,7 +6,11 @@ #include "test_env.h" #include "upstream_js_test.h" +#include #include +#include +#include +#include extern "C" napi_value Init(napi_env env, napi_value exports); @@ -25,7 +29,8 @@ TEST_F(Test41InstanceData, PortedCoreFlow) { // Finalizers at release. As in Node, every finalizer still pending when the // env is released runs while the engine is alive, in the env's realm, and can -// use N-API; the instance-data finalizer runs last. +// use N-API. The instance-data finalizer runs last, after every other +// finalizer (current Node interleaves it with them instead). namespace { @@ -229,7 +234,384 @@ TEST_F(Test41InstanceData, ValueTheInstanceDataFinalizerMakesIsNeverFinalized) { Release(s); ExpectUsedNapi(late.instance_data, "instance data"); - // Nothing finalizes after the instance data, as in Node: the engine is - // gone by the time the value is freed. + // Nothing finalizes after the instance data: the engine is gone by the time + // the value is freed. (Current Node would finalize it.) EXPECT_EQ(late.made.runs, 0); } + +namespace { + +// Memory an external buffer was made over, which its finalizer frees. +struct Owned { + int frees = 0; +}; + +void FreeOwned(node_api_basic_env, void* data, void* hint) { + ++static_cast(hint)->frees; + std::free(data); +} + +void* NewBytes(size_t length) { + void* bytes = std::malloc(length); + std::memset(bytes, 7, length); + return bytes; +} + +// Moves an array buffer's memory to a new one with ArrayBuffer.prototype.transfer. +napi_value Transfer(napi_env env, napi_value array_buffer) { + napi_value transfer = nullptr; + napi_value moved = nullptr; + EXPECT_EQ(napi_get_named_property(env, array_buffer, "transfer", &transfer), napi_ok); + EXPECT_EQ(napi_call_function(env, array_buffer, transfer, 0, nullptr, &moved), napi_ok); + return moved; +} + +} // namespace + +#if defined(NAPI_TEST_ENGINE_QUICKJS) +namespace { + +// What the instance-data finalizer finds of external buffers whose finalizers +// freed their memory. +struct AfterFree { + Owned array_buffer_memory; + Owned buffer_memory; + napi_ref array_buffer = nullptr; + napi_ref view = nullptr; + napi_ref buffer_array_buffer = nullptr; + int frees_seen = 0; + bool array_buffer_detached = false; + napi_status info_status = napi_generic_failure; + void* info_data = nullptr; + size_t info_length = SIZE_MAX; + napi_valuetype element = napi_number; + bool buffer_detached = false; +}; + +bool IsDetached(napi_env env, napi_ref ref) { + napi_value value = nullptr; + bool detached = false; + return napi_get_reference_value(env, ref, &value) == napi_ok && + napi_is_detached_arraybuffer(env, value, &detached) == napi_ok && detached; +} + +void InspectFreedBuffers(napi_env env, void* data, void*) { + auto* after = static_cast(data); + after->frees_seen = after->array_buffer_memory.frees + after->buffer_memory.frees; + napi_handle_scope scope = nullptr; + if (napi_open_handle_scope(env, &scope) != napi_ok) return; + after->array_buffer_detached = IsDetached(env, after->array_buffer); + after->buffer_detached = IsDetached(env, after->buffer_array_buffer); + napi_value value = nullptr; + if (napi_get_reference_value(env, after->array_buffer, &value) == napi_ok) + after->info_status = + napi_get_arraybuffer_info(env, value, &after->info_data, &after->info_length); + napi_value element = nullptr; + if (napi_get_reference_value(env, after->view, &value) == napi_ok && + napi_get_element(env, value, 3, &element) == napi_ok) + napi_typeof(env, element, &after->element); + napi_close_handle_scope(env, scope); +} + +} // namespace + +// As Node does, an external buffer is detached before its finalizer frees +// the memory, so code that runs later at release cannot read freed memory +// through it. The V8 provider does not detach them yet. +TEST_F(Test41InstanceData, ExternalBuffersAreDetachedBeforeTheirFinalizersAtRelease) { + EnvScope s(runtime_.get()); + AfterFree after; + napi_value array_buffer = nullptr; + ASSERT_EQ(napi_create_external_arraybuffer(s.env, NewBytes(64), 64, FreeOwned, + &after.array_buffer_memory, &array_buffer), + napi_ok); + napi_value view = nullptr; + ASSERT_EQ(napi_create_typedarray(s.env, napi_uint8_array, 64, array_buffer, 0, &view), napi_ok); + Keep(s.env, "view", view); + napi_value buffer = nullptr; + ASSERT_EQ(napi_create_external_buffer(s.env, 16, NewBytes(16), FreeOwned, &after.buffer_memory, + &buffer), + napi_ok); + Keep(s.env, "buffer", buffer); + napi_value buffer_array_buffer = nullptr; + ASSERT_EQ(napi_get_typedarray_info(s.env, buffer, nullptr, nullptr, nullptr, + &buffer_array_buffer, nullptr), + napi_ok); + ASSERT_EQ(napi_create_reference(s.env, array_buffer, 1, &after.array_buffer), napi_ok); + ASSERT_EQ(napi_create_reference(s.env, view, 1, &after.view), napi_ok); + ASSERT_EQ(napi_create_reference(s.env, buffer_array_buffer, 1, &after.buffer_array_buffer), + napi_ok); + ASSERT_EQ(napi_set_instance_data(s.env, &after, InspectFreedBuffers, nullptr), napi_ok); + + Release(s); + EXPECT_EQ(after.frees_seen, 2); + EXPECT_EQ(after.array_buffer_memory.frees, 1); + EXPECT_EQ(after.buffer_memory.frees, 1); + EXPECT_TRUE(after.array_buffer_detached); + // QuickJS refuses the info of a detached buffer; either way it does not + // hand out the freed memory. + EXPECT_TRUE(after.info_status != napi_ok || + (after.info_data == nullptr && after.info_length == 0)) + << "status " << after.info_status << ", length " << after.info_length; + EXPECT_EQ(after.element, napi_undefined); + EXPECT_TRUE(after.buffer_detached); +} +#endif + +// ArrayBuffer.prototype.transfer moves an external buffer's memory to a new +// buffer. Its finalizer still runs once at release, whether the buffer it was +// made as is alive then or not. +TEST_F(Test41InstanceData, TransferredExternalArrayBufferIsFinalizedOnceAtRelease) { + EnvScope s(runtime_.get()); + Owned kept_memory; + Owned dropped_memory; + napi_value array_buffer = nullptr; + ASSERT_EQ(napi_create_external_arraybuffer(s.env, NewBytes(32), 32, FreeOwned, &kept_memory, + &array_buffer), + napi_ok); + Keep(s.env, "original", array_buffer); + Keep(s.env, "moved", Transfer(s.env, array_buffer)); + napi_handle_scope scope = nullptr; + ASSERT_EQ(napi_open_handle_scope(s.env, &scope), napi_ok); + ASSERT_EQ(napi_create_external_arraybuffer(s.env, NewBytes(32), 32, FreeOwned, &dropped_memory, + &array_buffer), + napi_ok); + Keep(s.env, "movedFromDropped", Transfer(s.env, array_buffer)); + ASSERT_EQ(napi_close_handle_scope(s.env, scope), napi_ok); + + Release(s); + EXPECT_EQ(kept_memory.frees, 1); + EXPECT_EQ(dropped_memory.frees, 1); +} + +namespace { + +// A finalizer that makes an external array buffer at release. +struct BufferChain { + explicit BufferChain(int* clock) : first(clock), made(clock) {} + Seen first; + Seen made; + uint8_t bytes[8] = {}; +}; + +void FinalizeMakingAnArrayBuffer(node_api_basic_env basic_env, void*, void* hint) { + auto env = const_cast(basic_env); + auto* chain = static_cast(hint); + UseNapi(env, &chain->first); + napi_handle_scope scope = nullptr; + ASSERT_EQ(napi_open_handle_scope(env, &scope), napi_ok); + napi_value made = nullptr; + ASSERT_EQ(napi_create_external_arraybuffer(env, chain->bytes, sizeof(chain->bytes), + FinalizeValue, &chain->made, &made), + napi_ok); + Keep(env, "madeBuffer", made); + ASSERT_EQ(napi_close_handle_scope(env, scope), napi_ok); +} + +} // namespace + +TEST_F(Test41InstanceData, ExternalArrayBufferAFinalizerMakesAtReleaseIsFinalizedToo) { + EnvScope s(runtime_.get()); + int clock = 0; + BufferChain chain{&clock}; + Seen instance_data{&clock}; + MarkEnvGlobal(s.env); + napi_value external = nullptr; + ASSERT_EQ(napi_create_external(s.env, nullptr, FinalizeMakingAnArrayBuffer, &chain, &external), + napi_ok); + Keep(s.env, "external", external); + ASSERT_EQ(napi_set_instance_data(s.env, &instance_data, FinalizeInstanceData, nullptr), + napi_ok); + + Release(s); + ExpectUsedNapi(chain.first, "external"); + ExpectUsedNapi(instance_data, "instance data"); +#if defined(NAPI_TEST_ENGINE_QUICKJS) + // The V8 provider finalizes such a buffer only after the instance data, + // when N-API no longer works. + ExpectUsedNapi(chain.made, "array buffer its finalizer made"); + EXPECT_LT(chain.made.order, instance_data.order); +#endif +} + +namespace { + +// Cleanup hooks finalizers add at release, and when each ran. +struct LateHooks { + int clock = 0; + int value_hook = 0; + int instance_data = 0; + int instance_data_hook = 0; + napi_status value_add = napi_generic_failure; + napi_status instance_data_add = napi_generic_failure; +}; + +void ValueHook(void* arg) { + auto* hooks = static_cast(arg); + hooks->value_hook = ++hooks->clock; +} + +void InstanceDataHook(void* arg) { + auto* hooks = static_cast(arg); + hooks->instance_data_hook = ++hooks->clock; +} + +void FinalizeAddingAHook(node_api_basic_env env, void*, void* hint) { + auto* hooks = static_cast(hint); + hooks->value_add = napi_add_env_cleanup_hook(env, ValueHook, hooks); +} + +void FinalizeInstanceDataAddingAHook(napi_env env, void* data, void*) { + auto* hooks = static_cast(data); + hooks->instance_data = ++hooks->clock; + hooks->instance_data_add = napi_add_env_cleanup_hook(env, InstanceDataHook, hooks); +} + +} // namespace + +TEST_F(Test41InstanceData, CleanupHooksFinalizersAddAtReleaseRun) { + EnvScope s(runtime_.get()); + LateHooks hooks; + napi_value external = nullptr; + ASSERT_EQ(napi_create_external(s.env, nullptr, FinalizeAddingAHook, &hooks, &external), napi_ok); + Keep(s.env, "external", external); + ASSERT_EQ(napi_set_instance_data(s.env, &hooks, FinalizeInstanceDataAddingAHook, nullptr), + napi_ok); + + Release(s); + EXPECT_EQ(hooks.value_add, napi_ok); + EXPECT_EQ(hooks.instance_data_add, napi_ok); +#if defined(NAPI_TEST_ENGINE_QUICKJS) + // As in Node, a hook added during teardown still runs; one a value's + // finalizer adds runs before the instance-data finalizer. The V8 provider + // drops them. + EXPECT_GT(hooks.value_hook, 0); + EXPECT_LT(hooks.value_hook, hooks.instance_data); + EXPECT_GT(hooks.instance_data_hook, hooks.instance_data); +#endif +} + +namespace { + +struct Thrown { + napi_status throw_status = napi_generic_failure; + napi_status pending_status = napi_generic_failure; + bool pending = true; +}; + +void FinalizeThrowing(node_api_basic_env basic_env, void*, void* hint) { + auto* thrown = static_cast(hint); + thrown->throw_status = napi_throw_error(const_cast(basic_env), nullptr, "finalizer"); +} + +void FinalizeInstanceDataAfterAThrow(napi_env env, void* data, void*) { + auto* thrown = static_cast(data); + thrown->pending_status = napi_is_exception_pending(env, &thrown->pending); +} + +} // namespace + +TEST_F(Test41InstanceData, AnExceptionAFinalizerThrowsAtReleaseIsNotLeftPending) { + EnvScope s(runtime_.get()); + Thrown thrown; + napi_value external = nullptr; + ASSERT_EQ(napi_create_external(s.env, nullptr, FinalizeThrowing, &thrown, &external), napi_ok); + Keep(s.env, "external", external); + ASSERT_EQ(napi_set_instance_data(s.env, &thrown, FinalizeInstanceDataAfterAThrow, nullptr), + napi_ok); + + Release(s); + EXPECT_EQ(thrown.pending_status, napi_ok); +#if defined(NAPI_TEST_ENGINE_QUICKJS) + // Nothing can catch it, so, as Node does after each finalizer, it is + // dropped. The V8 provider still leaves it pending. + EXPECT_EQ(thrown.throw_status, napi_ok); + EXPECT_FALSE(thrown.pending); +#endif +} + +namespace { + +// A wrapped parent whose native object holds the only reference to a wrapped +// child. With `free_children` its finalizer deletes the reference, which +// frees the child. +struct Parent { + napi_ref child = nullptr; +}; + +struct Family { + bool free_children = false; + int parents = 0; + int children = 0; +}; + +void FinalizeChild(node_api_basic_env, void*, void* hint) { + ++static_cast(hint)->children; +} + +void FinalizeParent(node_api_basic_env env, void* data, void* hint) { + auto* parent = static_cast(data); + auto* family = static_cast(hint); + ++family->parents; + if (family->free_children) { + napi_delete_reference(env, parent->child); + parent->child = nullptr; + } +} + +// Releases an env holding `count` parents and their children, and returns +// how long the release took, in milliseconds. +double ReleaseFamilies(NapiTestRuntime* runtime, int count, Family* family) { + EnvScope s(runtime); + std::vector parents(count); + napi_value array = nullptr; + EXPECT_EQ(napi_create_array(s.env, &array), napi_ok); + Keep(s.env, "parents", array); + // Children first: the parents, made last, are finalized first, so each + // frees a child whose finalizer is still pending. + for (int i = 0; i < count; ++i) { + napi_handle_scope scope = nullptr; + EXPECT_EQ(napi_open_handle_scope(s.env, &scope), napi_ok); + napi_value child = nullptr; + EXPECT_EQ(napi_create_object(s.env, &child), napi_ok); + EXPECT_EQ(napi_wrap(s.env, child, nullptr, FinalizeChild, family, nullptr), napi_ok); + EXPECT_EQ(napi_create_reference(s.env, child, 1, &parents[i].child), napi_ok); + EXPECT_EQ(napi_close_handle_scope(s.env, scope), napi_ok); + } + for (int i = 0; i < count; ++i) { + napi_handle_scope scope = nullptr; + EXPECT_EQ(napi_open_handle_scope(s.env, &scope), napi_ok); + napi_value parent = nullptr; + EXPECT_EQ(napi_create_object(s.env, &parent), napi_ok); + EXPECT_EQ(napi_wrap(s.env, parent, &parents[i], FinalizeParent, family, nullptr), napi_ok); + EXPECT_EQ(napi_set_element(s.env, array, i, parent), napi_ok); + EXPECT_EQ(napi_close_handle_scope(s.env, scope), napi_ok); + } + + const auto start = std::chrono::steady_clock::now(); + Release(s); + const auto elapsed = std::chrono::steady_clock::now() - start; + return std::chrono::duration(elapsed).count(); +} + +} // namespace + +// The release pass takes time linear in the values it finalizes, also when +// each finalizer frees another value. +TEST_F(Test41InstanceData, ReleaseFinalizesValuesThatFreeOthersInLinearTime) { + constexpr int kCount = 40000; + Family keeping; + const double keeping_ms = ReleaseFamilies(runtime_.get(), kCount, &keeping); + Family freeing; + freeing.free_children = true; + const double freeing_ms = ReleaseFamilies(runtime_.get(), kCount, &freeing); + + for (const Family* family : {&keeping, &freeing}) { + EXPECT_EQ(family->parents, kCount); + EXPECT_EQ(family->children, kCount); + } + // Both are linear. A pass that rescanned every value after each one freed + // took over a hundred times as long. + EXPECT_LT(freeing_ms, 20 * keeping_ms + 50) + << "keeping " << keeping_ms << " ms, freeing " << freeing_ms << " ms"; +} From ef9a5df3ecfda3d66129aac9fd14a2792dd6f7de Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 14:46:38 -0800 Subject: [PATCH 040/150] V8: run external ArrayBuffer finalizers on the env's thread ExternalBackingStoreDeleter called the user's finalizer itself. V8 runs a backing store's deleter wherever the last reference drops: on its ArrayBufferSweeper threads, where neither V8 nor the env may be used, during a GC, or inside napi_detach_arraybuffer or ArrayBuffer.prototype.transfer while another realm is entered, where the finalizer saw that realm's global and left its scopes on the caller's stack. Only the teardown sweep went through env->CallFinalizer. As Node does, the deleter now only claims the callback, under the hints mutex, and queues it on its env. When the embedder attached an enqueue_foreground_task hook, the first deleter to queue posts one drain through it, outside the mutex: the hook may hand the drain to the env's thread and wait for it, and the drain takes the mutex. Without a hook the env's next checkpoint drains the queue. DrainFinalizerQueue runs the queued callbacks through CallFinalizer, in the env's realm with their own handle scope, after the ref and buffer finalizers, whose release can free more backing stores. The env stops posting when its teardown begins, FinalizeExternalBackingStoreHints runs what is queued along with the live hints, again after the instance-data finalizer so buffers the late finalizers make are finalized too, and the teardown waits for a post still in the hook before the env goes away. A deleter that runs after the sweep sees no env and only frees its hint, as before. The mutex is now NapiV8ExternalHintsMutex(), so unofficial_napi_attach_env writes the hook under it; a drain reads an atomic flag before taking it. New tests, in test_69 (V8 and QuickJS) and test_66 (V8). An external ArrayBuffer detached while another realm is entered is finalized once, on the env's thread, in the env's realm, after a checkpoint or at the latest at release, and on V8 not inside the detach. 1024 collected under allocation pressure with another realm entered are all finalized once, on the env's thread, in the env's realm, and on V8 none inside collect_garbage. With a queueing hook, 6400 are finalized from the hook's queue alone, never off the env's thread. A backing store freed on a std::thread is finalized by the drain that thread posts, while the test's hook holds the post until the env's thread has run it, so a lock held across the hook call deadlocks. The env outlives such a post when it is released meanwhile: the test lets the hook go only after the instance-data finalizer has run, and without the teardown wait ASan reports the env used after free. One finalizer the instance-data finalizer makes and detaches still runs (V8 only: QuickJS frees its context before that finalizer, which then crashes making values). At f928811 on V8 the detach finalizer ran inside the detach and saw the entered realm's global, also at release; 1024 of 1024 ran inside the collector, 896 of them off the env's thread and 128 in the entered realm; 6400 ran inside the collector, 6336 off the env's thread; the one freed on a std::thread ran there and posted no drain. QuickJS passed already: it finalizes on the env's thread in the env's realm. The instance-data case passed too, by finalizing inside the detach. No existing test encoded the old timing: test_33's transfer-and-detach test counts finalizers after release. V8 178/178 (also with the provider built with ASan), QuickJS 165/165 (also Debug+ASan), Rust lib 54, concurrent_envs 11, concurrent_stores 2, guest_callbacks 4, manifest 37/37 (native and WASIX), host-JS node 43/43, wasm-bindgen 26/26. Co-Authored-By: Claude Opus 5.5 --- .../test_66_foreground_task_handoff.cc | 243 +++++++++++++++++- .../runners/test_69_unofficial_realm_entry.cc | 194 ++++++++++++++ v8/src/internal/napi_v8_agent.h | 4 +- v8/src/internal/napi_v8_env.h | 31 +++ v8/src/js_native_api_v8.cc | 220 +++++++++++----- v8/src/unofficial_napi.cc | 8 +- 6 files changed, 629 insertions(+), 71 deletions(-) diff --git a/tests/runners/test_66_foreground_task_handoff.cc b/tests/runners/test_66_foreground_task_handoff.cc index 404ca03d33..88569f1a5f 100644 --- a/tests/runners/test_66_foreground_task_handoff.cc +++ b/tests/runners/test_66_foreground_task_handoff.cc @@ -15,15 +15,21 @@ // leaks its pending-task count, which makes unofficial_napi_release_env wait // forever; the watchdog below turns that into a failure. +#include #include #include #include #include #include +#include #include +#include #include #include #include +#include + +#include #include "test_env.h" @@ -54,11 +60,24 @@ struct HookState { const HookMode mode; napi_env env = nullptr; + // Made on the test's thread, which is the env's. + const std::thread::id env_thread = std::this_thread::get_id(); + // In kQueue mode, while set, a task posted from another thread also waits + // until the env's thread has run or released it. A hook may not wait like + // that in general, since it is called during GCs; tests do it while nothing + // collects, to show the provider holds no lock the task needs while it + // calls the hook. + std::atomic hand_off{false}; std::mutex mutex; std::condition_variable cv; bool closed = false; std::deque queue; + // Tasks queued, and tasks run or released since, in queue order. + uint64_t queued = 0; + uint64_t done = 0; + // Threads that waited in the hook because of `hand_off`. + std::vector waited; std::atomic enqueued{0}; std::atomic released{0}; @@ -99,10 +118,17 @@ napi_status EnqueueHook(void* target, return napi_ok; case HookMode::kQueue: { { - std::lock_guard lock(state->mutex); + std::unique_lock lock(state->mutex); if (!state->closed) { state->queue.push_back(task); + const uint64_t ticket = ++state->queued; + const bool wait = + state->hand_off.load() && std::this_thread::get_id() != state->env_thread; + if (wait) state->waited.push_back(std::this_thread::get_id()); state->cv.notify_all(); + if (wait) { + state->cv.wait(lock, [state, ticket] { return state->done >= ticket; }); + } return napi_ok; } } @@ -122,6 +148,11 @@ size_t RunQueuedTasks(HookState* state) { batch.swap(state->queue); } for (const HookedTask& task : batch) RunTask(state, task); + { + std::lock_guard lock(state->mutex); + state->done += batch.size(); + } + state->cv.notify_all(); return batch.size(); } @@ -135,6 +166,11 @@ void CloseQueue(HookState* state) { batch.swap(state->queue); } for (const HookedTask& task : batch) ReleaseTask(state, task); + { + std::lock_guard lock(state->mutex); + state->done += batch.size(); + } + state->cv.notify_all(); } // Aborts the process if it is not destroyed within `limit`. A provider that @@ -373,4 +409,209 @@ TEST_F(Test66ForegroundTaskHandoff, QueuedTasksRunOnTheEnvThread) { EXPECT_EQ(hook.released.load(), hook.enqueued.load()); } +struct ExternalFinalizerCounts { + std::thread::id env_thread = std::this_thread::get_id(); + std::atomic calls{0}; + std::atomic off_thread{0}; +}; + +void CountExternalFinalizer(node_api_basic_env /*env*/, void* data, void* hint) { + auto* counts = static_cast(hint); + if (std::this_thread::get_id() != counts->env_thread) counts->off_thread.fetch_add(1); + delete[] static_cast(data); + counts->calls.fetch_add(1); +} + +// V8 sweeps dead ArrayBuffers on its own threads too, and frees their backing +// stores there. An external ArrayBuffer's finalizer never runs there, nor +// inside the collector: the provider posts a drain through the hook, which +// runs it on the env's thread. +TEST_F(Test66ForegroundTaskHandoff, ExternalArrayBufferFinalizersRunFromAQueuedTask) { + constexpr int kBatches = 100; + constexpr int kBuffers = kBatches * 64; + ExternalFinalizerCounts counts; + HookState hook(HookMode::kQueue); + { + HookedEnv env(&hook); + ASSERT_NE(env.env(), nullptr); + ASSERT_TRUE(env.attached()); + + // Allocation pressure on the small heap, rather than a forced collection, + // makes V8 sweep concurrently. + for (int batch = 0; batch < kBatches; ++batch) { + napi_handle_scope handles = nullptr; + ASSERT_EQ(napi_open_handle_scope(env.env(), &handles), napi_ok); + for (int i = 0; i < kBuffers / kBatches; ++i) { + auto* bytes = new uint8_t[1024](); + napi_value buffer = nullptr; + ASSERT_EQ(napi_create_external_arraybuffer(env.env(), bytes, 1024, + CountExternalFinalizer, &counts, + &buffer), + napi_ok); + } + ASSERT_TRUE(RunJs(env.env(), + "{ let a = []; for (let i = 0; i < 20000; i++) a.push({ i }); }")); + ASSERT_EQ(napi_close_handle_scope(env.env(), handles), napi_ok); + } + ASSERT_EQ(unofficial_napi_collect_garbage(env.env()), napi_ok); + EXPECT_EQ(counts.calls.load(), 0) << "finalizers ran inside the collector"; + + // Only the hook's queue runs; nothing drains finalizers at a checkpoint. + const auto deadline = steady_clock::now() + seconds(20); + while (counts.calls.load() < kBuffers) { + ASSERT_LT(steady_clock::now(), deadline) + << "only " << counts.calls.load() << " of " << kBuffers + << " external finalizers ran"; + if (RunQueuedTasks(&hook) == 0) { + // Collects any buffer the first collection missed. + ASSERT_EQ(unofficial_napi_collect_garbage(env.env()), napi_ok); + std::unique_lock lock(hook.mutex); + hook.cv.wait_for(lock, milliseconds(10), + [&hook] { return !hook.queue.empty(); }); + } + } + EXPECT_EQ(counts.off_thread.load(), 0); + + CloseQueue(&hook); + env.Release(); + } + EXPECT_EQ(counts.calls.load(), kBuffers); + EXPECT_EQ(hook.released.load(), hook.enqueued.load()); +} + +// Makes an external ArrayBuffer and detaches it. Only `store` keeps its +// backing store alive. +void MakeDetachedExternalBuffer(napi_env env, + ExternalFinalizerCounts* counts, + std::shared_ptr* store) { + napi_handle_scope handles = nullptr; + ASSERT_EQ(napi_open_handle_scope(env, &handles), napi_ok); + auto* bytes = new uint8_t[1024](); + napi_value buffer = nullptr; + ASSERT_EQ(napi_create_external_arraybuffer(env, bytes, 1024, CountExternalFinalizer, counts, + &buffer), + napi_ok); + // This provider's napi_value is a v8::Local. + v8::Local value; + std::memcpy(static_cast(&value), &buffer, sizeof(buffer)); + *store = value.As()->GetBackingStore(); + ASSERT_EQ(napi_detach_arraybuffer(env, buffer), napi_ok); + ASSERT_EQ(napi_close_handle_scope(env, handles), napi_ok); + ASSERT_EQ(counts->calls.load(), 0); +} + +// The last reference to a backing store drops on another thread, so its +// deleter runs there and posts the drain. The hook hands the drain to the +// env's thread and waits until it has run, which deadlocks if the provider +// posts while holding a lock the drain takes. +TEST_F(Test66ForegroundTaskHandoff, + ExternalArrayBufferFreedOnAnotherThreadIsFinalizedByThePostedDrain) { + ExternalFinalizerCounts counts; + HookState hook(HookMode::kQueue); + { + HookedEnv env(&hook); + ASSERT_NE(env.env(), nullptr); + ASSERT_TRUE(env.attached()); + std::shared_ptr store; + ASSERT_NO_FATAL_FAILURE(MakeDetachedExternalBuffer(env.env(), &counts, &store)); + + { + Watchdog watchdog("the drain posted from another thread", seconds(30)); + hook.hand_off = true; + std::thread dropper([&store] { store.reset(); }); + // Only the hook's queue runs. + const auto deadline = steady_clock::now() + seconds(20); + while (counts.calls.load() == 0 && steady_clock::now() < deadline) { + if (RunQueuedTasks(&hook) == 0) { + std::unique_lock lock(hook.mutex); + hook.cv.wait_for(lock, milliseconds(10), + [&hook] { return !hook.queue.empty(); }); + } + } + // Releases what the hook still holds, so the dropper returns. + CloseQueue(&hook); + dropper.join(); + hook.hand_off = false; + } + EXPECT_EQ(counts.calls.load(), 1); + EXPECT_EQ(counts.off_thread.load(), 0); + env.Release(); + } + EXPECT_EQ(hook.released.load(), hook.enqueued.load()); +} + +struct InstanceDataSignal { + ExternalFinalizerCounts* counts = nullptr; + std::mutex mutex; + std::condition_variable cv; + bool finalized = false; + int calls_before = -1; +}; + +void SignalInstanceDataFinalized(napi_env /*env*/, void* data, void* /*hint*/) { + auto* signal = static_cast(data); + std::lock_guard lock(signal->mutex); + signal->calls_before = signal->counts->calls.load(); + signal->finalized = true; + signal->cv.notify_all(); +} + +// The env is released while a deleter on another thread is still in the +// hook, posting a drain. The release runs the queued finalizer itself, and +// the env outlives the post: the release waits for the hook to return, which +// here is only once the embedder lets go of the task. +TEST_F(Test66ForegroundTaskHandoff, ReleaseOutlastsADrainBeingPostedFromAnotherThread) { + ExternalFinalizerCounts counts; + InstanceDataSignal signal; + signal.counts = &counts; + HookState hook(HookMode::kQueue); + { + HookedEnv env(&hook); + ASSERT_NE(env.env(), nullptr); + ASSERT_TRUE(env.attached()); + std::shared_ptr store; + ASSERT_NO_FATAL_FAILURE(MakeDetachedExternalBuffer(env.env(), &counts, &store)); + // Runs last in the release, just before it waits for posts. + ASSERT_EQ(napi_set_instance_data(env.env(), &signal, SignalInstanceDataFinalized, nullptr), + napi_ok); + + Watchdog watchdog("the release while a drain was being posted", seconds(30)); + hook.hand_off = true; + std::thread dropper([&store] { store.reset(); }); + const std::thread::id dropper_id = dropper.get_id(); + bool posted = false; + { + // The dropper has posted its drain and waits in the hook. + std::unique_lock lock(hook.mutex); + posted = hook.cv.wait_for(lock, seconds(10), [&] { + return std::find(hook.waited.begin(), hook.waited.end(), dropper_id) != + hook.waited.end(); + }); + } + if (!posted) { + dropper.join(); + hook.hand_off = false; + FAIL() << "the deleter posted no drain from the dropper's thread"; + } + std::thread closer([&] { + { + std::unique_lock lock(signal.mutex); + signal.cv.wait(lock, [&] { return signal.finalized; }); + } + // By now the release waits for the post, or is about to. + std::this_thread::sleep_for(milliseconds(100)); + CloseQueue(&hook); + }); + env.Release(); + closer.join(); + dropper.join(); + hook.hand_off = false; + } + // The release ran the queued finalizer before the instance-data finalizer. + EXPECT_EQ(signal.calls_before, 1); + EXPECT_EQ(counts.calls.load(), 1); + EXPECT_EQ(counts.off_thread.load(), 0); + EXPECT_EQ(hook.released.load(), hook.enqueued.load()); +} + } // namespace diff --git a/tests/runners/test_69_unofficial_realm_entry.cc b/tests/runners/test_69_unofficial_realm_entry.cc index 9ccdb70183..d960f76da0 100644 --- a/tests/runners/test_69_unofficial_realm_entry.cc +++ b/tests/runners/test_69_unofficial_realm_entry.cc @@ -7,9 +7,12 @@ #include "unofficial_napi.h" +#include #include +#include #include #include +#include #include // The current realm: what N-API creates while a realm is entered or one of @@ -783,6 +786,197 @@ TEST_F(Test69UnofficialRealmEntry, ReplacedInstanceDataIsFinalizedInTheEnvsRealm } EXPECT_TRUE(StrictEquals(s.env, Global(s.env), env_global)); } + +// External ArrayBuffer finalizers. An engine may free a backing store +// wherever its last reference drops: on a collector thread, or inside a +// detach while another realm is entered. Its finalizer still runs on the +// env's thread, in the env's realm, as in Node. + +namespace { + +constexpr char kEnvMarker[] = "__envMarker"; + +// Marks the env's global, which no other realm's global has. +void MarkEnvGlobal(napi_env env) { + napi_value marker = nullptr; + ASSERT_EQ(napi_get_boolean(env, true, &marker), napi_ok); + ASSERT_EQ(napi_set_named_property(env, Global(env), kEnvMarker, marker), napi_ok); +} + +// Made on the test's thread, which is the env's. +struct ExternalFinalizerRecord { + std::thread::id env_thread = std::this_thread::get_id(); + uint8_t bytes[8] = {}; + std::atomic calls{0}; + std::atomic on_env_thread{false}; + std::atomic saw_env_global{false}; +}; + +void RecordExternalFinalizer(node_api_basic_env basic_env, void*, void* hint) { + auto* record = static_cast(hint); + const bool on_env_thread = std::this_thread::get_id() == record->env_thread; + record->on_env_thread = on_env_thread; + // N-API is only usable on the env's thread. + if (on_env_thread) { + auto env = const_cast(basic_env); + bool has_marker = false; + record->saw_env_global = + napi_has_named_property(env, Global(env), kEnvMarker, &has_marker) == napi_ok && + has_marker; + } + record->calls.fetch_add(1); +} + +} // namespace + +TEST_F(Test69UnofficialRealmEntry, DetachedExternalArrayBufferIsFinalizedLaterInTheEnvsRealm) { + ExternalFinalizerRecord record; + EnvScope s(runtime_.get()); + unofficial_napi_realm a = CreateRealm(s.env); + ASSERT_NE(a, nullptr); + MarkEnvGlobal(s.env); + napi_value buffer = nullptr; + ASSERT_EQ(napi_create_external_arraybuffer(s.env, record.bytes, sizeof(record.bytes), + RecordExternalFinalizer, &record, &buffer), + napi_ok); + + unofficial_napi_realm_scope scope = Enter(s.env, a); + ASSERT_EQ(napi_detach_arraybuffer(s.env, buffer), napi_ok); +#if defined(NAPI_TEST_ENGINE_V8) + // V8 frees the backing store inside the detach, and the finalizer waits + // for the env to drain its finalizers. QuickJS runs it in the detach, in + // the env's realm. + EXPECT_EQ(record.calls.load(), 0); +#endif + ASSERT_EQ(unofficial_napi_event_loop_checkpoint( + s.env, unofficial_napi_event_loop_checkpoint_microtasks, true, nullptr), + napi_ok); + Leave(s.env, scope); + + EXPECT_EQ(record.calls.load(), 1); + EXPECT_TRUE(record.on_env_thread.load()); + EXPECT_TRUE(record.saw_env_global.load()); +} + +// A finalizer still waiting when the env is released runs then, once. +TEST_F(Test69UnofficialRealmEntry, DetachedExternalArrayBufferIsFinalizedByTheEnvsRelease) { + ExternalFinalizerRecord record; + EnvScope s(runtime_.get()); + unofficial_napi_realm a = CreateRealm(s.env); + ASSERT_NE(a, nullptr); + MarkEnvGlobal(s.env); + napi_value buffer = nullptr; + ASSERT_EQ(napi_create_external_arraybuffer(s.env, record.bytes, sizeof(record.bytes), + RecordExternalFinalizer, &record, &buffer), + napi_ok); + + unofficial_napi_realm_scope scope = Enter(s.env, a); + ASSERT_EQ(napi_detach_arraybuffer(s.env, buffer), napi_ok); + Leave(s.env, scope); + Release(s); + + EXPECT_EQ(record.calls.load(), 1); + EXPECT_TRUE(record.on_env_thread.load()); + EXPECT_TRUE(record.saw_env_global.load()); +} + +#if defined(NAPI_TEST_ENGINE_V8) +namespace { + +void DetachExternalBufferFromInstanceDataFinalizer(napi_env env, void* data, void*) { + auto* record = static_cast(data); + napi_value buffer = nullptr; + if (napi_create_external_arraybuffer(env, record->bytes, sizeof(record->bytes), + RecordExternalFinalizer, record, &buffer) == napi_ok) { + (void)napi_detach_arraybuffer(env, buffer); + } +} + +} // namespace + +// The instance-data finalizer runs last in the release. An external buffer it +// makes and detaches is still finalized, once. V8 only: the QuickJS provider +// frees its context before it runs that finalizer, which then cannot make +// values. +TEST_F(Test69UnofficialRealmEntry, ExternalArrayBufferTheInstanceDataFinalizerDetachesIsFinalized) { + ExternalFinalizerRecord record; + EnvScope s(runtime_.get()); + MarkEnvGlobal(s.env); + ASSERT_EQ(napi_set_instance_data(s.env, &record, DetachExternalBufferFromInstanceDataFinalizer, + nullptr), + napi_ok); + Release(s); + + EXPECT_EQ(record.calls.load(), 1); + EXPECT_TRUE(record.on_env_thread.load()); + EXPECT_TRUE(record.saw_env_global.load()); +} +#endif + +TEST_F(Test69UnofficialRealmEntry, CollectedExternalArrayBuffersAreFinalizedOnTheEnvsThread) { + constexpr int kBatches = 16; + constexpr int kBuffers = kBatches * 64; + auto records = std::make_unique(kBuffers); + auto finalized = [&records] { + int calls = 0; + for (int i = 0; i < kBuffers; ++i) calls += records[i].calls.load(); + return calls; + }; + EnvScope s(runtime_.get()); + unofficial_napi_realm a = CreateRealm(s.env); + ASSERT_NE(a, nullptr); + MarkEnvGlobal(s.env); + + // The buffers become unreachable, and are collected and finalized, with A + // entered. Allocation between batches lets V8 collect, and sweep on its own + // threads, as it goes. + unofficial_napi_realm_scope scope = Enter(s.env, a); + for (int batch = 0; batch < kBatches; ++batch) { + napi_handle_scope handles = nullptr; + ASSERT_EQ(napi_open_handle_scope(s.env, &handles), napi_ok); + for (int i = batch * (kBuffers / kBatches); i < (batch + 1) * (kBuffers / kBatches); ++i) { + ExternalFinalizerRecord& record = records[i]; + napi_value buffer = nullptr; + ASSERT_EQ(napi_create_external_arraybuffer(s.env, record.bytes, sizeof(record.bytes), + RecordExternalFinalizer, &record, &buffer), + napi_ok); + } + ASSERT_NE(Eval(s.env, "{ let a = []; for (let i = 0; i < 20000; i++) a.push({ i }); 0 }"), + nullptr); + ASSERT_EQ(napi_close_handle_scope(s.env, handles), napi_ok); + } + ASSERT_EQ(unofficial_napi_collect_garbage(s.env), napi_ok); +#if defined(NAPI_TEST_ENGINE_V8) + // The collector only hands them to the env. QuickJS runs them as it + // collects, on this thread and in the env's realm. + EXPECT_EQ(finalized(), 0); +#endif + for (int round = 0; round < 10 && finalized() < kBuffers; ++round) { + ASSERT_EQ(unofficial_napi_event_loop_checkpoint( + s.env, unofficial_napi_event_loop_checkpoint_microtasks, true, nullptr), + napi_ok); + if (finalized() < kBuffers) ASSERT_EQ(unofficial_napi_collect_garbage(s.env), napi_ok); + } + Leave(s.env, scope); + + int not_once = 0; + int off_thread = 0; + int in_another_realm = 0; + for (int i = 0; i < kBuffers; ++i) { + const ExternalFinalizerRecord& record = records[i]; + if (record.calls.load() != 1) ++not_once; + if (record.calls.load() == 0) continue; + if (!record.on_env_thread.load()) { + ++off_thread; + } else if (!record.saw_env_global.load()) { + ++in_another_realm; + } + } + EXPECT_EQ(not_once, 0); + EXPECT_EQ(off_thread, 0); + EXPECT_EQ(in_another_realm, 0); +} + // Intrinsics in an entered realm: what N-API makes there comes from the // realm's own intrinsics, never from whatever its global now holds, which its // scripts control. diff --git a/v8/src/internal/napi_v8_agent.h b/v8/src/internal/napi_v8_agent.h index 2d14ea394a..67648ba4f8 100644 --- a/v8/src/internal/napi_v8_agent.h +++ b/v8/src/internal/napi_v8_agent.h @@ -19,7 +19,9 @@ class CpuProfiler; // its principal env; envs for other realms of the isolate will share it. // // Only the isolate's own thread reads or writes these fields, except -// `allocator` and `hash_seed`, which are fixed once the agent is set up. +// `allocator` and `hash_seed`, which are fixed once the agent is set up, and +// the enqueue hook, which backing-store deleters read on any thread under +// NapiV8ExternalHintsMutex(). struct napi_agent__ { explicit napi_agent__(v8::Isolate* isolate); ~napi_agent__(); diff --git a/v8/src/internal/napi_v8_env.h b/v8/src/internal/napi_v8_env.h index 98e5048761..cef4448308 100644 --- a/v8/src/internal/napi_v8_env.h +++ b/v8/src/internal/napi_v8_env.h @@ -2,9 +2,12 @@ #define NAPI_V8_ENV_H_ #include +#include +#include #include #include #include +#include #include #include #include @@ -48,6 +51,14 @@ inline v8::Local V8LocalValueFromJsValue(napi_value value) { return local; } +// An external backing store's finalizer, claimed by the store's deleter and +// waiting to run on the env's thread. +struct napi_external_finalizer__ { + node_api_basic_finalize cb = nullptr; + void* data = nullptr; + void* hint = nullptr; +}; + struct napi_callback_info__ { virtual ~napi_callback_info__() = default; virtual size_t argc() const = 0; @@ -150,6 +161,21 @@ struct napi_env__ { std::unordered_set pending_finalizers; std::unordered_set pending_buffer_finalizers; bool finalization_scheduled = false; + // External backing-store finalizers their deleters queued for the env's + // thread. Deleters run on any thread, so the fields below are guarded by + // NapiV8ExternalHintsMutex(); `has_external_finalizers` is also read + // without it, so a drain skips the lock when nothing is queued. + std::vector external_finalizers; + std::atomic has_external_finalizers{false}; + // A deleter posted a drain for them. + bool external_finalizer_drain_posted = false; + // Deleters in the embedder's hook, posting a drain. The env's teardown + // waits for them. + int external_drain_posts_in_flight = 0; + std::condition_variable external_drain_posts_done; + // The env is being torn down: deleters queue without posting, and the + // teardown runs what they queue. + bool releasing = false; // Realm hooks: unofficial_napi_set_promise_reject_callback and // unofficial_napi_set_promise_hooks (init, before, after, resolve). v8::Global promise_reject_callback; @@ -181,6 +207,11 @@ class napi_realm_frame_scope__ { size_t depth_; }; +// Guards what backing-store deleters share with the env's thread: the +// external hints, the hints' env pointers, the envs' queued external +// finalizers, and the enqueue hook a deleter posts their drain with. +std::mutex& NapiV8ExternalHintsMutex(); + napi_status napi_v8_set_last_error(napi_env env, napi_status status, const char* message); diff --git a/v8/src/js_native_api_v8.cc b/v8/src/js_native_api_v8.cc index f971dbd22d..97d326a8b3 100644 --- a/v8/src/js_native_api_v8.cc +++ b/v8/src/js_native_api_v8.cc @@ -28,6 +28,26 @@ #include #include +// Guards `napi_env__::external_backing_store_hints`, the `hint->env` back +// pointer, and the env's queue of external finalizers. +// +// V8 destroys backing stores from its ArrayBufferSweeper, which runs on +// background threads, so `ExternalBackingStoreDeleter` executes concurrently +// with the main thread creating new hints. The set was being mutated from both +// without synchronization, which corrupts the host heap — glibc aborts with +// "malloc_consolidate(): unaligned fastbin chunk detected" a few hundred +// requests into a payload-heavy workload. (`GuestHeap` already takes its own +// mutex for exactly this reason; this container was missed.) +// +// Process-global rather than a member because a deleter has to read +// `hint->env` before it can know which env to lock, and that read races +// teardown. Never destroyed, matching the other process-lifetime globals here +// (see the runtime-globals comment in unofficial_napi.cc). +std::mutex& NapiV8ExternalHintsMutex() { + static std::mutex& mutex = *new std::mutex(); + return mutex; +} + namespace { void DrainFinalizerQueueForegroundTask(napi_env env, void* data) { @@ -211,91 +231,129 @@ void BufferWeakCallback(const v8::WeakCallbackInfo& info) { } } -// Guards `napi_env__::external_backing_store_hints` and the `hint->env` back -// pointer. -// -// V8 destroys backing stores from its ArrayBufferSweeper, which runs on -// background threads, so `ExternalBackingStoreDeleter` executes concurrently -// with the main thread creating new hints. The set was being mutated from both -// without synchronization, which corrupts the host heap — glibc aborts with -// "malloc_consolidate(): unaligned fastbin chunk detected" a few hundred -// requests into a payload-heavy workload. (`GuestHeap` already takes its own -// mutex for exactly this reason; this container was missed.) -// -// Process-global rather than a member because a deleter has to read -// `hint->env` before it can know which env to lock, and that read races -// teardown. Never destroyed, matching the other process-lifetime globals here -// (see the runtime-globals comment in unofficial_napi.cc). -std::mutex& ExternalHintsMutex() { - static std::mutex& mutex = *new std::mutex(); - return mutex; +// Queues an external backing store's finalizer for the env's thread. Returns +// true when the caller must then post a drain for it, with +// PostExternalFinalizerDrain. The caller holds NapiV8ExternalHintsMutex(), +// which keeps `env` alive: its teardown takes the lock before it lets go of a +// hint. +bool QueueExternalFinalizer(napi_env env, const napi_external_finalizer__& finalizer) { + env->external_finalizers.push_back(finalizer); + env->has_external_finalizers.store(true, std::memory_order_release); + // Without a hook, the env's next checkpoint drains the queue; once the env + // is being torn down, the teardown does. + napi_agent__* agent = env->agent; + if (env->external_finalizer_drain_posted || env->releasing || agent == nullptr || + agent->enqueue_foreground_task_callback == nullptr) { + return false; + } + env->external_finalizer_drain_posted = true; + ++env->external_drain_posts_in_flight; + return true; } - +// Posts a drain of the env's external finalizers. Called without the lock: +// the hook may hand the drain to the env's thread and wait for it to run, and +// the drain takes the lock. The env's teardown waits for the post to finish. +void PostExternalFinalizerDrain(napi_env env, + unofficial_napi_enqueue_foreground_task_callback enqueue, + void* target) { + const bool posted = + enqueue(target, DrainFinalizerQueueForegroundTask, env, nullptr, 0) == napi_ok; + std::lock_guard lock(NapiV8ExternalHintsMutex()); + // Refused: another deleter may post, or the next checkpoint drains. + if (!posted) env->external_finalizer_drain_posted = false; + // Notified under the lock: the env may be gone once its teardown sees no + // post in flight. + if (--env->external_drain_posts_in_flight == 0) { + env->external_drain_posts_done.notify_all(); + } +} + +// Takes the external finalizers deleters queued for `env`. Env thread only. +std::vector TakeExternalFinalizers(napi_env env) { + std::vector taken; + if (!env->has_external_finalizers.load(std::memory_order_acquire)) return taken; + std::lock_guard lock(NapiV8ExternalHintsMutex()); + taken.swap(env->external_finalizers); + env->has_external_finalizers.store(false, std::memory_order_relaxed); + env->external_finalizer_drain_posted = false; + return taken; +} + +// V8 calls this wherever the last reference to the backing store drops: on +// one of its own threads, during a GC, or inside a detach or transfer while +// another realm is entered. None of those may run the finalizer, so, as Node +// does, this only claims it and hands it to the env's thread. void ExternalBackingStoreDeleter(void* data, size_t /*length*/, void* deleter_data) { auto* hint = static_cast(deleter_data); if (hint == nullptr) return; - // Read the env and unlink in one critical section: the pointer is cleared by - // FinalizeExternalBackingStoreHints under the same lock, so reading it - // outside would race teardown. - napi_env env = nullptr; - napi_finalize finalize_cb = nullptr; + napi_env post_to = nullptr; + unofficial_napi_enqueue_foreground_task_callback enqueue = nullptr; + void* target = nullptr; { - std::lock_guard lock(ExternalHintsMutex()); - env = hint->env; + // Reads the env and unlinks in one critical section: the env's teardown + // clears the pointer under the same lock. A cleared pointer means the + // teardown has claimed the finalizer, and maybe run it, already. + std::lock_guard lock(NapiV8ExternalHintsMutex()); + napi_env env = hint->env; if (env != nullptr) { v8impl::detail::napi_lifetime__:: record_release(env, hint); env->external_backing_store_hints.erase(hint); hint->env = nullptr; + if (hint->finalize_cb != nullptr && + QueueExternalFinalizer( + env, {hint->finalize_cb, + hint->external_data != nullptr ? hint->external_data : data, + hint->finalize_hint})) { + post_to = env; + enqueue = env->agent->enqueue_foreground_task_callback; + target = env->agent->enqueue_foreground_task_target; + } } - // Claim the callback under the lock so a concurrent teardown sweep cannot - // also run it. - finalize_cb = hint->finalize_cb; - hint->finalize_cb = nullptr; - } - // Outside the lock: a finalizer may re-enter N-API and create or destroy - // further hints. - if (finalize_cb != nullptr) { - finalize_cb(env, hint->external_data != nullptr ? hint->external_data : data, - hint->finalize_hint); } delete hint; + if (post_to != nullptr) PostExternalFinalizerDrain(post_to, enqueue, target); } void FinalizeExternalBackingStoreHints(napi_env env) { if (!CheckEnv(env)) return; - // Detach the whole set under the lock, then run the finalizers outside it. - // A backing store can still outlive the env, so each hint is unlinked from - // the dying env rather than deleted here — its deleter frees it later and, - // seeing a null env, skips the env-side bookkeeping. - // Each entry is the callback claimed from one hint, plus its arguments. The - // hints themselves are not touched after the lock is dropped: a concurrent - // deleter may already be freeing them. - std::vector> pending; - { - std::lock_guard lock(ExternalHintsMutex()); - std::unordered_set hints; - hints.swap(env->external_backing_store_hints); - pending.reserve(hints.size()); - for (auto* hint : hints) { - if (hint == nullptr) continue; - v8impl::detail::napi_lifetime__:: - record_release(env, hint); - hint->env = nullptr; - if (hint->finalize_cb != nullptr) { - pending.emplace_back(hint->finalize_cb, hint->external_data, - hint->finalize_hint); - hint->finalize_cb = nullptr; + // Claims, under the lock, the finalizers deleters queued and those of the + // backing stores still alive, then runs them outside it. A backing store + // can outlive the env, so each live hint is unlinked from the dying env + // rather than deleted here — its deleter frees it later and, seeing a null + // env, skips the env-side bookkeeping. The hints are not touched after the + // lock is dropped: a concurrent deleter may already be freeing them. + // Repeats while finalizers make more external buffers. + for (;;) { + std::vector pending; + { + std::lock_guard lock(NapiV8ExternalHintsMutex()); + pending.swap(env->external_finalizers); + env->has_external_finalizers.store(false, std::memory_order_relaxed); + env->external_finalizer_drain_posted = false; + std::unordered_set hints; + hints.swap(env->external_backing_store_hints); + if (pending.empty() && hints.empty()) return; + pending.reserve(pending.size() + hints.size()); + for (auto* hint : hints) { + if (hint == nullptr) continue; + v8impl::detail::napi_lifetime__:: + record_release(env, hint); + hint->env = nullptr; + if (hint->finalize_cb != nullptr) { + pending.push_back({hint->finalize_cb, hint->external_data, hint->finalize_hint}); + hint->finalize_cb = nullptr; + } } } - } - for (auto& [finalize_cb, external_data, finalize_hint] : pending) { - env->CallFinalizer(finalize_cb, external_data, finalize_hint); + for (const auto& finalizer : pending) { + env->CallFinalizer(finalizer.cb, finalizer.data, finalizer.hint); + } } } @@ -609,11 +667,15 @@ void napi_env__::DequeueFinalizer(napi_ref_tracker__* finalizer) { void napi_env__::DrainFinalizerQueue() { finalization_scheduled = false; - if (pending_finalizers.empty() && pending_buffer_finalizers.empty()) return; + std::vector external = TakeExternalFinalizers(this); + if (pending_finalizers.empty() && pending_buffer_finalizers.empty() && external.empty()) { + return; + } v8::HandleScope handle_scope(isolate); v8::Context::Scope context_scope(main_context()); napi_realm_frame_scope__ realm_frame(this, nullptr); - while (!pending_finalizers.empty() || !pending_buffer_finalizers.empty()) { + while (!pending_finalizers.empty() || !pending_buffer_finalizers.empty() || + !external.empty()) { while (!pending_finalizers.empty()) { napi_ref_tracker__* ref_tracker = *pending_finalizers.begin(); pending_finalizers.erase(ref_tracker); @@ -626,6 +688,13 @@ void napi_env__::DrainFinalizerQueue() { FinalizeBufferRecord(record); release(record); } + + for (const auto& finalizer : external) { + CallFinalizer(finalizer.cb, finalizer.data, finalizer.hint); + } + // Releasing a buffer record above can free its backing store, which + // queues the store's finalizer. + external = TakeExternalFinalizers(this); } } @@ -685,6 +754,12 @@ napi_env__::napi_env__(v8::Local context, int32_t module_api_versio napi_env__::~napi_env__() { NAPI_V8_LIFETIME_DUMP(this, "napi_env__ teardown begin"); + { + // A drain posted now could run after the env is gone. Deleters queue + // without posting; FinalizeExternalBackingStoreHints runs what they queue. + std::lock_guard lock(NapiV8ExternalHintsMutex()); + releasing = true; + } // Every scope closes. Cleanup hooks and finalizers each run in the env's // realm, and a scope one leaves open closes when it returns. PopRealmFrames(0); @@ -697,12 +772,23 @@ napi_env__::~napi_env__() { FinalizeExternalBackingStoreHints(this); napi_v8_finalize_buffer_records(this); CallFinalizer(instance_data_finalize_cb, instance_data, instance_data_finalize_hint); + // External buffers the finalizers above made: their finalizers run too, and + // no hint is left pointing at the env. + FinalizeExternalBackingStoreHints(this); // Backstop: nothing above should leave a scope open, and a context still // entered here would abort V8 at the embedder's next Context::Exit. PopRealmFrames(0); if (agent != nullptr && agent->principal_env == this) { agent->principal_env = nullptr; } + { + // A deleter still in the hook, posting a drain, touches the env when the + // hook returns. A hook that waits for the env's thread must let go of + // the task once the release begins; the release already needs that for + // the engine's own tasks. + std::unique_lock lock(NapiV8ExternalHintsMutex()); + external_drain_posts_done.wait(lock, [this] { return external_drain_posts_in_flight == 0; }); + } NAPI_V8_LIFETIME_DUMP(this, "napi_env__ teardown end"); } @@ -995,8 +1081,8 @@ napi_status NAPI_CDECL napi_create_external_arraybuffer( v8impl::detail::napi_lifetime__:: record_create(env, hint.get()); { - // Racing V8's ArrayBufferSweeper threads; see ExternalHintsMutex. - std::lock_guard lock(ExternalHintsMutex()); + // Racing V8's ArrayBufferSweeper threads; see NapiV8ExternalHintsMutex. + std::lock_guard lock(NapiV8ExternalHintsMutex()); env->external_backing_store_hints.insert(hint.release()); } out = v8::ArrayBuffer::New(env->isolate, std::move(backing)); @@ -3243,8 +3329,8 @@ napi_status NAPI_CDECL napi_create_external_buffer(napi_env env, v8impl::detail::napi_lifetime__:: record_create(env, hint.get()); { - // Racing V8's ArrayBufferSweeper threads; see ExternalHintsMutex. - std::lock_guard lock(ExternalHintsMutex()); + // Racing V8's ArrayBufferSweeper threads; see NapiV8ExternalHintsMutex. + std::lock_guard lock(NapiV8ExternalHintsMutex()); env->external_backing_store_hints.insert(hint.release()); } diff --git a/v8/src/unofficial_napi.cc b/v8/src/unofficial_napi.cc index df84d637aa..a3cdeceeec 100644 --- a/v8/src/unofficial_napi.cc +++ b/v8/src/unofficial_napi.cc @@ -1693,8 +1693,12 @@ napi_status NAPI_CDECL unofficial_napi_attach_env( napi_agent__* agent = env->agent; agent->fatal_error_callback = hooks->fatal_error_callback; agent->oom_error_callback = hooks->oom_error_callback; - agent->enqueue_foreground_task_callback = hooks->enqueue_foreground_task_callback; - agent->enqueue_foreground_task_target = hooks->data; + { + // Backing-store deleters read the hook on other threads. + std::lock_guard lock(NapiV8ExternalHintsMutex()); + agent->enqueue_foreground_task_callback = hooks->enqueue_foreground_task_callback; + agent->enqueue_foreground_task_target = hooks->data; + } agent->embedder_hooks_attached = true; env->isolate->SetFatalErrorHandler( From 0e9412e8076c5fb48cd8932e097338475e68e293 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 15:49:52 -0800 Subject: [PATCH 041/150] V8: free provider-owned external memory in the backing-store deleter The previous commit queued every external backing store's callback for the env's thread, including frees that need no env: the free() behind unofficial_napi_create_uninitialized_arraybuffer, the std::string behind the profile and heap-snapshot output, and the WASIX bridge's guest-heap frees, which back every guest napi_create_arraybuffer and uninitialized ArrayBuffer. The bridge attaches no enqueue hook, so that memory came back only at a guest checkpoint. A synchronous stretch that makes and drops buffers grew the guest heap without bound, and wasm memory never shrinks. Buffers were held until a drain even before that: each buffer record kept a reference to its backing store until the drain released the record. The uninitialized ArrayBuffer and the profile output now use a plain V8 deleter, with no napi hint. V8 frees them when it frees the store, wherever that happens, and the env's release no longer frees them while a buffer may still be in use. The new provider-private napi_v8_create_external_arraybuffer_with_free and napi_v8_create_external_buffer_with_free take a free callback (data, hint) in place of a finalizer. The deleter claims it under the hints mutex, as before, and runs it itself, outside the mutex. A store still alive at the env's release is freed then, once, as before. The bridge makes guest-heap ArrayBuffers and Buffers with them. User finalizers still wait for the env's thread. BufferWeakCallback now drops the record's reference to the store when the Buffer dies; nothing read it after the Buffer was made, and no record has a finalizer of its own. napi_create_external_buffer allocates its record before the backing store, so a failure no longer runs a callback whose data the caller still owns. Comments in the bridge and in guest_heap.rs no longer say these callbacks run synchronously in GC. New tests in test_66 (V8): - MemoryFreedInTheDeleterComesBackWithoutADrain makes 512 ArrayBuffers and 512 Buffers with a free callback, drops them, and collects garbage with neither the hook's queue nor a checkpoint run. All 1024 are freed. With the entry points forwarding to the user-finalizer path, as the bridge's calls did before this commit, 0 of 1024 were freed. With the free callback in the deleter but the records still holding their stores, 512 were (the Buffers stayed). - MemoryFreedInTheDeleterIsFreedOnceAtRelease: a live ArrayBuffer, a live Buffer and a detached store kept past the release are each freed once at the release, and not again when the store is dropped. It passes before the change too and guards the release. - UninitializedArrayBuffersAreFreedWithoutACheckpoint makes and drops 256 uninitialized 1 MiB ArrayBuffers and collects garbage. Before any checkpoint, malloc's bytes in use grow by less than 32 MiB. Before this commit, all 256 MiB stayed until the checkpoint. It is skipped under ASan, whose quarantine keeps freed memory, and where malloc statistics are missing. No existing test changed. A throwing finalizer still leaves its exception pending after the drain, for every finalizer kind, as at f928811. V8 181/181 on this tree. With the next commit applied, which changes only the env's teardown: V8 182/182 and the same with the provider built with ASan (the malloc test skipped there), QuickJS 165/165 (also Debug+ASan), Rust lib 54, concurrent_envs 11, concurrent_stores 2, guest_callbacks 4, manifest 37/37 (native and WASIX), host-JS node 43/43, wasm-bindgen 26/26. Co-Authored-By: Claude Opus 5.5 --- src/guest_heap.rs | 6 +- src/napi_bridge_init.cc | 24 +- .../test_66_foreground_task_handoff.cc | 178 +++++++++++++++ v8/src/internal/napi_env_records.h | 3 + v8/src/internal/napi_v8_env.h | 21 +- v8/src/js_native_api_v8.cc | 211 +++++++++++------- v8/src/unofficial_napi.cc | 47 ++-- 7 files changed, 378 insertions(+), 112 deletions(-) diff --git a/src/guest_heap.rs b/src/guest_heap.rs index 8d8a4dc97b..462466e1dd 100644 --- a/src/guest_heap.rs +++ b/src/guest_heap.rs @@ -743,7 +743,11 @@ pub extern "C" fn napi_host_guest_heap_release(ctx: *mut c_void) { } /// Finalizer for guest-heap-backed external buffers: frees the allocation and -/// drops the boxed context. Runs when V8 collects the buffer (any thread). +/// drops the boxed context. For a buffer it runs in V8's backing-store +/// deleter, on whatever thread frees the store, or at the env's release for a +/// buffer still alive then. Attached to another value +/// (`snapi_bridge_attach_guest_heap_finalizer`), it runs as that value's +/// finalizer, on the env's thread. #[unsafe(no_mangle)] pub extern "C" fn napi_host_guest_heap_buffer_finalize(_data: *mut c_void, hint: *mut c_void) { if hint.is_null() { diff --git a/src/napi_bridge_init.cc b/src/napi_bridge_init.cc index f76dc5079e..80a0cda62f 100644 --- a/src/napi_bridge_init.cc +++ b/src/napi_bridge_init.cc @@ -1705,6 +1705,13 @@ extern "C" __attribute__((weak)) void napi_host_guest_heap_buffer_finalize( void* /*data*/, void* /*hint*/) {} namespace { +// Runs in V8's backing-store deleter, on whatever thread frees the store, so +// the guest heap gets the memory back as V8 collects; GuestHeap takes its +// own lock. +void GuestHeapBufferFree(void* data, void* hint) { + napi_host_guest_heap_buffer_finalize(data, hint); +} + void GuestHeapBufferFinalizeTrampoline(node_api_basic_env /*env*/, void* data, void* hint) { napi_host_guest_heap_buffer_finalize(data, hint); @@ -1726,10 +1733,9 @@ namespace { // which fire on the *deferred* finalizer drain: their RefBase weak callbacks // enqueue into pending_finalizers, drained from the guest's // process-microtasks import call where an active callback ctx lets us re-enter -// the guest. (External array buffers/buffers deliberately do NOT use V8's -// backing-store deleter for the guest finalizer — those run synchronously in -// GC, with no way back into the guest — they attach via napi_add_finalizer -// instead.) Allocated on registration, freed exactly once when it fires. +// the guest. (External array buffers/buffers attach the guest finalizer the +// same way, with napi_add_finalizer, rather than as the backing store's own +// finalizer.) Allocated on registration, freed exactly once when it fires. struct GuestFinalizerRecord { SnapiEnvState* state; uint32_t guest_env; @@ -1865,9 +1871,8 @@ extern "C" int snapi_bridge_create_external_arraybuffer_finalized( napi_env env = bridge_state->env; void* data = (void*)(uintptr_t)data_addr; napi_value result; - napi_status s = napi_create_external_arraybuffer( - env, data, (size_t)byte_length, GuestHeapBufferFinalizeTrampoline, - finalize_hint, &result); + napi_status s = napi_v8_create_external_arraybuffer_with_free( + env, data, (size_t)byte_length, GuestHeapBufferFree, finalize_hint, &result); if (s != napi_ok) return s; if (backing_store_token_out) { *backing_store_token_out = napi_v8_get_arraybuffer_backing_store_token(env, result); @@ -1885,9 +1890,8 @@ extern "C" int snapi_bridge_create_external_buffer_finalized( napi_env env = bridge_state->env; void* data = (void*)(uintptr_t)data_addr; napi_value result; - napi_status s = napi_create_external_buffer( - env, (size_t)byte_length, data, GuestHeapBufferFinalizeTrampoline, - finalize_hint, &result); + napi_status s = napi_v8_create_external_buffer_with_free( + env, (size_t)byte_length, data, GuestHeapBufferFree, finalize_hint, &result); if (s != napi_ok) return s; if (backing_store_token_out) { *backing_store_token_out = napi_v8_get_arraybuffer_view_backing_store_token(env, result); diff --git a/tests/runners/test_66_foreground_task_handoff.cc b/tests/runners/test_66_foreground_task_handoff.cc index 88569f1a5f..c72f9ac459 100644 --- a/tests/runners/test_66_foreground_task_handoff.cc +++ b/tests/runners/test_66_foreground_task_handoff.cc @@ -30,9 +30,25 @@ #include #include +#if defined(__APPLE__) +#include +#elif defined(__GLIBC__) +#include +#endif #include "test_env.h" +// The V8 provider's own entry points for memory that only needs freeing +// (v8/src/internal/napi_v8_env.h). The WASIX bridge makes guest-heap buffers +// with them. +typedef void (*napi_v8_external_free_callback)(void* data, void* hint); +napi_status napi_v8_create_external_arraybuffer_with_free( + napi_env env, void* data, size_t byte_length, napi_v8_external_free_callback free_cb, + void* free_hint, napi_value* result); +napi_status napi_v8_create_external_buffer_with_free( + napi_env env, size_t length, void* data, napi_v8_external_free_callback free_cb, + void* free_hint, napi_value* result); + namespace { using std::chrono::milliseconds; @@ -614,4 +630,166 @@ TEST_F(Test66ForegroundTaskHandoff, ReleaseOutlastsADrainBeingPostedFromAnotherT EXPECT_EQ(hook.released.load(), hook.enqueued.load()); } +// Memory that only needs freeing comes back where V8 frees its backing store, +// unlike a user finalizer, which waits for the env's thread. Otherwise a +// synchronous stretch that makes and drops buffers keeps all of them until +// the next drain; a WASIX guest's heap then grows, and wasm memory never +// shrinks. + +struct FreeCounts { + std::atomic freed{0}; +}; + +void CountFree(void* data, void* hint) { + delete[] static_cast(data); + static_cast(hint)->freed.fetch_add(1); +} + +TEST_F(Test66ForegroundTaskHandoff, MemoryFreedInTheDeleterComesBackWithoutADrain) { + constexpr int kBatches = 16; + constexpr int kBuffers = kBatches * 64; + FreeCounts counts; + HookState hook(HookMode::kQueue); + { + HookedEnv env(&hook); + ASSERT_NE(env.env(), nullptr); + ASSERT_TRUE(env.attached()); + + for (int batch = 0; batch < kBatches; ++batch) { + napi_handle_scope handles = nullptr; + ASSERT_EQ(napi_open_handle_scope(env.env(), &handles), napi_ok); + for (int i = 0; i < kBuffers / kBatches; ++i) { + auto* bytes = new uint8_t[1024](); + napi_value buffer = nullptr; + // Half ArrayBuffers, half Buffers. + if (i % 2 == 0) { + ASSERT_EQ(napi_v8_create_external_arraybuffer_with_free(env.env(), bytes, 1024, + CountFree, &counts, &buffer), + napi_ok); + } else { + ASSERT_EQ(napi_v8_create_external_buffer_with_free(env.env(), 1024, bytes, CountFree, + &counts, &buffer), + napi_ok); + } + } + ASSERT_TRUE(RunJs(env.env(), + "{ let a = []; for (let i = 0; i < 20000; i++) a.push({ i }); }")); + ASSERT_EQ(napi_close_handle_scope(env.env(), handles), napi_ok); + } + // Neither the hook's queue nor a checkpoint runs; only the collector. + for (int round = 0; round < 20 && counts.freed.load() < kBuffers; ++round) { + ASSERT_EQ(unofficial_napi_collect_garbage(env.env()), napi_ok); + if (counts.freed.load() < kBuffers) std::this_thread::sleep_for(milliseconds(10)); + } + EXPECT_EQ(counts.freed.load(), kBuffers) << "freed only after a drain"; + + CloseQueue(&hook); + env.Release(); + } + EXPECT_EQ(counts.freed.load(), kBuffers); + EXPECT_EQ(hook.released.load(), hook.enqueued.load()); +} + +// What is still alive at the release is freed then, once, as before: the +// guest may reuse the memory after that. A backing store that outlives the +// env is not freed again when V8 drops it. +TEST_F(Test66ForegroundTaskHandoff, MemoryFreedInTheDeleterIsFreedOnceAtRelease) { + FreeCounts counts; + HookState hook(HookMode::kRefuse); + std::shared_ptr outliving; + { + HookedEnv env(&hook); + ASSERT_NE(env.env(), nullptr); + napi_handle_scope handles = nullptr; + ASSERT_EQ(napi_open_handle_scope(env.env(), &handles), napi_ok); + napi_value array_buffer = nullptr; + ASSERT_EQ(napi_v8_create_external_arraybuffer_with_free(env.env(), new uint8_t[16](), 16, + CountFree, &counts, &array_buffer), + napi_ok); + napi_value buffer = nullptr; + ASSERT_EQ(napi_v8_create_external_buffer_with_free(env.env(), 16, new uint8_t[16](), + CountFree, &counts, &buffer), + napi_ok); + napi_value detached = nullptr; + ASSERT_EQ(napi_v8_create_external_arraybuffer_with_free(env.env(), new uint8_t[16](), 16, + CountFree, &counts, &detached), + napi_ok); + // This provider's napi_value is a v8::Local. + v8::Local value; + std::memcpy(static_cast(&value), &detached, sizeof(detached)); + outliving = value.As()->GetBackingStore(); + ASSERT_EQ(napi_detach_arraybuffer(env.env(), detached), napi_ok); + // Keeps the other two alive until the release. + napi_value global = nullptr; + ASSERT_EQ(napi_get_global(env.env(), &global), napi_ok); + ASSERT_EQ(napi_set_named_property(env.env(), global, "liveArrayBuffer", array_buffer), + napi_ok); + ASSERT_EQ(napi_set_named_property(env.env(), global, "liveBuffer", buffer), napi_ok); + ASSERT_EQ(napi_close_handle_scope(env.env(), handles), napi_ok); + ASSERT_EQ(unofficial_napi_collect_garbage(env.env()), napi_ok); + EXPECT_EQ(counts.freed.load(), 0); + env.Release(); + } + EXPECT_EQ(counts.freed.load(), 3); + outliving.reset(); + EXPECT_EQ(counts.freed.load(), 3); + EXPECT_EQ(hook.released.load(), hook.enqueued.load()); +} + +#if defined(__has_feature) +#if __has_feature(address_sanitizer) +#define NAPI_TEST_ADDRESS_SANITIZER 1 +#endif +#endif +#if defined(__SANITIZE_ADDRESS__) +#define NAPI_TEST_ADDRESS_SANITIZER 1 +#endif + +// Bytes malloc has handed out and not had back, or 0 where unknown. +size_t MallocBytesInUse() { +#if defined(__APPLE__) + malloc_statistics_t stats{}; + malloc_zone_statistics(nullptr, &stats); + return stats.size_in_use; +#elif defined(__GLIBC__) && (__GLIBC__ > 2 || (__GLIBC__ == 2 && __GLIBC_MINOR__ >= 33)) + const struct mallinfo2 info = mallinfo2(); + return info.uordblks + info.hblkhd; +#else + return 0; +#endif +} + +// unofficial_napi_create_uninitialized_arraybuffer mallocs its memory, so a +// dropped buffer's memory comes back as V8 collects it. +TEST_F(Test66ForegroundTaskHandoff, UninitializedArrayBuffersAreFreedWithoutACheckpoint) { +#if defined(NAPI_TEST_ADDRESS_SANITIZER) + GTEST_SKIP() << "ASan holds freed memory in quarantine"; +#endif + if (MallocBytesInUse() == 0) GTEST_SKIP() << "no malloc statistics here"; + constexpr size_t kBufferSize = size_t{1} << 20; + constexpr int kBuffers = 256; + HookState hook(HookMode::kRefuse); + HookedEnv env(&hook); + ASSERT_NE(env.env(), nullptr); + RunMicrotasks(env.env()); + const size_t base = MallocBytesInUse(); + for (int i = 0; i < kBuffers; ++i) { + napi_handle_scope handles = nullptr; + ASSERT_EQ(napi_open_handle_scope(env.env(), &handles), napi_ok); + napi_value buffer = nullptr; + ASSERT_EQ(unofficial_napi_create_uninitialized_arraybuffer(env.env(), kBufferSize, false, + &buffer), + napi_ok); + ASSERT_EQ(napi_close_handle_scope(env.env(), handles), napi_ok); + if (i % 64 == 63) ASSERT_EQ(unofficial_napi_collect_garbage(env.env()), napi_ok); + } + ASSERT_EQ(unofficial_napi_collect_garbage(env.env()), napi_ok); + const size_t in_use = MallocBytesInUse(); + const size_t grown = in_use > base ? in_use - base : 0; + EXPECT_LT(grown, 32 * kBufferSize) + << (grown >> 20) << " MiB of " << ((kBuffers * kBufferSize) >> 20) + << " MiB of dropped buffers still held before a checkpoint"; + env.Release(); +} + } // namespace diff --git a/v8/src/internal/napi_env_records.h b/v8/src/internal/napi_env_records.h index 2b5a48638e..115bb0b8b7 100644 --- a/v8/src/internal/napi_env_records.h +++ b/v8/src/internal/napi_env_records.h @@ -65,6 +65,9 @@ struct napi_external_backing_store_hint__ { void* external_data = nullptr; node_api_basic_finalize finalize_cb = nullptr; void* finalize_hint = nullptr; + // Set instead of `finalize_cb` for memory that only needs freeing + // (napi_v8_external_free_callback); it gets `finalize_hint`. + void (*free_cb)(void* data, void* hint) = nullptr; }; using napi_external_backing_store_hint = napi_external_backing_store_hint__; diff --git a/v8/src/internal/napi_v8_env.h b/v8/src/internal/napi_v8_env.h index cef4448308..eb36b1b6bd 100644 --- a/v8/src/internal/napi_v8_env.h +++ b/v8/src/internal/napi_v8_env.h @@ -51,12 +51,18 @@ inline v8::Local V8LocalValueFromJsValue(napi_value value) { return local; } +// Frees an external backing store's memory. Runs in V8's deleter, on any +// thread, so it must not use V8 or an env. +typedef void (*napi_v8_external_free_callback)(void* data, void* hint); + // An external backing store's finalizer, claimed by the store's deleter and -// waiting to run on the env's thread. +// waiting to run on the env's thread. The teardown also claims stores' free +// callbacks: `free_cb` is set instead of `cb` for those. struct napi_external_finalizer__ { node_api_basic_finalize cb = nullptr; void* data = nullptr; void* hint = nullptr; + napi_v8_external_free_callback free_cb = nullptr; }; struct napi_callback_info__ { @@ -227,4 +233,17 @@ napi_value napi_v8_wrap_value(napi_env env, v8::Local value); v8::Local napi_v8_unwrap_value(napi_value value); void napi_v8_finalize_buffer_records(napi_env env); +// napi_create_external_arraybuffer and napi_create_external_buffer for memory +// that only needs freeing. `free_cb` runs in the backing store's deleter, +// wherever V8 frees it, so the memory comes back as V8 collects; a user +// finalizer instead waits for the env's thread. A store still alive at the +// env's release is freed then, and not again. Ownership of `free_hint` +// passes only on success. +napi_status napi_v8_create_external_arraybuffer_with_free( + napi_env env, void* data, size_t byte_length, napi_v8_external_free_callback free_cb, + void* free_hint, napi_value* result); +napi_status napi_v8_create_external_buffer_with_free( + napi_env env, size_t length, void* data, napi_v8_external_free_callback free_cb, + void* free_hint, napi_value* result); + #endif // NAPI_V8_ENV_H_ diff --git a/v8/src/js_native_api_v8.cc b/v8/src/js_native_api_v8.cc index 97d326a8b3..f59d19b087 100644 --- a/v8/src/js_native_api_v8.cc +++ b/v8/src/js_native_api_v8.cc @@ -224,6 +224,10 @@ void BufferWeakCallback(const v8::WeakCallbackInfo& info) { napi_buffer_record* owned_record = TakeBufferRecord(env, record); if (owned_record == nullptr) return; owned_record->holder.Reset(); + // Nothing reads the store once the Buffer is gone, and holding it until + // the drain would keep its memory until then. Freeing it here, if this + // is the last reference, uses no V8, so it is safe in a GC callback. + owned_record->backing_store.reset(); env->EnqueueBufferFinalizer(owned_record); } else { record->holder.Reset(); @@ -283,19 +287,22 @@ std::vector TakeExternalFinalizers(napi_env env) { // V8 calls this wherever the last reference to the backing store drops: on // one of its own threads, during a GC, or inside a detach or transfer while // another realm is entered. None of those may run the finalizer, so, as Node -// does, this only claims it and hands it to the env's thread. +// does, this only claims it and hands it to the env's thread. A free +// callback needs no env, so it runs here and the memory comes back now. void ExternalBackingStoreDeleter(void* data, size_t /*length*/, void* deleter_data) { auto* hint = static_cast(deleter_data); if (hint == nullptr) return; + if (hint->external_data != nullptr) data = hint->external_data; + napi_v8_external_free_callback free_cb = nullptr; napi_env post_to = nullptr; unofficial_napi_enqueue_foreground_task_callback enqueue = nullptr; void* target = nullptr; { // Reads the env and unlinks in one critical section: the env's teardown // clears the pointer under the same lock. A cleared pointer means the - // teardown has claimed the finalizer, and maybe run it, already. + // teardown has claimed the callback, and maybe run it, already. std::lock_guard lock(NapiV8ExternalHintsMutex()); napi_env env = hint->env; if (env != nullptr) { @@ -303,17 +310,16 @@ void ExternalBackingStoreDeleter(void* data, record_release(env, hint); env->external_backing_store_hints.erase(hint); hint->env = nullptr; + free_cb = hint->free_cb; if (hint->finalize_cb != nullptr && - QueueExternalFinalizer( - env, {hint->finalize_cb, - hint->external_data != nullptr ? hint->external_data : data, - hint->finalize_hint})) { + QueueExternalFinalizer(env, {hint->finalize_cb, data, hint->finalize_hint})) { post_to = env; enqueue = env->agent->enqueue_foreground_task_callback; target = env->agent->enqueue_foreground_task_target; } } } + if (free_cb != nullptr) free_cb(data, hint->finalize_hint); delete hint; if (post_to != nullptr) PostExternalFinalizerDrain(post_to, enqueue, target); } @@ -321,8 +327,9 @@ void ExternalBackingStoreDeleter(void* data, void FinalizeExternalBackingStoreHints(napi_env env) { if (!CheckEnv(env)) return; - // Claims, under the lock, the finalizers deleters queued and those of the - // backing stores still alive, then runs them outside it. A backing store + // Claims, under the lock, the finalizers deleters queued and the finalizers + // and free callbacks of the backing stores still alive, then runs them + // outside it. A backing store // can outlive the env, so each live hint is unlinked from the dying env // rather than deleted here — its deleter frees it later and, seeing a null // env, skips the env-side bookkeeping. The hints are not touched after the @@ -344,15 +351,21 @@ void FinalizeExternalBackingStoreHints(napi_env env) { v8impl::detail::napi_lifetime__:: record_release(env, hint); hint->env = nullptr; - if (hint->finalize_cb != nullptr) { - pending.push_back({hint->finalize_cb, hint->external_data, hint->finalize_hint}); + if (hint->finalize_cb != nullptr || hint->free_cb != nullptr) { + pending.push_back({hint->finalize_cb, hint->external_data, hint->finalize_hint, + hint->free_cb}); hint->finalize_cb = nullptr; + hint->free_cb = nullptr; } } } for (const auto& finalizer : pending) { - env->CallFinalizer(finalizer.cb, finalizer.data, finalizer.hint); + if (finalizer.free_cb != nullptr) { + finalizer.free_cb(finalizer.data, finalizer.hint); + } else { + env->CallFinalizer(finalizer.cb, finalizer.data, finalizer.hint); + } } } } @@ -622,6 +635,92 @@ void SetterTrampoline(v8::Local property, (void)HandleCallbackException(env); } +// A backing store over external memory. Its deleter hands `finalize_cb` to +// the env's thread, or runs `free_cb` itself; at most one is set. +std::unique_ptr NewExternalBackingStore(napi_env env, + void* data, + size_t length, + node_api_basic_finalize finalize_cb, + napi_v8_external_free_callback free_cb, + void* finalize_hint) { + auto hint = std::make_unique(env); + hint->external_data = data; + hint->finalize_cb = finalize_cb; + hint->finalize_hint = finalize_hint; + hint->free_cb = free_cb; + std::unique_ptr backing = + v8::ArrayBuffer::NewBackingStore(data, length, ExternalBackingStoreDeleter, hint.get()); + if (!backing) return nullptr; + v8impl::detail::napi_lifetime__:: + record_create(env, hint.get()); + { + // Racing V8's ArrayBufferSweeper threads; see NapiV8ExternalHintsMutex. + std::lock_guard lock(NapiV8ExternalHintsMutex()); + env->external_backing_store_hints.insert(hint.release()); + } + return backing; +} + +napi_status CreateExternalArrayBuffer(napi_env env, + void* external_data, + size_t byte_length, + node_api_basic_finalize finalize_cb, + napi_v8_external_free_callback free_cb, + void* finalize_hint, + napi_value* result) { + if (!CheckEnv(env) || result == nullptr) return napi_invalid_arg; + + v8::Local out; + if (external_data == nullptr && byte_length == 0) { + out = v8::ArrayBuffer::New(env->isolate, 0); + out->Detach(v8::Local()).FromMaybe(false); + } else { + if (external_data == nullptr) return napi_invalid_arg; + std::unique_ptr backing = NewExternalBackingStore( + env, external_data, byte_length, finalize_cb, free_cb, finalize_hint); + if (!backing) return napi_generic_failure; + out = v8::ArrayBuffer::New(env->isolate, std::move(backing)); + } + + *result = napi_v8_wrap_value(env, out); + return (*result == nullptr) ? napi_generic_failure : napi_ok; +} + +napi_status CreateExternalBuffer(napi_env env, + size_t length, + void* data, + node_api_basic_finalize finalize_cb, + napi_v8_external_free_callback free_cb, + void* finalize_hint, + napi_value* result) { + if (!CheckEnv(env) || data == nullptr || result == nullptr) return napi_invalid_arg; + v8::Local context = env->context(); + v8::Context::Scope context_scope(context); + + // Before the backing store: a failure after it would run the callback, + // whose data the caller still owns then. + auto* record = env->allocate(env); + if (record == nullptr) return napi_generic_failure; + record->backing_store = + NewExternalBackingStore(env, data, length, finalize_cb, free_cb, finalize_hint); + if (!record->backing_store) { + env->release(record); + return napi_generic_failure; + } + + v8::Local buffer_obj = CreateBufferObject(env, record->backing_store, 0, length); + record->holder.Reset(env->isolate, buffer_obj); + record->holder.SetWeak(record, BufferWeakCallback, v8::WeakCallbackType::kParameter); + v8::Local key = env->agent->buffer_private_key.Get(env->isolate); + buffer_obj + ->SetPrivate(env->context(), key, v8::External::New(env->isolate, record)) + .FromJust(); + env->buffer_records.push_back(record); + + *result = napi_v8_wrap_value(env, buffer_obj); + return (*result == nullptr) ? napi_generic_failure : napi_ok; +} + } // namespace void napi_v8_set_last_exception(napi_env env, @@ -692,8 +791,8 @@ void napi_env__::DrainFinalizerQueue() { for (const auto& finalizer : external) { CallFinalizer(finalizer.cb, finalizer.data, finalizer.hint); } - // Releasing a buffer record above can free its backing store, which - // queues the store's finalizer. + // A finalizer above can free a backing store, which queues the store's + // finalizer. external = TakeExternalFinalizers(this); } } @@ -854,6 +953,20 @@ v8::Local napi_v8_unwrap_value(napi_value value) { return V8LocalValueFromJsValue(value); } +napi_status napi_v8_create_external_arraybuffer_with_free( + napi_env env, void* data, size_t byte_length, napi_v8_external_free_callback free_cb, + void* free_hint, napi_value* result) { + if (free_cb == nullptr) return napi_invalid_arg; + return CreateExternalArrayBuffer(env, data, byte_length, nullptr, free_cb, free_hint, result); +} + +napi_status napi_v8_create_external_buffer_with_free( + napi_env env, size_t length, void* data, napi_v8_external_free_callback free_cb, + void* free_hint, napi_value* result) { + if (free_cb == nullptr) return napi_invalid_arg; + return CreateExternalBuffer(env, length, data, nullptr, free_cb, free_hint, result); +} + void napi_v8_finalize_buffer_records(napi_env env) { if (!CheckEnv(env)) return; for (auto* record : env->buffer_records) { @@ -1060,36 +1173,8 @@ napi_status NAPI_CDECL napi_create_external_arraybuffer( node_api_basic_finalize finalize_cb, void* finalize_hint, napi_value* result) { - if (!CheckEnv(env) || result == nullptr) return napi_invalid_arg; - - v8::Local out; - if (external_data == nullptr && byte_length == 0) { - out = v8::ArrayBuffer::New(env->isolate, 0); - out->Detach(v8::Local()).FromMaybe(false); - } else { - if (external_data == nullptr) return napi_invalid_arg; - auto hint = std::make_unique(env); - hint->external_data = external_data; - hint->finalize_cb = finalize_cb; - hint->finalize_hint = finalize_hint; - auto* hint_ptr = hint.get(); - std::unique_ptr backing = v8::ArrayBuffer::NewBackingStore( - external_data, byte_length, ExternalBackingStoreDeleter, hint_ptr); - if (!backing) { - return napi_generic_failure; - } - v8impl::detail::napi_lifetime__:: - record_create(env, hint.get()); - { - // Racing V8's ArrayBufferSweeper threads; see NapiV8ExternalHintsMutex. - std::lock_guard lock(NapiV8ExternalHintsMutex()); - env->external_backing_store_hints.insert(hint.release()); - } - out = v8::ArrayBuffer::New(env->isolate, std::move(backing)); - } - - *result = napi_v8_wrap_value(env, out); - return (*result == nullptr) ? napi_generic_failure : napi_ok; + return CreateExternalArrayBuffer( + env, external_data, byte_length, finalize_cb, nullptr, finalize_hint, result); } napi_status NAPI_CDECL napi_is_typedarray(napi_env env, napi_value value, bool* result) { @@ -3310,45 +3395,7 @@ napi_status NAPI_CDECL napi_create_external_buffer(napi_env env, node_api_basic_finalize finalize_cb, void* finalize_hint, napi_value* result) { - if (!CheckEnv(env) || data == nullptr || result == nullptr) return napi_invalid_arg; - v8::Local context = env->context(); - v8::Context::Scope context_scope(context); - - auto hint = std::make_unique(env); - hint->external_data = data; - hint->finalize_cb = finalize_cb; - hint->finalize_hint = finalize_hint; - auto* hint_ptr = hint.get(); - - std::unique_ptr backing = - v8::ArrayBuffer::NewBackingStore(data, length, ExternalBackingStoreDeleter, - hint_ptr); - if (!backing) { - return napi_generic_failure; - } - v8impl::detail::napi_lifetime__:: - record_create(env, hint.get()); - { - // Racing V8's ArrayBufferSweeper threads; see NapiV8ExternalHintsMutex. - std::lock_guard lock(NapiV8ExternalHintsMutex()); - env->external_backing_store_hints.insert(hint.release()); - } - - auto* record = env->allocate(env); - if (record == nullptr) return napi_generic_failure; - record->backing_store = std::move(backing); - - v8::Local buffer_obj = CreateBufferObject(env, record->backing_store, 0, length); - record->holder.Reset(env->isolate, buffer_obj); - record->holder.SetWeak(record, BufferWeakCallback, v8::WeakCallbackType::kParameter); - v8::Local key = env->agent->buffer_private_key.Get(env->isolate); - buffer_obj - ->SetPrivate(env->context(), key, v8::External::New(env->isolate, record)) - .FromJust(); - env->buffer_records.push_back(record); - - *result = napi_v8_wrap_value(env, buffer_obj); - return (*result == nullptr) ? napi_generic_failure : napi_ok; + return CreateExternalBuffer(env, length, data, finalize_cb, nullptr, finalize_hint, result); } napi_status NAPI_CDECL napi_is_buffer(napi_env env, napi_value value, bool* result) { diff --git a/v8/src/unofficial_napi.cc b/v8/src/unofficial_napi.cc index a3cdeceeec..447fb6a7cb 100644 --- a/v8/src/unofficial_napi.cc +++ b/v8/src/unofficial_napi.cc @@ -119,6 +119,26 @@ class StringOutputStream final : public v8::OutputStream { std::string output_; }; +// An ArrayBuffer over memory the provider owns. V8's deleter frees it as V8 +// collects the buffer: it needs no env, so it does not wait for the env's +// thread like a user finalizer, nor run at the env's release while the +// buffer may still be in use. Frees `data` itself on failure. +napi_status CreateOwnedArrayBuffer(napi_env env, + void* data, + size_t length, + v8::BackingStore::DeleterCallback deleter, + void* deleter_data, + napi_value* result) { + std::unique_ptr backing = + v8::ArrayBuffer::NewBackingStore(data, length, deleter, deleter_data); + if (!backing) { + deleter(data, length, deleter_data); + return napi_generic_failure; + } + *result = napi_v8_wrap_value(env, v8::ArrayBuffer::New(env->isolate, std::move(backing))); + return *result == nullptr ? napi_generic_failure : napi_ok; +} + napi_status CreateExternalUtf8Bytes(napi_env env, std::string&& bytes, napi_value* result) { @@ -133,22 +153,20 @@ napi_status CreateExternalUtf8Bytes(napi_env env, return napi_create_typedarray( env, napi_uint8_array, 0, arraybuffer, 0, result); } + const size_t size = owner->size(); napi_value arraybuffer = nullptr; - napi_status status = napi_create_external_arraybuffer( + napi_status status = CreateOwnedArrayBuffer( env, owner->data(), - owner->size(), - [](napi_env, void*, void* hint) { - delete static_cast(hint); + size, + [](void*, size_t, void* deleter_data) { + delete static_cast(deleter_data); }, owner, &arraybuffer); - if (status != napi_ok) { - delete owner; - return status; - } + if (status != napi_ok) return status; return napi_create_typedarray( - env, napi_uint8_array, owner->size(), arraybuffer, 0, result); + env, napi_uint8_array, size, arraybuffer, 0, result); } void DisposeProfilers(napi_agent__* agent) { @@ -2068,15 +2086,8 @@ napi_status NAPI_CDECL unofficial_napi_create_uninitialized_arraybuffer( void* data = zero_fill ? std::calloc(length, 1) : std::malloc(length); if (data == nullptr) return napi_generic_failure; - napi_status status = napi_create_external_arraybuffer( - env, - data, - length, - [](napi_env, void* bytes, void*) { std::free(bytes); }, - nullptr, - result); - if (status != napi_ok) std::free(data); - return status; + return CreateOwnedArrayBuffer( + env, data, length, [](void* bytes, size_t, void*) { std::free(bytes); }, nullptr, result); } napi_status NAPI_CDECL unofficial_napi_terminate_execution(napi_env env) { From 71d1c7d77212f6302b79f31671a30895faaae350 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 15:49:52 -0800 Subject: [PATCH 042/150] V8: finalize instance data a finalizer sets during the env's release The release ran the instance-data finalizer once and then swept external buffers a last time. A finalizer that ran in that sweep, or the instance-data finalizer itself, could set new instance data, and its finalizer never ran. Node finalizes references made while it finalizes the others. The release now repeats: sweep external buffers, then finalize the instance data if any is set, until none is. The callback is cleared before it runs, so instance data is finalized once. New test in test_69 (V8 only, like the other instance-data test there: QuickJS cannot make values in that finalizer). InstanceDataSetByALateFinalizerIsFinalized: the instance-data finalizer detaches an external buffer, whose finalizer sets instance data. That instance data is finalized once, in the env's realm. Before this commit, it was never finalized (0 calls), and the review saw the same at f928811. V8 182/182 and the same with the provider built with ASan (one test skipped there), QuickJS 165/165 (also Debug+ASan), Rust lib 54, concurrent_envs 11, concurrent_stores 2, guest_callbacks 4, manifest 37/37 (native and WASIX), host-JS node 43/43, wasm-bindgen 26/26. Co-Authored-By: Claude Opus 5.5 --- .../runners/test_69_unofficial_realm_entry.cc | 50 +++++++++++++++++++ v8/src/js_native_api_v8.cc | 15 ++++-- 2 files changed, 61 insertions(+), 4 deletions(-) diff --git a/tests/runners/test_69_unofficial_realm_entry.cc b/tests/runners/test_69_unofficial_realm_entry.cc index d960f76da0..efcdd4e87d 100644 --- a/tests/runners/test_69_unofficial_realm_entry.cc +++ b/tests/runners/test_69_unofficial_realm_entry.cc @@ -911,6 +911,56 @@ TEST_F(Test69UnofficialRealmEntry, ExternalArrayBufferTheInstanceDataFinalizerDe EXPECT_TRUE(record.on_env_thread.load()); EXPECT_TRUE(record.saw_env_global.load()); } + +namespace { + +struct LateInstanceData { + ExternalFinalizerRecord buffer; + std::atomic late_finalized{0}; + std::atomic late_saw_env_global{false}; +}; + +void FinalizeLateInstanceData(napi_env env, void* data, void*) { + auto* late = static_cast(data); + bool has_marker = false; + late->late_saw_env_global = + napi_has_named_property(env, Global(env), kEnvMarker, &has_marker) == napi_ok && + has_marker; + late->late_finalized.fetch_add(1); +} + +// The buffer's finalizer runs late in the release, and sets instance data. +void SetInstanceDataFromExternalFinalizer(node_api_basic_env basic_env, void* data, void* hint) { + auto* late = static_cast(hint); + RecordExternalFinalizer(basic_env, data, &late->buffer); + (void)napi_set_instance_data(basic_env, late, FinalizeLateInstanceData, nullptr); +} + +void DetachLateExternalBuffer(napi_env env, void* data, void*) { + auto* late = static_cast(data); + napi_value buffer = nullptr; + if (napi_create_external_arraybuffer(env, late->buffer.bytes, sizeof(late->buffer.bytes), + SetInstanceDataFromExternalFinalizer, late, + &buffer) == napi_ok) { + (void)napi_detach_arraybuffer(env, buffer); + } +} + +} // namespace + +// Instance data a finalizer sets during the release is finalized too, once, +// as Node finalizes references made while it finalizes the others. +TEST_F(Test69UnofficialRealmEntry, InstanceDataSetByALateFinalizerIsFinalized) { + LateInstanceData late; + EnvScope s(runtime_.get()); + MarkEnvGlobal(s.env); + ASSERT_EQ(napi_set_instance_data(s.env, &late, DetachLateExternalBuffer, nullptr), napi_ok); + Release(s); + + EXPECT_EQ(late.buffer.calls.load(), 1); + EXPECT_EQ(late.late_finalized.load(), 1); + EXPECT_TRUE(late.late_saw_env_global.load()); +} #endif TEST_F(Test69UnofficialRealmEntry, CollectedExternalArrayBuffersAreFinalizedOnTheEnvsThread) { diff --git a/v8/src/js_native_api_v8.cc b/v8/src/js_native_api_v8.cc index f59d19b087..925c710b18 100644 --- a/v8/src/js_native_api_v8.cc +++ b/v8/src/js_native_api_v8.cc @@ -870,10 +870,17 @@ napi_env__::~napi_env__() { finalization_scheduled = false; FinalizeExternalBackingStoreHints(this); napi_v8_finalize_buffer_records(this); - CallFinalizer(instance_data_finalize_cb, instance_data, instance_data_finalize_hint); - // External buffers the finalizers above made: their finalizers run too, and - // no hint is left pointing at the env. - FinalizeExternalBackingStoreHints(this); + // External buffers the finalizers above made are finalized too, then the + // instance data, then what its finalizer made, so no hint is left pointing + // at the env. Instance data a finalizer sets is finalized in turn, as Node + // finalizes refs made while it finalizes. + for (;;) { + FinalizeExternalBackingStoreHints(this); + if (instance_data_finalize_cb == nullptr) break; + napi_finalize finalize_cb = instance_data_finalize_cb; + instance_data_finalize_cb = nullptr; + CallFinalizer(finalize_cb, instance_data, instance_data_finalize_hint); + } // Backstop: nothing above should leave a scope open, and a context still // entered here would abort V8 at the embedder's next Context::Exit. PopRealmFrames(0); From 253bdc0438b90eb7dc9c1ff27432b7dbe3616c8d Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 16:18:58 -0800 Subject: [PATCH 043/150] QuickJS: finalize what the instance-data finalizer leaves at release The release ran the instance-data finalizer last and then marked the env's finalizers done. A value that finalizer made and kept, or instance data it set, was never finalized. The release now repeats: the cleanup hooks and the pending values' finalizers until neither is left, then the instance-data finalizer, and all of it again until nothing is pending; with nothing left it stops. This is the release contract both providers now follow (documented on unofficial_napi_release_env in a later commit). An exception a cleanup hook leaves pending at release is now dropped after the hook, as it already was after a finalizer. It used to stay pending into the next finalizer. Tests (shared by both engines): - test_41: ValueTheInstanceDataFinalizerMakesIsNeverFinalized becomes ValueTheInstanceDataFinalizerMakesIsFinalized. New WhatTheInstanceDataFinalizerLeavesIsReleasedInTheSameOrder: the hook, the value and the instance data that finalizer leaves run in that order. CleanupHooksFinalizersAddAtReleaseRun becomes CleanupHooksAddedAtReleaseRun and also covers a hook a hook adds, with the exact order. AnExceptionAFinalizerThrowsAtReleaseIsNotLeftPending becomes AnExceptionThrownAtReleaseIsNotLeftPending: a hook, a value's finalizer and the instance-data finalizer throw, and the next one to run finds nothing pending. It accepts either status from napi_throw_error (Node and QuickJS return napi_ok, V8 napi_pending_exception). The engine guards in these tests and in ExternalArrayBufferAFinalizerMakesAtReleaseIsFinalizedToo are gone; the V8 guard there was stale since "V8: finalize instance data a finalizer sets during the env's release". - test_69: ExternalArrayBufferTheInstanceDataFinalizerDetachesIsFinalized and InstanceDataSetByALateFinalizerIsFinalized run on QuickJS too. New ReleaseRunsInTheEnvsRealmWhileAnotherIsEntered: hooks and finalizers of values made in a realm left entered at release run once, in the env's realm. Before this commit, QuickJS failed ValueTheInstanceDataFinalizerMakesIsFinalized and WhatTheInstanceDataFinalizerLeavesIsReleasedInTheSameOrder (the values and the second instance data ran 0 times), AnExceptionThrownAtReleaseIsNotLeftPending (the hook's exception was pending in the value's finalizer) and InstanceDataSetByALateFinalizerIsFinalized (0 calls). It passes them now. The V8 provider fails ValueTheInstanceDataFinalizerMakesIsFinalized, WhatTheInstanceDataFinalizerLeavesIsReleasedInTheSameOrder, CleanupHooksAddedAtReleaseRun and AnExceptionThrownAtReleaseIsNotLeftPending until the next commit. Co-Authored-By: Claude Opus 5.5 --- quickjs/src/internal/napi_env.cc | 38 ++-- quickjs/src/internal/napi_env.h | 5 +- quickjs/src/unofficial_napi.cc | 4 +- tests/runners/test_41_instance_data.cc | 174 ++++++++++++++---- .../runners/test_69_unofficial_realm_entry.cc | 70 ++++++- 5 files changed, 228 insertions(+), 63 deletions(-) diff --git a/quickjs/src/internal/napi_env.cc b/quickjs/src/internal/napi_env.cc index 2a97e1d56c..3baa3e2ed7 100644 --- a/quickjs/src/internal/napi_env.cc +++ b/quickjs/src/internal/napi_env.cc @@ -135,24 +135,27 @@ void napi_env__::prepare_teardown() // Every scope closes. Cleanup hooks and finalizers each run in the env's // realm, and a scope one leaves open closes when it returns. pop_realm_frames(0); - // The cleanup hooks run, then the finalizers of the values still alive; a - // hook or value one of them adds runs too (Node also runs hooks added during - // cleanup), until neither is left. They run while the context and runtime - // are alive and the root scope is open, so they can use N-API; what they - // make is freed below. - run_cleanup_hooks(); - while (napi_external_backing_store_hint__::first_pending(pending_finalizers_) != nullptr) + // The release contract (unofficial_napi_release_env): the cleanup hooks + // run, then the finalizers of the values still pending, until neither is + // left; then the instance data's finalizer; and all of it again for what + // that finalizer leaves pending, until nothing is. They run while the + // context and runtime are alive and the root scope is open, so they can use + // N-API; what they make is freed below. + for (;;) { - finalize_pending_values(); run_cleanup_hooks(); + while (napi_external_backing_store_hint__::first_pending(pending_finalizers_) != nullptr) + { + finalize_pending_values(); + run_cleanup_hooks(); + } + if (instance_data_ == nullptr && instance_data_finalize_cb_ == nullptr) + break; + finalize_instance_data(); + drop_finalizer_exception(); } - // The instance data's finalizer runs last. Nothing is finalized after it, - // but hooks it adds still run. - finalize_instance_data(); - drop_finalizer_exception(); - run_cleanup_hooks(); - // A value still pending is never finalized: the runtime frees it after the - // context is gone. + // From here on nothing is finalized: the runtime frees what is still alive + // after the context is gone. finalizers_done_ = true; while (auto *hint = napi_external_backing_store_hint__::first_pending(pending_finalizers_)) hint->abandon_finalizer(); @@ -219,6 +222,7 @@ void napi_env__::run_cleanup_hooks() napi_realm_frame_scope__ realm_frame{this, nullptr, JS_UNDEFINED}; entry->run(); } + drop_finalizer_exception(); napi_env_cleanup_hook__::destroy(entry); } } @@ -239,8 +243,8 @@ void napi_env__::finalize_pending_values() void napi_env__::drop_finalizer_exception() { - // Nothing can catch what a finalizer threw at release. Node also clears it - // after each finalizer. + // Nothing can catch what a hook or finalizer threw at release. Node's + // CallIntoModule also drops it once JS can no longer run. clear_last_exception(); if (context_ != nullptr && JS_HasException(context_)) JS_FreeValue(context_, JS_GetException(context_)); diff --git a/quickjs/src/internal/napi_env.h b/quickjs/src/internal/napi_env.h index f89345e4c7..0cab982932 100644 --- a/quickjs/src/internal/napi_env.h +++ b/quickjs/src/internal/napi_env.h @@ -52,8 +52,9 @@ struct napi_env__ ~napi_env__(); // Runs the cleanup hooks and every pending finalizer, the instance data's - // last, while the context is alive, and lets go of the context. N-API calls - // on the env fail from then on. + // after the others, again for what they leave pending, while the context is + // alive, and lets go of the context. N-API calls on the env fail from then + // on. void prepare_teardown(); // Native callbacks are refused once teardown has started. bool is_closing() const; diff --git a/quickjs/src/unofficial_napi.cc b/quickjs/src/unofficial_napi.cc index 2b9285983e..688e002723 100644 --- a/quickjs/src/unofficial_napi.cc +++ b/quickjs/src/unofficial_napi.cc @@ -67,8 +67,8 @@ namespace napi_env env_to_delete = nullptr; if (scope->env != nullptr) { - // Runs every finalizer, the instance data's last, while the - // context and runtime are alive. + // Runs the cleanup hooks and every finalizer, as the release + // contract orders them, while the context and runtime are alive. env_to_delete = scope->env; status = DestroyEnvInstance(scope->env); scope->env = nullptr; diff --git a/tests/runners/test_41_instance_data.cc b/tests/runners/test_41_instance_data.cc index dce16adcb4..417cb0e3e7 100644 --- a/tests/runners/test_41_instance_data.cc +++ b/tests/runners/test_41_instance_data.cc @@ -10,6 +10,7 @@ #include #include #include +#include #include extern "C" napi_value Init(napi_env env, napi_value exports); @@ -27,10 +28,13 @@ TEST_F(Test41InstanceData, PortedCoreFlow) { s, std::string(NAPI_TESTS_ROOT_PATH) + "/js-native-api/test_instance_data/test.js")); } -// Finalizers at release. As in Node, every finalizer still pending when the -// env is released runs while the engine is alive, in the env's realm, and can -// use N-API. The instance-data finalizer runs last, after every other -// finalizer (current Node interleaves it with them instead). +// The release contract (unofficial_napi_release_env). The cleanup hooks run, +// then the finalizer of every value still pending, most recent first, until +// neither is left; then the instance-data finalizer; and all of it again for +// whatever those leave pending, until nothing is. Each runs while the engine +// is alive, on the env's thread, in the env's realm, and can use N-API. +// (Node up to 20 also finalized the instance data last; Node 25 interleaves +// it with the other finalizers.) namespace { @@ -224,7 +228,7 @@ TEST_F(Test41InstanceData, ValueAFinalizerMakesAtReleaseIsFinalizedToo) { ExpectUsedNapi(instance_data, "instance data"); } -TEST_F(Test41InstanceData, ValueTheInstanceDataFinalizerMakesIsNeverFinalized) { +TEST_F(Test41InstanceData, ValueTheInstanceDataFinalizerMakesIsFinalized) { EnvScope s(runtime_.get()); int clock = 0; Late late{&clock}; @@ -234,9 +238,66 @@ TEST_F(Test41InstanceData, ValueTheInstanceDataFinalizerMakesIsNeverFinalized) { Release(s); ExpectUsedNapi(late.instance_data, "instance data"); - // Nothing finalizes after the instance data: the engine is gone by the time - // the value is freed. (Current Node would finalize it.) - EXPECT_EQ(late.made.runs, 0); + // What the instance-data finalizer leaves pending is finalized after it, as + // Node's FinalizeAll finalizes until its lists are empty. + ExpectUsedNapi(late.made, "external the instance-data finalizer made"); + EXPECT_GT(late.made.order, late.instance_data.order); +} + +namespace { + +// What the instance-data finalizer leaves pending: a value, a cleanup hook and +// new instance data. +struct Rounds { + explicit Rounds(int* clock) : first(clock), hook(clock), value(clock), second(clock) {} + napi_env env = nullptr; + Seen first; + Seen hook; + Seen value; + Seen second; + napi_status add_hook = napi_generic_failure; + napi_status set_data = napi_generic_failure; +}; + +void RoundsHook(void* arg) { + auto* rounds = static_cast(arg); + UseNapi(rounds->env, &rounds->hook); +} + +void FinalizeSecondInstanceData(napi_env env, void* data, void*) { + UseNapi(env, &static_cast(data)->second); +} + +void FinalizeFirstInstanceData(napi_env env, void* data, void*) { + auto* rounds = static_cast(data); + UseNapi(env, &rounds->first); + KeepExternal(env, "leftValue", &rounds->value); + rounds->add_hook = napi_add_env_cleanup_hook(env, RoundsHook, rounds); + rounds->set_data = napi_set_instance_data(env, rounds, FinalizeSecondInstanceData, nullptr); +} + +} // namespace + +// The release repeats for what the instance-data finalizer leaves: its hook +// runs, then its value is finalized, then the instance data it set. +TEST_F(Test41InstanceData, WhatTheInstanceDataFinalizerLeavesIsReleasedInTheSameOrder) { + EnvScope s(runtime_.get()); + int clock = 0; + Rounds rounds{&clock}; + rounds.env = s.env; + MarkEnvGlobal(s.env); + ASSERT_EQ(napi_set_instance_data(s.env, &rounds, FinalizeFirstInstanceData, nullptr), napi_ok); + + Release(s); + EXPECT_EQ(rounds.add_hook, napi_ok); + EXPECT_EQ(rounds.set_data, napi_ok); + ExpectUsedNapi(rounds.first, "first instance data"); + ExpectUsedNapi(rounds.hook, "hook it added"); + ExpectUsedNapi(rounds.value, "value it made"); + ExpectUsedNapi(rounds.second, "instance data it set"); + EXPECT_LT(rounds.first.order, rounds.hook.order); + EXPECT_LT(rounds.hook.order, rounds.value.order); + EXPECT_LT(rounds.value.order, rounds.second.order); } namespace { @@ -426,26 +487,38 @@ TEST_F(Test41InstanceData, ExternalArrayBufferAFinalizerMakesAtReleaseIsFinalize Release(s); ExpectUsedNapi(chain.first, "external"); ExpectUsedNapi(instance_data, "instance data"); -#if defined(NAPI_TEST_ENGINE_QUICKJS) - // The V8 provider finalizes such a buffer only after the instance data, - // when N-API no longer works. ExpectUsedNapi(chain.made, "array buffer its finalizer made"); EXPECT_LT(chain.made.order, instance_data.order); -#endif } namespace { -// Cleanup hooks finalizers add at release, and when each ran. +// Cleanup hooks a hook and finalizers add at release, and when each ran. struct LateHooks { + napi_env env = nullptr; int clock = 0; + int registered_hook = 0; + int hook_hook = 0; + int value = 0; int value_hook = 0; int instance_data = 0; int instance_data_hook = 0; + napi_status hook_add = napi_generic_failure; napi_status value_add = napi_generic_failure; napi_status instance_data_add = napi_generic_failure; }; +void HookHook(void* arg) { + auto* hooks = static_cast(arg); + hooks->hook_hook = ++hooks->clock; +} + +void RegisteredHook(void* arg) { + auto* hooks = static_cast(arg); + hooks->registered_hook = ++hooks->clock; + hooks->hook_add = napi_add_env_cleanup_hook(hooks->env, HookHook, hooks); +} + void ValueHook(void* arg) { auto* hooks = static_cast(arg); hooks->value_hook = ++hooks->clock; @@ -458,6 +531,7 @@ void InstanceDataHook(void* arg) { void FinalizeAddingAHook(node_api_basic_env env, void*, void* hint) { auto* hooks = static_cast(hint); + hooks->value = ++hooks->clock; hooks->value_add = napi_add_env_cleanup_hook(env, ValueHook, hooks); } @@ -469,9 +543,14 @@ void FinalizeInstanceDataAddingAHook(napi_env env, void* data, void*) { } // namespace -TEST_F(Test41InstanceData, CleanupHooksFinalizersAddAtReleaseRun) { +// As in Node, a hook added during the release still runs. The hooks run +// before the values are finalized, and a hook a value's finalizer adds runs +// before the instance-data finalizer. +TEST_F(Test41InstanceData, CleanupHooksAddedAtReleaseRun) { EnvScope s(runtime_.get()); LateHooks hooks; + hooks.env = s.env; + ASSERT_EQ(napi_add_env_cleanup_hook(s.env, RegisteredHook, &hooks), napi_ok); napi_value external = nullptr; ASSERT_EQ(napi_create_external(s.env, nullptr, FinalizeAddingAHook, &hooks, &external), napi_ok); Keep(s.env, "external", external); @@ -479,41 +558,67 @@ TEST_F(Test41InstanceData, CleanupHooksFinalizersAddAtReleaseRun) { napi_ok); Release(s); + EXPECT_EQ(hooks.hook_add, napi_ok); EXPECT_EQ(hooks.value_add, napi_ok); EXPECT_EQ(hooks.instance_data_add, napi_ok); -#if defined(NAPI_TEST_ENGINE_QUICKJS) - // As in Node, a hook added during teardown still runs; one a value's - // finalizer adds runs before the instance-data finalizer. The V8 provider - // drops them. - EXPECT_GT(hooks.value_hook, 0); - EXPECT_LT(hooks.value_hook, hooks.instance_data); - EXPECT_GT(hooks.instance_data_hook, hooks.instance_data); -#endif + EXPECT_EQ(hooks.registered_hook, 1); + EXPECT_EQ(hooks.hook_hook, 2); + EXPECT_EQ(hooks.value, 3); + EXPECT_EQ(hooks.value_hook, 4); + EXPECT_EQ(hooks.instance_data, 5); + EXPECT_EQ(hooks.instance_data_hook, 6); } namespace { +// Exceptions thrown at release by a hook, a value's finalizer and the +// instance-data finalizer, and whether the next one to run found one pending. struct Thrown { + napi_env env = nullptr; napi_status throw_status = napi_generic_failure; - napi_status pending_status = napi_generic_failure; - bool pending = true; + bool pending_in_value = true; + bool pending_in_instance_data = true; + bool pending_in_late_hook = true; + int checks = 0; }; +void Check(napi_env env, Thrown* thrown, bool* pending) { + if (napi_is_exception_pending(env, pending) == napi_ok) ++thrown->checks; +} + +void ThrowingHook(void* arg) { + auto* thrown = static_cast(arg); + napi_throw_error(thrown->env, nullptr, "hook"); +} + void FinalizeThrowing(node_api_basic_env basic_env, void*, void* hint) { + auto env = const_cast(basic_env); auto* thrown = static_cast(hint); - thrown->throw_status = napi_throw_error(const_cast(basic_env), nullptr, "finalizer"); + Check(env, thrown, &thrown->pending_in_value); + thrown->throw_status = napi_throw_error(env, nullptr, "finalizer"); +} + +void LateHookAfterAThrow(void* arg) { + auto* thrown = static_cast(arg); + Check(thrown->env, thrown, &thrown->pending_in_late_hook); } void FinalizeInstanceDataAfterAThrow(napi_env env, void* data, void*) { auto* thrown = static_cast(data); - thrown->pending_status = napi_is_exception_pending(env, &thrown->pending); + Check(env, thrown, &thrown->pending_in_instance_data); + napi_add_env_cleanup_hook(env, LateHookAfterAThrow, thrown); + napi_throw_error(env, nullptr, "instance data"); } } // namespace -TEST_F(Test41InstanceData, AnExceptionAFinalizerThrowsAtReleaseIsNotLeftPending) { +// Nothing can catch what a hook or finalizer throws at release, so, as Node's +// CallIntoModule does once JS can no longer run, it is dropped. +TEST_F(Test41InstanceData, AnExceptionThrownAtReleaseIsNotLeftPending) { EnvScope s(runtime_.get()); Thrown thrown; + thrown.env = s.env; + ASSERT_EQ(napi_add_env_cleanup_hook(s.env, ThrowingHook, &thrown), napi_ok); napi_value external = nullptr; ASSERT_EQ(napi_create_external(s.env, nullptr, FinalizeThrowing, &thrown, &external), napi_ok); Keep(s.env, "external", external); @@ -521,13 +626,14 @@ TEST_F(Test41InstanceData, AnExceptionAFinalizerThrowsAtReleaseIsNotLeftPending) napi_ok); Release(s); - EXPECT_EQ(thrown.pending_status, napi_ok); -#if defined(NAPI_TEST_ENGINE_QUICKJS) - // Nothing can catch it, so, as Node does after each finalizer, it is - // dropped. The V8 provider still leaves it pending. - EXPECT_EQ(thrown.throw_status, napi_ok); - EXPECT_FALSE(thrown.pending); -#endif + // Node's napi_throw_error returns napi_ok; the V8 provider returns + // napi_pending_exception. Either way the error was thrown. + EXPECT_TRUE(thrown.throw_status == napi_ok || thrown.throw_status == napi_pending_exception) + << thrown.throw_status; + EXPECT_EQ(thrown.checks, 3); + EXPECT_FALSE(thrown.pending_in_value); + EXPECT_FALSE(thrown.pending_in_instance_data); + EXPECT_FALSE(thrown.pending_in_late_hook); } namespace { diff --git a/tests/runners/test_69_unofficial_realm_entry.cc b/tests/runners/test_69_unofficial_realm_entry.cc index efcdd4e87d..e91887bb91 100644 --- a/tests/runners/test_69_unofficial_realm_entry.cc +++ b/tests/runners/test_69_unofficial_realm_entry.cc @@ -762,8 +762,8 @@ TEST_F(Test69UnofficialRealmEntry, ScopeTheInstanceDataFinalizerLeavesOpenCloses Release(s); EXPECT_TRUE(record.checked); - // The finalizer runs last, and a provider may have let go of its realms by - // then. + // The finalizer runs after the other finalizers, and a provider may have + // let go of its realms by then. EXPECT_TRUE(record.enter_status == napi_ok || record.enter_status == napi_invalid_arg) << record.enter_status; EXPECT_EQ(record.enter_env_realm_status, napi_ok); @@ -880,7 +880,6 @@ TEST_F(Test69UnofficialRealmEntry, DetachedExternalArrayBufferIsFinalizedByTheEn EXPECT_TRUE(record.saw_env_global.load()); } -#if defined(NAPI_TEST_ENGINE_V8) namespace { void DetachExternalBufferFromInstanceDataFinalizer(napi_env env, void* data, void*) { @@ -894,10 +893,9 @@ void DetachExternalBufferFromInstanceDataFinalizer(napi_env env, void* data, voi } // namespace -// The instance-data finalizer runs last in the release. An external buffer it -// makes and detaches is still finalized, once. V8 only: the QuickJS provider -// frees its context before it runs that finalizer, which then cannot make -// values. +// The instance-data finalizer runs after the other finalizers in the release. +// An external buffer it makes and detaches is still finalized, once, on the +// env's thread and in the env's realm. TEST_F(Test69UnofficialRealmEntry, ExternalArrayBufferTheInstanceDataFinalizerDetachesIsFinalized) { ExternalFinalizerRecord record; EnvScope s(runtime_.get()); @@ -961,7 +959,63 @@ TEST_F(Test69UnofficialRealmEntry, InstanceDataSetByALateFinalizerIsFinalized) { EXPECT_EQ(late.late_finalized.load(), 1); EXPECT_TRUE(late.late_saw_env_global.load()); } -#endif + +namespace { + +struct ReleaseInARealm { + ExternalFinalizerRecord buffer; + ExternalFinalizerRecord external; + ExternalFinalizerRecord instance_data; + ExternalFinalizerRecord hook; + napi_env env = nullptr; +}; + +void RecordInstanceDataFinalizer(napi_env env, void* data, void*) { + RecordExternalFinalizer(env, nullptr, &static_cast(data)->instance_data); +} + +void RecordCleanupHook(void* arg) { + auto* release = static_cast(arg); + RecordExternalFinalizer(release->env, nullptr, &release->hook); +} + +} // namespace + +// The env is released while another realm is entered, holding values made in +// that realm. Every hook and finalizer still runs once, on the env's thread, +// in the env's realm. +TEST_F(Test69UnofficialRealmEntry, ReleaseRunsInTheEnvsRealmWhileAnotherIsEntered) { + ReleaseInARealm release; + EnvScope s(runtime_.get()); + release.env = s.env; + unofficial_napi_realm a = CreateRealm(s.env); + ASSERT_NE(a, nullptr); + MarkEnvGlobal(s.env); + ASSERT_EQ(napi_add_env_cleanup_hook(s.env, RecordCleanupHook, &release), napi_ok); + ASSERT_EQ(napi_set_instance_data(s.env, &release, RecordInstanceDataFinalizer, nullptr), napi_ok); + + // Made in A and kept on A's global; A stays entered. + (void)Enter(s.env, a); + napi_value buffer = nullptr; + ASSERT_EQ(napi_create_external_arraybuffer(s.env, release.buffer.bytes, + sizeof(release.buffer.bytes), + RecordExternalFinalizer, &release.buffer, &buffer), + napi_ok); + ASSERT_EQ(napi_set_named_property(s.env, Global(s.env), "keptBuffer", buffer), napi_ok); + napi_value external = nullptr; + ASSERT_EQ(napi_create_external(s.env, nullptr, RecordExternalFinalizer, &release.external, + &external), + napi_ok); + ASSERT_EQ(napi_set_named_property(s.env, Global(s.env), "keptExternal", external), napi_ok); + Release(s); + + for (const ExternalFinalizerRecord* record : + {&release.buffer, &release.external, &release.instance_data, &release.hook}) { + EXPECT_EQ(record->calls.load(), 1); + EXPECT_TRUE(record->on_env_thread.load()); + EXPECT_TRUE(record->saw_env_global.load()); + } +} TEST_F(Test69UnofficialRealmEntry, CollectedExternalArrayBuffersAreFinalizedOnTheEnvsThread) { constexpr int kBatches = 16; From a84eeb34ded7110e706a84b7408dad8ba2e0441b Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 16:18:58 -0800 Subject: [PATCH 044/150] V8: run the release in rounds and drop exceptions thrown at release The V8 release ran the cleanup hooks once, then the references' finalizers, then reset every plain reference, then external buffers and the instance data. A hook a finalizer added never ran, values the instance-data finalizer made were never finalized, plain references were already empty when the instance-data finalizer ran, and an exception a hook or finalizer threw stayed pending into the next one. ~napi_env__ now follows the release contract, as the QuickJS provider does: the hooks, the references with a finalizer (most recent first, as Node's FinalizeAll) and the external buffers, until no hook or reference is left; then the instance-data finalizer; and again until nothing is pending. Plain references are reset after all of it, as Node's FinalizeAll(&reflist) comes after the finalizers. Each hook, and each finalizer while the env is releasing, runs inside a v8::TryCatch, and the env's pending exception is cleared after it, as Node's CallIntoModule drops it once JS can no longer run. Finalizers outside the release are unchanged. The four test_41 tests the previous commit left failing on V8 pass: CleanupHooksAddedAtReleaseRun failed with value_hook 0 and instance_data_hook 0 (never ran); AnExceptionThrownAtReleaseIsNotLeftPending with pending_in_value, pending_in_instance_data and pending_in_late_hook all true; the two instance-data tests with the made value never finalized. Co-Authored-By: Claude Opus 5.5 --- v8/src/internal/napi_ref_tracker.h | 1 + v8/src/js_native_api_v8.cc | 50 +++++++++++++++++++++--------- 2 files changed, 37 insertions(+), 14 deletions(-) diff --git a/v8/src/internal/napi_ref_tracker.h b/v8/src/internal/napi_ref_tracker.h index bbcd83fd7b..10dc8ea4a1 100644 --- a/v8/src/internal/napi_ref_tracker.h +++ b/v8/src/internal/napi_ref_tracker.h @@ -12,6 +12,7 @@ struct napi_ref_tracker__ { virtual void Finalize() {} static void FinalizeAll(RefList* list); + static bool IsEmpty(const RefList* list) { return list->next_ == nullptr; } private: napi_ref_tracker__* next_ = nullptr; diff --git a/v8/src/js_native_api_v8.cc b/v8/src/js_native_api_v8.cc index 925c710b18..0539157d08 100644 --- a/v8/src/js_native_api_v8.cc +++ b/v8/src/js_native_api_v8.cc @@ -139,6 +139,11 @@ inline bool CheckEnv(napi_env env) { return env != nullptr && env->isolate != nullptr; } +void ClearLastException(napi_env env); + +// The env's cleanup hooks, at its release: most recent first, in rounds as +// Node's CleanupQueue::Drain runs them, so a hook added meanwhile runs in the +// next round. void RunEnvCleanupHooks(napi_env env) { if (!CheckEnv(env)) return; @@ -177,11 +182,14 @@ void RunEnvCleanupHooks(napi_env env) { { // Each hook runs in the env's realm, and a scope it leaves open - // closes when it returns. + // closes when it returns. Nothing can catch what it throws: as Node's + // CallIntoModule does once JS can no longer run, it is dropped. v8::HandleScope handle_scope(env->isolate); v8::Context::Scope context_scope(env->main_context()); napi_realm_frame_scope__ realm_frame(env, nullptr); + v8::TryCatch try_catch(env->isolate); snapshot.hook(snapshot.arg); + ClearLastException(env); } it = find_hook(env->env_cleanup_hooks, snapshot); @@ -741,7 +749,15 @@ void napi_env__::CallFinalizer(node_api_basic_finalize cb, void* data, void* hin v8::HandleScope handle_scope(isolate); v8::Context::Scope context_scope(main_context()); napi_realm_frame_scope__ realm_frame(this, nullptr); + if (!releasing) { + cb(this, data, hint); + return; + } + // At the release nothing can catch what the finalizer throws: as Node's + // CallIntoModule does once JS can no longer run, it is dropped. + v8::TryCatch try_catch(isolate); cb(this, data, hint); + ClearLastException(this); } void napi_env__::InvokeFinalizerFromGC(napi_ref_tracker__* finalizer) { @@ -862,25 +878,31 @@ napi_env__::~napi_env__() { // Every scope closes. Cleanup hooks and finalizers each run in the env's // realm, and a scope one leaves open closes when it returns. PopRealmFrames(0); - RunEnvCleanupHooks(this); - napi_ref_tracker__::FinalizeAll(&finalizing_reflist); - napi_ref_tracker__::FinalizeAll(&reflist); - pending_finalizers.clear(); - pending_buffer_finalizers.clear(); - finalization_scheduled = false; - FinalizeExternalBackingStoreHints(this); - napi_v8_finalize_buffer_records(this); - // External buffers the finalizers above made are finalized too, then the - // instance data, then what its finalizer made, so no hint is left pointing - // at the env. Instance data a finalizer sets is finalized in turn, as Node - // finalizes refs made while it finalizes. + // The release contract (unofficial_napi_release_env): the cleanup hooks + // run, then the finalizers of the values still pending (references with a + // finalizer most recent first, as Node's FinalizeAll, then external + // buffers), until neither is left; then the instance data's finalizer; and + // all of it again for what that finalizer leaves pending, until nothing is, + // so no hint is left pointing at the env. The callback is cleared before it + // runs, so instance data is finalized once. for (;;) { - FinalizeExternalBackingStoreHints(this); + do { + RunEnvCleanupHooks(this); + napi_ref_tracker__::FinalizeAll(&finalizing_reflist); + pending_finalizers.clear(); + pending_buffer_finalizers.clear(); + FinalizeExternalBackingStoreHints(this); + } while (!env_cleanup_hooks.empty() || !napi_ref_tracker__::IsEmpty(&finalizing_reflist)); if (instance_data_finalize_cb == nullptr) break; napi_finalize finalize_cb = instance_data_finalize_cb; instance_data_finalize_cb = nullptr; CallFinalizer(finalize_cb, instance_data, instance_data_finalize_hint); } + finalization_scheduled = false; + // Plain references keep their values until every finalizer has run, as in + // Node, whose FinalizeAll(&reflist) comes after the finalizers. + napi_v8_finalize_buffer_records(this); + napi_ref_tracker__::FinalizeAll(&reflist); // Backstop: nothing above should leave a scope open, and a context still // entered here would abort V8 at the embedder's next Context::Exit. PopRealmFrames(0); From 55ded9d4bbc502d89cf27425ff0cc3154953c4ea Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 16:18:59 -0800 Subject: [PATCH 045/150] QuickJS: finalize an external buffer once when its finalizer detaches it JS_DetachArrayBuffer calls the buffer's realloc callback before it marks the buffer detached. When the external buffer's finalizer, run from that callback, detached the same buffer again (napi_detach_arraybuffer through a reference), the callback ran a second time: the inner call destroyed the hint, and the outer one read the destroyed hint and destroyed it again. If the finalizer made a value after the detach, that value got the freed slot, and the outer call destroyed the new value's hint. release_array_buffer now returns at once when re-entered, so the outer call finishes and destroys the hint once. New test test_33 ExternalArrayBufferItsFinalizerDetachesIsFinalizedOnce (both engines): the finalizer detaches its own buffer through a reference, then makes an external kept on the global. Before this commit, the Release build reported the made external finalized 0 times instead of 1; the Debug+ASan build crashed at release: "AddressSanitizer: SEGV ... napi_intrinsic_link__::unlink() ... napi_external_backing_store_hint__::invoke_finalizer() ... napi_external__::finalizer ... JS_FreeRuntime". V8 passed already. Co-Authored-By: Claude Opus 5.5 --- .../napi_external_backing_store_hint.cc | 7 ++ .../napi_external_backing_store_hint.h | 2 + tests/runners/test_33_typedarray.cc | 81 +++++++++++++++++++ 3 files changed, 90 insertions(+) diff --git a/quickjs/src/internal/napi_external_backing_store_hint.cc b/quickjs/src/internal/napi_external_backing_store_hint.cc index d4696beedf..9fd58cfb71 100644 --- a/quickjs/src/internal/napi_external_backing_store_hint.cc +++ b/quickjs/src/internal/napi_external_backing_store_hint.cc @@ -26,6 +26,7 @@ napi_external_backing_store_hint__::~napi_external_backing_store_hint__() finalize_cb_ = nullptr; finalize_hint_ = nullptr; finalize_invoked_ = false; + released_ = false; weak_target_ = JS_UNDEFINED; } @@ -88,6 +89,12 @@ void napi_external_backing_store_hint__::invoke_finalizer() void napi_external_backing_store_hint__::release_array_buffer(JSRuntime *rt) { + // QuickJS marks the buffer detached only once this returns, so a finalizer + // that detaches the same buffer again calls back in here: the outer call + // finishes, and destroys the hint once. + if (released_) + return; + released_ = true; invoke_finalizer(); if (!detaching_) destroy_with_runtime(rt, this); diff --git a/quickjs/src/internal/napi_external_backing_store_hint.h b/quickjs/src/internal/napi_external_backing_store_hint.h index 587fb3f12b..f7a4e61d4d 100644 --- a/quickjs/src/internal/napi_external_backing_store_hint.h +++ b/quickjs/src/internal/napi_external_backing_store_hint.h @@ -78,6 +78,8 @@ struct napi_external_backing_store_hint__ JSNativeWeakRefLink array_buffer_link_{}; // Teardown is detaching array_buffer_ and destroys the hint itself. bool detaching_ = false; + // The array buffer let go of the memory (release_array_buffer ran). + bool released_ = false; }; #endif // NAPI_QUICKJS_EXTERNAL_BACKING_STORE_HINT_H_ diff --git a/tests/runners/test_33_typedarray.cc b/tests/runners/test_33_typedarray.cc index 4597773757..314e064c4f 100644 --- a/tests/runners/test_33_typedarray.cc +++ b/tests/runners/test_33_typedarray.cc @@ -87,6 +87,87 @@ TEST_F(Test33TypedArray, ExternalArrayBufferTransferAndDetachFinalizeOnce) { EXPECT_EQ(state.finalized, 1); } +namespace { + +void CountFinalizer(node_api_basic_env, void*, void* hint) { + ++*static_cast(hint); +} + +// An external array buffer whose finalizer detaches the buffer again, then +// makes an external, kept on the global. +struct SelfDetaching { + uint8_t bytes[8] = {}; + napi_ref buffer = nullptr; + int finalized = 0; + napi_status detach_status = napi_generic_failure; + bool detached = false; + napi_status made_status = napi_generic_failure; + int made_finalized = 0; +}; + +void FinalizeDetachingItself(node_api_basic_env basic_env, void* data, void* hint) { + auto env = const_cast(basic_env); + auto* state = static_cast(hint); + EXPECT_EQ(data, state->bytes); + ++state->finalized; + napi_handle_scope scope = nullptr; + if (napi_open_handle_scope(env, &scope) != napi_ok) return; + napi_value buffer = nullptr; + if (napi_get_reference_value(env, state->buffer, &buffer) == napi_ok && buffer != nullptr) { + state->detach_status = napi_detach_arraybuffer(env, buffer); + napi_is_detached_arraybuffer(env, buffer, &state->detached); + } + napi_value external = nullptr; + napi_value global = nullptr; + if (napi_create_external(env, nullptr, CountFinalizer, &state->made_finalized, &external) == + napi_ok && + napi_get_global(env, &global) == napi_ok) { + state->made_status = napi_set_named_property(env, global, "madeInFinalizer", external); + } + napi_close_handle_scope(env, scope); +} + +} // namespace + +// The finalizer of an external array buffer may detach that buffer again +// (napi_detach_arraybuffer runs the finalizer before the buffer is marked +// detached on some engines). It still runs once, and the provider's +// bookkeeping stays intact for the values made after it. +TEST_F(Test33TypedArray, ExternalArrayBufferItsFinalizerDetachesIsFinalizedOnce) { + SelfDetaching state; + int others = 0; + { + EnvScope s(runtime_.get()); + napi_value buffer = nullptr; + ASSERT_EQ(napi_create_external_arraybuffer(s.env, state.bytes, sizeof(state.bytes), + FinalizeDetachingItself, &state, &buffer), + napi_ok); + ASSERT_EQ(napi_create_reference(s.env, buffer, 1, &state.buffer), napi_ok); + ASSERT_EQ(napi_detach_arraybuffer(s.env, buffer), napi_ok); + // A provider that defers the finalizer runs it here. + ASSERT_EQ(unofficial_napi_event_loop_checkpoint( + s.env, unofficial_napi_event_loop_checkpoint_microtasks, true, nullptr), + napi_ok); + EXPECT_EQ(state.finalized, 1); + EXPECT_EQ(state.detach_status, napi_ok); + EXPECT_TRUE(state.detached); + EXPECT_EQ(state.made_status, napi_ok); + ASSERT_EQ(napi_delete_reference(s.env, state.buffer), napi_ok); + + // Values made afterwards each get their own finalizer record. + napi_value global = nullptr; + ASSERT_EQ(napi_get_global(s.env, &global), napi_ok); + for (const char* name : {"first", "second", "third"}) { + napi_value external = nullptr; + ASSERT_EQ(napi_create_external(s.env, nullptr, CountFinalizer, &others, &external), napi_ok); + ASSERT_EQ(napi_set_named_property(s.env, global, name, external), napi_ok); + } + } + EXPECT_EQ(state.finalized, 1); + EXPECT_EQ(state.made_finalized, 1); + EXPECT_EQ(others, 3); +} + #if defined(NAPI_TEST_ENGINE_QUICKJS) TEST_F(Test33TypedArray, ExternalArrayBufferResizeFailurePreservesBackingStore) { ExternalBufferState state; From 3a17cd69354c2a7860e3a8531e6e9119f8ae5b32 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 16:18:59 -0800 Subject: [PATCH 046/150] QuickJS: report a detached ArrayBuffer's info as empty, as Node napi_get_arraybuffer_info on a detached ArrayBuffer returned napi_invalid_arg, because JS_GetArrayBuffer throws for it. Node (and the V8 provider) return napi_ok with data NULL and a byte length of 0. The QuickJS provider now does the same for an ArrayBuffer; any other value is still napi_invalid_arg, and the exception JS_GetArrayBuffer raised is still cleared. New test test_33 DetachedArrayBufferInfoIsEmpty (both engines), for an owned and an external ArrayBuffer, and a plain object. Before this commit, QuickJS returned status 1 (napi_invalid_arg) and left the out-parameters untouched; V8 passed. Co-Authored-By: Claude Opus 5.5 --- quickjs/src/js_native_api_quickjs.cc | 8 ++++++-- tests/runners/test_33_typedarray.cc | 29 ++++++++++++++++++++++++++++ 2 files changed, 35 insertions(+), 2 deletions(-) diff --git a/quickjs/src/js_native_api_quickjs.cc b/quickjs/src/js_native_api_quickjs.cc index 2065e4a6d1..a19aee461c 100644 --- a/quickjs/src/js_native_api_quickjs.cc +++ b/quickjs/src/js_native_api_quickjs.cc @@ -1297,13 +1297,17 @@ extern "C" if (!napi_util__::check_value(env, arraybuffer)) return napi_util__::invalid_arg(env); + JSValue value = napi_quickjs_value_inner(env, arraybuffer); size_t len = 0; - uint8_t *ptr = JS_GetArrayBuffer(env->context(), &len, napi_quickjs_value_inner(env, arraybuffer)); + uint8_t *ptr = JS_GetArrayBuffer(env->context(), &len, value); if (ptr == nullptr && len == 0 && JS_HasException(env->context())) { JSValue exc = JS_GetException(env->context()); JS_FreeValue(env->context(), exc); - return napi_quickjs_set_last_error(env, napi_invalid_arg, "Invalid argument"); + // QuickJS throws for a detached ArrayBuffer. Node reports it as one + // with no data and a byte length of 0. + if (!JS_IsArrayBuffer(value)) + return napi_quickjs_set_last_error(env, napi_invalid_arg, "Invalid argument"); } if (data != nullptr) diff --git a/tests/runners/test_33_typedarray.cc b/tests/runners/test_33_typedarray.cc index 314e064c4f..920e227825 100644 --- a/tests/runners/test_33_typedarray.cc +++ b/tests/runners/test_33_typedarray.cc @@ -168,6 +168,35 @@ TEST_F(Test33TypedArray, ExternalArrayBufferItsFinalizerDetachesIsFinalizedOnce) EXPECT_EQ(others, 3); } +// As in Node, a detached ArrayBuffer has no data and a byte length of 0. +TEST_F(Test33TypedArray, DetachedArrayBufferInfoIsEmpty) { + ExternalBufferState state; + EnvScope s(runtime_.get()); + napi_value owned = nullptr; + ASSERT_EQ(napi_create_arraybuffer(s.env, 16, nullptr, &owned), napi_ok); + napi_value external = nullptr; + ASSERT_EQ(napi_create_external_arraybuffer(s.env, state.bytes, sizeof(state.bytes), + FinalizeExternalBuffer, &state, &external), + napi_ok); + for (napi_value buffer : {owned, external}) { + ASSERT_EQ(napi_detach_arraybuffer(s.env, buffer), napi_ok); + void* data = &state; + size_t length = 1; + EXPECT_EQ(napi_get_arraybuffer_info(s.env, buffer, &data, &length), napi_ok); + EXPECT_EQ(data, nullptr); + EXPECT_EQ(length, 0u); + bool pending = true; + ASSERT_EQ(napi_is_exception_pending(s.env, &pending), napi_ok); + EXPECT_FALSE(pending); + } + // Not an ArrayBuffer at all is still an invalid argument. + napi_value object = nullptr; + ASSERT_EQ(napi_create_object(s.env, &object), napi_ok); + void* data = nullptr; + size_t length = 0; + EXPECT_EQ(napi_get_arraybuffer_info(s.env, object, &data, &length), napi_invalid_arg); +} + #if defined(NAPI_TEST_ENGINE_QUICKJS) TEST_F(Test33TypedArray, ExternalArrayBufferResizeFailurePreservesBackingStore) { ExternalBufferState state; From 815aec9558b8ee5635d53d736bc54641174d6a44 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 16:18:59 -0800 Subject: [PATCH 047/150] QuickJS: run an external buffer's finalizer once detached at release At release the provider detached an external buffer and its finalizer ran from inside JS_DetachArrayBuffer, before QuickJS marked the buffer detached, so the finalizer still saw it attached. Node's CallbackInfo::Clean detaches first and then calls the finalizer. The realloc callback now only records that the buffer let go of the memory while the release is detaching it, and the release runs the finalizer once JS_DetachArrayBuffer has returned, then destroys the hint. A buffer that ArrayBuffer.prototype.transfer emptied is already detached; its finalizer runs as before and the hint stays with the buffer the memory moved to. test_41 ExternalBuffersAreDetachedBeforeTheirFinalizersAtRelease (still QuickJS only here) also checks, from each finalizer, that its array buffer is detached, and now expects napi_get_arraybuffer_info to report napi_ok, NULL and 0 for the detached buffer. Before this commit, both new checks failed on QuickJS (detached_when_freed false for the ArrayBuffer and the Buffer). Co-Authored-By: Claude Opus 5.5 --- .../napi_external_backing_store_hint.cc | 24 +++++---- .../napi_external_backing_store_hint.h | 6 +-- tests/runners/test_41_instance_data.cc | 52 ++++++++++++------- 3 files changed, 52 insertions(+), 30 deletions(-) diff --git a/quickjs/src/internal/napi_external_backing_store_hint.cc b/quickjs/src/internal/napi_external_backing_store_hint.cc index 9fd58cfb71..9217fbf5ae 100644 --- a/quickjs/src/internal/napi_external_backing_store_hint.cc +++ b/quickjs/src/internal/napi_external_backing_store_hint.cc @@ -95,9 +95,12 @@ void napi_external_backing_store_hint__::release_array_buffer(JSRuntime *rt) if (released_) return; released_ = true; + // Teardown runs the finalizer itself, once the buffer is marked detached, + // and destroys the hint. + if (detaching_) + return; invoke_finalizer(); - if (!detaching_) - destroy_with_runtime(rt, this); + destroy_with_runtime(rt, this); } void napi_external_backing_store_hint__::track_array_buffer(JSContext *ctx, @@ -135,23 +138,26 @@ void napi_external_backing_store_hint__::finalize_at_teardown() { if (JS_GetNativeWeakRefFromLink(&array_buffer_link_) != nullptr) { - // As Node does, detach the buffer first, so nothing can reach the memory - // the finalizer frees. Detaching runs the finalizer, unless - // ArrayBuffer.prototype.transfer already moved the memory to a buffer this - // hint cannot reach (Node cannot either). The reference keeps the buffer - // alive in case the finalizer drops the last other one. + // As Node's CallbackInfo::Clean does, detach the buffer before the + // finalizer runs, so the finalizer and the code after it see it detached + // and nothing reaches the memory the finalizer frees. The detach lets go + // of the memory, unless ArrayBuffer.prototype.transfer already moved it to + // a buffer this hint cannot reach (Node cannot either). The reference + // keeps the buffer alive in case the finalizer drops the last other one. JSContext *ctx = env_->main_context(); JSValue array_buffer = JS_DupValue(ctx, array_buffer_); detaching_ = true; JS_DetachArrayBuffer(ctx, array_buffer); detaching_ = false; - JS_FreeValue(ctx, array_buffer); - if (finalize_invoked_) + if (released_) { // The buffer no longer refers to the hint. + invoke_finalizer(); + JS_FreeValue(ctx, array_buffer); destroy(this); return; } + JS_FreeValue(ctx, array_buffer); } invoke_finalizer(); } diff --git a/quickjs/src/internal/napi_external_backing_store_hint.h b/quickjs/src/internal/napi_external_backing_store_hint.h index f7a4e61d4d..f412425104 100644 --- a/quickjs/src/internal/napi_external_backing_store_hint.h +++ b/quickjs/src/internal/napi_external_backing_store_hint.h @@ -30,7 +30,8 @@ struct napi_external_backing_store_hint__ void invoke_finalizer(); // The external array buffer this hint backs let go of the memory: it was - // detached or freed. + // detached or freed. Runs the finalizer and destroys the hint, unless + // teardown is detaching the buffer and does both itself. void release_array_buffer(JSRuntime *rt); // Remembers the external array buffer this hint backs, so teardown can // detach it before running the finalizer. @@ -40,8 +41,7 @@ struct napi_external_backing_store_hint__ // pending list until it runs or the hint is destroyed. void link_pending(napi_intrinsic_link__ &pending); static napi_external_backing_store_hint__ *first_pending(napi_intrinsic_link__ &pending); - // Runs the finalizer, detaching the array buffer first. May destroy the - // hint. + // Detaches the array buffer, then runs the finalizer. May destroy the hint. void finalize_at_teardown(); // Leaves the pending list for good: the finalizer will not run. void abandon_finalizer(); diff --git a/tests/runners/test_41_instance_data.cc b/tests/runners/test_41_instance_data.cc index 417cb0e3e7..49c488c23d 100644 --- a/tests/runners/test_41_instance_data.cc +++ b/tests/runners/test_41_instance_data.cc @@ -302,13 +302,33 @@ TEST_F(Test41InstanceData, WhatTheInstanceDataFinalizerLeavesIsReleasedInTheSame namespace { -// Memory an external buffer was made over, which its finalizer frees. +bool IsDetached(napi_env env, napi_ref ref) { + napi_value value = nullptr; + bool detached = false; + return napi_get_reference_value(env, ref, &value) == napi_ok && + napi_is_detached_arraybuffer(env, value, &detached) == napi_ok && detached; +} + +// Memory an external buffer was made over, which its finalizer frees. With +// `buffer` set, the finalizer records whether that array buffer was detached +// when it ran. struct Owned { int frees = 0; + napi_ref buffer = nullptr; + bool detached_when_freed = false; }; -void FreeOwned(node_api_basic_env, void* data, void* hint) { - ++static_cast(hint)->frees; +void FreeOwned(node_api_basic_env basic_env, void* data, void* hint) { + auto* owned = static_cast(hint); + ++owned->frees; + if (owned->buffer != nullptr) { + auto env = const_cast(basic_env); + napi_handle_scope scope = nullptr; + if (napi_open_handle_scope(env, &scope) == napi_ok) { + owned->detached_when_freed = IsDetached(env, owned->buffer); + napi_close_handle_scope(env, scope); + } + } std::free(data); } @@ -349,13 +369,6 @@ struct AfterFree { bool buffer_detached = false; }; -bool IsDetached(napi_env env, napi_ref ref) { - napi_value value = nullptr; - bool detached = false; - return napi_get_reference_value(env, ref, &value) == napi_ok && - napi_is_detached_arraybuffer(env, value, &detached) == napi_ok && detached; -} - void InspectFreedBuffers(napi_env env, void* data, void*) { auto* after = static_cast(data); after->frees_seen = after->array_buffer_memory.frees + after->buffer_memory.frees; @@ -376,9 +389,9 @@ void InspectFreedBuffers(napi_env env, void* data, void*) { } // namespace -// As Node does, an external buffer is detached before its finalizer frees -// the memory, so code that runs later at release cannot read freed memory -// through it. The V8 provider does not detach them yet. +// As Node's CallbackInfo::Clean does, an external buffer is detached before +// its finalizer frees the memory, so code that runs later at release sees it +// detached, never the freed memory. The V8 provider does not detach them yet. TEST_F(Test41InstanceData, ExternalBuffersAreDetachedBeforeTheirFinalizersAtRelease) { EnvScope s(runtime_.get()); AfterFree after; @@ -402,18 +415,21 @@ TEST_F(Test41InstanceData, ExternalBuffersAreDetachedBeforeTheirFinalizersAtRele ASSERT_EQ(napi_create_reference(s.env, view, 1, &after.view), napi_ok); ASSERT_EQ(napi_create_reference(s.env, buffer_array_buffer, 1, &after.buffer_array_buffer), napi_ok); + after.array_buffer_memory.buffer = after.array_buffer; + after.buffer_memory.buffer = after.buffer_array_buffer; ASSERT_EQ(napi_set_instance_data(s.env, &after, InspectFreedBuffers, nullptr), napi_ok); Release(s); EXPECT_EQ(after.frees_seen, 2); EXPECT_EQ(after.array_buffer_memory.frees, 1); EXPECT_EQ(after.buffer_memory.frees, 1); + EXPECT_TRUE(after.array_buffer_memory.detached_when_freed); + EXPECT_TRUE(after.buffer_memory.detached_when_freed); EXPECT_TRUE(after.array_buffer_detached); - // QuickJS refuses the info of a detached buffer; either way it does not - // hand out the freed memory. - EXPECT_TRUE(after.info_status != napi_ok || - (after.info_data == nullptr && after.info_length == 0)) - << "status " << after.info_status << ", length " << after.info_length; + // A detached array buffer has no data and a byte length of 0, as in Node. + EXPECT_EQ(after.info_status, napi_ok); + EXPECT_EQ(after.info_data, nullptr); + EXPECT_EQ(after.info_length, 0u); EXPECT_EQ(after.element, napi_undefined); EXPECT_TRUE(after.buffer_detached); } From 695eb2f986ff63d8d0be35dff3d9df2d379aef86 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 16:18:59 -0800 Subject: [PATCH 048/150] V8: detach external buffers before their finalizers at release The V8 release ran the finalizers of external ArrayBuffers and Buffers still alive without detaching them, so the instance-data finalizer, or any code after it, could read memory a finalizer had freed through them. Their order also followed an unordered_set. Each external store with a user finalizer now gets an id (never reused, unlike the hint's address), and the env keeps the ArrayBuffer made over it (for a Buffer, the Buffer's ArrayBuffer) in a weak v8::Global, in a map by id, on the env's thread only. The deleter queues the id with the finalizer; whoever runs a finalizer, a drain or the release, drops the entry first. At release, FinalizeExternalBackingStoreHints runs the queued finalizers, then takes the newest tracked buffer: it detaches it, as Node's CallbackInfo::Clean does, and then claims the finalizer under the lock if the hint is still in the env's set with that id. If the detach freed the store, the deleter claimed and queued the finalizer instead, and the next round runs it. Either way it is claimed once. The hint is dereferenced only under the lock while it is in the set; Globals are reset on the env's thread. What is left (free callbacks of provider-owned stores) is claimed and run as before. A buffer that ArrayBuffer.prototype.transfer moved a store to is not reachable from here; Node cannot reach it either. Deferral outside the release, the free callbacks in the deleter and the lock discipline are unchanged. Tests: test_41 ExternalBuffersAreDetachedBeforeTheirFinalizersAtRelease now runs on V8 too. Before this commit, V8 failed it: neither finalizer saw its buffer detached (detached_when_freed false for the ArrayBuffer and the Buffer), and the instance-data finalizer found neither detached (its references had also been reset by then, which the earlier V8 commit fixed). New ValuesAreFinalizedMostRecentFirstAtRelease: three externals, wraps and external ArrayBuffers, each kind finalized most recent first. Before this commit, V8 failed it in one of two runs (buffers in hash order: "actual: 8 vs 7"). Co-Authored-By: Claude Opus 5.5 --- tests/runners/test_41_instance_data.cc | 38 ++++++- v8/src/internal/napi_env_records.h | 3 + v8/src/internal/napi_v8_env.h | 18 ++++ v8/src/js_native_api_v8.cc | 142 ++++++++++++++++++++----- 4 files changed, 171 insertions(+), 30 deletions(-) diff --git a/tests/runners/test_41_instance_data.cc b/tests/runners/test_41_instance_data.cc index 49c488c23d..1e419d3fb1 100644 --- a/tests/runners/test_41_instance_data.cc +++ b/tests/runners/test_41_instance_data.cc @@ -300,6 +300,40 @@ TEST_F(Test41InstanceData, WhatTheInstanceDataFinalizerLeavesIsReleasedInTheSame EXPECT_LT(rounds.value.order, rounds.second.order); } +// Values are finalized most recent first, as Node's FinalizeAll does. The +// order between different kinds of values (references such as externals and +// wraps, and external array buffers) is not specified. +TEST_F(Test41InstanceData, ValuesAreFinalizedMostRecentFirstAtRelease) { + constexpr int kValues = 3; + EnvScope s(runtime_.get()); + int clock = 0; + std::vector externals(kValues, Seen{&clock}); + std::vector wraps(kValues, Seen{&clock}); + std::vector buffers(kValues, Seen{&clock}); + uint8_t bytes[kValues][8] = {}; + MarkEnvGlobal(s.env); + for (int i = 0; i < kValues; ++i) { + const std::string index = std::to_string(i); + KeepExternal(s.env, ("external" + index).c_str(), &externals[i]); + napi_value value = nullptr; + ASSERT_EQ(napi_create_object(s.env, &value), napi_ok); + ASSERT_EQ(napi_wrap(s.env, value, nullptr, FinalizeValue, &wraps[i], nullptr), napi_ok); + Keep(s.env, ("wrapped" + index).c_str(), value); + ASSERT_EQ(napi_create_external_arraybuffer(s.env, bytes[i], sizeof(bytes[i]), FinalizeValue, + &buffers[i], &value), + napi_ok); + Keep(s.env, ("arrayBuffer" + index).c_str(), value); + } + + Release(s); + for (const auto* kind : {&externals, &wraps, &buffers}) { + for (int i = 0; i < kValues; ++i) { + ExpectUsedNapi((*kind)[i], ("value " + std::to_string(i)).c_str()); + if (i > 0) EXPECT_LT((*kind)[i].order, (*kind)[i - 1].order) << "value " << i; + } + } +} + namespace { bool IsDetached(napi_env env, napi_ref ref) { @@ -349,7 +383,6 @@ napi_value Transfer(napi_env env, napi_value array_buffer) { } // namespace -#if defined(NAPI_TEST_ENGINE_QUICKJS) namespace { // What the instance-data finalizer finds of external buffers whose finalizers @@ -391,7 +424,7 @@ void InspectFreedBuffers(napi_env env, void* data, void*) { // As Node's CallbackInfo::Clean does, an external buffer is detached before // its finalizer frees the memory, so code that runs later at release sees it -// detached, never the freed memory. The V8 provider does not detach them yet. +// detached, never the freed memory. TEST_F(Test41InstanceData, ExternalBuffersAreDetachedBeforeTheirFinalizersAtRelease) { EnvScope s(runtime_.get()); AfterFree after; @@ -433,7 +466,6 @@ TEST_F(Test41InstanceData, ExternalBuffersAreDetachedBeforeTheirFinalizersAtRele EXPECT_EQ(after.element, napi_undefined); EXPECT_TRUE(after.buffer_detached); } -#endif // ArrayBuffer.prototype.transfer moves an external buffer's memory to a new // buffer. Its finalizer still runs once at release, whether the buffer it was diff --git a/v8/src/internal/napi_env_records.h b/v8/src/internal/napi_env_records.h index 115bb0b8b7..01669918c0 100644 --- a/v8/src/internal/napi_env_records.h +++ b/v8/src/internal/napi_env_records.h @@ -68,6 +68,9 @@ struct napi_external_backing_store_hint__ { // Set instead of `finalize_cb` for memory that only needs freeing // (napi_v8_external_free_callback); it gets `finalize_hint`. void (*free_cb)(void* data, void* hint) = nullptr; + // With `finalize_cb`: the store's key in the env's external_array_buffers. + // Never reused, unlike the hint's address. + uint64_t id = 0; }; using napi_external_backing_store_hint = napi_external_backing_store_hint__; diff --git a/v8/src/internal/napi_v8_env.h b/v8/src/internal/napi_v8_env.h index eb36b1b6bd..e8389a7cb6 100644 --- a/v8/src/internal/napi_v8_env.h +++ b/v8/src/internal/napi_v8_env.h @@ -6,6 +6,7 @@ #include #include #include +#include #include #include #include @@ -63,6 +64,18 @@ struct napi_external_finalizer__ { void* data = nullptr; void* hint = nullptr; napi_v8_external_free_callback free_cb = nullptr; + // The store's id (napi_external_backing_store_hint__::id), 0 for none. + uint64_t id = 0; +}; + +// The array buffer of an external backing store with a user finalizer, held +// weakly, so the env's release can detach it before the finalizer runs. +struct napi_external_array_buffer__ { + // The store's hint. Compared, and read only under NapiV8ExternalHintsMutex() + // while it is still in the env's external_backing_store_hints: its deleter + // may have freed it. + napi_external_backing_store_hint__* hint = nullptr; + v8::Global array_buffer; }; struct napi_callback_info__ { @@ -162,6 +175,11 @@ struct napi_env__ { uint64_t env_cleanup_hook_counter = 0; std::vector buffer_records; std::unordered_set external_backing_store_hints; + // The array buffers of the external stores with a user finalizer, by store + // id, so in the order they were made. An entry goes when its finalizer runs. + // Env thread only. + std::map external_array_buffers; + uint64_t last_external_id = 0; napi_ref_tracker__::RefList reflist; napi_ref_tracker__::RefList finalizing_reflist; std::unordered_set pending_finalizers; diff --git a/v8/src/js_native_api_v8.cc b/v8/src/js_native_api_v8.cc index 0539157d08..7860fca558 100644 --- a/v8/src/js_native_api_v8.cc +++ b/v8/src/js_native_api_v8.cc @@ -21,6 +21,7 @@ #include #include #include +#include #include #include #include @@ -320,7 +321,8 @@ void ExternalBackingStoreDeleter(void* data, hint->env = nullptr; free_cb = hint->free_cb; if (hint->finalize_cb != nullptr && - QueueExternalFinalizer(env, {hint->finalize_cb, data, hint->finalize_hint})) { + QueueExternalFinalizer( + env, {hint->finalize_cb, data, hint->finalize_hint, nullptr, hint->id})) { post_to = env; enqueue = env->agent->enqueue_foreground_task_callback; target = env->agent->enqueue_foreground_task_target; @@ -332,28 +334,89 @@ void ExternalBackingStoreDeleter(void* data, if (post_to != nullptr) PostExternalFinalizerDrain(post_to, enqueue, target); } +// The env's thread drops the array buffer it tracked for a store whose +// finalizer is about to run. +void ForgetExternalArrayBuffer(napi_env env, uint64_t id) { + if (id != 0) env->external_array_buffers.erase(id); +} + +// Runs the external finalizers deleters queued. Env thread only. +bool RunQueuedExternalFinalizers(napi_env env) { + std::vector queued = TakeExternalFinalizers(env); + for (const auto& finalizer : queued) { + ForgetExternalArrayBuffer(env, finalizer.id); + env->CallFinalizer(finalizer.cb, finalizer.data, finalizer.hint); + } + return !queued.empty(); +} + +// At the env's release: detaches the most recently made external array buffer +// still tracked, as Node's CallbackInfo::Clean does, then runs its finalizer, +// so code that runs later sees the buffer detached, never the freed memory. +// The detach may free the store; its deleter then claims the finalizer and +// queues it, and RunQueuedExternalFinalizers runs it. Either way the +// finalizer is claimed once, under the lock. A buffer that +// ArrayBuffer.prototype.transfer moved the store to is not reachable from +// here (Node cannot reach it either); the one it moved it from is detached +// already. +void FinalizeNewestExternalArrayBuffer(napi_env env) { + auto newest = std::prev(env->external_array_buffers.end()); + const uint64_t id = newest->first; + napi_external_backing_store_hint__* hint = newest->second.hint; + v8::Global handle = std::move(newest->second.array_buffer); + env->external_array_buffers.erase(newest); + { + v8::HandleScope handle_scope(env->isolate); + v8::Local array_buffer = handle.Get(env->isolate); + handle.Reset(); + if (!array_buffer.IsEmpty() && array_buffer->IsDetachable()) { + v8::Context::Scope context_scope(env->main_context()); + v8::TryCatch try_catch(env->isolate); + (void)array_buffer->Detach(v8::Local()); + } + } + napi_external_finalizer__ finalizer; + { + std::lock_guard lock(NapiV8ExternalHintsMutex()); + // Still in the set: the deleter has not run, so `hint` is alive. A new + // hint at the same address has another id. + if (env->external_backing_store_hints.count(hint) != 0 && hint->id == id) { + v8impl::detail::napi_lifetime__:: + record_release(env, hint); + env->external_backing_store_hints.erase(hint); + hint->env = nullptr; + finalizer = {hint->finalize_cb, hint->external_data, hint->finalize_hint}; + hint->finalize_cb = nullptr; + } + } + env->CallFinalizer(finalizer.cb, finalizer.data, finalizer.hint); +} + void FinalizeExternalBackingStoreHints(napi_env env) { if (!CheckEnv(env)) return; - // Claims, under the lock, the finalizers deleters queued and the finalizers - // and free callbacks of the backing stores still alive, then runs them - // outside it. A backing store - // can outlive the env, so each live hint is unlinked from the dying env - // rather than deleted here — its deleter frees it later and, seeing a null - // env, skips the env-side bookkeeping. The hints are not touched after the - // lock is dropped: a concurrent deleter may already be freeing them. - // Repeats while finalizers make more external buffers. + // At the env's release. Runs the finalizers deleters queued, then, most + // recent first, detaches each external array buffer with a user finalizer + // and runs its finalizer. Then claims, under the lock, what the backing + // stores still alive hold (the free callbacks of provider-owned memory), and + // runs it outside the lock. A backing store can outlive the env, so each + // live hint is unlinked from the dying env rather than deleted here — its + // deleter frees it later and, seeing a null env, skips the env-side + // bookkeeping. The hints are not touched after the lock is dropped: a + // concurrent deleter may already be freeing them. Repeats while finalizers + // make more external buffers. for (;;) { + const bool ran_queued = RunQueuedExternalFinalizers(env); + if (!env->external_array_buffers.empty()) { + FinalizeNewestExternalArrayBuffer(env); + continue; + } std::vector pending; { std::lock_guard lock(NapiV8ExternalHintsMutex()); - pending.swap(env->external_finalizers); - env->has_external_finalizers.store(false, std::memory_order_relaxed); - env->external_finalizer_drain_posted = false; std::unordered_set hints; hints.swap(env->external_backing_store_hints); - if (pending.empty() && hints.empty()) return; - pending.reserve(pending.size() + hints.size()); + pending.reserve(hints.size()); for (auto* hint : hints) { if (hint == nullptr) continue; v8impl::detail::napi_lifetime__:: @@ -367,6 +430,7 @@ void FinalizeExternalBackingStoreHints(napi_env env) { } } } + if (pending.empty() && !ran_queued) return; for (const auto& finalizer : pending) { if (finalizer.free_cb != nullptr) { @@ -644,23 +708,28 @@ void SetterTrampoline(v8::Local property, } // A backing store over external memory. Its deleter hands `finalize_cb` to -// the env's thread, or runs `free_cb` itself; at most one is set. -std::unique_ptr NewExternalBackingStore(napi_env env, - void* data, - size_t length, - node_api_basic_finalize finalize_cb, - napi_v8_external_free_callback free_cb, - void* finalize_hint) { +// the env's thread, or runs `free_cb` itself; at most one is set. Sets +// `*hint_out` to the store's hint, for TrackExternalArrayBuffer. +std::unique_ptr NewExternalBackingStore( + napi_env env, + void* data, + size_t length, + node_api_basic_finalize finalize_cb, + napi_v8_external_free_callback free_cb, + void* finalize_hint, + napi_external_backing_store_hint__** hint_out) { auto hint = std::make_unique(env); hint->external_data = data; hint->finalize_cb = finalize_cb; hint->finalize_hint = finalize_hint; hint->free_cb = free_cb; + if (finalize_cb != nullptr) hint->id = ++env->last_external_id; std::unique_ptr backing = v8::ArrayBuffer::NewBackingStore(data, length, ExternalBackingStoreDeleter, hint.get()); if (!backing) return nullptr; v8impl::detail::napi_lifetime__:: record_create(env, hint.get()); + *hint_out = hint.get(); { // Racing V8's ArrayBufferSweeper threads; see NapiV8ExternalHintsMutex. std::lock_guard lock(NapiV8ExternalHintsMutex()); @@ -669,6 +738,18 @@ std::unique_ptr NewExternalBackingStore(napi_env env, return backing; } +// Remembers, weakly, the array buffer made over a store with a user +// finalizer, so the env's release can detach it first. +void TrackExternalArrayBuffer(napi_env env, + napi_external_backing_store_hint__* hint, + v8::Local array_buffer) { + if (hint->id == 0) return; + napi_external_array_buffer__& entry = env->external_array_buffers[hint->id]; + entry.hint = hint; + entry.array_buffer.Reset(env->isolate, array_buffer); + entry.array_buffer.SetWeak(); +} + napi_status CreateExternalArrayBuffer(napi_env env, void* external_data, size_t byte_length, @@ -684,10 +765,13 @@ napi_status CreateExternalArrayBuffer(napi_env env, out->Detach(v8::Local()).FromMaybe(false); } else { if (external_data == nullptr) return napi_invalid_arg; + napi_external_backing_store_hint__* hint = nullptr; std::unique_ptr backing = NewExternalBackingStore( - env, external_data, byte_length, finalize_cb, free_cb, finalize_hint); + env, external_data, byte_length, finalize_cb, free_cb, finalize_hint, &hint); if (!backing) return napi_generic_failure; + // The array buffer holds the store, so its hint is alive here. out = v8::ArrayBuffer::New(env->isolate, std::move(backing)); + TrackExternalArrayBuffer(env, hint, out); } *result = napi_v8_wrap_value(env, out); @@ -709,14 +793,17 @@ napi_status CreateExternalBuffer(napi_env env, // whose data the caller still owns then. auto* record = env->allocate(env); if (record == nullptr) return napi_generic_failure; + napi_external_backing_store_hint__* hint = nullptr; record->backing_store = - NewExternalBackingStore(env, data, length, finalize_cb, free_cb, finalize_hint); + NewExternalBackingStore(env, data, length, finalize_cb, free_cb, finalize_hint, &hint); if (!record->backing_store) { env->release(record); return napi_generic_failure; } v8::Local buffer_obj = CreateBufferObject(env, record->backing_store, 0, length); + // The record holds the store, so its hint is alive here. + TrackExternalArrayBuffer(env, hint, buffer_obj.As()->Buffer()); record->holder.Reset(env->isolate, buffer_obj); record->holder.SetWeak(record, BufferWeakCallback, v8::WeakCallbackType::kParameter); v8::Local key = env->agent->buffer_private_key.Get(env->isolate); @@ -805,6 +892,7 @@ void napi_env__::DrainFinalizerQueue() { } for (const auto& finalizer : external) { + ForgetExternalArrayBuffer(this, finalizer.id); CallFinalizer(finalizer.cb, finalizer.data, finalizer.hint); } // A finalizer above can free a backing store, which queues the store's @@ -881,10 +969,10 @@ napi_env__::~napi_env__() { // The release contract (unofficial_napi_release_env): the cleanup hooks // run, then the finalizers of the values still pending (references with a // finalizer most recent first, as Node's FinalizeAll, then external - // buffers), until neither is left; then the instance data's finalizer; and - // all of it again for what that finalizer leaves pending, until nothing is, - // so no hint is left pointing at the env. The callback is cleared before it - // runs, so instance data is finalized once. + // buffers, each detached first), until neither is left; then the instance + // data's finalizer; and all of it again for what that finalizer leaves + // pending, until nothing is, so no hint is left pointing at the env. The + // callback is cleared before it runs, so instance data is finalized once. for (;;) { do { RunEnvCleanupHooks(this); From c49e63d0a66b826d6be4425aa52cc1349db97b6d Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 16:28:40 -0800 Subject: [PATCH 049/150] V8: make node_api_create_buffer_from_arraybuffer view the ArrayBuffer The V8 provider made the Buffer over a new ArrayBuffer sharing the source's backing store, and its record held the store too. Node (Buffer::New(isolate, ab, ...)) and the QuickJS provider make a Uint8Array view of the ArrayBuffer itself. So buffer.buffer was not the ArrayBuffer, detaching the ArrayBuffer left the Buffer attached, and at release, once an external ArrayBuffer was detached and its finalizer had freed the memory, a Buffer made from it still read that memory. The Buffer now views the ArrayBuffer (CreateBufferView, split out of CreateBufferObject), and its record no longer holds the store: the ArrayBuffer alone does, as in Node. Found by the Codex review of this series. Tests: - New test_33 BufferFromAnArrayBufferViewsIt (both engines): the Buffer's ArrayBuffer is the source, at the given offset and length, and after the source is detached its element 0 reads as undefined. V8 failed both checks before this change (not the same ArrayBuffer; element 0 still a number). - test_41 ExternalBuffersAreDetachedBeforeTheirFinalizersAtRelease also makes such a Buffer over the external ArrayBuffer and checks, in the instance-data finalizer, that it reads as detached. V8 read a number there before this change, from memory the finalizer had freed. Co-Authored-By: Claude Opus 5.5 --- tests/runners/test_33_typedarray.cc | 33 ++++++++++++++++++++++++++ tests/runners/test_41_instance_data.cc | 15 ++++++++++++ v8/src/js_native_api_v8.cc | 24 ++++++++++++------- 3 files changed, 64 insertions(+), 8 deletions(-) diff --git a/tests/runners/test_33_typedarray.cc b/tests/runners/test_33_typedarray.cc index 920e227825..980de59eff 100644 --- a/tests/runners/test_33_typedarray.cc +++ b/tests/runners/test_33_typedarray.cc @@ -2,6 +2,10 @@ #include "upstream_js_test.h" extern "C" napi_value Init(napi_env env, napi_value exports); +// node_api.h declares it from NAPI_VERSION 10; this target builds at 8. +extern "C" napi_status NAPI_CDECL node_api_create_buffer_from_arraybuffer( + napi_env env, napi_value arraybuffer, size_t byte_offset, size_t byte_length, + napi_value* result); class Test33TypedArray : public FixtureTestBase {}; @@ -197,6 +201,35 @@ TEST_F(Test33TypedArray, DetachedArrayBufferInfoIsEmpty) { EXPECT_EQ(napi_get_arraybuffer_info(s.env, object, &data, &length), napi_invalid_arg); } +// As in Node, node_api_create_buffer_from_arraybuffer makes a Buffer that +// views the ArrayBuffer itself, so detaching the ArrayBuffer detaches the +// Buffer too. +TEST_F(Test33TypedArray, BufferFromAnArrayBufferViewsIt) { + EnvScope s(runtime_.get()); + napi_value array_buffer = nullptr; + void* storage = nullptr; + ASSERT_EQ(napi_create_arraybuffer(s.env, 16, &storage, &array_buffer), napi_ok); + napi_value buffer = nullptr; + ASSERT_EQ(node_api_create_buffer_from_arraybuffer(s.env, array_buffer, 4, 8, &buffer), napi_ok); + napi_value viewed = nullptr; + size_t length = 0; + size_t offset = 0; + ASSERT_EQ(napi_get_typedarray_info(s.env, buffer, nullptr, &length, nullptr, &viewed, &offset), + napi_ok); + bool same = false; + ASSERT_EQ(napi_strict_equals(s.env, viewed, array_buffer, &same), napi_ok); + EXPECT_TRUE(same); + EXPECT_EQ(offset, 4u); + EXPECT_EQ(length, 8u); + + ASSERT_EQ(napi_detach_arraybuffer(s.env, array_buffer), napi_ok); + napi_value element = nullptr; + ASSERT_EQ(napi_get_element(s.env, buffer, 0, &element), napi_ok); + napi_valuetype type = napi_number; + ASSERT_EQ(napi_typeof(s.env, element, &type), napi_ok); + EXPECT_EQ(type, napi_undefined); +} + #if defined(NAPI_TEST_ENGINE_QUICKJS) TEST_F(Test33TypedArray, ExternalArrayBufferResizeFailurePreservesBackingStore) { ExternalBufferState state; diff --git a/tests/runners/test_41_instance_data.cc b/tests/runners/test_41_instance_data.cc index 1e419d3fb1..e02095e3b5 100644 --- a/tests/runners/test_41_instance_data.cc +++ b/tests/runners/test_41_instance_data.cc @@ -14,6 +14,10 @@ #include extern "C" napi_value Init(napi_env env, napi_value exports); +// node_api.h declares it from NAPI_VERSION 10; this target builds at 8. +extern "C" napi_status NAPI_CDECL node_api_create_buffer_from_arraybuffer( + napi_env env, napi_value arraybuffer, size_t byte_offset, size_t byte_length, + napi_value* result); class Test41InstanceData : public FixtureTestBase {}; @@ -393,12 +397,14 @@ struct AfterFree { napi_ref array_buffer = nullptr; napi_ref view = nullptr; napi_ref buffer_array_buffer = nullptr; + napi_ref alias = nullptr; int frees_seen = 0; bool array_buffer_detached = false; napi_status info_status = napi_generic_failure; void* info_data = nullptr; size_t info_length = SIZE_MAX; napi_valuetype element = napi_number; + napi_valuetype alias_element = napi_number; bool buffer_detached = false; }; @@ -417,6 +423,9 @@ void InspectFreedBuffers(napi_env env, void* data, void*) { if (napi_get_reference_value(env, after->view, &value) == napi_ok && napi_get_element(env, value, 3, &element) == napi_ok) napi_typeof(env, element, &after->element); + if (napi_get_reference_value(env, after->alias, &value) == napi_ok && + napi_get_element(env, value, 0, &element) == napi_ok) + napi_typeof(env, element, &after->alias_element); napi_close_handle_scope(env, scope); } @@ -435,6 +444,11 @@ TEST_F(Test41InstanceData, ExternalBuffersAreDetachedBeforeTheirFinalizersAtRele napi_value view = nullptr; ASSERT_EQ(napi_create_typedarray(s.env, napi_uint8_array, 64, array_buffer, 0, &view), napi_ok); Keep(s.env, "view", view); + // A Buffer over the same memory, made from the array buffer. + napi_value alias = nullptr; + ASSERT_EQ(node_api_create_buffer_from_arraybuffer(s.env, array_buffer, 8, 16, &alias), napi_ok); + Keep(s.env, "alias", alias); + ASSERT_EQ(napi_create_reference(s.env, alias, 1, &after.alias), napi_ok); napi_value buffer = nullptr; ASSERT_EQ(napi_create_external_buffer(s.env, 16, NewBytes(16), FreeOwned, &after.buffer_memory, &buffer), @@ -464,6 +478,7 @@ TEST_F(Test41InstanceData, ExternalBuffersAreDetachedBeforeTheirFinalizersAtRele EXPECT_EQ(after.info_data, nullptr); EXPECT_EQ(after.info_length, 0u); EXPECT_EQ(after.element, napi_undefined); + EXPECT_EQ(after.alias_element, napi_undefined); EXPECT_TRUE(after.buffer_detached); } diff --git a/v8/src/js_native_api_v8.cc b/v8/src/js_native_api_v8.cc index 7860fca558..18296dea67 100644 --- a/v8/src/js_native_api_v8.cc +++ b/v8/src/js_native_api_v8.cc @@ -457,11 +457,11 @@ bool GetArrayBufferViewInfo(v8::Local value, void** data, size_t* len return true; } -v8::Local CreateBufferObject(napi_env env, - std::shared_ptr backing_store, - size_t offset, - size_t length) { - v8::Local ab = v8::ArrayBuffer::New(env->isolate, backing_store); +// A Buffer viewing `ab`. +v8::Local CreateBufferView(napi_env env, + v8::Local ab, + size_t offset, + size_t length) { // Buffer is the env's: read it from the env's realm, never from the current // one, whose global its scripts control. v8::Local context = env->main_context(); @@ -497,6 +497,14 @@ v8::Local CreateBufferObject(napi_env env, return view; } +// A Buffer over a new ArrayBuffer holding `backing_store`. +v8::Local CreateBufferObject(napi_env env, + std::shared_ptr backing_store, + size_t offset, + size_t length) { + return CreateBufferView(env, v8::ArrayBuffer::New(env->isolate, backing_store), offset, length); +} + inline bool CheckValue(napi_env env, napi_value value) { return CheckEnv(env) && value != nullptr; } @@ -3550,10 +3558,10 @@ napi_status NAPI_CDECL node_api_create_buffer_from_arraybuffer( auto* record = env->allocate(env); if (record == nullptr) return napi_generic_failure; - record->backing_store = ab->GetBackingStore(); - v8::Local buffer_obj = - CreateBufferObject(env, record->backing_store, byte_offset, byte_length); + // As Node's Buffer::New(isolate, ab, ...), the Buffer views `ab` itself: + // detaching `ab` detaches it too, and `ab` alone holds the store. + v8::Local buffer_obj = CreateBufferView(env, ab, byte_offset, byte_length); record->holder.Reset(env->isolate, buffer_obj); record->holder.SetWeak(record, BufferWeakCallback, v8::WeakCallbackType::kParameter); v8::Local key = env->agent->buffer_private_key.Get(env->isolate); From b41bc611d84debceaa3b2cd95389fd24734c4afb Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 16:28:40 -0800 Subject: [PATCH 050/150] V8: finalize queued external buffers in their turn at release At release, FinalizeExternalBackingStoreHints ran every finalizer a deleter had queued (a buffer detached or collected before the release, whose drain had not run) before the finalizers of the buffers still alive, so an older buffer could be finalized before a newer one. It now runs them all most recent first by store id: on each step, the newest of the queued finalizers and the tracked buffers. A queued finalizer whose buffer is still tracked drops the entry before it runs, as before; nothing else changes. Found by the Codex review of this series. New test_41 ArrayBufferDetachedBeforeTheReleaseKeepsItsTurn (both engines): three external ArrayBuffers, the middle one detached before the release with no checkpoint. QuickJS finalizes it as it detaches; V8 queues it, and it must then run after the newest and before the oldest. Before this change V8 ran it first ("actual: 1 vs 2"). Co-Authored-By: Claude Opus 5.5 --- tests/runners/test_41_instance_data.cc | 37 ++++++++++++++++++++ v8/src/js_native_api_v8.cc | 48 +++++++++++++++----------- 2 files changed, 64 insertions(+), 21 deletions(-) diff --git a/tests/runners/test_41_instance_data.cc b/tests/runners/test_41_instance_data.cc index e02095e3b5..df85d47eaa 100644 --- a/tests/runners/test_41_instance_data.cc +++ b/tests/runners/test_41_instance_data.cc @@ -338,6 +338,43 @@ TEST_F(Test41InstanceData, ValuesAreFinalizedMostRecentFirstAtRelease) { } } +// An external array buffer detached before the release keeps its turn. The +// QuickJS provider finalizes it as it is detached; the V8 provider queues it +// for the env's thread, and the release then finalizes it after the buffers +// made after it and before those made before it. +TEST_F(Test41InstanceData, ArrayBufferDetachedBeforeTheReleaseKeepsItsTurn) { + constexpr int kValues = 3; + EnvScope s(runtime_.get()); + int clock = 0; + std::vector buffers(kValues, Seen{&clock}); + uint8_t bytes[kValues][8] = {}; + MarkEnvGlobal(s.env); + napi_value middle = nullptr; + for (int i = 0; i < kValues; ++i) { + napi_value value = nullptr; + ASSERT_EQ(napi_create_external_arraybuffer(s.env, bytes[i], sizeof(bytes[i]), FinalizeValue, + &buffers[i], &value), + napi_ok); + if (i == 1) { + middle = value; + } else { + Keep(s.env, ("arrayBuffer" + std::to_string(i)).c_str(), value); + } + } + ASSERT_EQ(napi_detach_arraybuffer(s.env, middle), napi_ok); + const int detached_at = clock; + + Release(s); + for (int i = 0; i < kValues; ++i) { + ExpectUsedNapi(buffers[i], ("value " + std::to_string(i)).c_str()); + } + EXPECT_LT(buffers[2].order, buffers[0].order); + if (buffers[1].order > detached_at) { + EXPECT_GT(buffers[1].order, buffers[2].order); + EXPECT_LT(buffers[1].order, buffers[0].order); + } +} + namespace { bool IsDetached(napi_env env, napi_ref ref) { diff --git a/v8/src/js_native_api_v8.cc b/v8/src/js_native_api_v8.cc index 18296dea67..0cc577e84c 100644 --- a/v8/src/js_native_api_v8.cc +++ b/v8/src/js_native_api_v8.cc @@ -23,6 +23,7 @@ #include #include #include +#include #include #include #include @@ -340,22 +341,12 @@ void ForgetExternalArrayBuffer(napi_env env, uint64_t id) { if (id != 0) env->external_array_buffers.erase(id); } -// Runs the external finalizers deleters queued. Env thread only. -bool RunQueuedExternalFinalizers(napi_env env) { - std::vector queued = TakeExternalFinalizers(env); - for (const auto& finalizer : queued) { - ForgetExternalArrayBuffer(env, finalizer.id); - env->CallFinalizer(finalizer.cb, finalizer.data, finalizer.hint); - } - return !queued.empty(); -} - // At the env's release: detaches the most recently made external array buffer // still tracked, as Node's CallbackInfo::Clean does, then runs its finalizer, // so code that runs later sees the buffer detached, never the freed memory. // The detach may free the store; its deleter then claims the finalizer and -// queues it, and RunQueuedExternalFinalizers runs it. Either way the -// finalizer is claimed once, under the lock. A buffer that +// queues it, and FinalizeExternalBackingStoreHints runs it next. Either way +// the finalizer is claimed once, under the lock. A buffer that // ArrayBuffer.prototype.transfer moved the store to is not reachable from // here (Node cannot reach it either); the one it moved it from is detached // already. @@ -395,19 +386,34 @@ void FinalizeNewestExternalArrayBuffer(napi_env env) { void FinalizeExternalBackingStoreHints(napi_env env) { if (!CheckEnv(env)) return; - // At the env's release. Runs the finalizers deleters queued, then, most - // recent first, detaches each external array buffer with a user finalizer - // and runs its finalizer. Then claims, under the lock, what the backing - // stores still alive hold (the free callbacks of provider-owned memory), and - // runs it outside the lock. A backing store can outlive the env, so each - // live hint is unlinked from the dying env rather than deleted here — its + // At the env's release. Runs the user finalizers of external stores most + // recent first, by store id: those deleters queued (their buffers were + // detached or collected) and those of the array buffers still tracked, each + // detached first. Then claims, under the lock, what the backing stores + // still alive hold (the free callbacks of provider-owned memory), and runs + // it outside the lock. A backing store can outlive the env, so each live + // hint is unlinked from the dying env rather than deleted here — its // deleter frees it later and, seeing a null env, skips the env-side // bookkeeping. The hints are not touched after the lock is dropped: a // concurrent deleter may already be freeing them. Repeats while finalizers // make more external buffers. + std::multimap queued; for (;;) { - const bool ran_queued = RunQueuedExternalFinalizers(env); - if (!env->external_array_buffers.empty()) { + for (const auto& finalizer : TakeExternalFinalizers(env)) { + queued.emplace(finalizer.id, finalizer); + } + const uint64_t newest_tracked = env->external_array_buffers.empty() + ? 0 + : env->external_array_buffers.rbegin()->first; + if (!queued.empty() && queued.rbegin()->first >= newest_tracked) { + auto newest = std::prev(queued.end()); + const napi_external_finalizer__ finalizer = newest->second; + queued.erase(newest); + ForgetExternalArrayBuffer(env, finalizer.id); + env->CallFinalizer(finalizer.cb, finalizer.data, finalizer.hint); + continue; + } + if (newest_tracked != 0) { FinalizeNewestExternalArrayBuffer(env); continue; } @@ -430,7 +436,7 @@ void FinalizeExternalBackingStoreHints(napi_env env) { } } } - if (pending.empty() && !ran_queued) return; + if (pending.empty()) return; for (const auto& finalizer : pending) { if (finalizer.free_cb != nullptr) { From 14bf075f639bd0f85239b467405dd5569c632037 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 16:28:40 -0800 Subject: [PATCH 051/150] QuickJS: finalize buffers detached while the release runs in its pass A cleanup hook or finalizer that detached an external ArrayBuffer at release (napi_detach_arraybuffer) ran the buffer's finalizer inside the detach, before QuickJS marked the buffer detached, and what that finalizer threw stayed pending in the hook until the hook returned. While the env's release pass runs, the realloc callback now only records that the buffer let go of the memory, and leaves the hint on the pending list; the pass finalizes it in its turn, with the buffer detached, and destroys it (finalize_at_teardown now destroys any released hint, detached there or before). Outside the release a detach still runs the finalizer at once, as before. A finalizer the collector runs inside another callback at release (an external or wrap freed by a GC an allocation triggers) now has its exception dropped when it returns, as one the pass runs does. invoke_finalizer reads the env before calling the finalizer, which may destroy the hint. Found by the Codex review of this series. New test_41 ArrayBufferAHookDetachesAtReleaseIsFinalizedDetached (both engines): a hook detaches an external ArrayBuffer at release; its finalizer runs once, sees the buffer detached and throws; the hook finds nothing pending after the detach, nor does the instance-data finalizer. Before this change QuickJS failed detached_in_finalizer (false) and pending_after_detach (true); V8 passed. Co-Authored-By: Claude Opus 5.5 --- quickjs/src/internal/napi_env.h | 4 +- .../napi_external_backing_store_hint.cc | 38 ++++++---- tests/runners/test_41_instance_data.cc | 70 +++++++++++++++++++ 3 files changed, 96 insertions(+), 16 deletions(-) diff --git a/quickjs/src/internal/napi_env.h b/quickjs/src/internal/napi_env.h index 0cab982932..b5dd0df2db 100644 --- a/quickjs/src/internal/napi_env.h +++ b/quickjs/src/internal/napi_env.h @@ -172,11 +172,13 @@ struct napi_env__ bool attach_embedder_hooks(const unofficial_napi_env_hooks &hooks); + // At release: drops the exception a hook or finalizer left pending. + void drop_finalizer_exception(); + private: void clear_refs_for_teardown(); void run_cleanup_hooks(); void finalize_pending_values(); - void drop_finalizer_exception(); void finalize_instance_data(); void call_instance_data_finalizer(void *data, napi_finalize finalize_cb, void *finalize_hint); diff --git a/quickjs/src/internal/napi_external_backing_store_hint.cc b/quickjs/src/internal/napi_external_backing_store_hint.cc index 9217fbf5ae..454cd313c2 100644 --- a/quickjs/src/internal/napi_external_backing_store_hint.cc +++ b/quickjs/src/internal/napi_external_backing_store_hint.cc @@ -81,10 +81,17 @@ void napi_external_backing_store_hint__::invoke_finalizer() // (the runtime frees what is still alive): no user code runs now. if (env_->finalizers_done()) return; + // The finalizer may destroy this hint (deleting the reference napi_wrap + // returned does). + napi_env env = env_; // Finalizers run in the env's own realm, also when the collector runs // inside another realm. - napi_realm_frame_scope__ realm_frame{env_, nullptr, JS_UNDEFINED}; - finalize_cb_(env_, external_data_, finalize_hint_); + napi_realm_frame_scope__ realm_frame{env, nullptr, JS_UNDEFINED}; + finalize_cb_(env, external_data_, finalize_hint_); + // At release nothing can catch what it threw, also when the collector ran + // it inside another callback. + if (env->is_closing()) + env->drop_finalizer_exception(); } void napi_external_backing_store_hint__::release_array_buffer(JSRuntime *rt) @@ -96,8 +103,11 @@ void napi_external_backing_store_hint__::release_array_buffer(JSRuntime *rt) return; released_ = true; // Teardown runs the finalizer itself, once the buffer is marked detached, - // and destroys the hint. - if (detaching_) + // and destroys the hint: when it is detaching the buffer, and when other + // code detaches or frees it while the release runs, so the finalizer still + // runs after the detach completes and as the release orders it. + if (detaching_ || (pending_link_.linked() && env_ != nullptr && env_->is_closing() && + !env_->finalizers_done())) return; invoke_finalizer(); destroy_with_runtime(rt, this); @@ -136,6 +146,8 @@ napi_external_backing_store_hint__ *napi_external_backing_store_hint__::first_pe void napi_external_backing_store_hint__::finalize_at_teardown() { + JSContext *ctx = env_->main_context(); + JSValue array_buffer = JS_UNDEFINED; if (JS_GetNativeWeakRefFromLink(&array_buffer_link_) != nullptr) { // As Node's CallbackInfo::Clean does, detach the buffer before the @@ -144,22 +156,18 @@ void napi_external_backing_store_hint__::finalize_at_teardown() // of the memory, unless ArrayBuffer.prototype.transfer already moved it to // a buffer this hint cannot reach (Node cannot either). The reference // keeps the buffer alive in case the finalizer drops the last other one. - JSContext *ctx = env_->main_context(); - JSValue array_buffer = JS_DupValue(ctx, array_buffer_); + array_buffer = JS_DupValue(ctx, array_buffer_); detaching_ = true; JS_DetachArrayBuffer(ctx, array_buffer); detaching_ = false; - if (released_) - { - // The buffer no longer refers to the hint. - invoke_finalizer(); - JS_FreeValue(ctx, array_buffer); - destroy(this); - return; - } - JS_FreeValue(ctx, array_buffer); } + // Released, by the detach above or earlier in the release: no buffer refers + // to the hint any more. + const bool released = released_; invoke_finalizer(); + JS_FreeValue(ctx, array_buffer); + if (released) + destroy(this); } void napi_external_backing_store_hint__::abandon_finalizer() diff --git a/tests/runners/test_41_instance_data.cc b/tests/runners/test_41_instance_data.cc index df85d47eaa..fc3b2dfbc4 100644 --- a/tests/runners/test_41_instance_data.cc +++ b/tests/runners/test_41_instance_data.cc @@ -519,6 +519,76 @@ TEST_F(Test41InstanceData, ExternalBuffersAreDetachedBeforeTheirFinalizersAtRele EXPECT_TRUE(after.buffer_detached); } +namespace { + +// An external array buffer a cleanup hook detaches at release. Its finalizer +// records whether the buffer was detached when it ran, then throws. +struct DetachedByAHook { + napi_env env = nullptr; + uint8_t bytes[8] = {}; + napi_ref buffer = nullptr; + int finalized = 0; + bool detached_in_finalizer = false; + napi_status detach_status = napi_generic_failure; + bool pending_after_detach = true; + bool pending_in_instance_data = true; +}; + +void FinalizeCheckingItsBuffer(node_api_basic_env basic_env, void*, void* hint) { + auto env = const_cast(basic_env); + auto* detached = static_cast(hint); + ++detached->finalized; + napi_handle_scope scope = nullptr; + if (napi_open_handle_scope(env, &scope) == napi_ok) { + detached->detached_in_finalizer = IsDetached(env, detached->buffer); + napi_close_handle_scope(env, scope); + } + napi_throw_error(env, nullptr, "finalizer"); +} + +void DetachingHook(void* arg) { + auto* detached = static_cast(arg); + napi_handle_scope scope = nullptr; + if (napi_open_handle_scope(detached->env, &scope) != napi_ok) return; + napi_value buffer = nullptr; + if (napi_get_reference_value(detached->env, detached->buffer, &buffer) == napi_ok) { + detached->detach_status = napi_detach_arraybuffer(detached->env, buffer); + napi_is_exception_pending(detached->env, &detached->pending_after_detach); + } + napi_close_handle_scope(detached->env, scope); +} + +void FinalizeInstanceDataAfterTheBuffer(napi_env env, void* data, void*) { + auto* detached = static_cast(data); + napi_is_exception_pending(env, &detached->pending_in_instance_data); +} + +} // namespace + +// A buffer a cleanup hook detaches at release is finalized as the release +// finalizes the others: after it is detached, and with what it throws dropped +// before anything else runs. +TEST_F(Test41InstanceData, ArrayBufferAHookDetachesAtReleaseIsFinalizedDetached) { + EnvScope s(runtime_.get()); + DetachedByAHook detached; + detached.env = s.env; + napi_value buffer = nullptr; + ASSERT_EQ(napi_create_external_arraybuffer(s.env, detached.bytes, sizeof(detached.bytes), + FinalizeCheckingItsBuffer, &detached, &buffer), + napi_ok); + ASSERT_EQ(napi_create_reference(s.env, buffer, 1, &detached.buffer), napi_ok); + ASSERT_EQ(napi_add_env_cleanup_hook(s.env, DetachingHook, &detached), napi_ok); + ASSERT_EQ(napi_set_instance_data(s.env, &detached, FinalizeInstanceDataAfterTheBuffer, nullptr), + napi_ok); + + Release(s); + EXPECT_EQ(detached.detach_status, napi_ok); + EXPECT_EQ(detached.finalized, 1); + EXPECT_TRUE(detached.detached_in_finalizer); + EXPECT_FALSE(detached.pending_after_detach); + EXPECT_FALSE(detached.pending_in_instance_data); +} + // ArrayBuffer.prototype.transfer moves an external buffer's memory to a new // buffer. Its finalizer still runs once at release, whether the buffer it was // made as is alive then or not. From 10fb03bd94c03d6b7241d120217ca9ae5980c042 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 16:18:59 -0800 Subject: [PATCH 052/150] Document the release contract on unofficial_napi_release_env Both providers now release an env in the same order: cleanup hooks, then the pending values' finalizers (each external buffer detached first), until neither is left; then the instance-data finalizer; and again until nothing is pending. Exceptions are dropped after each, everything runs on the env's thread in the env's realm, plain references stay valid until the end, and nothing is finalized after the pass. The comment states this as the providers' contract and notes where Node differs (Node 25 interleaves the instance-data finalizer with the others) and what neither can do (detach a buffer that ArrayBuffer.prototype.transfer moved the memory to). Co-Authored-By: Claude Opus 5.5 --- include/unofficial_napi.h | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/include/unofficial_napi.h b/include/unofficial_napi.h index 5925817fc6..a06493f145 100644 --- a/include/unofficial_napi.h +++ b/include/unofficial_napi.h @@ -141,6 +141,39 @@ NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_attach_env( napi_env env, const unofficial_napi_env_hooks* hooks, uint64_t* accepted_hooks_out); +// Releases an env made by unofficial_napi_create_env and the engine instance +// it owns. Before anything is freed, the release runs what the env still +// holds, in this order (the providers' contract; Node up to 20 also finalized +// the instance data after everything else, Node 25 interleaves it with the +// other finalizers): +// +// 1. The cleanup hooks run, most recent first. A hook added while releasing, +// by a hook or by a finalizer, runs too. +// 2. The finalizer of every value still pending runs: napi_wrap, +// napi_create_external, napi_add_finalizer, external ArrayBuffers and +// Buffers. Values of one kind are finalized most recent first, as Node's +// FinalizeAll does; the order between kinds is not specified. An external +// ArrayBuffer or Buffer is detached before its finalizer runs, as Node's +// CallbackInfo::Clean does, so the finalizer and the code that runs after +// it see it detached (byte length 0), never the freed memory. A buffer +// that ArrayBuffer.prototype.transfer moved the memory to is not detached: +// neither provider, nor Node, can reach it. 1 and 2 repeat until neither +// has anything left. +// 3. The instance-data finalizer runs, after all of those. +// 4. 1 to 3 repeat for whatever the instance-data finalizer leaves pending +// (values it made and kept, hooks it added, instance data it set), until +// nothing is pending, as Node's FinalizeAll finalizes until its lists are +// empty. An addon that makes a new value in every finalizer never +// finishes, as in Node. +// +// After each hook and finalizer, an exception it left pending is dropped: +// nothing can catch it then (Node's CallIntoModule drops it too once JS can +// no longer run). Each runs on the env's thread, in the env's realm (also when +// another realm was entered when the release began), with N-API usable. +// References made with napi_create_reference keep their values until all of +// them have run. A finalizer the engine would call after this pass, while it +// frees the engine instance, is dropped, and nothing touches the env once it +// is freed. NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_release_env( unofficial_napi_env_owner owner, struct uv_loop_s* loop_or_null); From 83c5e19868337a388088c0da82b2a32f92102afc Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 17:30:47 -0800 Subject: [PATCH 053/150] QuickJS: free a dropped pending exception after taking it clear_pending_exception freed the pending exception with JS_FreeValueRT before it reset has_pending_exception_ and pending_exception_. Freeing it can free an object with a finalizer, which QuickJS runs at once. At release that finalizer's invoke_finalizer drops the pending exception again, found the old value still pending and freed it a second time (ASan: SEGV in list_del from js_free_value_rt, under clear_pending_exception, under invoke_finalizer, under clear_pending_exception). A hook or a value's finalizer that throws an object it wrapped triggered it. clear_pending_exception now takes the value before freeing it, and set_pending_exception frees the old value only after the new one is in place. Tests: a hook and an external's finalizer that throw a wrapped object at release; each wrap is finalized once. Co-Authored-By: Claude Opus 5.5 --- quickjs/src/internal/napi_agent.cc | 12 +++-- tests/runners/test_41_instance_data.cc | 70 ++++++++++++++++++++++++++ 2 files changed, 78 insertions(+), 4 deletions(-) diff --git a/quickjs/src/internal/napi_agent.cc b/quickjs/src/internal/napi_agent.cc index bc9efc7ac1..58cc3e0d4e 100644 --- a/quickjs/src/internal/napi_agent.cc +++ b/quickjs/src/internal/napi_agent.cc @@ -144,9 +144,13 @@ bool napi_agent__::pending_exception_is_uncatchable() const void napi_agent__::set_pending_exception(JSValue exception) { - clear_pending_exception(); + // Freeing the old exception can free an object with a finalizer, which + // runs now and may itself read, clear or set the pending exception: the new + // one is in place first. + JSValue old_exception = take_pending_exception(); pending_exception_ = exception; has_pending_exception_ = true; + JS_FreeValueRT(runtime_, old_exception); } JSValue napi_agent__::take_pending_exception() @@ -165,9 +169,9 @@ void napi_agent__::clear_pending_exception() if (!has_pending_exception_) return; - JS_FreeValueRT(runtime_, pending_exception_); - pending_exception_ = JS_UNDEFINED; - has_pending_exception_ = false; + // Taken before it is freed: freeing it can free an object with a + // finalizer, which runs now and may itself clear the pending exception. + JS_FreeValueRT(runtime_, take_pending_exception()); } int64_t napi_agent__::adjust_external_memory(int64_t change_in_bytes) diff --git a/tests/runners/test_41_instance_data.cc b/tests/runners/test_41_instance_data.cc index fc3b2dfbc4..70273d6cfa 100644 --- a/tests/runners/test_41_instance_data.cc +++ b/tests/runners/test_41_instance_data.cc @@ -891,3 +891,73 @@ TEST_F(Test41InstanceData, ReleaseFinalizesValuesThatFreeOthersInLinearTime) { EXPECT_LT(freeing_ms, 20 * keeping_ms + 50) << "keeping " << keeping_ms << " ms, freeing " << freeing_ms << " ms"; } + +namespace { + +// An object a hook or a finalizer wraps and throws at release. Dropping the +// exception frees the object, and the release finalizes its wrap. +struct ThrownWrap { + napi_env env = nullptr; + napi_status throw_status = napi_generic_failure; + int wrap_finalized = 0; +}; + +void FinalizeThrownWrap(node_api_basic_env, void*, void* hint) { + ++static_cast(hint)->wrap_finalized; +} + +void ThrowAWrappedObject(ThrownWrap* thrown) { + napi_env env = thrown->env; + napi_handle_scope scope = nullptr; + ASSERT_EQ(napi_open_handle_scope(env, &scope), napi_ok); + napi_value object = nullptr; + ASSERT_EQ(napi_create_object(env, &object), napi_ok); + ASSERT_EQ(napi_wrap(env, object, nullptr, FinalizeThrownWrap, thrown, nullptr), napi_ok); + thrown->throw_status = napi_throw(env, object); + ASSERT_EQ(napi_close_handle_scope(env, scope), napi_ok); +} + +void HookThrowingAWrappedObject(void* arg) { + ThrowAWrappedObject(static_cast(arg)); +} + +void FinalizeThrowingAWrappedObject(node_api_basic_env, void*, void* hint) { + ThrowAWrappedObject(static_cast(hint)); +} + +void ExpectThrownAndFinalizedOnce(const ThrownWrap& thrown) { + // napi_throw returns napi_ok in Node, napi_pending_exception in QuickJS. + EXPECT_TRUE(thrown.throw_status == napi_ok || thrown.throw_status == napi_pending_exception) + << thrown.throw_status; + EXPECT_EQ(thrown.wrap_finalized, 1); +} + +} // namespace + +// Dropping what a hook threw at release can free the last reference to an +// object with a finalizer, and so run that finalizer while the exception is +// being dropped. The exception is dropped, and freed, once. +TEST_F(Test41InstanceData, AnObjectAHookThrowsIsDroppedOnceAtRelease) { + EnvScope s(runtime_.get()); + ThrownWrap thrown; + thrown.env = s.env; + ASSERT_EQ(napi_add_env_cleanup_hook(s.env, HookThrowingAWrappedObject, &thrown), napi_ok); + + Release(s); + ExpectThrownAndFinalizedOnce(thrown); +} + +// The same for what a value's finalizer throws at release. +TEST_F(Test41InstanceData, AnObjectAFinalizerThrowsIsDroppedOnceAtRelease) { + EnvScope s(runtime_.get()); + ThrownWrap thrown; + thrown.env = s.env; + napi_value external = nullptr; + ASSERT_EQ(napi_create_external(s.env, nullptr, FinalizeThrowingAWrappedObject, &thrown, + &external), + napi_ok); + Keep(s.env, "external", external); + + Release(s); + ExpectThrownAndFinalizedOnce(thrown); +} From 2e0a067c24fe3c3e5cd6793a9b7d47437c6d499e Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 17:30:56 -0800 Subject: [PATCH 054/150] QuickJS: keep the in-flight exception when a finalizer runs at release "QuickJS: finalize buffers detached while the release runs in its pass" made invoke_finalizer drop every pending exception after each finalizer it ran while the env was closing. QuickJS runs a value's finalizer as soon as the value is freed, also in the middle of other code: while JS unwinds a throw (a frame local held the last reference), or while a hook that has thrown closes a scope. The drop then took the exception that code was still propagating, not the finalizer's. A script's catch got the engine's uninitialized sentinel instead of the Error, an uncaught throw left that sentinel pending, and a hook lost its own pending exception. At release invoke_finalizer now takes both pending exceptions (the engine's, and the provider's last exception) before the finalizer runs, drops what the finalizer threw, and gives them back. The finalizer still runs with nothing pending, and what it throws is still dropped. Outside release nothing changes. Tests: a hook runs scripts that throw while freeing the last reference to an external whose finalizer throws; the catch still gets the Error, and an uncaught Error is still pending after napi_run_script. A hook that throws and then closes a scope holding an external still has its exception pending. Co-Authored-By: Claude Opus 5.5 --- quickjs/src/internal/napi_env.cc | 19 +++ quickjs/src/internal/napi_env.h | 11 ++ .../napi_external_backing_store_hint.cc | 25 ++- tests/runners/test_41_instance_data.cc | 158 ++++++++++++++++++ 4 files changed, 205 insertions(+), 8 deletions(-) diff --git a/quickjs/src/internal/napi_env.cc b/quickjs/src/internal/napi_env.cc index 3baa3e2ed7..9c174b714c 100644 --- a/quickjs/src/internal/napi_env.cc +++ b/quickjs/src/internal/napi_env.cc @@ -250,6 +250,25 @@ void napi_env__::drop_finalizer_exception() JS_FreeValue(context_, JS_GetException(context_)); } +napi_env__::pending_exceptions napi_env__::take_pending_exceptions() +{ + pending_exceptions taken; + if (context_ != nullptr) + taken.thrown = JS_GetException(context_); + if (has_last_exception()) + taken.last = take_last_exception(); + return taken; +} + +void napi_env__::restore_pending_exceptions(pending_exceptions taken) +{ + drop_finalizer_exception(); + if (!JS_IsUninitialized(taken.last)) + set_last_exception(taken.last); + if (!JS_IsUninitialized(taken.thrown)) + JS_Throw(context_, taken.thrown); +} + void napi_env__::finalize_instance_data() { void *data = instance_data_; diff --git a/quickjs/src/internal/napi_env.h b/quickjs/src/internal/napi_env.h index b5dd0df2db..9da36db4ff 100644 --- a/quickjs/src/internal/napi_env.h +++ b/quickjs/src/internal/napi_env.h @@ -174,6 +174,17 @@ struct napi_env__ // At release: drops the exception a hook or finalizer left pending. void drop_finalizer_exception(); + // The exceptions pending when the collector runs a finalizer in the middle + // of other code: the one JS is throwing, and the provider's. + struct pending_exceptions + { + JSValue thrown = JS_UNINITIALIZED; + JSValue last = JS_UNINITIALIZED; + }; + // At release, around such a finalizer: takes them, so the finalizer runs + // with none pending, then drops what it threw and gives them back. + pending_exceptions take_pending_exceptions(); + void restore_pending_exceptions(pending_exceptions taken); private: void clear_refs_for_teardown(); diff --git a/quickjs/src/internal/napi_external_backing_store_hint.cc b/quickjs/src/internal/napi_external_backing_store_hint.cc index 454cd313c2..981c78d4ab 100644 --- a/quickjs/src/internal/napi_external_backing_store_hint.cc +++ b/quickjs/src/internal/napi_external_backing_store_hint.cc @@ -84,14 +84,23 @@ void napi_external_backing_store_hint__::invoke_finalizer() // The finalizer may destroy this hint (deleting the reference napi_wrap // returned does). napi_env env = env_; - // Finalizers run in the env's own realm, also when the collector runs - // inside another realm. - napi_realm_frame_scope__ realm_frame{env, nullptr, JS_UNDEFINED}; - finalize_cb_(env, external_data_, finalize_hint_); - // At release nothing can catch what it threw, also when the collector ran - // it inside another callback. - if (env->is_closing()) - env->drop_finalizer_exception(); + if (!env->is_closing()) + { + // Finalizers run in the env's own realm, also when the collector runs + // inside another realm. + napi_realm_frame_scope__ realm_frame{env, nullptr, JS_UNDEFINED}; + finalize_cb_(env, external_data_, finalize_hint_); + return; + } + // At release nothing can catch what the finalizer throws, so it is + // dropped. The collector may run it in the middle of other code, while JS + // is throwing or a hook has an exception pending: that one is kept. + napi_env__::pending_exceptions outer = env->take_pending_exceptions(); + { + napi_realm_frame_scope__ realm_frame{env, nullptr, JS_UNDEFINED}; + finalize_cb_(env, external_data_, finalize_hint_); + } + env->restore_pending_exceptions(outer); } void napi_external_backing_store_hint__::release_array_buffer(JSRuntime *rt) diff --git a/tests/runners/test_41_instance_data.cc b/tests/runners/test_41_instance_data.cc index 70273d6cfa..c56e5e7343 100644 --- a/tests/runners/test_41_instance_data.cc +++ b/tests/runners/test_41_instance_data.cc @@ -961,3 +961,161 @@ TEST_F(Test41InstanceData, AnObjectAFinalizerThrowsIsDroppedOnceAtRelease) { Release(s); ExpectThrownAndFinalizedOnce(thrown); } + +namespace { + +// Counts into `hint`, then throws: what it throws at release is dropped. +void FinalizeCountingThenThrowing(node_api_basic_env basic_env, void*, void* hint) { + ++*static_cast(hint); + napi_throw_error(const_cast(basic_env), nullptr, "finalizer"); +} + +// Makes an external finalized by FinalizeCountingThenThrowing, kept only by +// the global's `name`. +void KeepThrowingExternal(napi_env env, const char* name, int* finalized) { + napi_handle_scope scope = nullptr; + ASSERT_EQ(napi_open_handle_scope(env, &scope), napi_ok); + napi_value external = nullptr; + ASSERT_EQ(napi_create_external(env, nullptr, FinalizeCountingThenThrowing, finalized, &external), + napi_ok); + Keep(env, name, external); + ASSERT_EQ(napi_close_handle_scope(env, scope), napi_ok); +} + +std::string StringOf(napi_env env, napi_value value) { + char text[64] = {}; + size_t length = 0; + if (value == nullptr || + napi_get_value_string_utf8(env, value, text, sizeof(text), &length) != napi_ok) { + return ""; + } + return std::string(text, length); +} + +// The message of the exception pending on `env`, which it clears. +std::string TakeExceptionMessage(napi_env env) { + napi_value error = nullptr; + if (napi_get_and_clear_last_exception(env, &error) != napi_ok || error == nullptr) { + return ""; + } + napi_valuetype type = napi_undefined; + if (napi_typeof(env, error, &type) != napi_ok || type != napi_object) return ""; + napi_value message = nullptr; + if (napi_get_named_property(env, error, "message", &message) != napi_ok) return ""; + return StringOf(env, message); +} + +// Scripts that throw while they drop the last reference to an external, so +// an engine that frees values as soon as nothing refers to them finalizes it +// while the exception is still being thrown. +const char kCatchWhileFreeing[] = + "(function () {" + " try {" + " (function () {" + " let held = globalThis.caughtExternal;" + " globalThis.caughtExternal = undefined;" + " throw new Error('caught');" + " })();" + " } catch (error) {" + " return error instanceof Error ? error.message : 'not an Error: ' + typeof error;" + " }" + " return 'not thrown';" + "})()"; +const char kThrowWhileFreeing[] = + "(function () {" + " let held = globalThis.uncaughtExternal;" + " globalThis.uncaughtExternal = undefined;" + " throw new Error('uncaught');" + "})()"; + +// What a cleanup hook saw of the exceptions its scripts threw. +struct InFlight { + napi_env env = nullptr; + int finalized = 0; + napi_status caught_status = napi_generic_failure; + std::string caught; + napi_status uncaught_status = napi_generic_failure; + bool uncaught_pending = false; + std::string uncaught; +}; + +void HookThrowingWhileFreeing(void* arg) { + auto* in_flight = static_cast(arg); + napi_env env = in_flight->env; + napi_handle_scope scope = nullptr; + ASSERT_EQ(napi_open_handle_scope(env, &scope), napi_ok); + napi_value source = nullptr; + napi_value result = nullptr; + ASSERT_EQ(napi_create_string_utf8(env, kCatchWhileFreeing, NAPI_AUTO_LENGTH, &source), napi_ok); + in_flight->caught_status = napi_run_script(env, source, &result); + if (in_flight->caught_status == napi_ok) in_flight->caught = StringOf(env, result); + ASSERT_EQ(napi_create_string_utf8(env, kThrowWhileFreeing, NAPI_AUTO_LENGTH, &source), napi_ok); + in_flight->uncaught_status = napi_run_script(env, source, &result); + ASSERT_EQ(napi_is_exception_pending(env, &in_flight->uncaught_pending), napi_ok); + if (in_flight->uncaught_pending) in_flight->uncaught = TakeExceptionMessage(env); + ASSERT_EQ(napi_close_handle_scope(env, scope), napi_ok); +} + +// A hook that throws, then closes a scope holding the only reference to an +// external. +struct PendingInAHook { + napi_env env = nullptr; + int finalized = 0; + bool pending_before = false; + bool pending_after = false; + std::string message; +}; + +void HookThrowingThenFreeing(void* arg) { + auto* hook = static_cast(arg); + napi_env env = hook->env; + napi_handle_scope scope = nullptr; + ASSERT_EQ(napi_open_handle_scope(env, &scope), napi_ok); + napi_value external = nullptr; + ASSERT_EQ(napi_create_external(env, nullptr, FinalizeCountingThenThrowing, &hook->finalized, + &external), + napi_ok); + napi_throw_error(env, nullptr, "hook"); + ASSERT_EQ(napi_is_exception_pending(env, &hook->pending_before), napi_ok); + ASSERT_EQ(napi_close_handle_scope(env, scope), napi_ok); + ASSERT_EQ(napi_is_exception_pending(env, &hook->pending_after), napi_ok); + if (hook->pending_after) hook->message = TakeExceptionMessage(env); +} + +} // namespace + +// An engine may run a finalizer while JS is throwing, when the throw frees +// the last reference to a value. At release, what that finalizer throws is +// dropped, but the exception JS is throwing is not: JS still catches it, and +// one nothing catches is still pending when napi_run_script returns. +TEST_F(Test41InstanceData, AnExceptionJsIsThrowingSurvivesAFinalizerAtRelease) { + EnvScope s(runtime_.get()); + InFlight in_flight; + in_flight.env = s.env; + KeepThrowingExternal(s.env, "caughtExternal", &in_flight.finalized); + KeepThrowingExternal(s.env, "uncaughtExternal", &in_flight.finalized); + ASSERT_EQ(napi_add_env_cleanup_hook(s.env, HookThrowingWhileFreeing, &in_flight), napi_ok); + + Release(s); + EXPECT_EQ(in_flight.caught_status, napi_ok); + EXPECT_EQ(in_flight.caught, "caught"); + EXPECT_EQ(in_flight.uncaught_status, napi_pending_exception); + EXPECT_TRUE(in_flight.uncaught_pending); + EXPECT_EQ(in_flight.uncaught, "uncaught"); + EXPECT_EQ(in_flight.finalized, 2); +} + +// The same for an exception a hook has pending when a finalizer runs inside +// it: the hook still finds its own exception pending afterwards. +TEST_F(Test41InstanceData, AHookExceptionSurvivesAFinalizerRunInsideIt) { + EnvScope s(runtime_.get()); + PendingInAHook hook; + hook.env = s.env; + ASSERT_EQ(napi_add_env_cleanup_hook(s.env, HookThrowingThenFreeing, &hook), napi_ok); + + Release(s); + EXPECT_TRUE(hook.pending_before); + EXPECT_TRUE(hook.pending_after); + EXPECT_EQ(hook.message, "hook"); + EXPECT_EQ(hook.finalized, 1); +} From 95204fcecff7baaa811a4960c117e8b4f0613c97 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 17:33:43 -0800 Subject: [PATCH 055/150] Drop a wrap from its object when the release finalizes it The release finalizes wraps whose objects can still be reached: through the global, and, since "V8: run the release in rounds and drop exceptions thrown at release" keeps plain references until the end, through a napi_ref kept in instance data. Code that runs later in the release could then unwrap such an object. On V8 the object kept its private External pointing at the wrap's reference. A reference owned by the provider (napi_wrap without a result) is destroyed after its finalizer, so napi_unwrap read a freed pool slot. Once a new wrap reused the slot, napi_unwrap returned the new wrap's native pointer and napi_remove_wrap destroyed the new wrap's reference, whose finalizer then never ran. A wrap finalizer that removed its own object's wrap destroyed the reference that FinalizeAll destroyed again after it (SEGV in napi_allocator__::destroy under FinalizeAll; this crash predates the series). napi_ref__::Finalize now deletes the wrap's private from the object first, if it still points at this reference. napi_wrap marks its references for this. In the GC path the object is gone and nothing changes. On QuickJS the wrap record survived its finalizer, so napi_unwrap returned the native pointer the finalizer had been handed. napi_unwrap and napi_remove_wrap now treat a wrap whose finalizer has run, or is running, as absent. napi_remove_wrap on an object with no wrap now returns napi_invalid_arg, as Node and the V8 provider do, instead of napi_generic_failure. On both engines napi_unwrap and napi_remove_wrap now return napi_invalid_arg for an object whose wrap the release has finalized, also from that wrap's own finalizer. Tests: the instance-data finalizer unwraps a finalized wrap's object through a reference and the global, after making a new wrap, then removes it; the new wrap is still finalized. Wrap finalizers (one owned by the provider, one with a napi_wrap result) remove their own object's wrap at release. Co-Authored-By: Claude Opus 5.5 --- .../napi_external_backing_store_hint.cc | 5 + .../napi_external_backing_store_hint.h | 2 + quickjs/src/js_native_api_quickjs.cc | 10 +- tests/runners/test_41_instance_data.cc | 121 ++++++++++++++++++ v8/src/internal/napi_ref.cc | 23 ++++ v8/src/internal/napi_ref.h | 4 + v8/src/js_native_api_v8.cc | 1 + 7 files changed, 163 insertions(+), 3 deletions(-) diff --git a/quickjs/src/internal/napi_external_backing_store_hint.cc b/quickjs/src/internal/napi_external_backing_store_hint.cc index 981c78d4ab..b1c9816d54 100644 --- a/quickjs/src/internal/napi_external_backing_store_hint.cc +++ b/quickjs/src/internal/napi_external_backing_store_hint.cc @@ -215,6 +215,11 @@ void *napi_external_backing_store_hint__::external_data() const return external_data_; } +bool napi_external_backing_store_hint__::finalize_invoked() const +{ + return finalize_invoked_; +} + JSValue napi_external_backing_store_hint__::weak_target() const { return weak_target_; diff --git a/quickjs/src/internal/napi_external_backing_store_hint.h b/quickjs/src/internal/napi_external_backing_store_hint.h index f412425104..ac60967a25 100644 --- a/quickjs/src/internal/napi_external_backing_store_hint.h +++ b/quickjs/src/internal/napi_external_backing_store_hint.h @@ -49,6 +49,8 @@ struct napi_external_backing_store_hint__ napi_env env() const; JSRuntime *runtime() const; void *external_data() const; + // The finalizer has run, or is running. + bool finalize_invoked() const; JSValue weak_target() const; JSValue finalizer_target(JSValue fallback) const; void set_weak_target(JSValue weak_target); diff --git a/quickjs/src/js_native_api_quickjs.cc b/quickjs/src/js_native_api_quickjs.cc index a19aee461c..278c5798fc 100644 --- a/quickjs/src/js_native_api_quickjs.cc +++ b/quickjs/src/js_native_api_quickjs.cc @@ -2992,7 +2992,9 @@ extern "C" auto obj = napi_quickjs_value_inner(env, js_object); auto *wrap = napi_external__::get_wrap_record(env->context(), obj); - if (wrap == nullptr) + // A wrap the env's release has finalized is gone: its finalizer may have + // freed the native object. + if (wrap == nullptr || wrap->finalize_invoked()) return napi_invalid_arg; *result = wrap->external_data(); @@ -3009,8 +3011,10 @@ extern "C" return napi_object_expected; auto *wrap = napi_external__::get_wrap_record(env->context(), obj); - if (wrap == nullptr) - return napi_generic_failure; + // As Node, an object with no wrap is an invalid argument; so is one whose + // wrap the env's release has finalized, as in napi_unwrap. + if (wrap == nullptr || wrap->finalize_invoked()) + return napi_util__::invalid_arg(env); *result = wrap->external_data(); diff --git a/tests/runners/test_41_instance_data.cc b/tests/runners/test_41_instance_data.cc index c56e5e7343..90908182a8 100644 --- a/tests/runners/test_41_instance_data.cc +++ b/tests/runners/test_41_instance_data.cc @@ -1119,3 +1119,124 @@ TEST_F(Test41InstanceData, AHookExceptionSurvivesAFinalizerRunInsideIt) { EXPECT_EQ(hook.message, "hook"); EXPECT_EQ(hook.finalized, 1); } + +namespace { + +// A wrap the release finalizes while its object is still reachable, through +// the global and through a reference, and what the instance-data finalizer +// then finds on the object. +struct FinalizedWrap { + napi_ref object = nullptr; + int native = 1; + int fresh_native = 2; + int finalized = 0; + int fresh_finalized = 0; + napi_status unwrap_by_reference = napi_generic_failure; + napi_status unwrap_by_global = napi_generic_failure; + napi_status remove = napi_generic_failure; +}; + +void FinalizeTheWrap(node_api_basic_env, void* data, void* hint) { + auto* wrap = static_cast(hint); + EXPECT_EQ(data, &wrap->native); + ++wrap->finalized; +} + +void FinalizeTheFreshWrap(node_api_basic_env, void* data, void* hint) { + auto* wrap = static_cast(hint); + EXPECT_EQ(data, &wrap->fresh_native); + ++wrap->fresh_finalized; +} + +void FinalizeInstanceDataUnwrapping(napi_env env, void* data, void*) { + auto* wrap = static_cast(data); + napi_handle_scope scope = nullptr; + ASSERT_EQ(napi_open_handle_scope(env, &scope), napi_ok); + // A wrap made now may take what the finalized one let go of. + napi_value fresh = nullptr; + ASSERT_EQ(napi_create_object(env, &fresh), napi_ok); + ASSERT_EQ(napi_wrap(env, fresh, &wrap->fresh_native, FinalizeTheFreshWrap, wrap, nullptr), + napi_ok); + Keep(env, "fresh", fresh); + napi_value object = nullptr; + ASSERT_EQ(napi_get_reference_value(env, wrap->object, &object), napi_ok); + ASSERT_NE(object, nullptr); + void* native = nullptr; + wrap->unwrap_by_reference = napi_unwrap(env, object, &native); + napi_value global = nullptr; + ASSERT_EQ(napi_get_global(env, &global), napi_ok); + napi_value by_global = nullptr; + ASSERT_EQ(napi_get_named_property(env, global, "wrapped", &by_global), napi_ok); + wrap->unwrap_by_global = napi_unwrap(env, by_global, &native); + wrap->remove = napi_remove_wrap(env, object, &native); + ASSERT_EQ(napi_close_handle_scope(env, scope), napi_ok); +} + +// Wraps whose finalizers remove the wrap of their own object at release. +struct RemovingItsWrap { + napi_ref object = nullptr; + napi_ref wrap = nullptr; + int finalized = 0; + napi_status remove = napi_generic_failure; +}; + +void FinalizeRemovingItsWrap(node_api_basic_env basic_env, void*, void* hint) { + auto env = const_cast(basic_env); + auto* self = static_cast(hint); + ++self->finalized; + napi_handle_scope scope = nullptr; + ASSERT_EQ(napi_open_handle_scope(env, &scope), napi_ok); + napi_value object = nullptr; + ASSERT_EQ(napi_get_reference_value(env, self->object, &object), napi_ok); + ASSERT_NE(object, nullptr); + void* native = nullptr; + self->remove = napi_remove_wrap(env, object, &native); + ASSERT_EQ(napi_close_handle_scope(env, scope), napi_ok); +} + +} // namespace + +// Once the release has finalized a wrap, its object no longer has it, also +// while the object is still reachable: napi_unwrap and napi_remove_wrap fail +// as for an object never wrapped, rather than reach what the finalizer let go +// of, or a wrap made later. +TEST_F(Test41InstanceData, AWrapFinalizedAtReleaseIsGoneFromItsObject) { + EnvScope s(runtime_.get()); + FinalizedWrap wrap; + napi_value object = nullptr; + ASSERT_EQ(napi_create_object(s.env, &object), napi_ok); + ASSERT_EQ(napi_wrap(s.env, object, &wrap.native, FinalizeTheWrap, &wrap, nullptr), napi_ok); + Keep(s.env, "wrapped", object); + ASSERT_EQ(napi_create_reference(s.env, object, 1, &wrap.object), napi_ok); + ASSERT_EQ(napi_set_instance_data(s.env, &wrap, FinalizeInstanceDataUnwrapping, nullptr), + napi_ok); + + Release(s); + EXPECT_EQ(wrap.finalized, 1); + EXPECT_EQ(wrap.unwrap_by_reference, napi_invalid_arg); + EXPECT_EQ(wrap.unwrap_by_global, napi_invalid_arg); + EXPECT_EQ(wrap.remove, napi_invalid_arg); + EXPECT_EQ(wrap.fresh_finalized, 1); +} + +// A wrap's finalizer that removes the wrap of its own object at release finds +// it gone too, whether the provider or a reference napi_wrap returned owns +// the wrap. Each is finalized once. +TEST_F(Test41InstanceData, AWrapFinalizerFindsItsOwnWrapGoneAtRelease) { + EnvScope s(runtime_.get()); + RemovingItsWrap owned, referenced; + for (RemovingItsWrap* self : {&owned, &referenced}) { + napi_value object = nullptr; + ASSERT_EQ(napi_create_object(s.env, &object), napi_ok); + ASSERT_EQ(napi_wrap(s.env, object, nullptr, FinalizeRemovingItsWrap, self, + self == &referenced ? &self->wrap : nullptr), + napi_ok); + ASSERT_EQ(napi_create_reference(s.env, object, 1, &self->object), napi_ok); + } + + Release(s); + for (const RemovingItsWrap* self : {&owned, &referenced}) { + EXPECT_EQ(self->finalized, 1); + EXPECT_EQ(self->remove, napi_invalid_arg); + } +} diff --git a/v8/src/internal/napi_ref.cc b/v8/src/internal/napi_ref.cc index 3d9bcd1704..dc0fe1b057 100644 --- a/v8/src/internal/napi_ref.cc +++ b/v8/src/internal/napi_ref.cc @@ -92,6 +92,7 @@ void napi_ref__::Invalidate() { } void napi_ref__::Finalize() { + ForgetWrap(); value_.Reset(); bool deleteMe = ownership_ == napi_ref_ownership__::kRuntime; Unlink(); @@ -101,6 +102,28 @@ void napi_ref__::Finalize() { } } +// A wrap finalized while its object is alive, as the env's release does: +// the object lets go of the wrap first, so napi_unwrap and napi_remove_wrap +// find none, rather than this reference, which the finalizer may delete and +// which is freed after it if the provider owns it. +void napi_ref__::ForgetWrap() { + if (!wrap_ || value_.IsEmpty() || env_ == nullptr) return; + wrap_ = false; + v8::Isolate* isolate = env_->isolate; + v8::HandleScope handle_scope(isolate); + v8::Local value = value_.Get(isolate); + if (!value->IsObject()) return; + v8::Local object = value.As(); + v8::Local context = env_->main_context(); + v8::Context::Scope context_scope(context); + v8::Local key = env_->agent->wrap_private_key.Get(isolate); + v8::Local wrapped; + if (object->GetPrivate(context, key).ToLocal(&wrapped) && wrapped->IsExternal() && + wrapped.As()->Value() == this) { + (void)object->DeletePrivate(context, key); + } +} + void napi_ref__::InvokeFinalizerFromGC() { Finalize(); } diff --git a/v8/src/internal/napi_ref.h b/v8/src/internal/napi_ref.h index 8824907d00..32bdcbf247 100644 --- a/v8/src/internal/napi_ref.h +++ b/v8/src/internal/napi_ref.h @@ -33,6 +33,8 @@ struct napi_ref__ : public napi_ref_tracker__ { void Invalidate(); void Finalize() override; napi_ref_ownership__ ownership() const { return ownership_; } + // napi_wrap made this reference for its object. + void MarkWrap() { wrap_ = true; } napi_ref__(napi_env__* env, v8::Local value, @@ -47,11 +49,13 @@ struct napi_ref__ : public napi_ref_tracker__ { private: static void WeakCallback(const v8::WeakCallbackInfo& info); void SetWeak(); + void ForgetWrap(); v8::Global value_; uint32_t refcount_ = 0; napi_ref_ownership__ ownership_ = napi_ref_ownership__::kUserland; bool can_be_weak_ = false; + bool wrap_ = false; }; #endif // NAPI_V8_REF_H_ diff --git a/v8/src/js_native_api_v8.cc b/v8/src/js_native_api_v8.cc index 0cc577e84c..adf91a275f 100644 --- a/v8/src/js_native_api_v8.cc +++ b/v8/src/js_native_api_v8.cc @@ -3104,6 +3104,7 @@ napi_status NAPI_CDECL napi_wrap(napi_env env, env, object, 0, napi_ref_ownership__::kRuntime, native_object); } if (ref == nullptr) return napi_generic_failure; + ref->MarkWrap(); if (!object ->SetPrivate(env->context(), From 4537eac3764f8515553cd8fd20137d7480b10f71 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 17:34:53 -0800 Subject: [PATCH 056/150] V8: leave queued external finalizers to the release pass in a checkpoint At release FinalizeExternalBackingStoreHints takes the finalizers the deleters queued into a local map, and runs them and the tracked buffers most recent first by store id. A finalizer that called unofficial_napi_event_loop_checkpoint ran DrainFinalizerQueue, which took and ran any external finalizer queued since, ahead of older-made but newer-by-id ones still waiting in the pass. Each still ran once; only the order was wrong. While the env is releasing, DrainFinalizerQueue no longer takes the external queue; the pass takes what was queued meanwhile at its next step and merges it by id. Reference finalizers and buffer records it drains as before. Test: external ArrayBuffers A, B and C; at release a hook detaches B, and C's finalizer detaches A and runs a checkpoint. They are finalized C, B, A (on V8 it was C, A, B). Co-Authored-By: Claude Opus 5.5 --- tests/runners/test_41_instance_data.cc | 76 ++++++++++++++++++++++++++ v8/src/js_native_api_v8.cc | 9 ++- 2 files changed, 83 insertions(+), 2 deletions(-) diff --git a/tests/runners/test_41_instance_data.cc b/tests/runners/test_41_instance_data.cc index 90908182a8..25aa427c18 100644 --- a/tests/runners/test_41_instance_data.cc +++ b/tests/runners/test_41_instance_data.cc @@ -1240,3 +1240,79 @@ TEST_F(Test41InstanceData, AWrapFinalizerFindsItsOwnWrapGoneAtRelease) { EXPECT_EQ(self->remove, napi_invalid_arg); } } + +namespace { + +// External array buffers A, B and C, made in that order. At release a hook +// detaches B, then C's finalizer detaches A and runs a checkpoint. +struct CheckpointAtRelease { + napi_env env = nullptr; + uint8_t bytes[3][8] = {}; + napi_ref a = nullptr; + napi_ref b = nullptr; + std::string order; + napi_status detach_a = napi_generic_failure; + napi_status detach_b = napi_generic_failure; +}; + +struct NamedBuffer { + CheckpointAtRelease* state; + char name; +}; + +void Detach(napi_env env, napi_ref ref, napi_status* status) { + napi_handle_scope scope = nullptr; + ASSERT_EQ(napi_open_handle_scope(env, &scope), napi_ok); + napi_value buffer = nullptr; + ASSERT_EQ(napi_get_reference_value(env, ref, &buffer), napi_ok); + *status = napi_detach_arraybuffer(env, buffer); + ASSERT_EQ(napi_close_handle_scope(env, scope), napi_ok); +} + +void HookDetachingB(void* arg) { + auto* state = static_cast(arg); + Detach(state->env, state->b, &state->detach_b); +} + +void FinalizeNamedBuffer(node_api_basic_env basic_env, void*, void* hint) { + auto env = const_cast(basic_env); + auto* named = static_cast(hint); + named->state->order += named->name; + if (named->name != 'C') return; + Detach(env, named->state->a, &named->state->detach_a); + // Runs what the env has queued, here in the middle of the release. + unofficial_napi_event_loop_checkpoint(env, unofficial_napi_event_loop_checkpoint_microtasks, + true, nullptr); +} + +} // namespace + +// External buffers are finalized most recent first at release, also when one +// of their finalizers runs a checkpoint, which runs what the env has queued. +TEST_F(Test41InstanceData, ACheckpointInAFinalizerKeepsTheReleaseOrder) { + EnvScope s(runtime_.get()); + CheckpointAtRelease state; + state.env = s.env; + NamedBuffer a{&state, 'A'}, b{&state, 'B'}, c{&state, 'C'}; + napi_value buffer = nullptr; + ASSERT_EQ(napi_create_external_arraybuffer(s.env, state.bytes[0], 8, FinalizeNamedBuffer, &a, + &buffer), + napi_ok); + Keep(s.env, "a", buffer); + ASSERT_EQ(napi_create_reference(s.env, buffer, 1, &state.a), napi_ok); + ASSERT_EQ(napi_create_external_arraybuffer(s.env, state.bytes[1], 8, FinalizeNamedBuffer, &b, + &buffer), + napi_ok); + Keep(s.env, "b", buffer); + ASSERT_EQ(napi_create_reference(s.env, buffer, 1, &state.b), napi_ok); + ASSERT_EQ(napi_create_external_arraybuffer(s.env, state.bytes[2], 8, FinalizeNamedBuffer, &c, + &buffer), + napi_ok); + Keep(s.env, "c", buffer); + ASSERT_EQ(napi_add_env_cleanup_hook(s.env, HookDetachingB, &state), napi_ok); + + Release(s); + EXPECT_EQ(state.detach_b, napi_ok); + EXPECT_EQ(state.detach_a, napi_ok); + EXPECT_EQ(state.order, "CBA"); +} diff --git a/v8/src/js_native_api_v8.cc b/v8/src/js_native_api_v8.cc index adf91a275f..3388db8016 100644 --- a/v8/src/js_native_api_v8.cc +++ b/v8/src/js_native_api_v8.cc @@ -883,7 +883,12 @@ void napi_env__::DequeueFinalizer(napi_ref_tracker__* finalizer) { void napi_env__::DrainFinalizerQueue() { finalization_scheduled = false; - std::vector external = TakeExternalFinalizers(this); + // While the env is releasing (a finalizer there may run a checkpoint), its + // release pass runs the external finalizers, those queued meanwhile too, + // in its order: most recent first. + const bool take_external = !releasing; + std::vector external; + if (take_external) external = TakeExternalFinalizers(this); if (pending_finalizers.empty() && pending_buffer_finalizers.empty() && external.empty()) { return; } @@ -911,7 +916,7 @@ void napi_env__::DrainFinalizerQueue() { } // A finalizer above can free a backing store, which queues the store's // finalizer. - external = TakeExternalFinalizers(this); + if (take_external) external = TakeExternalFinalizers(this); } } From 93bf688cb18f64046e2d741364d89d65a96058a5 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 17:38:05 -0800 Subject: [PATCH 057/150] QuickJS: report views over a detached ArrayBuffer as empty, as Node QuickJS's accessors throw for a typed array or DataView whose buffer is detached. napi_get_typedarray_info and napi_get_dataview_info returned napi_pending_exception and left a TypeError pending, and napi_get_buffer_info (and napi_is_buffer, through has_typed_array_backing) treated a detached Buffer as no Buffer and returned napi_invalid_arg. Node and the V8 provider return napi_ok with data NULL and a length and offset of 0, and the view's ArrayBuffer. "QuickJS: report a detached ArrayBuffer's info as empty, as Node" made napi_get_arraybuffer_info do so on QuickJS; the release now detaches every external Buffer before its finalizer, so a finalizer that reads one hit this. When an accessor throws for a typed array or DataView, the provider now reads the view's buffer (its getter does not throw), and if that ArrayBuffer is detached, clears the exception and reports the view as empty. napi_get_dataview_info reads the buffer first and skips the byteLength and byteOffset getters for a detached one. napi_get_buffer_info and napi_is_buffer accept a detached Buffer. Test: a Uint8Array, a Buffer made by node_api_create_buffer_from_arraybuffer and a DataView over one ArrayBuffer, and an external Buffer, each detached: every getter returns napi_ok, data NULL, 0 and the same ArrayBuffer, with nothing pending, and both Buffers are still Buffers. Co-Authored-By: Claude Opus 5.5 --- quickjs/src/internal/napi_buffer.cc | 16 +++++ quickjs/src/internal/napi_util.cc | 32 ++++++++++ quickjs/src/internal/napi_util.h | 10 ++++ quickjs/src/js_native_api_quickjs.cc | 55 +++++++++++++----- tests/runners/test_33_typedarray.cc | 87 ++++++++++++++++++++++++++++ 5 files changed, 184 insertions(+), 16 deletions(-) diff --git a/quickjs/src/internal/napi_buffer.cc b/quickjs/src/internal/napi_buffer.cc index 2cc2ba44d1..bd7eaeddb9 100644 --- a/quickjs/src/internal/napi_buffer.cc +++ b/quickjs/src/internal/napi_buffer.cc @@ -1,6 +1,7 @@ #include "internal/napi_buffer.h" #include "internal/napi_env.h" +#include "internal/napi_util.h" #include @@ -118,7 +119,10 @@ bool napi_buffer__::has_typed_array_backing(JSValueConst value) const return false; JSValue arraybuffer = JS_GetTypedArrayBuffer(context_, value, nullptr, nullptr, nullptr); + // QuickJS throws for a view over a detached buffer, which is still one. if (JS_IsException(arraybuffer)) + arraybuffer = napi_util__::detached_view_buffer(context_, value); + if (JS_IsUndefined(arraybuffer)) { clear_pending_exception_if_any(); return false; @@ -247,6 +251,18 @@ napi_status napi_buffer__::get_buffer_info(JSValueConst value, void **data, size JSValue arraybuffer = JS_GetTypedArrayBuffer(context_, value, &offset, &byte_len, nullptr); if (JS_IsException(arraybuffer)) { + // QuickJS throws for a Buffer over a detached ArrayBuffer. Node reports + // it as one with no data and a length of 0. + JSValue detached = napi_util__::detached_view_buffer(context_, value); + if (!JS_IsUndefined(detached)) + { + JS_FreeValue(context_, detached); + if (data != nullptr) + *data = nullptr; + if (length != nullptr) + *length = 0; + return napi_quickjs_clear_last_error(env_); + } clear_pending_exception_if_any(); return napi_quickjs_set_last_error(env_, napi_invalid_arg, "Invalid argument"); } diff --git a/quickjs/src/internal/napi_util.cc b/quickjs/src/internal/napi_util.cc index 05aee1c17f..01ebff22c7 100644 --- a/quickjs/src/internal/napi_util.cc +++ b/quickjs/src/internal/napi_util.cc @@ -594,6 +594,38 @@ bool napi_util__::from_quickjs_array_type(int type, napi_typedarray_type *out) } } +bool napi_util__::is_detached_array_buffer(JSContext *ctx, JSValueConst value) +{ + if (!JS_IsArrayBuffer(value)) + return false; + size_t length = 0; + if (JS_GetArrayBuffer(ctx, &length, value) != nullptr || !JS_HasException(ctx)) + return false; + JS_FreeValue(ctx, JS_GetException(ctx)); + return true; +} + +JSValue napi_util__::detached_view_buffer(JSContext *ctx, JSValueConst view) +{ + if (JS_GetTypedArrayType(view) < 0 && !JS_IsDataView(view)) + return JS_UNDEFINED; + JSValue thrown = JS_GetException(ctx); + // The buffer getters of typed arrays and DataViews do not throw for a + // detached buffer. + JSValue buffer = JS_GetPropertyStr(ctx, view, "buffer"); + if (!JS_IsException(buffer) && is_detached_array_buffer(ctx, buffer)) + { + JS_FreeValue(ctx, thrown); + return buffer; + } + if (JS_IsException(buffer)) + JS_FreeValue(ctx, JS_GetException(ctx)); + else + JS_FreeValue(ctx, buffer); + JS_Throw(ctx, thrown); + return JS_UNDEFINED; +} + void *napi_util__::realloc_array_buffer_data(JSRuntime *rt, void *opaque, void *ptr, size_t size) { (void)opaque; diff --git a/quickjs/src/internal/napi_util.h b/quickjs/src/internal/napi_util.h index 527a9ac130..1673750423 100644 --- a/quickjs/src/internal/napi_util.h +++ b/quickjs/src/internal/napi_util.h @@ -68,6 +68,16 @@ class napi_util__ static void *realloc_array_buffer_data(JSRuntime *rt, void *opaque, void *ptr, size_t size); + // QuickJS's accessors throw for a detached ArrayBuffer and the views over + // one; Node reports them as having no data and a length of 0. + // True for a detached ArrayBuffer. Leaves no exception pending. + static bool is_detached_array_buffer(JSContext *ctx, JSValueConst value); + // After an accessor of a typed array or DataView threw: the view's + // ArrayBuffer if it is detached, with that exception cleared; otherwise + // (also when `view` is no such view) JS_UNDEFINED, with the exception + // still pending. + static JSValue detached_view_buffer(JSContext *ctx, JSValueConst view); + static int key_filter_to_gpn(napi_key_filter key_filter); static napi_status get_property_names(napi_env env, napi_value object, diff --git a/quickjs/src/js_native_api_quickjs.cc b/quickjs/src/js_native_api_quickjs.cc index 278c5798fc..7d881b4284 100644 --- a/quickjs/src/js_native_api_quickjs.cc +++ b/quickjs/src/js_native_api_quickjs.cc @@ -520,10 +520,17 @@ extern "C" size_t byte_len; size_t offset; JSValue abuf = JS_GetTypedArrayBuffer(env->context(), local, &offset, &byte_len, nullptr); - + // QuickJS throws for a typed array over a detached buffer. Node reports + // it as one with no data and a length and offset of 0. + bool detached = false; if (JS_IsException(abuf)) { - return napi_util__::return_pending_if_caught(env, "Failed to get typed array info"); + abuf = napi_util__::detached_view_buffer(env->context(), local); + if (JS_IsUndefined(abuf)) + return napi_util__::return_pending_if_caught(env, "Failed to get typed array info"); + detached = true; + byte_len = 0; + offset = 0; } if (length != nullptr) @@ -562,7 +569,11 @@ extern "C" *byte_offset = offset; } - if (data != nullptr) + if (data != nullptr && detached) + { + *data = nullptr; + } + else if (data != nullptr) { size_t ab_len; uint8_t *ab_data = JS_GetArrayBuffer(env->context(), &ab_len, abuf); @@ -1444,29 +1455,41 @@ extern "C" if (!JS_IsDataView(view)) return napi_util__::invalid_arg(env); - JSValue len_val = JS_GetPropertyStr(env->context(), view, "byteLength"); - JSValue offset_val = JS_GetPropertyStr(env->context(), view, "byteOffset"); JSValue buffer_val = JS_GetPropertyStr(env->context(), view, "buffer"); - if (JS_IsException(len_val) || JS_IsException(offset_val) || JS_IsException(buffer_val)) + if (JS_IsException(buffer_val)) + return napi_util__::return_pending_if_caught(env, "Failed to get DataView info"); + // QuickJS's byteLength and byteOffset getters throw for a DataView over a + // detached buffer. Node reports it as one with no data and a length and + // offset of 0. + const bool detached = napi_util__::is_detached_array_buffer(env->context(), buffer_val); + uint32_t len = 0; + uint32_t offset = 0; + if (!detached) { + JSValue len_val = JS_GetPropertyStr(env->context(), view, "byteLength"); + JSValue offset_val = JS_GetPropertyStr(env->context(), view, "byteOffset"); + if (JS_IsException(len_val) || JS_IsException(offset_val)) + { + JS_FreeValue(env->context(), len_val); + JS_FreeValue(env->context(), offset_val); + JS_FreeValue(env->context(), buffer_val); + return napi_util__::return_pending_if_caught(env, "Failed to get DataView info"); + } + JS_ToUint32(env->context(), &len, len_val); + JS_ToUint32(env->context(), &offset, offset_val); JS_FreeValue(env->context(), len_val); JS_FreeValue(env->context(), offset_val); - JS_FreeValue(env->context(), buffer_val); - return napi_util__::return_pending_if_caught(env, "Failed to get DataView info"); } - uint32_t len = 0; - uint32_t offset = 0; - JS_ToUint32(env->context(), &len, len_val); - JS_ToUint32(env->context(), &offset, offset_val); - JS_FreeValue(env->context(), len_val); - JS_FreeValue(env->context(), offset_val); - if (byte_length != nullptr) *byte_length = len; if (byte_offset != nullptr) *byte_offset = offset; - if (data != nullptr) + if (data != nullptr && detached) + { + *data = nullptr; + } + else if (data != nullptr) { size_t ab_len = 0; uint8_t *ab_data = JS_GetArrayBuffer(env->context(), &ab_len, buffer_val); diff --git a/tests/runners/test_33_typedarray.cc b/tests/runners/test_33_typedarray.cc index 980de59eff..9992383475 100644 --- a/tests/runners/test_33_typedarray.cc +++ b/tests/runners/test_33_typedarray.cc @@ -1,3 +1,8 @@ +#ifdef NAPI_MODULE +#undef NAPI_MODULE +#endif +#include "node_api.h" + #include "test_env.h" #include "upstream_js_test.h" @@ -230,6 +235,88 @@ TEST_F(Test33TypedArray, BufferFromAnArrayBufferViewsIt) { EXPECT_EQ(type, napi_undefined); } +// As in Node, a view over a detached ArrayBuffer has no data and a length and +// offset of 0: a typed array, a DataView and a Buffer, and an external Buffer +// whose ArrayBuffer is detached (as the release does before its finalizer). +// A Buffer is still a Buffer. +TEST_F(Test33TypedArray, DetachedViewInfoIsEmpty) { + ExternalBufferState state; + EnvScope s(runtime_.get()); + napi_value array_buffer = nullptr; + ASSERT_EQ(napi_create_arraybuffer(s.env, 16, nullptr, &array_buffer), napi_ok); + napi_value typed_array = nullptr; + ASSERT_EQ(napi_create_typedarray(s.env, napi_uint8_array, 8, array_buffer, 4, &typed_array), + napi_ok); + napi_value buffer = nullptr; + ASSERT_EQ(node_api_create_buffer_from_arraybuffer(s.env, array_buffer, 2, 6, &buffer), napi_ok); + napi_value data_view = nullptr; + ASSERT_EQ(napi_create_dataview(s.env, 8, array_buffer, 8, &data_view), napi_ok); + napi_value external = nullptr; + ASSERT_EQ(napi_create_external_buffer(s.env, sizeof(state.bytes), state.bytes, + FinalizeExternalBuffer, &state, &external), + napi_ok); + napi_value external_array_buffer = nullptr; + ASSERT_EQ(napi_get_typedarray_info(s.env, external, nullptr, nullptr, nullptr, + &external_array_buffer, nullptr), + napi_ok); + ASSERT_EQ(napi_detach_arraybuffer(s.env, array_buffer), napi_ok); + ASSERT_EQ(napi_detach_arraybuffer(s.env, external_array_buffer), napi_ok); + + auto expect_nothing_pending = [&](const char* what) { + bool pending = true; + ASSERT_EQ(napi_is_exception_pending(s.env, &pending), napi_ok); + EXPECT_FALSE(pending) << what; + napi_value exception = nullptr; + if (pending) napi_get_and_clear_last_exception(s.env, &exception); + }; + auto expect_same = [&](napi_value viewed, napi_value expected, const char* what) { + bool same = false; + ASSERT_NE(viewed, nullptr) << what; + ASSERT_EQ(napi_strict_equals(s.env, viewed, expected, &same), napi_ok); + EXPECT_TRUE(same) << what; + }; + + for (napi_value view : {typed_array, buffer, external}) { + const char* what = view == typed_array ? "typed array" : view == buffer ? "buffer" : "external"; + napi_typedarray_type type = napi_int8_array; + size_t length = 99; + void* data = &state; + napi_value viewed = nullptr; + size_t offset = 99; + EXPECT_EQ(napi_get_typedarray_info(s.env, view, &type, &length, &data, &viewed, &offset), + napi_ok) + << what; + EXPECT_EQ(type, napi_uint8_array) << what; + EXPECT_EQ(length, 0u) << what; + EXPECT_EQ(data, nullptr) << what; + EXPECT_EQ(offset, 0u) << what; + expect_same(viewed, view == external ? external_array_buffer : array_buffer, what); + expect_nothing_pending(what); + } + for (napi_value view : {buffer, external}) { + const char* what = view == buffer ? "buffer" : "external"; + bool is_buffer = false; + EXPECT_EQ(napi_is_buffer(s.env, view, &is_buffer), napi_ok) << what; + EXPECT_TRUE(is_buffer) << what; + size_t length = 99; + void* data = &state; + EXPECT_EQ(napi_get_buffer_info(s.env, view, &data, &length), napi_ok) << what; + EXPECT_EQ(length, 0u) << what; + EXPECT_EQ(data, nullptr) << what; + expect_nothing_pending(what); + } + size_t length = 99; + void* data = &state; + napi_value viewed = nullptr; + size_t offset = 99; + EXPECT_EQ(napi_get_dataview_info(s.env, data_view, &length, &data, &viewed, &offset), napi_ok); + EXPECT_EQ(length, 0u); + EXPECT_EQ(data, nullptr); + EXPECT_EQ(offset, 0u); + expect_same(viewed, array_buffer, "data view"); + expect_nothing_pending("data view"); +} + #if defined(NAPI_TEST_ENGINE_QUICKJS) TEST_F(Test33TypedArray, ExternalArrayBufferResizeFailurePreservesBackingStore) { ExternalBufferState state; From 77d0f0d02e25537bbfd09ae7c8bb56313eb3023f Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 17:38:28 -0800 Subject: [PATCH 058/150] QuickJS: call the instance-data finalizer for NULL data call_instance_data_finalizer returned when the data was NULL, so napi_set_instance_data(env, NULL, cb, hint) never had cb called at release, nor did NULL instance data the instance-data finalizer set while the env was releasing. Node and the V8 provider call a finalizer whenever one is set, whatever the data. The release now calls it whenever a finalizer is set. Replacing instance data still finalizes the old data only when it is not NULL (Node never finalizes replaced data; that difference is unchanged). Test: NULL instance data with a finalizer is finalized once at release, with NULL; an instance-data finalizer that sets NULL data with a finalizer has that finalizer called too. Co-Authored-By: Claude Opus 5.5 --- quickjs/src/internal/napi_env.cc | 8 ++++-- tests/runners/test_41_instance_data.cc | 37 ++++++++++++++++++++++++++ 2 files changed, 43 insertions(+), 2 deletions(-) diff --git a/quickjs/src/internal/napi_env.cc b/quickjs/src/internal/napi_env.cc index 9c174b714c..686f10f3d2 100644 --- a/quickjs/src/internal/napi_env.cc +++ b/quickjs/src/internal/napi_env.cc @@ -286,7 +286,8 @@ void napi_env__::call_instance_data_finalizer(void *data, napi_finalize finalize_cb, void *finalize_hint) { - if (data == nullptr || finalize_cb == nullptr) + // As Node, whatever the data, NULL too. + if (finalize_cb == nullptr) return; // In the env's realm, as any finalizer. napi_realm_frame_scope__ realm_frame{this, nullptr, JS_UNDEFINED}; @@ -619,7 +620,10 @@ void napi_env__::set_instance_data(void *data, napi_finalize finalize_cb, void * instance_data_finalize_cb_ = nullptr; instance_data_finalize_hint_ = nullptr; - call_instance_data_finalizer(old_data, old_finalize_cb, old_finalize_hint); + // Unlike Node, which never finalizes replaced instance data, this + // finalizes it, but only non-NULL data. + if (old_data != nullptr) + call_instance_data_finalizer(old_data, old_finalize_cb, old_finalize_hint); instance_data_ = data; instance_data_finalize_cb_ = finalize_cb; diff --git a/tests/runners/test_41_instance_data.cc b/tests/runners/test_41_instance_data.cc index 25aa427c18..c83e9baaf0 100644 --- a/tests/runners/test_41_instance_data.cc +++ b/tests/runners/test_41_instance_data.cc @@ -1316,3 +1316,40 @@ TEST_F(Test41InstanceData, ACheckpointInAFinalizerKeepsTheReleaseOrder) { EXPECT_EQ(state.detach_a, napi_ok); EXPECT_EQ(state.order, "CBA"); } + +namespace { + +// Records the data each instance-data finalizer call gets. +void RecordInstanceData(napi_env, void* data, void* hint) { + static_cast*>(hint)->push_back(data); +} + +// Records, then sets NULL instance data with a finalizer. +void RecordThenSetNullInstanceData(napi_env env, void* data, void* hint) { + RecordInstanceData(env, data, hint); + EXPECT_EQ(napi_set_instance_data(env, nullptr, RecordInstanceData, hint), napi_ok); +} + +} // namespace + +// As in Node, the release calls the instance-data finalizer whatever the +// data, NULL too, also when the instance-data finalizer set it. +TEST_F(Test41InstanceData, TheInstanceDataFinalizerRunsForNullData) { + std::vector null_data; + { + EnvScope s(runtime_.get()); + ASSERT_EQ(napi_set_instance_data(s.env, nullptr, RecordInstanceData, &null_data), napi_ok); + Release(s); + } + int marker = 0; + std::vector set_at_release; + { + EnvScope s(runtime_.get()); + ASSERT_EQ( + napi_set_instance_data(s.env, &marker, RecordThenSetNullInstanceData, &set_at_release), + napi_ok); + Release(s); + } + EXPECT_EQ(null_data, std::vector{nullptr}); + EXPECT_EQ(set_at_release, (std::vector{&marker, nullptr})); +} From 78adfa63b80a68e87be34f370b12bac4cc74e54b Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 17:39:42 -0800 Subject: [PATCH 059/150] Document the release contract's fixes and its transfer limitation The header's release contract now says what the previous commits made both providers do: finalizers run most recent first also when one runs a checkpoint; a wrapped object lets go of its wrap before the wrap's finalizer, so napi_unwrap and napi_remove_wrap then return napi_invalid_arg; the instance-data finalizer runs for NULL data; and a finalizer an engine runs in the middle of other code drops only its own exception. It also corrects the transfer carve-out. It said neither provider can reach a buffer ArrayBuffer.prototype.transfer moved the memory to. On QuickJS that buffer holds the hint, though the hint cannot find the buffer to detach it. Either way the finalizer still runs in its turn and frees memory that buffer still exposes, so code that reads it later in the release reads freed memory, as in Node. The header and the comments in both providers now say so. Leaving such a finalizer to the moved buffer's own release would leak the memory instead: a buffer alive at the release is freed only after the pass, when finalizers are dropped. Tried on QuickJS, the existing test TransferredExternalArrayBufferIsFinalizedOnceAtRelease then freed the kept buffer's memory 0 times instead of 1. Co-Authored-By: Claude Opus 5.5 --- include/unofficial_napi.h | 41 ++++++++++++------- .../napi_external_backing_store_hint.cc | 8 +++- v8/src/js_native_api_v8.cc | 5 ++- 3 files changed, 36 insertions(+), 18 deletions(-) diff --git a/include/unofficial_napi.h b/include/unofficial_napi.h index a06493f145..449317359c 100644 --- a/include/unofficial_napi.h +++ b/include/unofficial_napi.h @@ -152,14 +152,24 @@ NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_attach_env( // 2. The finalizer of every value still pending runs: napi_wrap, // napi_create_external, napi_add_finalizer, external ArrayBuffers and // Buffers. Values of one kind are finalized most recent first, as Node's -// FinalizeAll does; the order between kinds is not specified. An external -// ArrayBuffer or Buffer is detached before its finalizer runs, as Node's -// CallbackInfo::Clean does, so the finalizer and the code that runs after -// it see it detached (byte length 0), never the freed memory. A buffer -// that ArrayBuffer.prototype.transfer moved the memory to is not detached: -// neither provider, nor Node, can reach it. 1 and 2 repeat until neither -// has anything left. -// 3. The instance-data finalizer runs, after all of those. +// FinalizeAll does (also when a finalizer runs +// unofficial_napi_event_loop_checkpoint); the order between kinds is not +// specified. An external ArrayBuffer or Buffer is detached before its +// finalizer runs, as Node's CallbackInfo::Clean does, so the finalizer and +// the code that runs after it see it detached (no data, byte length 0), +// never the freed memory. The exception is a buffer that +// ArrayBuffer.prototype.transfer moved the memory to: neither provider can +// find it to detach it (QuickJS learns of it only once it is freed, and +// Node cannot either), so the finalizer still runs in its turn and frees +// memory that buffer still exposes; code that reads it later in the +// release reads freed memory, as in Node. (Waiting for that buffer to be +// freed would leak the memory instead: a buffer still alive is freed only +// after this pass.) A wrapped object lets go of its wrap before the wrap's +// finalizer runs: from then on napi_unwrap and napi_remove_wrap return +// napi_invalid_arg for it, as for an object never wrapped. 1 and 2 repeat +// until neither has anything left. +// 3. The instance-data finalizer runs, after all of those, whatever the data +// (NULL too), as in Node. // 4. 1 to 3 repeat for whatever the instance-data finalizer leaves pending // (values it made and kept, hooks it added, instance data it set), until // nothing is pending, as Node's FinalizeAll finalizes until its lists are @@ -168,12 +178,15 @@ NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_attach_env( // // After each hook and finalizer, an exception it left pending is dropped: // nothing can catch it then (Node's CallIntoModule drops it too once JS can -// no longer run). Each runs on the env's thread, in the env's realm (also when -// another realm was entered when the release began), with N-API usable. -// References made with napi_create_reference keep their values until all of -// them have run. A finalizer the engine would call after this pass, while it -// frees the engine instance, is dropped, and nothing touches the env once it -// is freed. +// no longer run). An engine may run a finalizer in the middle of other code, +// when that code frees the last reference to a value (QuickJS does): there +// only the finalizer's own exception is dropped, and one that JS is throwing, +// or that a hook has pending, is kept. Each runs on the env's thread, in the +// env's realm (also when another realm was entered when the release began), +// with N-API usable. References made with napi_create_reference keep their +// values until all of them have run. A finalizer the engine would call after +// this pass, while it frees the engine instance, is dropped, and nothing +// touches the env once it is freed. NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_release_env( unofficial_napi_env_owner owner, struct uv_loop_s* loop_or_null); diff --git a/quickjs/src/internal/napi_external_backing_store_hint.cc b/quickjs/src/internal/napi_external_backing_store_hint.cc index b1c9816d54..6a4e2f0463 100644 --- a/quickjs/src/internal/napi_external_backing_store_hint.cc +++ b/quickjs/src/internal/napi_external_backing_store_hint.cc @@ -163,8 +163,12 @@ void napi_external_backing_store_hint__::finalize_at_teardown() // finalizer runs, so the finalizer and the code after it see it detached // and nothing reaches the memory the finalizer frees. The detach lets go // of the memory, unless ArrayBuffer.prototype.transfer already moved it to - // a buffer this hint cannot reach (Node cannot either). The reference - // keeps the buffer alive in case the finalizer drops the last other one. + // another buffer. That buffer holds this hint, but the hint cannot find + // it to detach it (Node cannot either), so the finalizer below frees + // memory it still exposes; waiting for its release instead would leak the + // memory, since a buffer alive now is freed only after the release pass. + // The reference keeps the buffer alive in case the finalizer drops the + // last other one. array_buffer = JS_DupValue(ctx, array_buffer_); detaching_ = true; JS_DetachArrayBuffer(ctx, array_buffer); diff --git a/v8/src/js_native_api_v8.cc b/v8/src/js_native_api_v8.cc index 3388db8016..d5631b790b 100644 --- a/v8/src/js_native_api_v8.cc +++ b/v8/src/js_native_api_v8.cc @@ -348,8 +348,9 @@ void ForgetExternalArrayBuffer(napi_env env, uint64_t id) { // queues it, and FinalizeExternalBackingStoreHints runs it next. Either way // the finalizer is claimed once, under the lock. A buffer that // ArrayBuffer.prototype.transfer moved the store to is not reachable from -// here (Node cannot reach it either); the one it moved it from is detached -// already. +// here (Node cannot reach it either), and the one it moved it from is +// detached already: the store stays alive, and the finalizer frees memory +// that buffer still exposes. void FinalizeNewestExternalArrayBuffer(napi_env env) { auto newest = std::prev(env->external_array_buffers.end()); const uint64_t id = newest->first; From 13c8c2747151a0f31a9c4bc5df64e8340485a608 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 18:00:41 -0800 Subject: [PATCH 060/150] QuickJS: read a view's buffer through the intrinsic getters Found by the Codex review of this fix-up. "QuickJS: report views over a detached ArrayBuffer as empty, as Node" decided whether a typed array or DataView was over a detached ArrayBuffer by reading the view's `buffer` property, which a script can redefine on the view. A typed array whose own buffer was detached, with `buffer` redefined to another detached ArrayBuffer, reported that other one. A live DataView with `buffer` redefined to a detached ArrayBuffer reported no data and a length and offset of 0 instead of its own bytes. The env now keeps the getters of %TypedArray%.prototype.buffer and DataView.prototype.buffer, read when it is made (as it keeps the DataView constructor), and napi_env__::view_buffer calls them; they read the view's internal slot, whatever realm made the view. napi_get_typedarray_info, napi_get_buffer_info and napi_is_buffer use it for a detached view, and napi_get_dataview_info uses it for the buffer it reports and reads data from (the property is read only if the env has no such getter). napi_util__::is_detached_array_buffer now keeps an exception that was pending before it. Test: a typed array over a detached buffer and a live DataView, each with `buffer` redefined to another, detached, ArrayBuffer: each reports its own ArrayBuffer, and the DataView its own bytes. Co-Authored-By: Claude Opus 5.5 --- quickjs/src/internal/napi_buffer.cc | 4 +- quickjs/src/internal/napi_env.cc | 91 ++++++++++++++++++++++++++++ quickjs/src/internal/napi_env.h | 15 +++++ quickjs/src/internal/napi_util.cc | 34 +++-------- quickjs/src/internal/napi_util.h | 11 +--- quickjs/src/js_native_api_quickjs.cc | 7 ++- tests/runners/test_33_typedarray.cc | 60 ++++++++++++++++++ 7 files changed, 185 insertions(+), 37 deletions(-) diff --git a/quickjs/src/internal/napi_buffer.cc b/quickjs/src/internal/napi_buffer.cc index bd7eaeddb9..f2de406a90 100644 --- a/quickjs/src/internal/napi_buffer.cc +++ b/quickjs/src/internal/napi_buffer.cc @@ -121,7 +121,7 @@ bool napi_buffer__::has_typed_array_backing(JSValueConst value) const JSValue arraybuffer = JS_GetTypedArrayBuffer(context_, value, nullptr, nullptr, nullptr); // QuickJS throws for a view over a detached buffer, which is still one. if (JS_IsException(arraybuffer)) - arraybuffer = napi_util__::detached_view_buffer(context_, value); + arraybuffer = env_->detached_view_buffer(value); if (JS_IsUndefined(arraybuffer)) { clear_pending_exception_if_any(); @@ -253,7 +253,7 @@ napi_status napi_buffer__::get_buffer_info(JSValueConst value, void **data, size { // QuickJS throws for a Buffer over a detached ArrayBuffer. Node reports // it as one with no data and a length of 0. - JSValue detached = napi_util__::detached_view_buffer(context_, value); + JSValue detached = env_->detached_view_buffer(value); if (!JS_IsUndefined(detached)) { JS_FreeValue(context_, detached); diff --git a/quickjs/src/internal/napi_env.cc b/quickjs/src/internal/napi_env.cc index 686f10f3d2..80f31631a4 100644 --- a/quickjs/src/internal/napi_env.cc +++ b/quickjs/src/internal/napi_env.cc @@ -2,6 +2,7 @@ #include "internal/napi_external.h" #include "internal/napi_lifetime_macros.h" +#include "internal/napi_util.h" #include #include @@ -40,6 +41,55 @@ int runtime_interrupt_handler(JSRuntime *rt, void *opaque) return 0; } +// The getter of `object`'s own property `name`; undefined if there is none. +JSValue own_getter(JSContext *ctx, JSValueConst object, const char *name) +{ + if (!JS_IsObject(object)) + return JS_UNDEFINED; + JSAtom atom = JS_NewAtom(ctx, name); + if (atom == JS_ATOM_NULL) + { + JS_FreeValue(ctx, JS_GetException(ctx)); + return JS_UNDEFINED; + } + JSPropertyDescriptor desc; + const int has = JS_GetOwnProperty(ctx, &desc, object, atom); + JS_FreeAtom(ctx, atom); + if (has < 0) + JS_FreeValue(ctx, JS_GetException(ctx)); + if (has <= 0) + return JS_UNDEFINED; + JS_FreeValue(ctx, desc.value); + JS_FreeValue(ctx, desc.setter); + if (JS_IsFunction(ctx, desc.getter)) + return desc.getter; + JS_FreeValue(ctx, desc.getter); + return JS_UNDEFINED; +} + +// The getter of `name` on the prototype of `constructor_name` in the global +// (or on that prototype's own prototype, with `inherited`). +JSValue prototype_getter(JSContext *ctx, JSValueConst global, const char *constructor_name, + bool inherited, const char *name) +{ + JSValue constructor = JS_GetPropertyStr(ctx, global, constructor_name); + JSValue prototype = JS_IsObject(constructor) + ? JS_GetPropertyStr(ctx, constructor, "prototype") + : JS_UNDEFINED; + if (inherited && JS_IsObject(prototype)) + { + JSValue parent = JS_GetPrototype(ctx, prototype); + JS_FreeValue(ctx, prototype); + prototype = parent; + } + JSValue getter = JS_IsException(prototype) ? JS_UNDEFINED : own_getter(ctx, prototype, name); + JS_FreeValue(ctx, prototype); + JS_FreeValue(ctx, constructor); + if (JS_HasException(ctx)) + JS_FreeValue(ctx, JS_GetException(ctx)); + return getter; +} + napi_runtime_interrupts__ *installed_runtime_interrupts(JSRuntime *rt) { auto *handler = reinterpret_cast( @@ -108,6 +158,10 @@ napi_env__::napi_env__(napi_agent__ *agent, JSContext *context, int32_t module_a agent_->open_root_scope(this); JSValue global = JS_GetGlobalObject(context_); JSValue data_view = JS_GetPropertyStr(context_, global, "DataView"); + // Typed arrays of any realm share these getters' behaviour: they read the + // view's internal slot, whatever realm made it. + typed_array_buffer_getter_ = prototype_getter(context_, global, "Uint8Array", true, "buffer"); + data_view_buffer_getter_ = prototype_getter(context_, global, "DataView", false, "buffer"); JS_FreeValue(context_, global); if (JS_IsConstructor(context_, data_view)) data_view_constructor_ = data_view; @@ -183,8 +237,14 @@ void napi_env__::prepare_teardown() contextify_.teardown(); buffers_.teardown(); if (context_ != nullptr) + { JS_FreeValue(context_, data_view_constructor_); + JS_FreeValue(context_, typed_array_buffer_getter_); + JS_FreeValue(context_, data_view_buffer_getter_); + } data_view_constructor_ = JS_UNDEFINED; + typed_array_buffer_getter_ = JS_UNDEFINED; + data_view_buffer_getter_ = JS_UNDEFINED; if (principal) agent_->clear_promise_hooks(); promises_.teardown(); @@ -329,6 +389,37 @@ JSContext *napi_env__::main_context() const return context_; } +JSValue napi_env__::view_buffer(JSValueConst view) const +{ + JSValueConst getter = JS_IsDataView(view) ? data_view_buffer_getter_ + : JS_GetTypedArrayType(view) >= 0 ? typed_array_buffer_getter_ + : JS_UNDEFINED; + if (context_ == nullptr || JS_IsUndefined(getter)) + return JS_UNDEFINED; + JSValue earlier = JS_GetException(context_); + JSValue buffer = JS_Call(context_, getter, view, 0, nullptr); + if (JS_IsException(buffer)) + { + JS_FreeValue(context_, JS_GetException(context_)); + buffer = JS_UNDEFINED; + } + if (!JS_IsUninitialized(earlier)) + JS_Throw(context_, earlier); + return buffer; +} + +JSValue napi_env__::detached_view_buffer(JSValueConst view) const +{ + JSValue buffer = view_buffer(view); + if (napi_util__::is_detached_array_buffer(context_, buffer)) + { + JS_FreeValue(context_, JS_GetException(context_)); + return buffer; + } + JS_FreeValue(context_, buffer); + return JS_UNDEFINED; +} + JSValueConst napi_env__::data_view_constructor() const { return data_view_constructor_; diff --git a/quickjs/src/internal/napi_env.h b/quickjs/src/internal/napi_env.h index 9da36db4ff..b97bdb837a 100644 --- a/quickjs/src/internal/napi_env.h +++ b/quickjs/src/internal/napi_env.h @@ -74,6 +74,17 @@ struct napi_env__ // The env realm's DataView constructor, read when the env was made, before // any script could replace it; undefined if there was none. JSValueConst data_view_constructor() const; + // The ArrayBuffer a typed array or DataView views, read through the + // intrinsic buffer getters as the env was made, never through the view's + // own `buffer` property, which scripts can redefine. JS_UNDEFINED for + // anything else. Leaves any pending exception as it was. + JSValue view_buffer(JSValueConst view) const; + // After an accessor of a typed array or DataView threw: the view's + // ArrayBuffer if it is detached (QuickJS's accessors throw for it; Node + // reports such a view as having no data and a length of 0), with that + // exception cleared. Otherwise JS_UNDEFINED, with the exception still + // pending. + JSValue detached_view_buffer(JSValueConst view) const; // A function of the current realm that keeps it alive; undefined for the // env's own realm. JSValueConst current_realm_anchor() const; @@ -201,6 +212,10 @@ struct napi_env__ JSContext *context_; int32_t module_api_version_ = 8; JSValue data_view_constructor_ = JS_UNDEFINED; + // The getters of %TypedArray%.prototype.buffer and DataView.prototype.buffer, + // read when the env was made; undefined if there were none. + JSValue typed_array_buffer_getter_ = JS_UNDEFINED; + JSValue data_view_buffer_getter_ = JS_UNDEFINED; // The realms N-API acts in, innermost last. Empty means the env's own. std::vector realm_frames_; diff --git a/quickjs/src/internal/napi_util.cc b/quickjs/src/internal/napi_util.cc index 01ebff22c7..da781fd1d9 100644 --- a/quickjs/src/internal/napi_util.cc +++ b/quickjs/src/internal/napi_util.cc @@ -596,34 +596,18 @@ bool napi_util__::from_quickjs_array_type(int type, napi_typedarray_type *out) bool napi_util__::is_detached_array_buffer(JSContext *ctx, JSValueConst value) { - if (!JS_IsArrayBuffer(value)) + if (ctx == nullptr || !JS_IsArrayBuffer(value)) return false; + // JS_GetArrayBuffer throws for a detached buffer only; what was pending + // before is set aside and kept. + JSValue earlier = JS_GetException(ctx); size_t length = 0; - if (JS_GetArrayBuffer(ctx, &length, value) != nullptr || !JS_HasException(ctx)) - return false; - JS_FreeValue(ctx, JS_GetException(ctx)); - return true; -} - -JSValue napi_util__::detached_view_buffer(JSContext *ctx, JSValueConst view) -{ - if (JS_GetTypedArrayType(view) < 0 && !JS_IsDataView(view)) - return JS_UNDEFINED; - JSValue thrown = JS_GetException(ctx); - // The buffer getters of typed arrays and DataViews do not throw for a - // detached buffer. - JSValue buffer = JS_GetPropertyStr(ctx, view, "buffer"); - if (!JS_IsException(buffer) && is_detached_array_buffer(ctx, buffer)) - { - JS_FreeValue(ctx, thrown); - return buffer; - } - if (JS_IsException(buffer)) + const bool detached = JS_GetArrayBuffer(ctx, &length, value) == nullptr && JS_HasException(ctx); + if (detached) JS_FreeValue(ctx, JS_GetException(ctx)); - else - JS_FreeValue(ctx, buffer); - JS_Throw(ctx, thrown); - return JS_UNDEFINED; + if (!JS_IsUninitialized(earlier)) + JS_Throw(ctx, earlier); + return detached; } void *napi_util__::realloc_array_buffer_data(JSRuntime *rt, void *opaque, void *ptr, size_t size) diff --git a/quickjs/src/internal/napi_util.h b/quickjs/src/internal/napi_util.h index 1673750423..32913516e3 100644 --- a/quickjs/src/internal/napi_util.h +++ b/quickjs/src/internal/napi_util.h @@ -68,15 +68,10 @@ class napi_util__ static void *realloc_array_buffer_data(JSRuntime *rt, void *opaque, void *ptr, size_t size); - // QuickJS's accessors throw for a detached ArrayBuffer and the views over - // one; Node reports them as having no data and a length of 0. - // True for a detached ArrayBuffer. Leaves no exception pending. + // True for a detached ArrayBuffer, which QuickJS's accessors throw for + // (Node reports it as having no data and a length of 0). Leaves any + // pending exception as it was. static bool is_detached_array_buffer(JSContext *ctx, JSValueConst value); - // After an accessor of a typed array or DataView threw: the view's - // ArrayBuffer if it is detached, with that exception cleared; otherwise - // (also when `view` is no such view) JS_UNDEFINED, with the exception - // still pending. - static JSValue detached_view_buffer(JSContext *ctx, JSValueConst view); static int key_filter_to_gpn(napi_key_filter key_filter); static napi_status get_property_names(napi_env env, diff --git a/quickjs/src/js_native_api_quickjs.cc b/quickjs/src/js_native_api_quickjs.cc index 7d881b4284..cde17423a1 100644 --- a/quickjs/src/js_native_api_quickjs.cc +++ b/quickjs/src/js_native_api_quickjs.cc @@ -525,7 +525,7 @@ extern "C" bool detached = false; if (JS_IsException(abuf)) { - abuf = napi_util__::detached_view_buffer(env->context(), local); + abuf = env->detached_view_buffer(local); if (JS_IsUndefined(abuf)) return napi_util__::return_pending_if_caught(env, "Failed to get typed array info"); detached = true; @@ -1455,7 +1455,10 @@ extern "C" if (!JS_IsDataView(view)) return napi_util__::invalid_arg(env); - JSValue buffer_val = JS_GetPropertyStr(env->context(), view, "buffer"); + // The view's own buffer, never what its `buffer` property says. + JSValue buffer_val = env->view_buffer(view); + if (JS_IsUndefined(buffer_val)) + buffer_val = JS_GetPropertyStr(env->context(), view, "buffer"); if (JS_IsException(buffer_val)) return napi_util__::return_pending_if_caught(env, "Failed to get DataView info"); // QuickJS's byteLength and byteOffset getters throw for a DataView over a diff --git a/tests/runners/test_33_typedarray.cc b/tests/runners/test_33_typedarray.cc index 9992383475..7dbc7e6d4c 100644 --- a/tests/runners/test_33_typedarray.cc +++ b/tests/runners/test_33_typedarray.cc @@ -317,6 +317,66 @@ TEST_F(Test33TypedArray, DetachedViewInfoIsEmpty) { expect_nothing_pending("data view"); } +// A view's own `buffer` property, which a script can redefine, does not +// decide which ArrayBuffer a view has, nor whether it is detached. +TEST_F(Test33TypedArray, ViewInfoIgnoresARedefinedBufferProperty) { + EnvScope s(runtime_.get()); + RunBufferScript(s.env, + "globalThis.backing = new ArrayBuffer(16);" + "globalThis.other = new ArrayBuffer(16);" + "globalThis.typed = new Uint8Array(backing);" + "Object.defineProperty(typed, 'buffer', { value: other });" + "globalThis.liveBacking = new ArrayBuffer(16);" + "globalThis.detachedOther = new ArrayBuffer(16);" + "globalThis.view = new DataView(liveBacking, 2, 4);" + "Object.defineProperty(view, 'buffer', { value: detachedOther });" + "0"); + napi_value global = nullptr; + ASSERT_EQ(napi_get_global(s.env, &global), napi_ok); + auto named = [&](const char* name) { + napi_value value = nullptr; + EXPECT_EQ(napi_get_named_property(s.env, global, name, &value), napi_ok); + return value; + }; + napi_value backing = named("backing"); + napi_value live_backing = named("liveBacking"); + ASSERT_EQ(napi_detach_arraybuffer(s.env, backing), napi_ok); + ASSERT_EQ(napi_detach_arraybuffer(s.env, named("other")), napi_ok); + ASSERT_EQ(napi_detach_arraybuffer(s.env, named("detachedOther")), napi_ok); + + // The typed array's own buffer is detached: empty, and that buffer. + size_t length = 99; + void* data = &length; + napi_value viewed = nullptr; + size_t offset = 99; + ASSERT_EQ( + napi_get_typedarray_info(s.env, named("typed"), nullptr, &length, &data, &viewed, &offset), + napi_ok); + EXPECT_EQ(length, 0u); + EXPECT_EQ(data, nullptr); + EXPECT_EQ(offset, 0u); + bool same = false; + ASSERT_EQ(napi_strict_equals(s.env, viewed, backing, &same), napi_ok); + EXPECT_TRUE(same) << "the typed array's own ArrayBuffer"; + + // The DataView's own buffer is alive: its bytes 2 to 6, and that buffer. + void* live_data = nullptr; + size_t live_length = 0; + ASSERT_EQ(napi_get_arraybuffer_info(s.env, live_backing, &live_data, &live_length), napi_ok); + length = 99; + data = nullptr; + viewed = nullptr; + offset = 99; + ASSERT_EQ(napi_get_dataview_info(s.env, named("view"), &length, &data, &viewed, &offset), + napi_ok); + EXPECT_EQ(length, 4u); + EXPECT_EQ(offset, 2u); + EXPECT_EQ(data, static_cast(live_data) + 2); + same = false; + ASSERT_EQ(napi_strict_equals(s.env, viewed, live_backing, &same), napi_ok); + EXPECT_TRUE(same) << "the DataView's own ArrayBuffer"; +} + #if defined(NAPI_TEST_ENGINE_QUICKJS) TEST_F(Test33TypedArray, ExternalArrayBufferResizeFailurePreservesBackingStore) { ExternalBufferState state; From d065cee79e8c93bc764d1429018f96fd5c6218d0 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 18:00:50 -0800 Subject: [PATCH 061/150] V8: forget an env's error formatting state after its release DestroyEnvInstance dropped the runtime's per-env state (error formatting and prepare-stack-trace callbacks, kept in maps keyed by the env's address) before deleting the env, so before the release ran its hooks and finalizers. Those can make such state again: napi_get_and_clear_last_exception keeps the taken error's formatting, with v8::Global handles. The entry outlived the env and its isolate. An env made later at the same address found it, and its release reset those handles: V8 aborted with "Check failed: node->IsInUse()" in GlobalHandles::NodeSpace::Release under ResetErrorFormattingState. This predates the series; the new release tests, run in one process, hit it. The env's release now drops that state again once its hooks and finalizers have run, at the end of ~napi_env__, while the env still owns its address (unofficial_napi_internal::ForgetEnvState, also used by DestroyEnvInstance as before). Test: 32 envs in a row, each with a hook that throws at release and takes the error back with napi_get_and_clear_last_exception. Before the fix the V8 Release build aborted (the ASan build, whose allocator does not reuse addresses at once, did not). Co-Authored-By: Claude Opus 5.5 --- tests/runners/test_41_instance_data.cc | 23 +++++++++++++++++++++++ v8/src/js_native_api_v8.cc | 5 +++++ v8/src/unofficial_napi.cc | 22 ++++++++++++++++------ v8/src/unofficial_napi_error_utils.h | 3 +++ 4 files changed, 47 insertions(+), 6 deletions(-) diff --git a/tests/runners/test_41_instance_data.cc b/tests/runners/test_41_instance_data.cc index c83e9baaf0..d8d228a85e 100644 --- a/tests/runners/test_41_instance_data.cc +++ b/tests/runners/test_41_instance_data.cc @@ -1353,3 +1353,26 @@ TEST_F(Test41InstanceData, TheInstanceDataFinalizerRunsForNullData) { EXPECT_EQ(null_data, std::vector{nullptr}); EXPECT_EQ(set_at_release, (std::vector{&marker, nullptr})); } + +namespace { + +// A hook that throws at release and takes the exception back. +void HookThrowingAndTaking(void* arg) { + auto env = static_cast(arg); + napi_throw_error(env, nullptr, "taken at release"); + napi_value error = nullptr; + napi_get_and_clear_last_exception(env, &error); +} + +} // namespace + +// What N-API keeps for an env while its release runs (here, the error a hook +// takes back) goes with the env: envs made later, which may reuse its +// address, start without it. +TEST_F(Test41InstanceData, StateMadeAtReleaseGoesWithTheEnv) { + for (int i = 0; i < 32; ++i) { + EnvScope s(runtime_.get()); + ASSERT_EQ(napi_add_env_cleanup_hook(s.env, HookThrowingAndTaking, s.env), napi_ok); + Release(s); + } +} diff --git a/v8/src/js_native_api_v8.cc b/v8/src/js_native_api_v8.cc index d5631b790b..0d3cbe99ca 100644 --- a/v8/src/js_native_api_v8.cc +++ b/v8/src/js_native_api_v8.cc @@ -1014,6 +1014,11 @@ napi_env__::~napi_env__() { // Backstop: nothing above should leave a scope open, and a context still // entered here would abort V8 at the embedder's next Context::Exit. PopRealmFrames(0); + // The hooks and finalizers above can make state the runtime keeps by the + // env's address (napi_get_and_clear_last_exception keeps the error's + // formatting). Left behind, an env made later at the same address would + // find it, and reset handles of an isolate already disposed. + unofficial_napi_internal::ForgetEnvState(this); if (agent != nullptr && agent->principal_env == this) { agent->principal_env = nullptr; } diff --git a/v8/src/unofficial_napi.cc b/v8/src/unofficial_napi.cc index 447fb6a7cb..af1a03317d 100644 --- a/v8/src/unofficial_napi.cc +++ b/v8/src/unofficial_napi.cc @@ -1648,6 +1648,20 @@ void NapiV8ApplyPromiseHooksToContext(napi_env env, v8::Local conte #endif } +namespace unofficial_napi_internal { + +void ForgetEnvState(napi_env env) { + std::lock_guard lock(g_runtime_mu); + auto prepare_it = g_prepare_stack_trace_callbacks.find(env); + if (prepare_it != g_prepare_stack_trace_callbacks.end()) { + ResetPrepareStackTraceState(&prepare_it->second); + g_prepare_stack_trace_callbacks.erase(prepare_it); + } + ResetErrorFormattingState(env); +} + +} // namespace unofficial_napi_internal + extern "C" { napi_status NAPI_CDECL unofficial_napi_configure_runtime( @@ -1743,13 +1757,8 @@ static napi_status DestroyEnvInstance(napi_env env) { if (g_runtime.platform != nullptr) { g_runtime.platform->ClearForegroundTaskTarget(env->isolate, env); } - auto prepare_it = g_prepare_stack_trace_callbacks.find(env); - if (prepare_it != g_prepare_stack_trace_callbacks.end()) { - ResetPrepareStackTraceState(&prepare_it->second); - g_prepare_stack_trace_callbacks.erase(prepare_it); - } - unofficial_napi_internal::ResetErrorFormattingState(env); } + unofficial_napi_internal::ForgetEnvState(env); env->promise_reject_callback.Reset(); for (auto& hook : env->promise_hooks) { hook.Reset(); @@ -1758,6 +1767,7 @@ static napi_status DestroyEnvInstance(napi_env env) { if (env->agent != nullptr && env->agent->principal_env == env) { env->agent->Shutdown(); } + // Its release forgets the state again once its hooks and finalizers ran. delete env; return napi_ok; } diff --git a/v8/src/unofficial_napi_error_utils.h b/v8/src/unofficial_napi_error_utils.h index 212a053a6b..9628abbf6d 100644 --- a/v8/src/unofficial_napi_error_utils.h +++ b/v8/src/unofficial_napi_error_utils.h @@ -42,6 +42,9 @@ napi_status GetErrorMetadata(napi_env env, unofficial_napi_error_metadata_mode mode, unofficial_napi_error_metadata* out); void ResetErrorFormattingState(napi_env env); +// Drops what the runtime keeps for `env` outside it, keyed by its address: +// its error formatting and prepare-stack-trace state. Takes the runtime lock. +void ForgetEnvState(napi_env env); } // namespace unofficial_napi_internal From eb19903398d0ffe7b09791b8a49e13808c5d9c32 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 15:02:38 -0800 Subject: [PATCH 062/150] Bring back the contextify calls and version-1 option structs on realms next removed unofficial_napi_contextify_make_context, _run_script and _compile_function, and changed the bytecode-open and module-create options in place, so code built against main stopped compiling or misread its structs. The calls are back with main's signatures, marked deprecated, as one engine-independent layer over the public realm API (lib/src/napi_compat.cc, built into both providers). A sandbox or parsing context names the realm of a contextified object, the env's realm for the env's own global, or the current realm when there is none, as the env's context did on main. Both option structs keep main's version-1 layout and append realm_or_null as version 2. Version 1 works in the current realm. A version-2 module struct may still use the deprecated context_or_undefined, where nothing means the env's realm. The header gains UNOFFICIAL_NAPI_DEPRECATED and friends, silenced by UNOFFICIAL_NAPI_NO_DEPRECATION_WARNINGS, and keeps C++ code that merely copies a struct with a deprecated field from warning. The wasm32 layouts follow, and the guest layer reads them. Guests built against main send main's layouts: bytecode-open options of 48 bytes and module-create options of 40 bytes with context_or_undefined, both version 1. Guests built against this header send version 2, which appends a u32 realm id. The readers take each struct by its version and read only that version's bytes. A new src/guest/compat.rs maps the old context arguments to realm ids for both guest backends, as lib/src/napi_compat.cc does natively. Version 1 bytecode compiles for the current realm. A version 1 module's context is a contextified object (its realm), the env's global (the env's realm) or nothing (the current realm). Version 2 takes realm_or_null, and with no realm treats nothing as the env's realm; naming both a realm and a context is napi_invalid_arg. The current realm is the realm of napi_get_global's value, unless that value is the env's own global. The WAT test guest sent version 2 module options of version 1's size. It now sends main's version 1 bytes. Co-Authored-By: Claude Opus 5.5 --- build.rs | 1 + include/unofficial_napi.h | 148 ++++++++++++- include/unofficial_napi_wasm32_abi.h | 25 ++- lib/src/napi_compat.cc | 202 ++++++++++++++++++ lib/src/napi_compat.h | 40 ++++ quickjs/CMakeLists.txt | 1 + quickjs/src/unofficial_napi.cc | 25 ++- src/guest/abi.rs | 135 +++++++++--- src/guest/compat.rs | 135 ++++++++++++ src/guest/mod.rs | 1 + src/guest/napi.rs | 20 +- src/guest/napi_js.rs | 20 +- tests/build-test-native.sh | 1 + .../runners/test_65_unofficial_contextify.cc | 2 +- tests/runners/test_66_unofficial_realm.cc | 8 +- tests/wat_guest/mod.rs | 4 +- v8/CMakeLists.txt | 1 + v8/src/unofficial_napi_contextify.cc | 28 +-- 18 files changed, 720 insertions(+), 77 deletions(-) create mode 100644 lib/src/napi_compat.cc create mode 100644 lib/src/napi_compat.h create mode 100644 src/guest/compat.rs diff --git a/build.rs b/build.rs index 8f8a803e8b..cfa8003e06 100644 --- a/build.rs +++ b/build.rs @@ -106,6 +106,7 @@ fn main() { .unwrap(), ) .file(napi_lib_src.join("napi_buffer_lease.cc").to_str().unwrap()) + .file(napi_lib_src.join("napi_compat.cc").to_str().unwrap()) .file(napi_lib_src.join("napi_periodic_gate.cc").to_str().unwrap()) .file(napi_lib_src.join("napi_text.cc").to_str().unwrap()) .file( diff --git a/include/unofficial_napi.h b/include/unofficial_napi.h index 449317359c..708d0db2b4 100644 --- a/include/unofficial_napi.h +++ b/include/unofficial_napi.h @@ -5,6 +5,46 @@ #include "js_native_api.h" +// Marks the API kept only for compatibility with code written against +// version 1 of these extensions: the contextify calls, the context-token +// hooks and the module options' `context_or_undefined`. It still works and +// is removed in a future major release. Define +// UNOFFICIAL_NAPI_NO_DEPRECATION_WARNINGS to silence the warnings. +#if defined(UNOFFICIAL_NAPI_NO_DEPRECATION_WARNINGS) +#define UNOFFICIAL_NAPI_DEPRECATED(message) +#elif defined(__GNUC__) || defined(__clang__) +#define UNOFFICIAL_NAPI_DEPRECATED(message) __attribute__((deprecated(message))) +#elif defined(_MSC_VER) +#define UNOFFICIAL_NAPI_DEPRECATED(message) __declspec(deprecated(message)) +#else +#define UNOFFICIAL_NAPI_DEPRECATED(message) +#endif + +// The same for struct fields and enumerators, which MSVC cannot mark. +#if !defined(UNOFFICIAL_NAPI_NO_DEPRECATION_WARNINGS) && \ + (defined(__GNUC__) || defined(__clang__)) +#define UNOFFICIAL_NAPI_DEPRECATED_MEMBER(message) __attribute__((deprecated(message))) +#else +#define UNOFFICIAL_NAPI_DEPRECATED_MEMBER(message) +#endif + +// Silences deprecation warnings in between, for code that implements the +// deprecated API. Around a struct with deprecated fields it also keeps C++ +// compilers from warning wherever the struct is merely copied. +#if defined(__GNUC__) || defined(__clang__) +#define UNOFFICIAL_NAPI_SUPPRESS_DEPRECATED_BEGIN \ + _Pragma("GCC diagnostic push") \ + _Pragma("GCC diagnostic ignored \"-Wdeprecated-declarations\"") +#define UNOFFICIAL_NAPI_SUPPRESS_DEPRECATED_END _Pragma("GCC diagnostic pop") +#elif defined(_MSC_VER) +#define UNOFFICIAL_NAPI_SUPPRESS_DEPRECATED_BEGIN \ + __pragma(warning(push)) __pragma(warning(disable : 4996)) +#define UNOFFICIAL_NAPI_SUPPRESS_DEPRECATED_END __pragma(warning(pop)) +#else +#define UNOFFICIAL_NAPI_SUPPRESS_DEPRECATED_BEGIN +#define UNOFFICIAL_NAPI_SUPPRESS_DEPRECATED_END +#endif + #ifdef __cplusplus extern "C" { #endif @@ -807,7 +847,9 @@ NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_create_serdes_binding(n // Script, function and module compilation. These are engine-specific APIs // and are not part of the public Node-API. Each runs or compiles code in -// `realm_or_null`, or in the env's own realm when it is NULL. +// `realm_or_null`, or in the env's own realm when it is NULL. The deprecated +// forms (the contextify calls and version 1 of the option structs) work in +// the current realm instead, as they did before realms existed. // Provider-owned compiled JavaScript, compiled for one realm. The handle is // bound to its env and must be released explicitly. @@ -865,12 +907,15 @@ typedef enum { unofficial_napi_bytecode_cache_compile_on_reject = 0, unofficial_napi_bytecode_cache_validate_only = 1, } unofficial_napi_bytecode_cache_policy; -// Version 2 added `realm_or_null`, the realm the code is compiled for. + +// Version 2 appended `realm_or_null`, the realm the code is compiled for (NULL: +// the env's own). Version 1, which ends before it (`size` at least +// UNOFFICIAL_NAPI_BYTECODE_OPEN_OPTIONS_V1_SIZE), is deprecated but still +// accepted: it compiles for the current realm. #define UNOFFICIAL_NAPI_BYTECODE_OPEN_OPTIONS_VERSION 2u typedef struct unofficial_napi_bytecode_open_options { uint32_t size; uint32_t version; - unofficial_napi_realm realm_or_null; napi_value source_text; napi_value filename; int32_t shape; @@ -882,8 +927,13 @@ typedef struct unofficial_napi_bytecode_open_options { size_t cache_byte_length; uint8_t has_cache; uint8_t cache_policy; + // Version 2. + unofficial_napi_realm realm_or_null; } unofficial_napi_bytecode_open_options; +#define UNOFFICIAL_NAPI_BYTECODE_OPEN_OPTIONS_V1_SIZE \ + offsetof(unofficial_napi_bytecode_open_options, realm_or_null) + typedef struct unofficial_napi_bytecode_open_result { unofficial_napi_bytecode bytecode; uint8_t cache_rejected; @@ -937,6 +987,69 @@ NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_compile_function( napi_value host_defined_option_id, napi_value* result_out); +// Deprecated: the contextify calls, which take contextified objects instead of +// realms. Use unofficial_napi_create_realm, unofficial_napi_run_script and +// unofficial_napi_compile_function. They are kept for compatibility and +// removed in a future major release. Each is a thin wrapper over the realm +// API, so the objects and realms of both mix freely. + +// Deprecated: use unofficial_napi_create_realm. An object or function sandbox +// becomes the sandbox of a new realm; a symbol (vm.constants.DONT_CONTEXTIFY) +// makes a realm with a fresh global. The other arguments become the realm +// options of the same names (`origin_or_undefined` is `origin`). `result_out` +// receives the realm's global as create_realm reports it: the sandbox, or the +// fresh global. Fails with napi_invalid_arg when `name` is NULL, for any other +// sandbox, and for a sandbox that already belongs to a realm. +UNOFFICIAL_NAPI_DEPRECATED("use unofficial_napi_create_realm") +NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_contextify_make_context( + napi_env env, + napi_value sandbox_or_symbol, + napi_value name, + napi_value origin_or_undefined, + bool allow_code_gen_strings, + bool allow_code_gen_wasm, + bool own_microtask_queue, + napi_value host_defined_option_id, + napi_value* result_out); + +// Deprecated: use unofficial_napi_run_script. The script runs in the realm +// `sandbox_or_null` names: the realm of a contextified object (a realm's +// global or sandbox), the env's realm for the env's own global, or the +// current realm for NULL, undefined or null. Unlike unofficial_napi_run_script +// with a NULL realm, that is the realm entered or of the running callback, +// which is the env's own unless the embedder enters realms. Any other value +// fails with napi_invalid_arg. +UNOFFICIAL_NAPI_DEPRECATED("use unofficial_napi_run_script") +NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_contextify_run_script( + napi_env env, + napi_value sandbox_or_null, + const unofficial_napi_js_source* source, + napi_value filename, + int32_t line_offset, + int32_t column_offset, + int64_t timeout, + bool display_errors, + bool break_on_sigint, + bool break_on_first_line, + napi_value host_defined_option_id, + napi_value* result_out); + +// Deprecated: use unofficial_napi_compile_function. The function is compiled +// in the realm `parsing_context_or_undefined` names, which resolves as +// unofficial_napi_contextify_run_script's `sandbox_or_null` does. +UNOFFICIAL_NAPI_DEPRECATED("use unofficial_napi_compile_function") +NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_contextify_compile_function( + napi_env env, + const unofficial_napi_js_source* source, + napi_value filename, + int32_t line_offset, + int32_t column_offset, + napi_value parsing_context_or_undefined, + napi_value context_extensions_or_undefined, + napi_value params_or_undefined, + napi_value host_defined_option_id, + napi_value* result_out); + NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_contextify_contains_module_syntax( napi_env env, napi_value code, @@ -951,9 +1064,19 @@ typedef struct unofficial_napi_module__* unofficial_napi_module; // Versioned, tagged transaction for creating either kind of module. Keeping // creation behind one descriptor gives providers one validation boundary and -// lets the ABI grow without adding one import per module kind. The module -// lives in `realm_or_null`, or in the env's realm. Version 2 replaced -// `context_or_undefined` with it; providers reject version 1. +// lets the ABI grow without adding one import per module kind. +// +// Version 2 appended `realm_or_null`, the realm the module lives in. Version +// 1, which ends before it (`size` at least +// UNOFFICIAL_NAPI_MODULE_CREATE_OPTIONS_V1_SIZE), is deprecated but still +// accepted. The realm is: +// - version 2 with `realm_or_null` set: that realm. `context_or_undefined` +// must then be NULL, undefined or null, else napi_invalid_arg. +// - otherwise, from the deprecated `context_or_undefined`: the realm of a +// contextified object (a realm's global or sandbox), the env's realm for +// the env's own global, and for NULL, undefined or null the env's realm +// (version 2) or the current realm (version 1). Any other value is +// napi_invalid_arg. #define UNOFFICIAL_NAPI_MODULE_CREATE_OPTIONS_VERSION 2u typedef enum { @@ -973,18 +1096,29 @@ typedef struct { napi_value synthetic_evaluation_steps; } unofficial_napi_synthetic_module_options; +UNOFFICIAL_NAPI_SUPPRESS_DEPRECATED_BEGIN typedef struct { size_t size; uint32_t version; unofficial_napi_module_kind kind; napi_value wrapper; napi_value url; - unofficial_napi_realm realm_or_null; + // Deprecated: use `realm_or_null`, with unofficial_napi_get_realm on the + // contextified object. Kept for compatibility and removed in a future major + // release. + napi_value context_or_undefined + UNOFFICIAL_NAPI_DEPRECATED_MEMBER("use realm_or_null"); union { unofficial_napi_source_text_module_options source_text; unofficial_napi_synthetic_module_options synthetic; } payload; + // Version 2. + unofficial_napi_realm realm_or_null; } unofficial_napi_module_create_options; +UNOFFICIAL_NAPI_SUPPRESS_DEPRECATED_END + +#define UNOFFICIAL_NAPI_MODULE_CREATE_OPTIONS_V1_SIZE \ + offsetof(unofficial_napi_module_create_options, realm_or_null) // Immutable metadata produced by the same transaction that creates a module. // The layout is selected by options.version, so adding fields requires a new diff --git a/include/unofficial_napi_wasm32_abi.h b/include/unofficial_napi_wasm32_abi.h index 6881d3c268..0a53303459 100644 --- a/include/unofficial_napi_wasm32_abi.h +++ b/include/unofficial_napi_wasm32_abi.h @@ -44,7 +44,6 @@ typedef struct { typedef struct { uint32_t size; uint32_t version; - uint32_t realm_or_null; uint32_t source_text; uint32_t filename; int32_t shape; @@ -57,6 +56,12 @@ typedef struct { uint8_t has_cache; uint8_t cache_policy; uint8_t reserved[2]; +} unofficial_napi_wasm32_bytecode_open_options_v1; + +// Version 2 appends the realm. +typedef struct { + unofficial_napi_wasm32_bytecode_open_options_v1 v1; + uint32_t realm_or_null; } unofficial_napi_wasm32_bytecode_open_options_v2; typedef struct { @@ -65,8 +70,14 @@ typedef struct { int32_t kind; uint32_t wrapper; uint32_t url; - uint32_t realm_or_null; + uint32_t context_or_undefined; uint8_t payload[16]; +} unofficial_napi_wasm32_module_create_options_v1; + +// Version 2 appends the realm. +typedef struct { + unofficial_napi_wasm32_module_create_options_v1 v1; + uint32_t realm_or_null; } unofficial_napi_wasm32_module_create_options_v2; typedef struct { @@ -94,8 +105,10 @@ static_assert(sizeof(unofficial_napi_wasm32_runtime_options_v1) == 16); static_assert(sizeof(unofficial_napi_wasm32_env_create_options_v1) == 48); static_assert(sizeof(unofficial_napi_wasm32_env_hooks_v2) == 24); static_assert(sizeof(unofficial_napi_wasm32_js_source) == 12); +static_assert(sizeof(unofficial_napi_wasm32_bytecode_open_options_v1) == 48); static_assert(sizeof(unofficial_napi_wasm32_bytecode_open_options_v2) == 52); -static_assert(sizeof(unofficial_napi_wasm32_module_create_options_v2) == 40); +static_assert(sizeof(unofficial_napi_wasm32_module_create_options_v1) == 40); +static_assert(sizeof(unofficial_napi_wasm32_module_create_options_v2) == 44); static_assert(sizeof(unofficial_napi_wasm32_module_hooks_v1) == 16); static_assert(sizeof(unofficial_napi_wasm32_realm_options_v1) == 28); #else @@ -107,9 +120,13 @@ _Static_assert(sizeof(unofficial_napi_wasm32_env_hooks_v2) == 24, "wasm32 env-hooks wire layout changed"); _Static_assert(sizeof(unofficial_napi_wasm32_js_source) == 12, "wasm32 JS-source wire layout changed"); +_Static_assert(sizeof(unofficial_napi_wasm32_bytecode_open_options_v1) == 48, + "wasm32 bytecode-open wire layout changed"); _Static_assert(sizeof(unofficial_napi_wasm32_bytecode_open_options_v2) == 52, "wasm32 bytecode-open wire layout changed"); -_Static_assert(sizeof(unofficial_napi_wasm32_module_create_options_v2) == 40, +_Static_assert(sizeof(unofficial_napi_wasm32_module_create_options_v1) == 40, + "wasm32 module-create wire layout changed"); +_Static_assert(sizeof(unofficial_napi_wasm32_module_create_options_v2) == 44, "wasm32 module-create wire layout changed"); _Static_assert(sizeof(unofficial_napi_wasm32_module_hooks_v1) == 16, "wasm32 module-hooks wire layout changed"); diff --git a/lib/src/napi_compat.cc b/lib/src/napi_compat.cc new file mode 100644 index 0000000000..9ae02da98e --- /dev/null +++ b/lib/src/napi_compat.cc @@ -0,0 +1,202 @@ +// This file implements the deprecated API. +#define UNOFFICIAL_NAPI_NO_DEPRECATION_WARNINGS +#include "napi_compat.h" + +namespace napi::compat { +namespace { + +bool is_nullish(napi_env env, napi_value value, napi_valuetype* type_out) { + *type_out = napi_undefined; + if (value == nullptr) return true; + if (napi_typeof(env, value, type_out) != napi_ok) { + *type_out = napi_undefined; + return false; + } + return *type_out == napi_undefined || *type_out == napi_null; +} + +// The env's own global, whichever realm is current. +napi_status env_global(napi_env env, napi_value* global_out) { + unofficial_napi_realm_scope scope = 0; + napi_status status = unofficial_napi_enter_realm(env, nullptr, &scope); + if (status != napi_ok) return status; + status = napi_get_global(env, global_out); + const napi_status left = unofficial_napi_leave_realm(env, scope); + return status != napi_ok ? status : left; +} + +napi_status is_env_global(napi_env env, napi_value value, bool* result_out) { + napi_value global = nullptr; + napi_status status = env_global(env, &global); + if (status != napi_ok) return status; + return napi_strict_equals(env, value, global, result_out); +} + +} // namespace + +napi_status current_realm(napi_env env, unofficial_napi_realm* realm_out) { + *realm_out = nullptr; + napi_value global = nullptr; + napi_status status = napi_get_global(env, &global); + if (status != napi_ok) return status; + unofficial_napi_realm realm = nullptr; + status = unofficial_napi_get_realm(env, global, &realm); + if (status != napi_ok || realm == nullptr) return status; + bool env_own = false; + status = is_env_global(env, global, &env_own); + if (status != napi_ok) return status; + if (!env_own) *realm_out = realm; + return napi_ok; +} + +napi_status realm_from_context(napi_env env, + napi_value context, + bool nullish_is_current, + unofficial_napi_realm* realm_out) { + *realm_out = nullptr; + napi_valuetype type = napi_undefined; + if (is_nullish(env, context, &type)) { + return nullish_is_current ? current_realm(env, realm_out) : napi_ok; + } + if (type != napi_object && type != napi_function) return napi_invalid_arg; + if (unofficial_napi_get_realm(env, context, realm_out) != napi_ok) return napi_invalid_arg; + if (*realm_out != nullptr) return napi_ok; + bool env_own = false; + const napi_status status = is_env_global(env, context, &env_own); + if (status != napi_ok) return status; + return env_own ? napi_ok : napi_invalid_arg; +} + +napi_status bytecode_open_realm(napi_env env, + const unofficial_napi_bytecode_open_options* options, + unofficial_napi_realm* realm_out) { + *realm_out = nullptr; + if (options == nullptr) return napi_invalid_arg; + if (options->version == 1) { + if (options->size < UNOFFICIAL_NAPI_BYTECODE_OPEN_OPTIONS_V1_SIZE) return napi_invalid_arg; + return current_realm(env, realm_out); + } + if (options->version != UNOFFICIAL_NAPI_BYTECODE_OPEN_OPTIONS_VERSION || + options->size < sizeof(*options)) { + return napi_invalid_arg; + } + *realm_out = options->realm_or_null; + return napi_ok; +} + +napi_status module_create_realm(napi_env env, + const unofficial_napi_module_create_options* options, + unofficial_napi_realm* realm_out) { + *realm_out = nullptr; + if (options == nullptr) return napi_invalid_arg; + const bool v1 = options->version == 1; + if (v1 ? options->size < UNOFFICIAL_NAPI_MODULE_CREATE_OPTIONS_V1_SIZE + : options->version != UNOFFICIAL_NAPI_MODULE_CREATE_OPTIONS_VERSION || + options->size < sizeof(*options)) { + return napi_invalid_arg; + } + if (!v1 && options->realm_or_null != nullptr) { + napi_valuetype type = napi_undefined; + if (!is_nullish(env, options->context_or_undefined, &type)) return napi_invalid_arg; + *realm_out = options->realm_or_null; + return napi_ok; + } + return realm_from_context(env, options->context_or_undefined, v1, realm_out); +} + +} // namespace napi::compat + +extern "C" { + +napi_status NAPI_CDECL unofficial_napi_contextify_make_context( + napi_env env, + napi_value sandbox_or_symbol, + napi_value name, + napi_value origin_or_undefined, + bool allow_code_gen_strings, + bool allow_code_gen_wasm, + bool own_microtask_queue, + napi_value host_defined_option_id, + napi_value* result_out) { + if (env == nullptr || sandbox_or_symbol == nullptr || name == nullptr || result_out == nullptr) { + return napi_invalid_arg; + } + napi_valuetype type = napi_undefined; + if (napi_typeof(env, sandbox_or_symbol, &type) != napi_ok || + (type != napi_symbol && type != napi_object && type != napi_function)) { + return napi_invalid_arg; + } + unofficial_napi_realm_options options; + unofficial_napi_realm_options_init(&options); + options.sandbox_or_null = type == napi_symbol ? nullptr : sandbox_or_symbol; + options.name = name; + options.origin = origin_or_undefined; + options.host_defined_option_id = host_defined_option_id; + options.allow_code_gen_strings = allow_code_gen_strings; + options.allow_code_gen_wasm = allow_code_gen_wasm; + options.own_microtask_queue = own_microtask_queue; + unofficial_napi_realm realm = nullptr; + return unofficial_napi_create_realm(env, &options, &realm, result_out); +} + +napi_status NAPI_CDECL unofficial_napi_contextify_run_script( + napi_env env, + napi_value sandbox_or_null, + const unofficial_napi_js_source* source, + napi_value filename, + int32_t line_offset, + int32_t column_offset, + int64_t timeout, + bool display_errors, + bool break_on_sigint, + bool break_on_first_line, + napi_value host_defined_option_id, + napi_value* result_out) { + if (env == nullptr) return napi_invalid_arg; + unofficial_napi_realm realm = nullptr; + const napi_status status = + napi::compat::realm_from_context(env, sandbox_or_null, true, &realm); + if (status != napi_ok) return status; + return unofficial_napi_run_script(env, + realm, + source, + filename, + line_offset, + column_offset, + timeout, + display_errors, + break_on_sigint, + break_on_first_line, + host_defined_option_id, + result_out); +} + +napi_status NAPI_CDECL unofficial_napi_contextify_compile_function( + napi_env env, + const unofficial_napi_js_source* source, + napi_value filename, + int32_t line_offset, + int32_t column_offset, + napi_value parsing_context_or_undefined, + napi_value context_extensions_or_undefined, + napi_value params_or_undefined, + napi_value host_defined_option_id, + napi_value* result_out) { + if (env == nullptr) return napi_invalid_arg; + unofficial_napi_realm realm = nullptr; + const napi_status status = + napi::compat::realm_from_context(env, parsing_context_or_undefined, true, &realm); + if (status != napi_ok) return status; + return unofficial_napi_compile_function(env, + realm, + source, + filename, + line_offset, + column_offset, + context_extensions_or_undefined, + params_or_undefined, + host_defined_option_id, + result_out); +} + +} // extern "C" diff --git a/lib/src/napi_compat.h b/lib/src/napi_compat.h new file mode 100644 index 0000000000..95328b4a5f --- /dev/null +++ b/lib/src/napi_compat.h @@ -0,0 +1,40 @@ +#ifndef NAPI_COMPAT_H_ +#define NAPI_COMPAT_H_ + +#include "unofficial_napi.h" + +// The deprecated API (the contextify calls and version 1 of the option +// structs) on the public realm API, the same for every provider. Where it +// named a context it named a contextified object, the env's own global, or +// nothing for the current context, which is the current realm now. +namespace napi::compat { + +// The current realm: NULL for the env's own. The env's own global means the +// env's realm even when it is also a realm's sandbox, as the env's context +// did before realms existed. +napi_status current_realm(napi_env env, unofficial_napi_realm* realm_out); + +// The realm `context` names: a contextified object's (a realm's global or +// sandbox), the env's (NULL) for the env's own global, and for NULL, undefined +// or null the current realm, or the env's when `nullish_is_current` is false. +// Any other value fails with napi_invalid_arg. +napi_status realm_from_context(napi_env env, + napi_value context, + bool nullish_is_current, + unofficial_napi_realm* realm_out); + +// Checks the size and version of bytecode-open options (version 1 or 2) and +// returns the realm to compile for: version 1 compiles for the current realm. +napi_status bytecode_open_realm(napi_env env, + const unofficial_napi_bytecode_open_options* options, + unofficial_napi_realm* realm_out); + +// Checks the size and version of module-create options (version 1 or 2) and +// returns the realm the module lives in, as unofficial_napi.h describes. +napi_status module_create_realm(napi_env env, + const unofficial_napi_module_create_options* options, + unofficial_napi_realm* realm_out); + +} // namespace napi::compat + +#endif // NAPI_COMPAT_H_ diff --git a/quickjs/CMakeLists.txt b/quickjs/CMakeLists.txt index c1f1e2dd35..286a6d4643 100644 --- a/quickjs/CMakeLists.txt +++ b/quickjs/CMakeLists.txt @@ -56,6 +56,7 @@ file(GLOB_RECURSE NAPI_QUICKJS_SRC_FILES add_library(napi_quickjs STATIC ../lib/src/napi_buffer_lease.cc + ../lib/src/napi_compat.cc ../lib/src/napi_error_state.cc ../lib/src/napi_lifetime_tracker.cc ../lib/src/napi_periodic_gate.cc diff --git a/quickjs/src/unofficial_napi.cc b/quickjs/src/unofficial_napi.cc index 688e002723..04ca443c9c 100644 --- a/quickjs/src/unofficial_napi.cc +++ b/quickjs/src/unofficial_napi.cc @@ -8,6 +8,7 @@ #include "internal/napi_util.h" #include "internal/napi_shared_array_buffer.h" #include "internal/quickjs_trace.h" +#include "napi_compat.h" #include "node_api.h" #include @@ -1230,16 +1231,19 @@ extern "C" const unofficial_napi_bytecode_open_options *options, unofficial_napi_bytecode_open_result *result) { - if (!napi_util__::check_env(env) || options == nullptr || result == nullptr || - options->size < sizeof(*options) || - options->version != UNOFFICIAL_NAPI_BYTECODE_OPEN_OPTIONS_VERSION || - options->source_text == nullptr || options->filename == nullptr || + if (!napi_util__::check_env(env) || options == nullptr || result == nullptr) + return napi_invalid_arg; + unofficial_napi_realm realm = nullptr; + napi_status realm_status = napi::compat::bytecode_open_realm(env, options, &realm); + if (realm_status != napi_ok) + return realm_status; + if (options->source_text == nullptr || options->filename == nullptr || (options->cache_policy != unofficial_napi_bytecode_cache_compile_on_reject && options->cache_policy != unofficial_napi_bytecode_cache_validate_only)) return napi_invalid_arg; *result = {}; - JSContext *target = env->contextify().realm_context(options->realm_or_null); + JSContext *target = env->contextify().realm_context(realm); if (target == nullptr) return napi_invalid_arg; if (options->has_cache != 0 && options->cache_bytes != nullptr && @@ -1347,13 +1351,14 @@ extern "C" const unofficial_napi_module_create_options *options, unofficial_napi_module_create_result *result_out) { - if (!napi_util__::check_env(env) || options == nullptr || - options->size < sizeof(*options) || - options->version != UNOFFICIAL_NAPI_MODULE_CREATE_OPTIONS_VERSION || - result_out == nullptr) + if (!napi_util__::check_env(env) || options == nullptr || result_out == nullptr) return napi_invalid_arg; + unofficial_napi_realm realm = nullptr; + napi_status realm_status = napi::compat::module_create_realm(env, options, &realm); + if (realm_status != napi_ok) + return realm_status; *result_out = {}; - JSContext *ctx = env->contextify().realm_context(options->realm_or_null); + JSContext *ctx = env->contextify().realm_context(realm); if (ctx == nullptr) return napi_invalid_arg; napi_status status = napi_invalid_arg; diff --git a/src/guest/abi.rs b/src/guest/abi.rs index 09ed3183f3..464de4b817 100644 --- a/src/guest/abi.rs +++ b/src/guest/abi.rs @@ -49,10 +49,9 @@ struct Wasm32JsSource { } #[repr(C)] -struct Wasm32BytecodeOpenOptionsV2 { +struct Wasm32BytecodeOpenOptionsV1 { size: u32, version: u32, - realm_or_null: u32, source_text: u32, filename: u32, shape: i32, @@ -67,17 +66,31 @@ struct Wasm32BytecodeOpenOptionsV2 { reserved: [u8; 2], } +/// Version 2 appends the realm to version 1. #[repr(C)] -struct Wasm32ModuleCreateOptionsV2 { +struct Wasm32BytecodeOpenOptionsV2 { + v1: Wasm32BytecodeOpenOptionsV1, + realm_or_null: u32, +} + +#[repr(C)] +struct Wasm32ModuleCreateOptionsV1 { size: u32, version: u32, kind: i32, wrapper: u32, url: u32, - realm_or_null: u32, + context_or_undefined: u32, payload: [u8; 16], } +/// Version 2 appends the realm to version 1. +#[repr(C)] +struct Wasm32ModuleCreateOptionsV2 { + v1: Wasm32ModuleCreateOptionsV1, + realm_or_null: u32, +} + #[repr(C)] struct Wasm32ModuleCreateJsPayload { source: u32, @@ -118,8 +131,10 @@ struct Wasm32RealmOptionsV1 { const JS_SOURCE_SIZE: usize = std::mem::size_of::(); const RUNTIME_OPTIONS_SIZE: usize = std::mem::size_of::(); const ENV_CREATE_PREFIX_SIZE: usize = std::mem::size_of::(); -const BYTECODE_OPEN_SIZE: usize = std::mem::size_of::(); -const MODULE_CREATE_SIZE: usize = std::mem::size_of::(); +const BYTECODE_OPEN_V1_SIZE: usize = std::mem::size_of::(); +const BYTECODE_OPEN_V2_SIZE: usize = std::mem::size_of::(); +const MODULE_CREATE_V1_SIZE: usize = std::mem::size_of::(); +const MODULE_CREATE_V2_SIZE: usize = std::mem::size_of::(); const MODULE_HOOKS_SIZE: usize = std::mem::size_of::(); const ENV_HOOKS_SIZE: usize = std::mem::size_of::(); const REALM_OPTIONS_SIZE: usize = std::mem::size_of::(); @@ -128,8 +143,10 @@ const _: () = assert!(std::mem::size_of::() == 8); const _: () = assert!(JS_SOURCE_SIZE == 12); const _: () = assert!(RUNTIME_OPTIONS_SIZE == 16); const _: () = assert!(ENV_CREATE_PREFIX_SIZE == 48); -const _: () = assert!(BYTECODE_OPEN_SIZE == 52); -const _: () = assert!(MODULE_CREATE_SIZE == 40); +const _: () = assert!(BYTECODE_OPEN_V1_SIZE == 48); +const _: () = assert!(BYTECODE_OPEN_V2_SIZE == 52); +const _: () = assert!(MODULE_CREATE_V1_SIZE == 40); +const _: () = assert!(MODULE_CREATE_V2_SIZE == 44); const _: () = assert!(std::mem::size_of::() == 16); const _: () = assert!(std::mem::size_of::() == 16); const _: () = assert!(MODULE_HOOKS_SIZE == 16); @@ -166,6 +183,29 @@ fn read_versioned( Some(bytes) } +/// Reads a struct that grows at the end, whose version `n` is `sizes[n - 1]` +/// bytes long. Returns the version and only that version's bytes. +fn read_grown( + env: &mut FunctionEnvMut, + guest_ptr: u32, + sizes: &[usize], +) -> Option<(u32, Vec)> { + if guest_ptr == 0 { + return None; + } + let header = read_guest_bytes(env, guest_ptr, std::mem::size_of::())?; + let size = u32_at(&header, std::mem::offset_of!(Wasm32VersionedHeader, size))?; + let version = u32_at( + &header, + std::mem::offset_of!(Wasm32VersionedHeader, version), + )?; + let prefix_size = *sizes.get(usize::try_from(version).ok()?.checked_sub(1)?)?; + if size < prefix_size as u32 { + return None; + } + Some((version, read_guest_bytes(env, guest_ptr, prefix_size)?)) +} + pub(crate) fn read_output_header( env: &mut FunctionEnvMut, guest_ptr: u32, @@ -283,7 +323,10 @@ pub(crate) fn read_js_source( } pub(crate) struct BytecodeOpen { - /// The guest realm id (0 for the env's own realm). + /// 1 or 2. Version 1 compiles for the current realm. + pub version: u32, + /// The guest realm id of version 2 (0 for the env's own realm); 0 in + /// version 1. pub realm_or_null: u32, pub source_text: u32, pub filename: u32, @@ -301,18 +344,22 @@ pub(crate) fn read_bytecode_open( env: &mut FunctionEnvMut, guest_ptr: u32, ) -> Option { - let bytes = read_versioned(env, guest_ptr, BYTECODE_OPEN_SIZE, 2)?; + let (version, bytes) = read_grown( + env, + guest_ptr, + &[BYTECODE_OPEN_V1_SIZE, BYTECODE_OPEN_V2_SIZE], + )?; let cache_ptr = u32_at( &bytes, - std::mem::offset_of!(Wasm32BytecodeOpenOptionsV2, cache_bytes), + std::mem::offset_of!(Wasm32BytecodeOpenOptionsV1, cache_bytes), )?; let cache_length = u32_at( &bytes, - std::mem::offset_of!(Wasm32BytecodeOpenOptionsV2, cache_byte_length), + std::mem::offset_of!(Wasm32BytecodeOpenOptionsV1, cache_byte_length), )? as usize; - let has_cache = *bytes.get(std::mem::offset_of!(Wasm32BytecodeOpenOptionsV2, has_cache))?; + let has_cache = *bytes.get(std::mem::offset_of!(Wasm32BytecodeOpenOptionsV1, has_cache))?; let cache_policy = *bytes.get(std::mem::offset_of!( - Wasm32BytecodeOpenOptionsV2, + Wasm32BytecodeOpenOptionsV1, cache_policy ))?; let cache = if has_cache != 0 && cache_length != 0 { @@ -324,37 +371,42 @@ pub(crate) fn read_bytecode_open( Vec::new() }; Some(BytecodeOpen { - realm_or_null: u32_at( - &bytes, - std::mem::offset_of!(Wasm32BytecodeOpenOptionsV2, realm_or_null), - )?, + version, + realm_or_null: if version >= 2 { + u32_at( + &bytes, + std::mem::offset_of!(Wasm32BytecodeOpenOptionsV2, realm_or_null), + )? + } else { + 0 + }, source_text: u32_at( &bytes, - std::mem::offset_of!(Wasm32BytecodeOpenOptionsV2, source_text), + std::mem::offset_of!(Wasm32BytecodeOpenOptionsV1, source_text), )?, filename: u32_at( &bytes, - std::mem::offset_of!(Wasm32BytecodeOpenOptionsV2, filename), + std::mem::offset_of!(Wasm32BytecodeOpenOptionsV1, filename), )?, shape: i32_at( &bytes, - std::mem::offset_of!(Wasm32BytecodeOpenOptionsV2, shape), + std::mem::offset_of!(Wasm32BytecodeOpenOptionsV1, shape), )?, params_or_undefined: u32_at( &bytes, - std::mem::offset_of!(Wasm32BytecodeOpenOptionsV2, params_or_undefined), + std::mem::offset_of!(Wasm32BytecodeOpenOptionsV1, params_or_undefined), )?, host_defined_option_id: u32_at( &bytes, - std::mem::offset_of!(Wasm32BytecodeOpenOptionsV2, host_defined_option_id), + std::mem::offset_of!(Wasm32BytecodeOpenOptionsV1, host_defined_option_id), )?, line_offset: i32_at( &bytes, - std::mem::offset_of!(Wasm32BytecodeOpenOptionsV2, line_offset), + std::mem::offset_of!(Wasm32BytecodeOpenOptionsV1, line_offset), )?, column_offset: i32_at( &bytes, - std::mem::offset_of!(Wasm32BytecodeOpenOptionsV2, column_offset), + std::mem::offset_of!(Wasm32BytecodeOpenOptionsV1, column_offset), )?, cache, has_cache, @@ -363,10 +415,14 @@ pub(crate) fn read_bytecode_open( } pub(crate) struct ModuleCreate { + /// 1 or 2. + pub version: u32, pub kind: i32, pub wrapper: u32, pub url: u32, - /// The guest realm id (0 for the env's own realm). + /// The deprecated context's value id (0 for NULL). + pub context_or_undefined: u32, + /// The guest realm id of version 2 (0 for NULL); 0 in version 1. pub realm_or_null: u32, pub source_text: u32, pub source_bytecode: u32, @@ -381,12 +437,16 @@ pub(crate) fn read_module_create( env: &mut FunctionEnvMut, guest_ptr: u32, ) -> Option { - let bytes = read_versioned(env, guest_ptr, MODULE_CREATE_SIZE, 2)?; + let (version, bytes) = read_grown( + env, + guest_ptr, + &[MODULE_CREATE_V1_SIZE, MODULE_CREATE_V2_SIZE], + )?; let kind = i32_at( &bytes, - std::mem::offset_of!(Wasm32ModuleCreateOptionsV2, kind), + std::mem::offset_of!(Wasm32ModuleCreateOptionsV1, kind), )?; - let payload_offset = std::mem::offset_of!(Wasm32ModuleCreateOptionsV2, payload); + let payload_offset = std::mem::offset_of!(Wasm32ModuleCreateOptionsV1, payload); let ( source_text, source_bytecode, @@ -444,19 +504,28 @@ pub(crate) fn read_module_create( _ => return None, }; Some(ModuleCreate { + version, kind, wrapper: u32_at( &bytes, - std::mem::offset_of!(Wasm32ModuleCreateOptionsV2, wrapper), + std::mem::offset_of!(Wasm32ModuleCreateOptionsV1, wrapper), )?, url: u32_at( &bytes, - std::mem::offset_of!(Wasm32ModuleCreateOptionsV2, url), + std::mem::offset_of!(Wasm32ModuleCreateOptionsV1, url), )?, - realm_or_null: u32_at( + context_or_undefined: u32_at( &bytes, - std::mem::offset_of!(Wasm32ModuleCreateOptionsV2, realm_or_null), + std::mem::offset_of!(Wasm32ModuleCreateOptionsV1, context_or_undefined), )?, + realm_or_null: if version >= 2 { + u32_at( + &bytes, + std::mem::offset_of!(Wasm32ModuleCreateOptionsV2, realm_or_null), + )? + } else { + 0 + }, source_text, source_bytecode, line_offset, diff --git a/src/guest/compat.rs b/src/guest/compat.rs new file mode 100644 index 0000000000..13e47e4fab --- /dev/null +++ b/src/guest/compat.rs @@ -0,0 +1,135 @@ +//! The deprecated guest API (version 1 of the option structs) on the bridge's +//! realm calls, for both guest backends, as lib/src/napi_compat.cc does for +//! native code. Ids are guest value ids, 0 is NULL, and a realm id is the +//! value id of the realm's global or sandbox, 0 for the env's own realm. + +use crate::snapi::*; + +const NAPI_OK: i32 = 0; +const NAPI_INVALID_ARG: i32 = 1; + +// napi_valuetype. +const NAPI_UNDEFINED: i32 = 0; +const NAPI_NULL: i32 = 1; +const NAPI_OBJECT: i32 = 6; +const NAPI_FUNCTION: i32 = 7; + +fn check(status: i32) -> Result<(), i32> { + if status == NAPI_OK { + Ok(()) + } else { + Err(status) + } +} + +/// The type of `value`, or None when it is NULL or not a live value. +fn type_of(env: SnapiEnv, value: u32) -> Option { + if value == 0 { + return None; + } + let mut value_type = 0; + (unsafe { snapi_bridge_typeof(env, value, &mut value_type) } == NAPI_OK).then_some(value_type) +} + +fn is_nullish(env: SnapiEnv, value: u32) -> bool { + value == 0 || matches!(type_of(env, value), Some(NAPI_UNDEFINED | NAPI_NULL)) +} + +/// The env's own global, whichever realm is current. +fn env_global(env: SnapiEnv) -> Result { + let mut scope = 0u64; + check(unsafe { snapi_bridge_unofficial_enter_realm(env, 0, &mut scope) })?; + let mut global = 0u32; + let status = unsafe { snapi_bridge_get_global(env, &mut global) }; + let left = unsafe { snapi_bridge_unofficial_leave_realm(env, scope) }; + check(status)?; + check(left)?; + Ok(global) +} + +fn is_env_global(env: SnapiEnv, value: u32) -> Result { + let global = env_global(env)?; + let mut equal = 0i32; + check(unsafe { snapi_bridge_strict_equals(env, value, global, &mut equal) })?; + Ok(equal != 0) +} + +/// The id of the realm `value` is the global or sandbox of, 0 if none. +fn realm_of(env: SnapiEnv, value: u32) -> Result { + let mut realm = 0u32; + check(unsafe { snapi_bridge_unofficial_get_realm(env, value, &mut realm) })?; + Ok(realm) +} + +/// The current realm, which the env's context meant before realms. The env's +/// own global means the env's realm even when it is also a realm's sandbox. +pub(crate) fn current_realm(env: SnapiEnv) -> Result { + let mut global = 0u32; + check(unsafe { snapi_bridge_get_global(env, &mut global) })?; + let realm = realm_of(env, global)?; + if realm == 0 || is_env_global(env, global)? { + return Ok(0); + } + Ok(realm) +} + +/// The realm a context argument names: a contextified object's, the env's +/// for its own global, and for NULL, undefined or null the current realm, or +/// the env's when `nullish_is_current` is false. Anything else is +/// napi_invalid_arg. +pub(crate) fn realm_from_context( + env: SnapiEnv, + context: u32, + nullish_is_current: bool, +) -> Result { + match type_of(env, context) { + None if context == 0 => {} + Some(NAPI_UNDEFINED | NAPI_NULL) => {} + Some(NAPI_OBJECT | NAPI_FUNCTION) => { + let realm = realm_of(env, context).map_err(|_| NAPI_INVALID_ARG)?; + if realm != 0 || is_env_global(env, context)? { + return Ok(realm); + } + return Err(NAPI_INVALID_ARG); + } + _ => return Err(NAPI_INVALID_ARG), + } + if nullish_is_current { + current_realm(env) + } else { + Ok(0) + } +} + +/// The realm bytecode-open options compile for: the current realm in +/// version 1, `realm_or_null` in version 2. +pub(crate) fn bytecode_open_realm( + env: SnapiEnv, + version: u32, + realm_or_null: u32, +) -> Result { + if version == 1 { + current_realm(env) + } else { + Ok(realm_or_null) + } +} + +/// The realm module-create options make the module in. Version 2 takes +/// `realm_or_null`, and then the deprecated context must be nullish; else the +/// context names the realm, nullish meaning the current realm in version 1 +/// and the env's in version 2. +pub(crate) fn module_create_realm( + env: SnapiEnv, + version: u32, + context_or_undefined: u32, + realm_or_null: u32, +) -> Result { + if version >= 2 && realm_or_null != 0 { + if !is_nullish(env, context_or_undefined) { + return Err(NAPI_INVALID_ARG); + } + return Ok(realm_or_null); + } + realm_from_context(env, context_or_undefined, version == 1) +} diff --git a/src/guest/mod.rs b/src/guest/mod.rs index 90c4e963c2..6580ae8dce 100644 --- a/src/guest/mod.rs +++ b/src/guest/mod.rs @@ -6,6 +6,7 @@ pub mod callback; pub mod callback; #[cfg(not(all(target_arch = "wasm32", feature = "js")))] pub(crate) mod callback_cache; +pub(crate) mod compat; #[cfg(not(all(target_arch = "wasm32", feature = "js")))] pub mod napi; #[cfg(all(target_arch = "wasm32", feature = "js"))] diff --git a/src/guest/napi.rs b/src/guest/napi.rs index b9256b31c6..b839fba6a5 100644 --- a/src/guest/napi.rs +++ b/src/guest/napi.rs @@ -19,7 +19,7 @@ use crate::{ snapi::*, }; -use super::{abi, util::*}; +use super::{abi, compat, util::*}; fn guest_napi_wasm_init_env(mut env: FunctionEnvMut) -> i32 { let _ = unsafe { snapi_bridge_init() }; @@ -1312,13 +1312,18 @@ fn guest_unofficial_napi_bytecode_open( return 1; } let env_handle = snapi_env(&env, napi_env); + let realm = + match compat::bytecode_open_realm(env_handle, options.version, options.realm_or_null) { + Ok(realm) => realm, + Err(status) => return status, + }; let mut bytecode_id = 0u32; let mut cache_rejected = 0u8; let mut can_parse_as_module = 0u8; let status = unsafe { snapi_bridge_unofficial_bytecode_open( env_handle, - options.realm_or_null, + realm, options.source_text, options.filename, options.shape, @@ -1385,6 +1390,15 @@ fn guest_unofficial_napi_module_wrap_create( return 1; } let env_handle = snapi_env(&env, napi_env); + let realm = match compat::module_create_realm( + env_handle, + options.version, + options.context_or_undefined, + options.realm_or_null, + ) { + Ok(realm) => realm, + Err(status) => return status, + }; let mut handle_id = 0u32; let mut requests_id = 0u32; let mut has_top_level_await = 0u8; @@ -1394,7 +1408,7 @@ fn guest_unofficial_napi_module_wrap_create( options.kind, options.wrapper, options.url, - options.realm_or_null, + realm, options.source_text, options.source_bytecode, options.line_offset, diff --git a/src/guest/napi_js.rs b/src/guest/napi_js.rs index 73c39e2d40..1e0eff8a07 100644 --- a/src/guest/napi_js.rs +++ b/src/guest/napi_js.rs @@ -27,7 +27,7 @@ use crate::{ snapi::*, }; -use super::{abi, util::*}; +use super::{abi, compat, util::*}; use crate::snapi_js::{ host_js_get_named_property, host_js_has_named_property, host_js_put_primitive, host_js_set_named_property, host_js_value, @@ -1753,13 +1753,18 @@ fn guest_unofficial_napi_bytecode_open( return 1; } let env_handle = snapi_env(&env, napi_env); + let realm = + match compat::bytecode_open_realm(env_handle, options.version, options.realm_or_null) { + Ok(realm) => realm, + Err(status) => return status, + }; let mut bytecode_id = 0u32; let mut cache_rejected = 0u8; let mut can_parse_as_module = 0u8; let status = unsafe { snapi_bridge_unofficial_bytecode_open( env_handle, - options.realm_or_null, + realm, options.source_text, options.filename, options.shape, @@ -1826,6 +1831,15 @@ fn guest_unofficial_napi_module_wrap_create( return 1; } let env_handle = snapi_env(&env, napi_env); + let realm = match compat::module_create_realm( + env_handle, + options.version, + options.context_or_undefined, + options.realm_or_null, + ) { + Ok(realm) => realm, + Err(status) => return status, + }; let mut handle_id = 0u32; let mut requests_id = 0u32; let mut has_top_level_await = 0u8; @@ -1835,7 +1849,7 @@ fn guest_unofficial_napi_module_wrap_create( options.kind, options.wrapper, options.url, - options.realm_or_null, + realm, options.source_text, options.source_bytecode, options.line_offset, diff --git a/tests/build-test-native.sh b/tests/build-test-native.sh index e4d97eb38f..fb9f854604 100755 --- a/tests/build-test-native.sh +++ b/tests/build-test-native.sh @@ -196,6 +196,7 @@ done < <(find "$NAPI_INCLUDE_DIR" "$TEST_INCLUDE_DIR" -type f \( -name '*.h' -o NAPI_V8_SOURCES=( "$NAPI_LIB_SRC/napi_buffer_lease.cc" + "$NAPI_LIB_SRC/napi_compat.cc" "$NAPI_LIB_SRC/napi_error_state.cc" "$NAPI_LIB_SRC/napi_lifetime_tracker.cc" "$NAPI_LIB_SRC/napi_periodic_gate.cc" diff --git a/tests/runners/test_65_unofficial_contextify.cc b/tests/runners/test_65_unofficial_contextify.cc index dc9087a7b6..78ecc2cbdd 100644 --- a/tests/runners/test_65_unofficial_contextify.cc +++ b/tests/runners/test_65_unofficial_contextify.cc @@ -467,7 +467,7 @@ TEST_F(Test65UnofficialContextify, ModuleStateIsOneAtomicSnapshot) { EXPECT_EQ(unofficial_napi_module_wrap_create(s.env, &invalid_options, &create_result), napi_invalid_arg); invalid_options = create_options; - invalid_options.version = 1; + invalid_options.size = UNOFFICIAL_NAPI_MODULE_CREATE_OPTIONS_V1_SIZE; EXPECT_EQ(unofficial_napi_module_wrap_create(s.env, &invalid_options, &create_result), napi_invalid_arg); invalid_options = create_options; diff --git a/tests/runners/test_66_unofficial_realm.cc b/tests/runners/test_66_unofficial_realm.cc index ba922f9efb..e4e8aa97a8 100644 --- a/tests/runners/test_66_unofficial_realm.cc +++ b/tests/runners/test_66_unofficial_realm.cc @@ -355,9 +355,11 @@ TEST_F(Test66UnofficialRealm, BytecodeIsOpenedForARealm) { options.host_defined_option_id = undefined; unofficial_napi_bytecode_open_result opened{}; - unofficial_napi_bytecode_open_options v1 = options; - v1.version = 1; - EXPECT_EQ(unofficial_napi_bytecode_open(s.env, &v1, &opened), napi_invalid_arg); + // Version 2 must be long enough to hold the realm. (Version 1 is + // test_71's.) + unofficial_napi_bytecode_open_options short_v2 = options; + short_v2.size = UNOFFICIAL_NAPI_BYTECODE_OPEN_OPTIONS_V1_SIZE; + EXPECT_EQ(unofficial_napi_bytecode_open(s.env, &short_v2, &opened), napi_invalid_arg); for (unofficial_napi_realm target : {realm, static_cast(nullptr)}) { options.realm_or_null = target; diff --git a/tests/wat_guest/mod.rs b/tests/wat_guest/mod.rs index f4189e3737..3b296d7e51 100644 --- a/tests/wat_guest/mod.rs +++ b/tests/wat_guest/mod.rs @@ -152,6 +152,8 @@ const WAT: &str = r#"(module (i32.const 1) (i32.const 0) (i32.const 0) (i32.const 0) (i32.const 32))) ;; Creates, links, instantiates, evaluates and destroys a source text ;; module. Returns 0, or 1000 * step + status for the first failing step. + ;; The options are version 1, as a guest built against older headers + ;; sends them, with no context: the current realm. (func (export "eval_module") (param $ptr i32) (param $len i32) (result i32) (local $status i32) (local $module i32) (i32.store (i32.const 16) (i32.const 0)) @@ -159,7 +161,7 @@ const WAT: &str = r#"(module (i32.store (i32.const 24) (i32.const 0)) (if (call $create_object (global.get $env) (i32.const 52)) (then unreachable)) (i32.store (i32.const 128) (i32.const 40)) - (i32.store (i32.const 132) (i32.const 2)) + (i32.store (i32.const 132) (i32.const 1)) (i32.store (i32.const 136) (i32.const 1)) (i32.store (i32.const 140) (i32.load (i32.const 52))) (i32.store (i32.const 144) (call $string (i32.const 180) (i32.const 8))) diff --git a/v8/CMakeLists.txt b/v8/CMakeLists.txt index 15d5cbffb7..9d3a3d2ba6 100644 --- a/v8/CMakeLists.txt +++ b/v8/CMakeLists.txt @@ -35,6 +35,7 @@ endforeach() add_library(napi_v8 STATIC ../lib/src/napi_buffer_lease.cc + ../lib/src/napi_compat.cc ../lib/src/napi_error_state.cc ../lib/src/napi_lifetime_tracker.cc ../lib/src/napi_periodic_gate.cc diff --git a/v8/src/unofficial_napi_contextify.cc b/v8/src/unofficial_napi_contextify.cc index f76ada45a5..c792284287 100644 --- a/v8/src/unofficial_napi_contextify.cc +++ b/v8/src/unofficial_napi_contextify.cc @@ -32,6 +32,7 @@ #include "internal/napi_v8_env.h" #include "internal/napi_module_wrap_record.h" #include "internal/unofficial_napi_bridge.h" +#include "napi_compat.h" #include "node_api.h" #include "unofficial_napi_error_utils.h" @@ -1914,17 +1915,18 @@ napi_status NAPI_CDECL unofficial_napi_bytecode_open( napi_env env, const unofficial_napi_bytecode_open_options* options, unofficial_napi_bytecode_open_result* result) { - if (env == nullptr || options == nullptr || result == nullptr || - options->size < sizeof(*options) || - options->version != UNOFFICIAL_NAPI_BYTECODE_OPEN_OPTIONS_VERSION || - options->source_text == nullptr || options->filename == nullptr || + if (env == nullptr || options == nullptr || result == nullptr) return napi_invalid_arg; + v8::HandleScope handle_scope(env->isolate); + unofficial_napi_realm realm = nullptr; + const napi_status realm_status = napi::compat::bytecode_open_realm(env, options, &realm); + if (realm_status != napi_ok) return realm_status; + if (options->source_text == nullptr || options->filename == nullptr || (options->cache_policy != unofficial_napi_bytecode_cache_compile_on_reject && options->cache_policy != unofficial_napi_bytecode_cache_validate_only)) { return napi_invalid_arg; } *result = {}; - v8::HandleScope handle_scope(env->isolate); - v8::Local context = RealmContext(env, options->realm_or_null); + v8::Local context = RealmContext(env, realm); if (context.IsEmpty()) return napi_invalid_arg; if (options->has_cache != 0 && options->cache_bytes != nullptr && @@ -2571,10 +2573,12 @@ napi_status NAPI_CDECL unofficial_napi_module_wrap_create( napi_env env, const unofficial_napi_module_create_options* options, unofficial_napi_module_create_result* result_out) { - if (options == nullptr || options->size < sizeof(*options) || - options->version != UNOFFICIAL_NAPI_MODULE_CREATE_OPTIONS_VERSION || - result_out == nullptr) { - return napi_invalid_arg; + if (env == nullptr || options == nullptr || result_out == nullptr) return napi_invalid_arg; + unofficial_napi_realm realm = nullptr; + { + v8::HandleScope handle_scope(env->isolate); + const napi_status realm_status = napi::compat::module_create_realm(env, options, &realm); + if (realm_status != napi_ok) return realm_status; } *result_out = {}; napi_status status = napi_invalid_arg; @@ -2584,7 +2588,7 @@ napi_status NAPI_CDECL unofficial_napi_module_wrap_create( env, options->wrapper, options->url, - options->realm_or_null, + realm, options->payload.source_text.source, options->payload.source_text.line_offset, options->payload.source_text.column_offset, @@ -2596,7 +2600,7 @@ napi_status NAPI_CDECL unofficial_napi_module_wrap_create( env, options->wrapper, options->url, - options->realm_or_null, + realm, options->payload.synthetic.export_names, options->payload.synthetic.synthetic_evaluation_steps, &result_out->module); From 4643fcfa8f3abb3b5e610ddf01b5e7080cfb4866 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 15:03:01 -0800 Subject: [PATCH 063/150] Restore the context-token hooks, as tokens on realms Version 2 of the env hooks deleted the context-token callbacks from the middle of the struct, so main's binaries attached their hooks at the wrong offsets and main's source no longer compiled. The struct is main's version 1 again, with the callbacks and their bits marked deprecated. V8 accepts them as on main and gives each realm a token, its record. It assigns the token when create_realm (and so make_context) makes the realm and unassigns it once: when it frees the record of a collected realm, now also in collect_garbage, or at env release, before the cleanup hooks run and again after them for realms they made (after the hooks of each round of the release). Realms made before the hooks were attached get none. Both hooks run in the env's realm. QuickJS still accepts none of the hooks and never calls them, as on main. The guest layer reads main's 32-byte version 1 env hooks again, with the token callbacks' bits. As on main, the bridge gives the provider none of a guest's hooks. Co-Authored-By: Claude Opus 5.5 --- include/unofficial_napi.h | 43 ++++++++++++++--- include/unofficial_napi_wasm32_abi.h | 8 ++-- src/guest/abi.rs | 47 +++++++++++++++---- tests/runners/test_21_general.cc | 3 -- v8/src/internal/napi_v8_agent.h | 5 ++ v8/src/internal/napi_v8_env.h | 3 ++ v8/src/internal/unofficial_napi_bridge.h | 4 ++ v8/src/js_native_api_v8.cc | 5 ++ v8/src/unofficial_napi.cc | 7 +++ v8/src/unofficial_napi_contextify.cc | 59 ++++++++++++++++++++++-- 10 files changed, 158 insertions(+), 26 deletions(-) diff --git a/include/unofficial_napi.h b/include/unofficial_napi.h index 708d0db2b4..7ad9401a0f 100644 --- a/include/unofficial_napi.h +++ b/include/unofficial_napi.h @@ -99,6 +99,10 @@ typedef struct { unofficial_napi_guest_heap guest_heap; } unofficial_napi_env_create_options; +// Deprecated with the context-token hooks below. +typedef void (*unofficial_napi_context_token_callback)(napi_env env, + void* token, + void* data); typedef void (*unofficial_napi_foreground_task_callback)(napi_env env, void* data); typedef void (*unofficial_napi_foreground_task_cleanup)(napi_env env, @@ -136,33 +140,59 @@ typedef void (*unofficial_napi_oom_error_callback)(napi_env env, bool is_heap_oom, const char* detail); -// Bits 0 and 1 belonged to the context-token callbacks that version 2 of the -// hooks struct removed. They are not reused. typedef enum { + unofficial_napi_env_hook_context_token_assign + UNOFFICIAL_NAPI_DEPRECATED_MEMBER("realms replace context tokens") = 1u << 0, + unofficial_napi_env_hook_context_token_unassign + UNOFFICIAL_NAPI_DEPRECATED_MEMBER("realms replace context tokens") = 1u << 1, unofficial_napi_env_hook_enqueue_foreground_task = 1u << 2, unofficial_napi_env_hook_fatal_error = 1u << 3, unofficial_napi_env_hook_oom_error = 1u << 4, } unofficial_napi_env_hook; -enum { UNOFFICIAL_NAPI_ENV_HOOKS_VERSION = 2 }; +enum { UNOFFICIAL_NAPI_ENV_HOOKS_VERSION = 1 }; // Immutable embedder callbacks attached as one complete environment state // transition. `size` and `version` make additions ABI-compatible. `data` is // owned by the embedder and must remain valid until the environment is released. -// Version 2 removed the context-token callbacks; providers reject version 1. +// +// Deprecated: the context-token callbacks. Use unofficial_napi_create_realm and +// keep per-realm state keyed by the realm's global instead. They are kept for +// compatibility and removed in a future major release. A provider that accepts +// them (V8) gives every realm a token, an opaque pointer that stays the same +// for the realm and is not reused while assigned. It calls +// `context_token_assign_callback(env, token, data)` when the realm is created +// (unofficial_napi_create_realm, and so unofficial_napi_contextify_make_context), +// and `context_token_unassign_callback(env, token, data)` once for each +// token: when the provider frees the record of a collected realm (in +// unofficial_napi_create_realm and unofficial_napi_collect_garbage), or, for a +// realm still alive, when the env is released, before its cleanup hooks run +// (and after them for realms they made). Both run in the env's realm. Realms +// made before the hooks were attached get no token. QuickJS does not accept +// them and never calls them. +UNOFFICIAL_NAPI_SUPPRESS_DEPRECATED_BEGIN typedef struct { uint32_t size; uint32_t version; void* data; + unofficial_napi_context_token_callback context_token_assign_callback + UNOFFICIAL_NAPI_DEPRECATED_MEMBER("realms replace context tokens"); + unofficial_napi_context_token_callback context_token_unassign_callback + UNOFFICIAL_NAPI_DEPRECATED_MEMBER("realms replace context tokens"); unofficial_napi_enqueue_foreground_task_callback enqueue_foreground_task_callback; unofficial_napi_fatal_error_callback fatal_error_callback; unofficial_napi_oom_error_callback oom_error_callback; } unofficial_napi_env_hooks; +// Reads the deprecated fields too, without warning. static inline uint64_t unofficial_napi_env_hooks_requested( const unofficial_napi_env_hooks* hooks) { if (hooks == NULL) return 0; uint64_t requested = 0; + if (hooks->context_token_assign_callback != NULL) + requested |= unofficial_napi_env_hook_context_token_assign; + if (hooks->context_token_unassign_callback != NULL) + requested |= unofficial_napi_env_hook_context_token_unassign; if (hooks->enqueue_foreground_task_callback != NULL) requested |= unofficial_napi_env_hook_enqueue_foreground_task; if (hooks->fatal_error_callback != NULL) @@ -171,6 +201,7 @@ static inline uint64_t unofficial_napi_env_hooks_requested( requested |= unofficial_napi_env_hook_oom_error; return requested; } +UNOFFICIAL_NAPI_SUPPRESS_DEPRECATED_END NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_create_env( int32_t module_api_version, @@ -1231,7 +1262,7 @@ static_assert(sizeof(unofficial_napi_env_create_options) == static_assert(sizeof(unofficial_napi_runtime_options) == sizeof(unofficial_napi_wasm32_runtime_options_v1)); static_assert(sizeof(unofficial_napi_env_hooks) == - sizeof(unofficial_napi_wasm32_env_hooks_v2)); + sizeof(unofficial_napi_wasm32_env_hooks_v1)); static_assert(sizeof(unofficial_napi_js_source) == sizeof(unofficial_napi_wasm32_js_source)); static_assert(sizeof(unofficial_napi_bytecode_open_options) == @@ -1250,7 +1281,7 @@ _Static_assert(sizeof(unofficial_napi_runtime_options) == sizeof(unofficial_napi_wasm32_runtime_options_v1), "public runtime-options layout differs from its wasm32 wire ABI"); _Static_assert(sizeof(unofficial_napi_env_hooks) == - sizeof(unofficial_napi_wasm32_env_hooks_v2), + sizeof(unofficial_napi_wasm32_env_hooks_v1), "public env-hooks layout differs from its wasm32 wire ABI"); _Static_assert(sizeof(unofficial_napi_js_source) == sizeof(unofficial_napi_wasm32_js_source), diff --git a/include/unofficial_napi_wasm32_abi.h b/include/unofficial_napi_wasm32_abi.h index 0a53303459..5d0620ed93 100644 --- a/include/unofficial_napi_wasm32_abi.h +++ b/include/unofficial_napi_wasm32_abi.h @@ -30,10 +30,12 @@ typedef struct { uint32_t size; uint32_t version; uint32_t data; + uint32_t context_token_assign_callback; + uint32_t context_token_unassign_callback; uint32_t enqueue_foreground_task_callback; uint32_t fatal_error_callback; uint32_t oom_error_callback; -} unofficial_napi_wasm32_env_hooks_v2; +} unofficial_napi_wasm32_env_hooks_v1; typedef struct { int32_t kind; @@ -103,7 +105,7 @@ typedef struct { #if defined(__cplusplus) static_assert(sizeof(unofficial_napi_wasm32_runtime_options_v1) == 16); static_assert(sizeof(unofficial_napi_wasm32_env_create_options_v1) == 48); -static_assert(sizeof(unofficial_napi_wasm32_env_hooks_v2) == 24); +static_assert(sizeof(unofficial_napi_wasm32_env_hooks_v1) == 32); static_assert(sizeof(unofficial_napi_wasm32_js_source) == 12); static_assert(sizeof(unofficial_napi_wasm32_bytecode_open_options_v1) == 48); static_assert(sizeof(unofficial_napi_wasm32_bytecode_open_options_v2) == 52); @@ -116,7 +118,7 @@ _Static_assert(sizeof(unofficial_napi_wasm32_runtime_options_v1) == 16, "wasm32 runtime-options wire layout changed"); _Static_assert(sizeof(unofficial_napi_wasm32_env_create_options_v1) == 48, "wasm32 env-create wire layout changed"); -_Static_assert(sizeof(unofficial_napi_wasm32_env_hooks_v2) == 24, +_Static_assert(sizeof(unofficial_napi_wasm32_env_hooks_v1) == 32, "wasm32 env-hooks wire layout changed"); _Static_assert(sizeof(unofficial_napi_wasm32_js_source) == 12, "wasm32 JS-source wire layout changed"); diff --git a/src/guest/abi.rs b/src/guest/abi.rs index 464de4b817..cc29b9942b 100644 --- a/src/guest/abi.rs +++ b/src/guest/abi.rs @@ -32,10 +32,12 @@ struct Wasm32EnvCreateOptionsV1 { } #[repr(C)] -struct Wasm32EnvHooksV2 { +struct Wasm32EnvHooksV1 { size: u32, version: u32, data: u32, + context_token_assign_callback: u32, + context_token_unassign_callback: u32, enqueue_foreground_task_callback: u32, fatal_error_callback: u32, oom_error_callback: u32, @@ -136,7 +138,7 @@ const BYTECODE_OPEN_V2_SIZE: usize = std::mem::size_of::(); const MODULE_CREATE_V2_SIZE: usize = std::mem::size_of::(); const MODULE_HOOKS_SIZE: usize = std::mem::size_of::(); -const ENV_HOOKS_SIZE: usize = std::mem::size_of::(); +const ENV_HOOKS_SIZE: usize = std::mem::size_of::(); const REALM_OPTIONS_SIZE: usize = std::mem::size_of::(); const _: () = assert!(std::mem::size_of::() == 8); @@ -150,7 +152,7 @@ const _: () = assert!(MODULE_CREATE_V2_SIZE == 44); const _: () = assert!(std::mem::size_of::() == 16); const _: () = assert!(std::mem::size_of::() == 16); const _: () = assert!(MODULE_HOOKS_SIZE == 16); -const _: () = assert!(ENV_HOOKS_SIZE == 24); +const _: () = assert!(ENV_HOOKS_SIZE == 32); const _: () = assert!(REALM_OPTIONS_SIZE == 28); fn u32_at(bytes: &[u8], offset: usize) -> Option { @@ -629,19 +631,44 @@ pub(crate) fn read_env_hooks( env: &mut FunctionEnvMut, guest_ptr: u32, ) -> Option { - let bytes = read_versioned(env, guest_ptr, ENV_HOOKS_SIZE, 2)?; - let enqueue = std::mem::offset_of!(Wasm32EnvHooksV2, enqueue_foreground_task_callback); - let fatal = std::mem::offset_of!(Wasm32EnvHooksV2, fatal_error_callback); - let oom = std::mem::offset_of!(Wasm32EnvHooksV2, oom_error_callback); + let bytes = read_versioned(env, guest_ptr, ENV_HOOKS_SIZE, 1)?; + let hook_fields = [ + ( + std::mem::offset_of!(Wasm32EnvHooksV1, context_token_assign_callback), + 1u64 << 0, + ), + ( + std::mem::offset_of!(Wasm32EnvHooksV1, context_token_unassign_callback), + 1u64 << 1, + ), + ( + std::mem::offset_of!(Wasm32EnvHooksV1, enqueue_foreground_task_callback), + 1u64 << 2, + ), + ( + std::mem::offset_of!(Wasm32EnvHooksV1, fatal_error_callback), + 1u64 << 3, + ), + ( + std::mem::offset_of!(Wasm32EnvHooksV1, oom_error_callback), + 1u64 << 4, + ), + ]; let mut requested = 0; - for (offset, bit) in [(enqueue, 1u64 << 2), (fatal, 1u64 << 3), (oom, 1u64 << 4)] { + for (offset, bit) in hook_fields { if u32_at(&bytes, offset)? != 0 { requested |= bit; } } Some(EnvHooks { - fatal: u32_at(&bytes, fatal)?, - oom: u32_at(&bytes, oom)?, + fatal: u32_at( + &bytes, + std::mem::offset_of!(Wasm32EnvHooksV1, fatal_error_callback), + )?, + oom: u32_at( + &bytes, + std::mem::offset_of!(Wasm32EnvHooksV1, oom_error_callback), + )?, requested, }) } diff --git a/tests/runners/test_21_general.cc b/tests/runners/test_21_general.cc index 236c394b13..6db26c6d1b 100644 --- a/tests/runners/test_21_general.cc +++ b/tests/runners/test_21_general.cc @@ -161,9 +161,6 @@ TEST_F(Test21General, EnvironmentHooksAttachAtomicallyOnce) { invalid.version += 1; uint64_t accepted_hooks = 0; EXPECT_EQ(unofficial_napi_attach_env(env, &invalid, &accepted_hooks), napi_invalid_arg); - // Version 1 had the context-token callbacks, which version 2 removed. - invalid.version = 1; - EXPECT_EQ(unofficial_napi_attach_env(env, &invalid, &accepted_hooks), napi_invalid_arg); ASSERT_EQ(unofficial_napi_attach_env(env, &hooks, &accepted_hooks), napi_ok); EXPECT_EQ(accepted_hooks, 0); EXPECT_EQ(unofficial_napi_attach_env(env, &hooks, &accepted_hooks), napi_invalid_arg); diff --git a/v8/src/internal/napi_v8_agent.h b/v8/src/internal/napi_v8_agent.h index 67648ba4f8..85bf6a8c3b 100644 --- a/v8/src/internal/napi_v8_agent.h +++ b/v8/src/internal/napi_v8_agent.h @@ -57,6 +57,11 @@ struct napi_agent__ { unofficial_napi_enqueue_foreground_task_callback enqueue_foreground_task_callback = nullptr; void* enqueue_foreground_task_target = nullptr; + // The deprecated context-token hooks, called for the realms of the agent's + // env. `context_token_data` is the hooks' `data`. + unofficial_napi_context_token_callback context_token_assign_callback = nullptr; + unofficial_napi_context_token_callback context_token_unassign_callback = nullptr; + void* context_token_data = nullptr; // The one near-heap-limit slot. `near_heap_limit_installed` is true while // the provider's trampoline is registered with V8. diff --git a/v8/src/internal/napi_v8_env.h b/v8/src/internal/napi_v8_env.h index e8389a7cb6..77f4583e3d 100644 --- a/v8/src/internal/napi_v8_env.h +++ b/v8/src/internal/napi_v8_env.h @@ -96,6 +96,9 @@ struct unofficial_napi_realm__ { napi_env env = nullptr; v8::Global context; std::unique_ptr own_microtask_queue; + // The record is the realm's context token. True while the realm has one, + // until the unassign hook, which runs before the record is freed. + bool token_assigned = false; }; // A realm N-API acts in: a scope opened with unofficial_napi_enter_realm, or diff --git a/v8/src/internal/unofficial_napi_bridge.h b/v8/src/internal/unofficial_napi_bridge.h index b1baf85e65..a579fd12bf 100644 --- a/v8/src/internal/unofficial_napi_bridge.h +++ b/v8/src/internal/unofficial_napi_bridge.h @@ -11,6 +11,10 @@ bool NapiV8LookupForegroundTaskTarget(v8::Isolate* isolate, bool NapiV8IsContextifyContext(napi_env env, v8::Local context); void NapiV8ApplyPromiseHooksToContext(napi_env env, v8::Local context); void NapiV8ApplyPromiseHooksToContextifyContexts(napi_env env); +// Frees the records of collected realms, unassigning their context tokens. +void NapiV8ReleaseCollectedRealms(napi_env env); +// Unassigns the context token of every realm that still has one. +void NapiV8UnassignRealmTokens(napi_env env); void NapiV8TrackProviderPromise(v8::Isolate* isolate, v8::Local promise); bool NapiV8HasPendingProviderWork(napi_env env); diff --git a/v8/src/js_native_api_v8.cc b/v8/src/js_native_api_v8.cc index 0d3cbe99ca..1e16783895 100644 --- a/v8/src/js_native_api_v8.cc +++ b/v8/src/js_native_api_v8.cc @@ -993,9 +993,14 @@ napi_env__::~napi_env__() { // data's finalizer; and all of it again for what that finalizer leaves // pending, until nothing is, so no hint is left pointing at the env. The // callback is cleared before it runs, so instance data is finalized once. + // Realms still alive give up their context tokens before the cleanup hooks + // run, while the embedder's state is intact, and so do realms the hooks + // make. + NapiV8UnassignRealmTokens(this); for (;;) { do { RunEnvCleanupHooks(this); + NapiV8UnassignRealmTokens(this); napi_ref_tracker__::FinalizeAll(&finalizing_reflist); pending_finalizers.clear(); pending_buffer_finalizers.clear(); diff --git a/v8/src/unofficial_napi.cc b/v8/src/unofficial_napi.cc index af1a03317d..1969db36a3 100644 --- a/v8/src/unofficial_napi.cc +++ b/v8/src/unofficial_napi.cc @@ -1723,6 +1723,11 @@ napi_status NAPI_CDECL unofficial_napi_attach_env( } napi_agent__* agent = env->agent; + UNOFFICIAL_NAPI_SUPPRESS_DEPRECATED_BEGIN + agent->context_token_assign_callback = hooks->context_token_assign_callback; + agent->context_token_unassign_callback = hooks->context_token_unassign_callback; + UNOFFICIAL_NAPI_SUPPRESS_DEPRECATED_END + agent->context_token_data = hooks->data; agent->fatal_error_callback = hooks->fatal_error_callback; agent->oom_error_callback = hooks->oom_error_callback; { @@ -1951,6 +1956,8 @@ napi_status NAPI_CDECL unofficial_napi_collect_garbage(napi_env env) { // memory as possible. RequestGarbageCollectionForTesting is intentionally // not used: it aborts unless V8 was initialized with testing-only flags. env->isolate->LowMemoryNotification(); + // Realms collected now are released now, with their context tokens. + NapiV8ReleaseCollectedRealms(env); return napi_ok; } diff --git a/v8/src/unofficial_napi_contextify.cc b/v8/src/unofficial_napi_contextify.cc index c792284287..8a945ff0b9 100644 --- a/v8/src/unofficial_napi_contextify.cc +++ b/v8/src/unofficial_napi_contextify.cc @@ -9,6 +9,7 @@ #include #include #include +#include #include #include #include @@ -1314,12 +1315,45 @@ v8::Local RealmContext(napi_env env, unofficial_napi_realm realm) { return realm->context.Get(env->isolate); } -// Frees the records of realms whose context was collected. +// Calls a deprecated context-token hook for `realm`, in the env's realm as +// every env hook runs. +void CallContextTokenHook(napi_env env, + unofficial_napi_context_token_callback hook, + unofficial_napi_realm realm) { + if (hook == nullptr) return; + v8::HandleScope handle_scope(env->isolate); + v8::Context::Scope context_scope(env->main_context()); + napi_realm_frame_scope__ realm_frame(env, nullptr); + hook(env, realm, env->agent->context_token_data); +} + +// A realm has a token while either hook is attached, as each context did. +void AssignRealmToken(napi_env env, unofficial_napi_realm realm) { + if (env->agent->context_token_assign_callback == nullptr && + env->agent->context_token_unassign_callback == nullptr) { + return; + } + realm->token_assigned = true; + CallContextTokenHook(env, env->agent->context_token_assign_callback, realm); +} + +void UnassignRealmToken(napi_env env, unofficial_napi_realm realm) { + if (!realm->token_assigned) return; + realm->token_assigned = false; + CallContextTokenHook(env, env->agent->context_token_unassign_callback, realm); +} + +// Frees the records of realms whose context was collected. They leave +// env->realms before any hook runs, so a hook may make realms. void ReleaseCollectedRealms(napi_env env) { auto& realms = env->realms; - realms.erase(std::remove_if(realms.begin(), realms.end(), - [](const auto& realm) { return realm->context.IsEmpty(); }), - realms.end()); + auto collected = std::stable_partition( + realms.begin(), realms.end(), [](const auto& realm) { return !realm->context.IsEmpty(); }); + if (collected == realms.end()) return; + std::vector> released( + std::make_move_iterator(collected), std::make_move_iterator(realms.end())); + realms.erase(collected, realms.end()); + for (const auto& realm : released) UnassignRealmToken(env, realm.get()); } bool CompileAsModule(v8::Isolate* isolate, @@ -1619,6 +1653,22 @@ void NapiV8ApplyPromiseHooksToContextifyContexts(napi_env env) { } } +void NapiV8ReleaseCollectedRealms(napi_env env) { + if (env == nullptr || env->isolate == nullptr) return; + ReleaseCollectedRealms(env); +} + +void NapiV8UnassignRealmTokens(napi_env env) { + if (env == nullptr || env->isolate == nullptr) return; + // A hook may make or free realms, so look again after each one. + for (;;) { + auto it = std::find_if(env->realms.begin(), env->realms.end(), + [](const auto& realm) { return realm->token_assigned; }); + if (it == env->realms.end()) return; + UnassignRealmToken(env, it->get()); + } +} + extern "C" { napi_status NAPI_CDECL unofficial_napi_create_realm( @@ -1728,6 +1778,7 @@ napi_status NAPI_CDECL unofficial_napi_create_realm( if (global_napi == nullptr) return napi_generic_failure; if (global_out != nullptr) *global_out = global_napi; *realm_out = handle; + AssignRealmToken(env, handle); return napi_ok; } From 34bdf3a2d105f3a7cccbc514d7de95520799538c Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 15:03:12 -0800 Subject: [PATCH 064/150] Test the deprecated API with main's contextify tests test_71 runs main's test_65_unofficial_contextify.cc unchanged but for the fixture name, so code written against main keeps passing it on both providers. The rest pins how the old API maps onto realms: a symbol makes a fresh global, make_context refuses what main's V8 refused, contextified objects are realms, nothing means the current realm (entered, or of the running callback), both versions of the bytecode and module options (version 1 passed in main's exact layout, so a read past it shows under ASan), and the context tokens assigned on creation and unassigned on collection and at release. Co-Authored-By: Claude Opus 5.5 --- tests/CMakeLists.txt | 3 + tests/runners/test_71_contextify_compat.cc | 1664 ++++++++++++++++++++ 2 files changed, 1667 insertions(+) create mode 100644 tests/runners/test_71_contextify_compat.cc diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt index cf543b9fcb..51cc295e5a 100644 --- a/tests/CMakeLists.txt +++ b/tests/CMakeLists.txt @@ -336,6 +336,9 @@ add_fixture_test(${_napi_test_prefix}_test_69_unofficial_realm_entry add_fixture_test(${_napi_test_prefix}_test_70_realm_entry_attack runners/test_70_realm_entry_attack.cc ) +add_fixture_test(${_napi_test_prefix}_test_71_contextify_compat + runners/test_71_contextify_compat.cc +) if(_napi_test_engine STREQUAL "v8") # Only the V8 provider posts engine tasks through the enqueue hook. add_fixture_test(${_napi_test_prefix}_test_66_foreground_task_handoff diff --git a/tests/runners/test_71_contextify_compat.cc b/tests/runners/test_71_contextify_compat.cc new file mode 100644 index 0000000000..fd61274990 --- /dev/null +++ b/tests/runners/test_71_contextify_compat.cc @@ -0,0 +1,1664 @@ +// The deprecated API, kept for compatibility: the contextify calls, the +// context-token hooks and version 1 of the option structs, on top of realms. +// The first half is main's test_65_unofficial_contextify.cc, unchanged but +// for the fixture name, so code written against main keeps passing it. +#define UNOFFICIAL_NAPI_NO_DEPRECATION_WARNINGS +#ifdef NAPI_MODULE +#undef NAPI_MODULE +#endif +#include "node_api.h" + +#include "test_env.h" + +#include "unofficial_napi.h" + +#include +#include +#include +#include + +class Test71ContextifyCompat : public FixtureTestBase {}; + +namespace { + +napi_value Str(napi_env env, const char* value) { + napi_value out = nullptr; + if (napi_create_string_utf8(env, value, NAPI_AUTO_LENGTH, &out) != napi_ok) return nullptr; + return out; +} + +napi_value Sym(napi_env env, const char* value) { + napi_value desc = Str(env, value); + if (desc == nullptr) return nullptr; + napi_value out = nullptr; + if (napi_create_symbol(env, desc, &out) != napi_ok) return nullptr; + return out; +} + +#if defined(NAPI_TEST_ENGINE_V8) +constexpr char kPreparedStack[] = + "Error: sentinel\n" + " at process.processTicksAndRejections (node:internal/process/task_queues:85:11)\n" + " at triggerUncaughtException (node:internal/process/promises:251:13)"; + +napi_value ReturnPreparedStack(napi_env env, napi_callback_info /*info*/) { + return Str(env, kPreparedStack); +} + +napi_value CaptureDynamicImportId(napi_env env, napi_callback_info info) { + size_t argc = 5; + napi_value argv[5] = {nullptr, nullptr, nullptr, nullptr, nullptr}; + if (napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr) != napi_ok || + argc < 1 || argv[0] == nullptr) { + return nullptr; + } + + napi_value global = nullptr; + if (napi_get_global(env, &global) != napi_ok || global == nullptr || + napi_set_named_property(env, global, "__captured_dynamic_import_id", argv[0]) != napi_ok) { + return nullptr; + } + + napi_deferred deferred = nullptr; + napi_value promise = nullptr; + napi_value undefined = nullptr; + if (napi_create_promise(env, &deferred, &promise) != napi_ok || + napi_get_undefined(env, &undefined) != napi_ok || + napi_resolve_deferred(env, deferred, undefined) != napi_ok) { + return nullptr; + } + return promise; +} +#endif + +} // namespace + +TEST_F(Test71ContextifyCompat, MakeRunRoundTrip) { + EnvScope s(runtime_.get()); + + napi_value sandbox = nullptr; + ASSERT_EQ(napi_create_object(s.env, &sandbox), napi_ok); + + napi_value result = nullptr; + ASSERT_EQ(unofficial_napi_contextify_make_context(s.env, + sandbox, + Str(s.env, "ctx"), + Str(s.env, "test://origin"), + true, + true, + true, + Sym(s.env, "hdo"), + &result), + napi_ok); + ASSERT_NE(result, nullptr); + + napi_value eval_result = nullptr; + const unofficial_napi_js_source run_source = + unofficial_napi_js_source_from_text(Str(s.env, "globalThis.answer = 42; answer")); + ASSERT_EQ(unofficial_napi_contextify_run_script(s.env, + sandbox, + &run_source, + Str(s.env, "ctx.js"), + 0, + 0, + -1, + true, + false, + false, + Sym(s.env, "hdo"), + &eval_result), + napi_ok); + ASSERT_NE(eval_result, nullptr); + + int32_t answer = 0; + ASSERT_EQ(napi_get_value_int32(s.env, eval_result, &answer), napi_ok); + EXPECT_EQ(answer, 42); + + napi_value answer_value = nullptr; + ASSERT_EQ(napi_get_named_property(s.env, sandbox, "answer", &answer_value), napi_ok); + ASSERT_EQ(napi_get_value_int32(s.env, answer_value, &answer), napi_ok); + EXPECT_EQ(answer, 42); + +} + +#if defined(NAPI_TEST_ENGINE_V8) +TEST_F(Test71ContextifyCompat, MakeContextPreservesThrownProxyException) { + EnvScope s(runtime_.get()); + + napi_value source = Str( + s.env, + "(() => { const sentinel = {}; return { sentinel, sandbox: new Proxy({}, { ownKeys() { throw sentinel; } }) }; })()"); + ASSERT_NE(source, nullptr); + napi_value fixture = nullptr; + ASSERT_EQ(napi_run_script(s.env, source, &fixture), napi_ok); + ASSERT_NE(fixture, nullptr); + + napi_value sentinel = nullptr; + napi_value sandbox = nullptr; + ASSERT_EQ(napi_get_named_property(s.env, fixture, "sentinel", &sentinel), napi_ok); + ASSERT_EQ(napi_get_named_property(s.env, fixture, "sandbox", &sandbox), napi_ok); + + napi_value result = nullptr; + EXPECT_EQ(unofficial_napi_contextify_make_context(s.env, + sandbox, + Str(s.env, "ctx"), + Str(s.env, "test://origin"), + true, + true, + false, + Sym(s.env, "hdo"), + &result), + napi_pending_exception); + EXPECT_EQ(result, nullptr); + + bool pending = false; + ASSERT_EQ(napi_is_exception_pending(s.env, &pending), napi_ok); + EXPECT_TRUE(pending); + napi_value caught = nullptr; + ASSERT_EQ(napi_get_and_clear_last_exception(s.env, &caught), napi_ok); + bool same = false; + ASSERT_EQ(napi_strict_equals(s.env, caught, sentinel, &same), napi_ok); + EXPECT_TRUE(same); +} +#endif + +TEST_F(Test71ContextifyCompat, SandboxGlobalThisIsNotEnumerableForDeepFreeze) { + EnvScope s(runtime_.get()); + + napi_value sandbox = nullptr; + ASSERT_EQ(napi_create_object(s.env, &sandbox), napi_ok); + + napi_value result = nullptr; + ASSERT_EQ(unofficial_napi_contextify_make_context(s.env, + sandbox, + Str(s.env, "ctx"), + Str(s.env, "test://origin"), + true, + true, + true, + Sym(s.env, "hdo"), + &result), + napi_ok); + ASSERT_NE(result, nullptr); + +#if defined(NAPI_TEST_ENGINE_QUICKJS) + // QuickJS keeps its context marker on the sandbox rather than copying it + // into the context global. Pin the host-visible property contract directly. + napi_value marker_key = Str(s.env, "__quickjs_contextified"); + bool has_marker = false; + ASSERT_EQ(napi_has_own_property(s.env, sandbox, marker_key, &has_marker), napi_ok); + EXPECT_TRUE(has_marker); + + napi_value enumerable_keys = nullptr; + ASSERT_EQ(napi_get_all_property_names(s.env, + sandbox, + napi_key_own_only, + napi_key_enumerable, + napi_key_numbers_to_strings, + &enumerable_keys), + napi_ok); + uint32_t key_count = 0; + ASSERT_EQ(napi_get_array_length(s.env, enumerable_keys, &key_count), napi_ok); + for (uint32_t index = 0; index < key_count; ++index) { + napi_value key = nullptr; + ASSERT_EQ(napi_get_element(s.env, enumerable_keys, index, &key), napi_ok); + char text[64] = {}; + size_t copied = 0; + ASSERT_EQ(napi_get_value_string_utf8(s.env, key, text, sizeof(text), &copied), napi_ok); + EXPECT_STRNE(text, "__quickjs_contextified"); + } + + napi_value marker_false = nullptr; + napi_value marker_true = nullptr; + ASSERT_EQ(napi_get_boolean(s.env, false, &marker_false), napi_ok); + ASSERT_EQ(napi_get_boolean(s.env, true, &marker_true), napi_ok); + ASSERT_EQ(napi_set_named_property(s.env, sandbox, "__quickjs_contextified", marker_false), napi_ok); + ASSERT_EQ(napi_set_named_property(s.env, sandbox, "__quickjs_contextified", marker_true), napi_ok); +#endif + + napi_value eval_result = nullptr; + std::string freeze_script = R"JS( +const globalThisDescriptor = Object.getOwnPropertyDescriptor(globalThis, "globalThis"); +if (!globalThisDescriptor || globalThisDescriptor.enumerable || + !globalThisDescriptor.writable || !globalThisDescriptor.configurable) { + throw new Error("globalThis should be writable/configurable but non-enumerable"); +} +const keys = Object.keys(globalThis); +if (keys.includes("globalThis")) { + throw new Error("contextify internals should not be enumerable"); +} +)JS"; + freeze_script += R"JS( +globalThis.__RSC_MANIFEST = {}; +globalThis.__RSC_MANIFEST["/x"] = { ok: true }; +function deepFreeze(obj) { + if (obj === null || typeof obj !== "object" || Object.isFrozen(obj)) { + return obj; + } + for (const value of Object.values(obj)) { + deepFreeze(value); + } + return Object.freeze(obj); +} +deepFreeze(globalThis); +globalThis.__RSC_MANIFEST["/x"].ok; +)JS"; + const unofficial_napi_js_source freeze_source = unofficial_napi_js_source_from_text( + Str(s.env, freeze_script.c_str())); + ASSERT_EQ(unofficial_napi_contextify_run_script(s.env, + sandbox, + &freeze_source, + Str(s.env, "deep_freeze.js"), + 0, + 0, + -1, + true, + false, + false, + Sym(s.env, "hdo"), + &eval_result), + napi_ok); + ASSERT_NE(eval_result, nullptr); + + bool ok = false; + ASSERT_EQ(napi_get_value_bool(s.env, eval_result, &ok), napi_ok); + EXPECT_TRUE(ok); +} + +TEST_F(Test71ContextifyCompat, CompileFunctionAndCachedData) { + EnvScope s(runtime_.get()); + + napi_value params = nullptr; + ASSERT_EQ(napi_create_array_with_length(s.env, 2, ¶ms), napi_ok); + ASSERT_EQ(napi_set_element(s.env, params, 0, Str(s.env, "a")), napi_ok); + ASSERT_EQ(napi_set_element(s.env, params, 1, Str(s.env, "b")), napi_ok); + + napi_value context_extensions = nullptr; + ASSERT_EQ(napi_create_array_with_length(s.env, 0, &context_extensions), napi_ok); + + napi_value undef = nullptr; + ASSERT_EQ(napi_get_undefined(s.env, &undef), napi_ok); + + napi_value out = nullptr; + const unofficial_napi_js_source fn_source = + unofficial_napi_js_source_from_text(Str(s.env, "return a + b;")); + ASSERT_EQ(unofficial_napi_contextify_compile_function(s.env, + &fn_source, + Str(s.env, "fn.js"), + 0, + 0, + undef, + context_extensions, + params, + Sym(s.env, "hdo"), + &out), + napi_ok); + ASSERT_NE(out, nullptr); + + napi_value fn = nullptr; + ASSERT_EQ(napi_get_named_property(s.env, out, "function", &fn), napi_ok); + ASSERT_NE(fn, nullptr); + + napi_value global = nullptr; + ASSERT_EQ(napi_get_global(s.env, &global), napi_ok); + napi_value argv[2] = {nullptr, nullptr}; + ASSERT_EQ(napi_create_int32(s.env, 2, &argv[0]), napi_ok); + ASSERT_EQ(napi_create_int32(s.env, 3, &argv[1]), napi_ok); + + napi_value fn_result = nullptr; + ASSERT_EQ(napi_call_function(s.env, global, fn, 2, argv, &fn_result), napi_ok); + int32_t sum = 0; + ASSERT_EQ(napi_get_value_int32(s.env, fn_result, &sum), napi_ok); + EXPECT_EQ(sum, 5); + + // Cached data now flows through the bytecode handle APIs: compile eagerly, + // serialize the engine bytes, and restore a live artifact from them. + unofficial_napi_bytecode_open_options open_options{}; + open_options.size = sizeof(open_options); + open_options.version = UNOFFICIAL_NAPI_BYTECODE_OPEN_OPTIONS_VERSION; + open_options.source_text = Str(s.env, "1 + 1"); + open_options.filename = Str(s.env, "script.js"); + open_options.shape = unofficial_napi_bytecode_shape_script; + open_options.params_or_undefined = undef; + open_options.host_defined_option_id = Sym(s.env, "hdo"); + unofficial_napi_bytecode_open_result open_result{}; + ASSERT_EQ(unofficial_napi_bytecode_open(s.env, &open_options, &open_result), napi_ok); + unofficial_napi_bytecode bytecode = open_result.bytecode; + ASSERT_NE(bytecode, nullptr); + + napi_value cached_data = nullptr; + ASSERT_EQ(unofficial_napi_bytecode_serialize(s.env, bytecode, &cached_data), napi_ok); + ASSERT_NE(cached_data, nullptr); + bool is_typedarray = false; + ASSERT_EQ(napi_is_typedarray(s.env, cached_data, &is_typedarray), napi_ok); + EXPECT_TRUE(is_typedarray); + ASSERT_EQ(unofficial_napi_bytecode_release(s.env, bytecode), napi_ok); + + const uint8_t* bytes = nullptr; + size_t byte_length = 0; + napi_typedarray_type array_type = napi_uint8_array; + napi_value arraybuffer = nullptr; + size_t byte_offset = 0; + void* data = nullptr; + ASSERT_EQ(napi_get_typedarray_info(s.env, cached_data, &array_type, &byte_length, &data, + &arraybuffer, &byte_offset), + napi_ok); + ASSERT_GT(byte_length, 0u); + bytes = static_cast(data); + + open_options.cache_bytes = bytes; + open_options.cache_byte_length = byte_length; + open_options.has_cache = 1; + open_result = {}; + ASSERT_EQ(unofficial_napi_bytecode_open(s.env, &open_options, &open_result), napi_ok); + EXPECT_EQ(open_result.cache_rejected, 0); + unofficial_napi_bytecode restored = open_result.bytecode; + ASSERT_NE(restored, nullptr); + ASSERT_EQ(unofficial_napi_bytecode_release(s.env, restored), napi_ok); + + open_options.source_text = Str(s.env, "1000 + 2000 + 3000"); + open_options.cache_policy = unofficial_napi_bytecode_cache_validate_only; + open_result = {}; + ASSERT_EQ(unofficial_napi_bytecode_open(s.env, &open_options, &open_result), napi_ok); + EXPECT_EQ(open_result.cache_rejected, 1); + EXPECT_EQ(open_result.bytecode, nullptr); + + // A present-but-empty cache is a cache miss, not a malformed transaction. + // The provider reports the rejection and atomically prepares the fallback + // artifact from source so callers never need a deserialize/compile branch. + open_options.cache_bytes = nullptr; + open_options.cache_byte_length = 0; + open_options.has_cache = 1; + open_options.cache_policy = unofficial_napi_bytecode_cache_compile_on_reject; + open_result = {}; + ASSERT_EQ(unofficial_napi_bytecode_open(s.env, &open_options, &open_result), napi_ok); + EXPECT_EQ(open_result.cache_rejected, 1); + ASSERT_NE(open_result.bytecode, nullptr); + ASSERT_EQ(unofficial_napi_bytecode_release(s.env, open_result.bytecode), napi_ok); +} + +TEST_F(Test71ContextifyCompat, ModuleStateIsOneAtomicSnapshot) { + EnvScope s(runtime_.get()); + + napi_value wrapper = nullptr; + napi_value undefined = nullptr; + ASSERT_EQ(napi_create_object(s.env, &wrapper), napi_ok); + ASSERT_EQ(napi_get_undefined(s.env, &undefined), napi_ok); + const unofficial_napi_js_source source = + unofficial_napi_js_source_from_text(Str(s.env, "export const value = 42;")); + unofficial_napi_module_create_options create_options{}; + create_options.size = sizeof(create_options); + create_options.version = UNOFFICIAL_NAPI_MODULE_CREATE_OPTIONS_VERSION; + create_options.kind = unofficial_napi_module_source_text; + create_options.wrapper = wrapper; + create_options.url = Str(s.env, "state.mjs"); + create_options.context_or_undefined = undefined; + create_options.payload.source_text.source = &source; + create_options.payload.source_text.host_defined_option_id = undefined; + unofficial_napi_module_create_result create_result{}; + + auto invalid_options = create_options; + invalid_options.size = sizeof(invalid_options) - 1; + EXPECT_EQ(unofficial_napi_module_wrap_create(s.env, &invalid_options, &create_result), + napi_invalid_arg); + invalid_options = create_options; + invalid_options.version++; + EXPECT_EQ(unofficial_napi_module_wrap_create(s.env, &invalid_options, &create_result), + napi_invalid_arg); + invalid_options = create_options; + invalid_options.kind = static_cast(99); + EXPECT_EQ(unofficial_napi_module_wrap_create(s.env, &invalid_options, &create_result), + napi_invalid_arg); + + ASSERT_EQ(unofficial_napi_module_wrap_create(s.env, &create_options, &create_result), + napi_ok); + unofficial_napi_module module = create_result.module; + ASSERT_NE(module, nullptr); + ASSERT_NE(create_result.module_requests, nullptr); + uint32_t request_count = 1; + ASSERT_EQ(napi_get_array_length(s.env, create_result.module_requests, &request_count), + napi_ok); + EXPECT_EQ(request_count, 0u); + EXPECT_FALSE(create_result.has_top_level_await); + + EXPECT_EQ(unofficial_napi_module_wrap_get_state( + s.env, module, nullptr, nullptr, nullptr), + napi_invalid_arg); + int32_t status = -1; + napi_value error = nullptr; + bool has_async_graph = true; + ASSERT_EQ(unofficial_napi_module_wrap_get_state( + s.env, module, &status, &error, &has_async_graph), + napi_ok); + EXPECT_EQ(status, 0); + EXPECT_FALSE(has_async_graph); + ASSERT_NE(error, nullptr); + napi_valuetype error_type = napi_object; + ASSERT_EQ(napi_typeof(s.env, error, &error_type), napi_ok); + EXPECT_EQ(error_type, napi_undefined); + + ASSERT_EQ(unofficial_napi_module_wrap_link(s.env, module, 0, nullptr), napi_ok); + ASSERT_EQ(unofficial_napi_module_wrap_instantiate(s.env, module), napi_ok); + status = -1; + has_async_graph = true; + ASSERT_EQ(unofficial_napi_module_wrap_get_state( + s.env, module, &status, nullptr, &has_async_graph), + napi_ok); + EXPECT_EQ(status, 2); + EXPECT_FALSE(has_async_graph); + + EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, module), napi_ok); +} + +// Node's ESM loader rejects JSON modules whose request lost its +// `with { type: 'json' }` clause (ERR_IMPORT_ATTRIBUTE_MISSING), so every +// provider must surface parsed import attributes on the created requests. +TEST_F(Test71ContextifyCompat, ModuleRequestsPreserveImportAttributes) { + EnvScope s(runtime_.get()); + + napi_value wrapper = nullptr; + napi_value undefined = nullptr; + ASSERT_EQ(napi_create_object(s.env, &wrapper), napi_ok); + ASSERT_EQ(napi_get_undefined(s.env, &undefined), napi_ok); + const unofficial_napi_js_source source = + unofficial_napi_js_source_from_text(Str(s.env, + "import data from './data.json' with { type: 'json' };\n" + "export const ok = data;")); + unofficial_napi_module_create_options options{}; + options.size = sizeof(options); + options.version = UNOFFICIAL_NAPI_MODULE_CREATE_OPTIONS_VERSION; + options.kind = unofficial_napi_module_source_text; + options.wrapper = wrapper; + options.url = Str(s.env, "attributed.mjs"); + options.context_or_undefined = undefined; + options.payload.source_text.source = &source; + options.payload.source_text.host_defined_option_id = undefined; + unofficial_napi_module_create_result created{}; + ASSERT_EQ(unofficial_napi_module_wrap_create(s.env, &options, &created), napi_ok); + ASSERT_NE(created.module, nullptr); + ASSERT_NE(created.module_requests, nullptr); + + uint32_t request_count = 0; + ASSERT_EQ(napi_get_array_length(s.env, created.module_requests, &request_count), + napi_ok); + ASSERT_EQ(request_count, 1u); + napi_value request = nullptr; + ASSERT_EQ(napi_get_element(s.env, created.module_requests, 0, &request), napi_ok); + + napi_value specifier = nullptr; + char text[64] = {0}; + size_t text_length = 0; + ASSERT_EQ(napi_get_named_property(s.env, request, "specifier", &specifier), + napi_ok); + ASSERT_EQ(napi_get_value_string_utf8(s.env, specifier, text, sizeof(text), + &text_length), + napi_ok); + EXPECT_STREQ(text, "./data.json"); + + napi_value attributes = nullptr; + ASSERT_EQ(napi_get_named_property(s.env, request, "attributes", &attributes), + napi_ok); + napi_valuetype attributes_type = napi_undefined; + ASSERT_EQ(napi_typeof(s.env, attributes, &attributes_type), napi_ok); + ASSERT_EQ(attributes_type, napi_object); + napi_value type_value = nullptr; + ASSERT_EQ(napi_get_named_property(s.env, attributes, "type", &type_value), + napi_ok); + ASSERT_EQ(napi_get_value_string_utf8(s.env, type_value, text, sizeof(text), + &text_length), + napi_ok); + EXPECT_STREQ(text, "json"); + + napi_value phase = nullptr; + int32_t phase_number = 0; + ASSERT_EQ(napi_get_named_property(s.env, request, "phase", &phase), napi_ok); + ASSERT_EQ(napi_get_value_int32(s.env, phase, &phase_number), napi_ok); + EXPECT_EQ(phase_number, 2); + + EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, created.module), napi_ok); +} + +TEST_F(Test71ContextifyCompat, SyncModuleErrorDoesNotLeaveUnhandledRejection) { + EnvScope s(runtime_.get()); + + napi_value callback = nullptr; + ASSERT_EQ(napi_run_script(s.env, Str(s.env, + "globalThis.unhandledModulePromises = new Set();" + "globalThis.moduleError = new Error('module failure');" + "(event, promise) => {" + " if (event === 0) unhandledModulePromises.add(promise);" + " if (event === 1) unhandledModulePromises.delete(promise);" + "}"), &callback), napi_ok); + ASSERT_EQ(unofficial_napi_set_promise_reject_callback(s.env, callback), napi_ok); + + napi_value wrapper = nullptr; + napi_value undefined = nullptr; + ASSERT_EQ(napi_create_object(s.env, &wrapper), napi_ok); + ASSERT_EQ(napi_get_undefined(s.env, &undefined), napi_ok); + const unofficial_napi_js_source source = + unofficial_napi_js_source_from_text(Str(s.env, "throw globalThis.moduleError;")); + unofficial_napi_module_create_options options{}; + options.size = sizeof(options); + options.version = UNOFFICIAL_NAPI_MODULE_CREATE_OPTIONS_VERSION; + options.kind = unofficial_napi_module_source_text; + options.wrapper = wrapper; + options.url = Str(s.env, "throwing.mjs"); + options.context_or_undefined = undefined; + options.payload.source_text.source = &source; + options.payload.source_text.host_defined_option_id = undefined; + unofficial_napi_module_create_result created{}; + ASSERT_EQ(unofficial_napi_module_wrap_create(s.env, &options, &created), napi_ok); + ASSERT_EQ(unofficial_napi_module_wrap_link(s.env, created.module, 0, nullptr), napi_ok); + ASSERT_EQ(unofficial_napi_module_wrap_instantiate(s.env, created.module), napi_ok); + + napi_value result = nullptr; + EXPECT_EQ(unofficial_napi_module_wrap_evaluate_sync( + s.env, created.module, options.url, undefined, &result), + napi_pending_exception); + napi_value exception = nullptr; + ASSERT_EQ(napi_get_and_clear_last_exception(s.env, &exception), napi_ok); + napi_value expected = nullptr; + ASSERT_EQ(napi_run_script(s.env, Str(s.env, "globalThis.moduleError"), &expected), napi_ok); + bool same_error = false; + ASSERT_EQ(napi_strict_equals(s.env, exception, expected, &same_error), napi_ok); + EXPECT_TRUE(same_error); + + ASSERT_EQ(unofficial_napi_event_loop_checkpoint( + s.env, unofficial_napi_event_loop_checkpoint_microtasks, true, nullptr), + napi_ok); + ASSERT_EQ(napi_run_script(s.env, Str(s.env, "unhandledModulePromises.size"), &result), napi_ok); + uint32_t unhandled_count = 0; + ASSERT_EQ(napi_get_value_uint32(s.env, result, &unhandled_count), napi_ok); + EXPECT_EQ(unhandled_count, 0u); + EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, created.module), napi_ok); +} + +TEST_F(Test71ContextifyCompat, ModuleHooksUseOneVersionedConfiguration) { + EnvScope s(runtime_.get()); + + unofficial_napi_module_hooks hooks{}; + hooks.size = sizeof(hooks) - 1; + hooks.version = UNOFFICIAL_NAPI_MODULE_HOOKS_VERSION; + EXPECT_EQ(unofficial_napi_module_wrap_set_hooks(s.env, &hooks), napi_invalid_arg); + + hooks.size = sizeof(hooks); + hooks.version = 0; + EXPECT_EQ(unofficial_napi_module_wrap_set_hooks(s.env, &hooks), napi_invalid_arg); + + hooks.version = UNOFFICIAL_NAPI_MODULE_HOOKS_VERSION; + EXPECT_EQ(unofficial_napi_module_wrap_set_hooks(s.env, &hooks), napi_ok); +} + +#if defined(NAPI_TEST_ENGINE_V8) +// V8 stores the host-defined-options block in each compiled function's +// ScriptOrigin. This regression covers the V8 bytecode fast path changed in +// v8/src/unofficial_napi_contextify.cc. QuickJS resolves dynamic imports by +// referrer name instead and has no equivalent per-function ScriptOrigin. +TEST_F(Test71ContextifyCompat, + FunctionBytecodePreservesExplicitHostDefinedOptionIdentity) { + EnvScope s(runtime_.get()); + + napi_value callback = nullptr; + ASSERT_EQ(napi_create_function(s.env, + "captureDynamicImportId", + NAPI_AUTO_LENGTH, + CaptureDynamicImportId, + nullptr, + &callback), + napi_ok); + const unofficial_napi_module_hooks hooks = { + sizeof(unofficial_napi_module_hooks), + UNOFFICIAL_NAPI_MODULE_HOOKS_VERSION, + callback, + nullptr, + }; + ASSERT_EQ(unofficial_napi_module_wrap_set_hooks(s.env, &hooks), napi_ok); + + napi_value undefined = nullptr; + ASSERT_EQ(napi_get_undefined(s.env, &undefined), napi_ok); + napi_value explicit_id = Sym(s.env, "explicit-cjs-host-id"); + ASSERT_NE(explicit_id, nullptr); + + auto compile_invoke_and_capture = [&](napi_value host_id) -> napi_value { + unofficial_napi_bytecode_open_options options{}; + options.size = sizeof(options); + options.version = UNOFFICIAL_NAPI_BYTECODE_OPEN_OPTIONS_VERSION; + options.source_text = Str(s.env, "return import('node:test');"); + options.filename = Str(s.env, "host-id.js"); + options.shape = unofficial_napi_bytecode_shape_cjs_function; + options.params_or_undefined = undefined; + options.host_defined_option_id = host_id; + unofficial_napi_bytecode_open_result result{}; + EXPECT_EQ(unofficial_napi_bytecode_open(s.env, &options, &result), napi_ok); + unofficial_napi_bytecode bytecode = result.bytecode; + EXPECT_NE(bytecode, nullptr); + if (bytecode == nullptr) return nullptr; + + const unofficial_napi_js_source source = + unofficial_napi_js_source_from_bytecode(bytecode); + napi_value compiled = nullptr; + EXPECT_EQ(unofficial_napi_contextify_compile_function(s.env, + &source, + Str(s.env, "host-id.js"), + 0, + 0, + undefined, + undefined, + undefined, + host_id, + &compiled), + napi_ok); + EXPECT_NE(compiled, nullptr); + + napi_value fn = nullptr; + napi_value global = nullptr; + napi_value import_result = nullptr; + if (compiled != nullptr) { + EXPECT_EQ(napi_get_named_property(s.env, compiled, "function", &fn), napi_ok); + EXPECT_EQ(napi_get_global(s.env, &global), napi_ok); + EXPECT_EQ(napi_call_function(s.env, global, fn, 0, nullptr, &import_result), napi_ok); + } + + napi_value captured = nullptr; + if (global != nullptr) { + EXPECT_EQ(napi_get_named_property( + s.env, global, "__captured_dynamic_import_id", &captured), + napi_ok); + if (import_result != nullptr) { + EXPECT_EQ(napi_set_named_property(s.env, global, "__host_id_import_result", import_result), + napi_ok); + napi_value ignored = nullptr; + EXPECT_EQ(napi_run_script( + s.env, + Str(s.env, "__host_id_import_result.catch(() => {});"), + &ignored), + napi_ok); + } + } + EXPECT_EQ(unofficial_napi_bytecode_release(s.env, bytecode), napi_ok); + return captured; + }; + + napi_value captured_without_id = compile_invoke_and_capture(undefined); + ASSERT_NE(captured_without_id, nullptr); + bool equal = false; + ASSERT_EQ(napi_strict_equals(s.env, captured_without_id, undefined, &equal), napi_ok); + EXPECT_TRUE(equal); + + napi_value captured_with_id = compile_invoke_and_capture(explicit_id); + ASSERT_NE(captured_with_id, nullptr); + ASSERT_EQ(napi_strict_equals(s.env, captured_with_id, explicit_id, &equal), napi_ok); + EXPECT_TRUE(equal); + + uint32_t checkpoint_state = unofficial_napi_event_loop_checkpoint_state_none; + EXPECT_EQ(unofficial_napi_event_loop_checkpoint( + s.env, + unofficial_napi_event_loop_checkpoint_microtasks, + true, + &checkpoint_state), + napi_ok); +} +#endif + +TEST_F(Test71ContextifyCompat, CompileFunctionDoesNotUseGlobalFunctionConstructor) { + EnvScope s(runtime_.get()); + + napi_value patch_result = nullptr; + ASSERT_EQ(napi_run_script( + s.env, + Str(s.env, + R"JS( +globalThis.Function = function Function() { + throw new Error("global Function constructor should not be called"); +}; +1; +)JS"), + &patch_result), + napi_ok); + + napi_value undef = nullptr; + ASSERT_EQ(napi_get_undefined(s.env, &undef), napi_ok); + + napi_value params = nullptr; + ASSERT_EQ(napi_create_array_with_length(s.env, 1, ¶ms), napi_ok); + ASSERT_EQ(napi_set_element(s.env, params, 0, Str(s.env, "value")), napi_ok); + + napi_value out = nullptr; + const unofficial_napi_js_source fn_source = + unofficial_napi_js_source_from_text(Str(s.env, "return value + 1;")); + ASSERT_EQ(unofficial_napi_contextify_compile_function(s.env, + &fn_source, + Str(s.env, "no-global-function.js"), + 0, + 0, + undef, + undef, + params, + undef, + &out), + napi_ok); + ASSERT_NE(out, nullptr); + + napi_value fn = nullptr; + ASSERT_EQ(napi_get_named_property(s.env, out, "function", &fn), napi_ok); + ASSERT_NE(fn, nullptr); + + napi_value global = nullptr; + ASSERT_EQ(napi_get_global(s.env, &global), napi_ok); + napi_value argv[1] = {nullptr}; + ASSERT_EQ(napi_create_int32(s.env, 41, &argv[0]), napi_ok); + + napi_value fn_result = nullptr; + ASSERT_EQ(napi_call_function(s.env, global, fn, 1, argv, &fn_result), napi_ok); + int32_t answer = 0; + ASSERT_EQ(napi_get_value_int32(s.env, fn_result, &answer), napi_ok); + EXPECT_EQ(answer, 42); +} + +TEST_F(Test71ContextifyCompat, CompileFunctionAcceptsHashbangBody) { + EnvScope s(runtime_.get()); + + napi_value undef = nullptr; + ASSERT_EQ(napi_get_undefined(s.env, &undef), napi_ok); + + napi_value out = nullptr; + const unofficial_napi_js_source hashbang_source = unofficial_napi_js_source_from_text( + Str(s.env, "#!/usr/bin/env node\nreturn 42;")); + ASSERT_EQ(unofficial_napi_contextify_compile_function(s.env, + &hashbang_source, + Str(s.env, ""), + 0, + 0, + undef, + undef, + undef, + undef, + &out), + napi_ok); + ASSERT_NE(out, nullptr); + + napi_value fn = nullptr; + ASSERT_EQ(napi_get_named_property(s.env, out, "function", &fn), napi_ok); + ASSERT_NE(fn, nullptr); + + napi_value global = nullptr; + ASSERT_EQ(napi_get_global(s.env, &global), napi_ok); + napi_value fn_result = nullptr; + ASSERT_EQ(napi_call_function(s.env, global, fn, 0, nullptr, &fn_result), napi_ok); + + int32_t answer = 0; + ASSERT_EQ(napi_get_value_int32(s.env, fn_result, &answer), napi_ok); + EXPECT_EQ(answer, 42); +} + +TEST_F(Test71ContextifyCompat, CompileFunctionRejectsBomBeforeHashbang) { + EnvScope s(runtime_.get()); + + napi_value undef = nullptr; + ASSERT_EQ(napi_get_undefined(s.env, &undef), napi_ok); + + napi_value out = nullptr; + const unofficial_napi_js_source bom_source = unofficial_napi_js_source_from_text( + Str(s.env, "\xEF\xBB\xBF#!/usr/bin/env node\nreturn 42;")); + EXPECT_EQ(unofficial_napi_contextify_compile_function(s.env, + &bom_source, + Str(s.env, "bom_hashbang.js"), + 0, + 0, + undef, + undef, + undef, + undef, + &out), + napi_pending_exception); + + bool pending = false; + ASSERT_EQ(napi_is_exception_pending(s.env, &pending), napi_ok); + EXPECT_TRUE(pending); + if (pending) { + napi_value error = nullptr; + ASSERT_EQ(napi_get_and_clear_last_exception(s.env, &error), napi_ok); + ASSERT_NE(error, nullptr); + } +} + +TEST_F(Test71ContextifyCompat, FunctionPrototypeSourceLocationsDoNotBlockStaticAssignments) { + EnvScope s(runtime_.get()); + + napi_value result = nullptr; + ASSERT_EQ(napi_run_script( + s.env, + Str(s.env, + R"JS( +"use strict"; +for (const key of ["fileName", "lineNumber", "columnNumber"]) { + if (Object.getOwnPropertyDescriptor(Function.prototype, key) !== undefined) { + throw new Error(`${key} should not be inherited from Function.prototype`); + } +} +class Manifest {} +Manifest.fileName = "package.json"; +Manifest.lineNumber = 1; +Manifest.columnNumber = 2; +const fileName = Object.getOwnPropertyDescriptor(Manifest, "fileName"); +const lineNumber = Object.getOwnPropertyDescriptor(Manifest, "lineNumber"); +const columnNumber = Object.getOwnPropertyDescriptor(Manifest, "columnNumber"); +fileName.value === "package.json" && fileName.writable && + lineNumber.value === 1 && lineNumber.writable && + columnNumber.value === 2 && columnNumber.writable ? 1 : 0; +)JS"), + &result), + napi_ok); + ASSERT_NE(result, nullptr); + + int32_t ok = 0; + ASSERT_EQ(napi_get_value_int32(s.env, result, &ok), napi_ok); + EXPECT_EQ(ok, 1); +} + +TEST_F(Test71ContextifyCompat, CjsCompileAndSyntaxDetection) { + EnvScope s(runtime_.get()); + + napi_value params = nullptr; + ASSERT_EQ(napi_create_array_with_length(s.env, 5, ¶ms), napi_ok); + ASSERT_EQ(napi_set_element(s.env, params, 0, Str(s.env, "exports")), napi_ok); + ASSERT_EQ(napi_set_element(s.env, params, 1, Str(s.env, "require")), napi_ok); + ASSERT_EQ(napi_set_element(s.env, params, 2, Str(s.env, "module")), napi_ok); + ASSERT_EQ(napi_set_element(s.env, params, 3, Str(s.env, "__filename")), napi_ok); + ASSERT_EQ(napi_set_element(s.env, params, 4, Str(s.env, "__dirname")), napi_ok); + + napi_value undef = nullptr; + ASSERT_EQ(napi_get_undefined(s.env, &undef), napi_ok); + + napi_value out = nullptr; + const unofficial_napi_js_source cjs_source = + unofficial_napi_js_source_from_text(Str(s.env, "module.exports = 1;")); + ASSERT_EQ(unofficial_napi_contextify_compile_function(s.env, + &cjs_source, + Str(s.env, "cjs.js"), + 0, + 0, + undef, + undef, + params, + undef, + &out), + napi_ok); + ASSERT_NE(out, nullptr); + napi_value fn = nullptr; + ASSERT_EQ(napi_get_named_property(s.env, out, "function", &fn), napi_ok); + ASSERT_NE(fn, nullptr); + + bool contains = false; + ASSERT_EQ(unofficial_napi_contextify_contains_module_syntax(s.env, + Str(s.env, "export const x = 1;"), + Str(s.env, "esmish.js"), + Str(s.env, "file:///esmish.js"), + true, + &contains), + napi_ok); + EXPECT_TRUE(contains); + + ASSERT_EQ(unofficial_napi_contextify_contains_module_syntax(s.env, + Str(s.env, "module.exports = 1;"), + Str(s.env, "cjs.js"), + Str(s.env, "file:///cjs.js"), + true, + &contains), + napi_ok); + EXPECT_FALSE(contains); + + ASSERT_EQ(unofficial_napi_contextify_contains_module_syntax( + s.env, + Str(s.env, + "var __export = (target, all) => target;\n" + "// Annotate the CommonJS export names for ESM import in node:\n" + "0 && (module.exports = { build });\n"), + Str(s.env, "esbuild-ish.js"), + Str(s.env, "file:///esbuild-ish.js"), + true, + &contains), + napi_ok); + EXPECT_FALSE(contains); + + ASSERT_EQ(unofficial_napi_contextify_contains_module_syntax(s.env, + Str(s.env, "import('node:fs');"), + Str(s.env, "dynamic-import.cjs"), + Str(s.env, "file:///dynamic-import.cjs"), + true, + &contains), + napi_ok); + EXPECT_FALSE(contains); + + ASSERT_EQ(unofficial_napi_contextify_contains_module_syntax(s.env, + Str(s.env, "await 1;"), + Str(s.env, "tla.js"), + Str(s.env, "file:///tla.js"), + true, + &contains), + napi_ok); + EXPECT_TRUE(contains); +} + +TEST_F(Test71ContextifyCompat, PrivateSymbolAcceptsAutoLength) { + EnvScope s(runtime_.get()); + + napi_value symbol = nullptr; + ASSERT_EQ(unofficial_napi_create_private_symbol( + s.env, "node:arrowMessage", NAPI_AUTO_LENGTH, &symbol), + napi_ok); + ASSERT_NE(symbol, nullptr); + + napi_valuetype type = napi_undefined; + ASSERT_EQ(napi_typeof(s.env, symbol, &type), napi_ok); + EXPECT_TRUE(type == napi_symbol || type == napi_object); +} + +#if defined(NAPI_TEST_ENGINE_V8) +TEST_F(Test71ContextifyCompat, PrepareStackTraceResultIsNotRewritten) { + EnvScope s(runtime_.get()); + + napi_value callback = nullptr; + ASSERT_EQ(napi_create_function(s.env, + "prepareStackTrace", + NAPI_AUTO_LENGTH, + ReturnPreparedStack, + nullptr, + &callback), + napi_ok); + ASSERT_NE(callback, nullptr); + ASSERT_EQ(unofficial_napi_set_prepare_stack_trace_callback(s.env, callback), + napi_ok); + + napi_value source = Str(s.env, "new Error('sentinel').stack"); + napi_value stack = nullptr; + ASSERT_EQ(napi_run_script(s.env, source, &stack), napi_ok); + ASSERT_NE(stack, nullptr); + + size_t length = 0; + ASSERT_EQ(napi_get_value_string_utf8(s.env, stack, nullptr, 0, &length), + napi_ok); + std::string actual(length + 1, '\0'); + size_t written = 0; + ASSERT_EQ(napi_get_value_string_utf8( + s.env, stack, actual.data(), actual.size(), &written), + napi_ok); + actual.resize(written); + EXPECT_EQ(actual, kPreparedStack); + + ASSERT_EQ(unofficial_napi_set_prepare_stack_trace_callback(s.env, nullptr), + napi_ok); +} +#endif + +// The rest pins how the deprecated API maps onto realms. + +namespace { + +napi_value Undefined(napi_env env) { + napi_value out = nullptr; + if (napi_get_undefined(env, &out) != napi_ok) return nullptr; + return out; +} + +napi_value Null(napi_env env) { + napi_value out = nullptr; + if (napi_get_null(env, &out) != napi_ok) return nullptr; + return out; +} + +napi_value Global(napi_env env) { + napi_value out = nullptr; + if (napi_get_global(env, &out) != napi_ok) return nullptr; + return out; +} + +napi_value Object(napi_env env) { + napi_value out = nullptr; + if (napi_create_object(env, &out) != napi_ok) return nullptr; + return out; +} + +napi_value Prototype(napi_env env, napi_value object) { + napi_value out = nullptr; + if (object == nullptr || napi_get_prototype(env, object, &out) != napi_ok) return nullptr; + return out; +} + +bool StrictEquals(napi_env env, napi_value a, napi_value b) { + bool same = false; + return a != nullptr && b != nullptr && napi_strict_equals(env, a, b, &same) == napi_ok && + same; +} + +// Runs `source` with the realm API (NULL: the env's own realm). +napi_value RunIn(napi_env env, unofficial_napi_realm realm, const char* source) { + const unofficial_napi_js_source script = unofficial_napi_js_source_from_text(Str(env, source)); + napi_value result = nullptr; + if (unofficial_napi_run_script(env, realm, &script, Str(env, "realm.js"), 0, 0, -1, true, false, + false, nullptr, &result) != napi_ok) { + return nullptr; + } + return result; +} + +// Runs `source` with the deprecated call. +napi_status RunInContext(napi_env env, + napi_value sandbox_or_null, + const char* source, + napi_value* result_out) { + const unofficial_napi_js_source script = unofficial_napi_js_source_from_text(Str(env, source)); + return unofficial_napi_contextify_run_script(env, sandbox_or_null, &script, Str(env, "ctx.js"), 0, + 0, -1, true, false, false, nullptr, result_out); +} + +// Compiles and calls `body` with the deprecated call. +napi_status CallCompiled(napi_env env, + napi_value parsing_context, + const char* body, + napi_value* result_out) { + const unofficial_napi_js_source source = unofficial_napi_js_source_from_text(Str(env, body)); + napi_value compiled = nullptr; + napi_status status = unofficial_napi_contextify_compile_function( + env, &source, Str(env, "fn.js"), 0, 0, parsing_context, nullptr, nullptr, nullptr, + &compiled); + if (status != napi_ok) return status; + napi_value fn = nullptr; + status = napi_get_named_property(env, compiled, "function", &fn); + if (status != napi_ok) return status; + return napi_call_function(env, Undefined(env), fn, 0, nullptr, result_out); +} + +napi_status MakeContext(napi_env env, napi_value sandbox_or_symbol, napi_value* result_out) { + return unofficial_napi_contextify_make_context(env, sandbox_or_symbol, Str(env, "ctx"), + Str(env, "test://origin"), true, true, false, + Sym(env, "hdo"), result_out); +} + +unofficial_napi_realm FreshRealm(napi_env env, napi_value* global_out) { + unofficial_napi_realm realm = nullptr; + if (unofficial_napi_create_realm(env, nullptr, &realm, global_out) != napi_ok) return nullptr; + return realm; +} + +// main's version-1 layouts, which binaries built against main pass. The +// providers must read no further than they end. +struct MainBytecodeOpenOptionsV1 { + uint32_t size; + uint32_t version; + napi_value source_text; + napi_value filename; + int32_t shape; + napi_value params_or_undefined; + napi_value host_defined_option_id; + int32_t line_offset; + int32_t column_offset; + const uint8_t* cache_bytes; + size_t cache_byte_length; + uint8_t has_cache; + uint8_t cache_policy; +}; + +struct MainModuleCreateOptionsV1 { + size_t size; + uint32_t version; + unofficial_napi_module_kind kind; + napi_value wrapper; + napi_value url; + napi_value context_or_undefined; + union { + unofficial_napi_source_text_module_options source_text; + unofficial_napi_synthetic_module_options synthetic; + } payload; +}; + +struct MainEnvHooksV1 { + uint32_t size; + uint32_t version; + void* data; + unofficial_napi_context_token_callback context_token_assign_callback; + unofficial_napi_context_token_callback context_token_unassign_callback; + unofficial_napi_enqueue_foreground_task_callback enqueue_foreground_task_callback; + unofficial_napi_fatal_error_callback fatal_error_callback; + unofficial_napi_oom_error_callback oom_error_callback; +}; + +static_assert(sizeof(MainBytecodeOpenOptionsV1) == UNOFFICIAL_NAPI_BYTECODE_OPEN_OPTIONS_V1_SIZE); +static_assert(offsetof(unofficial_napi_bytecode_open_options, cache_policy) == + offsetof(MainBytecodeOpenOptionsV1, cache_policy)); +static_assert(sizeof(MainModuleCreateOptionsV1) == UNOFFICIAL_NAPI_MODULE_CREATE_OPTIONS_V1_SIZE); +static_assert(offsetof(unofficial_napi_module_create_options, context_or_undefined) == + offsetof(MainModuleCreateOptionsV1, context_or_undefined)); +static_assert(offsetof(unofficial_napi_module_create_options, payload) == + offsetof(MainModuleCreateOptionsV1, payload)); +static_assert(sizeof(MainEnvHooksV1) == sizeof(unofficial_napi_env_hooks)); +static_assert(offsetof(unofficial_napi_env_hooks, context_token_unassign_callback) == + offsetof(MainEnvHooksV1, context_token_unassign_callback)); +static_assert(offsetof(unofficial_napi_env_hooks, oom_error_callback) == + offsetof(MainEnvHooksV1, oom_error_callback)); +static_assert(UNOFFICIAL_NAPI_ENV_HOOKS_VERSION == 1); + +MainBytecodeOpenOptionsV1 MainBytecodeOptions(napi_env env, const char* source) { + MainBytecodeOpenOptionsV1 options{}; + options.size = sizeof(options); + options.version = 1; + options.source_text = Str(env, source); + options.filename = Str(env, "bytecode.js"); + options.shape = unofficial_napi_bytecode_shape_script; + options.params_or_undefined = Undefined(env); + options.host_defined_option_id = Undefined(env); + return options; +} + +// Opens a script that does not parse and returns the prototype of the +// SyntaxError, which shows the realm it was compiled for. +napi_value SyntaxErrorPrototype(napi_env env, const void* options) { + unofficial_napi_bytecode_open_result opened{}; + if (unofficial_napi_bytecode_open( + env, static_cast(options), &opened) != + napi_pending_exception) { + return nullptr; + } + napi_value error = nullptr; + if (napi_get_and_clear_last_exception(env, &error) != napi_ok) return nullptr; + return Prototype(env, error); +} + +// Creates "export const g = globalThis;" from `options` (main's version-1 +// layout or the current one), evaluates it and returns g. `status_out` +// receives module_wrap_create's status. +template +napi_value ModuleGlobal(napi_env env, Options options, napi_status* status_out) { + const unofficial_napi_js_source source = + unofficial_napi_js_source_from_text(Str(env, "export const g = globalThis;")); + options.kind = unofficial_napi_module_source_text; + options.wrapper = Object(env); + options.url = Str(env, "compat.mjs"); + options.payload.source_text.source = &source; + options.payload.source_text.host_defined_option_id = Undefined(env); + unofficial_napi_module_create_result created{}; + *status_out = unofficial_napi_module_wrap_create( + env, reinterpret_cast(&options), &created); + if (*status_out != napi_ok) return nullptr; + napi_value evaluated = nullptr; + napi_value ns = nullptr; + napi_value g = nullptr; + if (unofficial_napi_module_wrap_link(env, created.module, 0, nullptr) != napi_ok || + unofficial_napi_module_wrap_instantiate(env, created.module) != napi_ok || + unofficial_napi_module_wrap_evaluate(env, created.module, -1, false, &evaluated) != + napi_ok || + unofficial_napi_module_wrap_get_namespace(env, created.module, &ns) != napi_ok || + napi_get_named_property(env, ns, "g", &g) != napi_ok) { + g = nullptr; + } + unofficial_napi_module_wrap_destroy(env, created.module); + return g; +} + +MainModuleCreateOptionsV1 MainModuleOptions(napi_value context) { + MainModuleCreateOptionsV1 options{}; + options.size = sizeof(options); + options.version = 1; + options.context_or_undefined = context; + return options; +} + +unofficial_napi_module_create_options ModuleOptions(unofficial_napi_realm realm, + napi_value context) { + unofficial_napi_module_create_options options{}; + options.size = sizeof(options); + options.version = UNOFFICIAL_NAPI_MODULE_CREATE_OPTIONS_VERSION; + options.realm_or_null = realm; + options.context_or_undefined = context; + return options; +} + +// Opens a realm scope for the enclosing block. +class EnteredRealm { + public: + EnteredRealm(napi_env env, unofficial_napi_realm realm) : env_(env) { + EXPECT_EQ(unofficial_napi_enter_realm(env, realm, &scope_), napi_ok); + } + ~EnteredRealm() { EXPECT_EQ(unofficial_napi_leave_realm(env_, scope_), napi_ok); } + EnteredRealm(const EnteredRealm&) = delete; + EnteredRealm& operator=(const EnteredRealm&) = delete; + + private: + napi_env env_; + unofficial_napi_realm_scope scope_ = 0; +}; + +struct CallbackRealm { + napi_ref seen = nullptr; +}; + +// Records the global a deprecated run with no sandbox sees. +napi_value SeeNullishContext(napi_env env, napi_callback_info info) { + void* data = nullptr; + if (napi_get_cb_info(env, info, nullptr, nullptr, nullptr, &data) != napi_ok) return nullptr; + napi_value seen = nullptr; + if (RunInContext(env, nullptr, "globalThis", &seen) != napi_ok) return nullptr; + napi_create_reference(env, seen, 1, &static_cast(data)->seen); + return nullptr; +} + +} // namespace + +// vm.constants.DONT_CONTEXTIFY: a symbol makes a realm with a fresh global. +TEST_F(Test71ContextifyCompat, MakeContextWithASymbolMakesAFreshGlobal) { + EnvScope s(runtime_.get()); + + napi_value global = nullptr; + ASSERT_EQ(MakeContext(s.env, Sym(s.env, "DONT_CONTEXTIFY"), &global), napi_ok); + ASSERT_NE(global, nullptr); + EXPECT_FALSE(StrictEquals(s.env, global, Global(s.env))); + + unofficial_napi_realm realm = nullptr; + ASSERT_EQ(unofficial_napi_get_realm(s.env, global, &realm), napi_ok); + ASSERT_NE(realm, nullptr); + EXPECT_TRUE(StrictEquals(s.env, RunIn(s.env, realm, "globalThis"), global)); + napi_value seen = nullptr; + ASSERT_EQ(RunInContext(s.env, global, "globalThis", &seen), napi_ok); + EXPECT_TRUE(StrictEquals(s.env, seen, global)); + EXPECT_FALSE(StrictEquals(s.env, RunIn(s.env, realm, "Object.prototype"), + RunIn(s.env, nullptr, "Object.prototype"))); +} + +// main's V8 statuses. (main's QuickJS took a NULL name, and returned an +// already contextified sandbox again; both providers now refuse.) +TEST_F(Test71ContextifyCompat, MakeContextRefusesWhatMainRefused) { + EnvScope s(runtime_.get()); + + napi_value sandbox = Object(s.env); + napi_value number = nullptr; + ASSERT_EQ(napi_create_int32(s.env, 7, &number), napi_ok); + napi_value result = nullptr; + EXPECT_EQ(unofficial_napi_contextify_make_context(s.env, sandbox, nullptr, nullptr, true, true, + false, nullptr, &result), + napi_invalid_arg); + EXPECT_EQ(MakeContext(s.env, nullptr, &result), napi_invalid_arg); + EXPECT_EQ(MakeContext(s.env, number, &result), napi_invalid_arg); + EXPECT_EQ(MakeContext(s.env, Undefined(s.env), &result), napi_invalid_arg); + EXPECT_EQ(MakeContext(s.env, sandbox, nullptr), napi_invalid_arg); + EXPECT_EQ(result, nullptr); + + ASSERT_EQ(MakeContext(s.env, sandbox, &result), napi_ok); + EXPECT_TRUE(StrictEquals(s.env, result, sandbox)); + // A sandbox belongs to one realm, whichever call made it. + napi_value again = nullptr; + EXPECT_EQ(MakeContext(s.env, sandbox, &again), napi_invalid_arg); + napi_value realm_sandbox = Object(s.env); + unofficial_napi_realm_options options; + unofficial_napi_realm_options_init(&options); + options.sandbox_or_null = realm_sandbox; + unofficial_napi_realm realm = nullptr; + ASSERT_EQ(unofficial_napi_create_realm(s.env, &options, &realm, nullptr), napi_ok); + EXPECT_EQ(MakeContext(s.env, realm_sandbox, &again), napi_invalid_arg); + EXPECT_EQ(again, nullptr); +} + +// The objects and realms of both APIs mix. +TEST_F(Test71ContextifyCompat, ContextifiedObjectsAreRealms) { + EnvScope s(runtime_.get()); + + napi_value sandbox = Object(s.env); + napi_value result = nullptr; + ASSERT_EQ(MakeContext(s.env, sandbox, &result), napi_ok); + unofficial_napi_realm realm = nullptr; + ASSERT_EQ(unofficial_napi_get_realm(s.env, sandbox, &realm), napi_ok); + ASSERT_NE(realm, nullptr); + ASSERT_NE(RunIn(s.env, realm, "globalThis.answer = 42; 1"), nullptr); + napi_value answer = nullptr; + ASSERT_EQ(RunInContext(s.env, sandbox, "answer", &answer), napi_ok); + int32_t value = 0; + ASSERT_EQ(napi_get_value_int32(s.env, answer, &value), napi_ok); + EXPECT_EQ(value, 42); + + // (QuickJS copies a sandbox into its realm's own global, so a sandbox + // realm is told apart by its properties, not by globalThis.) + napi_value realm_sandbox = Object(s.env); + napi_value marker = Object(s.env); + ASSERT_EQ(napi_set_named_property(s.env, realm_sandbox, "marker", marker), napi_ok); + unofficial_napi_realm_options options; + unofficial_napi_realm_options_init(&options); + options.sandbox_or_null = realm_sandbox; + ASSERT_EQ(unofficial_napi_create_realm(s.env, &options, &realm, nullptr), napi_ok); + napi_value seen = nullptr; + ASSERT_EQ(RunInContext(s.env, realm_sandbox, "marker", &seen), napi_ok); + EXPECT_TRUE(StrictEquals(s.env, seen, marker)); + ASSERT_EQ(CallCompiled(s.env, realm_sandbox, "return marker;", &seen), napi_ok); + EXPECT_TRUE(StrictEquals(s.env, seen, marker)); +} + +// A sandbox or parsing context is a contextified object, the env's own global +// or nothing; anything else fails as in main's V8. (main's QuickJS compiled in +// the env's context for an object that was not contextified.) +TEST_F(Test71ContextifyCompat, ContextArgumentsNameARealm) { + EnvScope s(runtime_.get()); + + napi_value env_global = Global(s.env); + for (napi_value nothing : {static_cast(nullptr), Undefined(s.env), Null(s.env)}) { + napi_value seen = nullptr; + ASSERT_EQ(RunInContext(s.env, nothing, "globalThis", &seen), napi_ok); + EXPECT_TRUE(StrictEquals(s.env, seen, env_global)); + seen = nullptr; + ASSERT_EQ(CallCompiled(s.env, nothing, "return globalThis;", &seen), napi_ok); + EXPECT_TRUE(StrictEquals(s.env, seen, env_global)); + } + napi_value seen = nullptr; + ASSERT_EQ(RunInContext(s.env, env_global, "globalThis", &seen), napi_ok); + EXPECT_TRUE(StrictEquals(s.env, seen, env_global)); + ASSERT_EQ(CallCompiled(s.env, env_global, "return globalThis;", &seen), napi_ok); + EXPECT_TRUE(StrictEquals(s.env, seen, env_global)); + + napi_value number = nullptr; + ASSERT_EQ(napi_create_int32(s.env, 7, &number), napi_ok); + for (napi_value other : {Object(s.env), number}) { + EXPECT_EQ(RunInContext(s.env, other, "1", &seen), napi_invalid_arg); + EXPECT_EQ(CallCompiled(s.env, other, "return 1;", &seen), napi_invalid_arg); + } +} + +// No sandbox means the current realm, as the env's context did in main: the +// realm entered, or the realm of the running callback. The realm API's NULL +// is always the env's own realm. +TEST_F(Test71ContextifyCompat, NoContextMeansTheCurrentRealm) { + EnvScope s(runtime_.get()); + + napi_value env_global = Global(s.env); + napi_value realm_global = nullptr; + unofficial_napi_realm realm = FreshRealm(s.env, &realm_global); + ASSERT_NE(realm, nullptr); + + CallbackRealm callback; + napi_value fn = nullptr; + { + EnteredRealm entered(s.env, realm); + napi_value seen = nullptr; + ASSERT_EQ(RunInContext(s.env, Undefined(s.env), "globalThis", &seen), napi_ok); + EXPECT_TRUE(StrictEquals(s.env, seen, realm_global)); + ASSERT_EQ(CallCompiled(s.env, nullptr, "return globalThis;", &seen), napi_ok); + EXPECT_TRUE(StrictEquals(s.env, seen, realm_global)); + EXPECT_TRUE(StrictEquals(s.env, RunIn(s.env, nullptr, "globalThis"), env_global)); + // A native function made here belongs to the realm. + ASSERT_EQ(napi_create_function(s.env, "see", NAPI_AUTO_LENGTH, SeeNullishContext, &callback, + &fn), + napi_ok); + } + + napi_value seen = nullptr; + ASSERT_EQ(RunInContext(s.env, nullptr, "globalThis", &seen), napi_ok); + EXPECT_TRUE(StrictEquals(s.env, seen, env_global)); + + ASSERT_EQ(napi_call_function(s.env, env_global, fn, 0, nullptr, &seen), napi_ok); + ASSERT_NE(callback.seen, nullptr); + ASSERT_EQ(napi_get_reference_value(s.env, callback.seen, &seen), napi_ok); + EXPECT_TRUE(StrictEquals(s.env, seen, realm_global)); + ASSERT_EQ(napi_delete_reference(s.env, callback.seen), napi_ok); +} + +// Version 1 of the bytecode options (main's layout) compiles for the current +// realm; version 2 for its `realm_or_null`, NULL being the env's own. +TEST_F(Test71ContextifyCompat, BytecodeOptionsOfBothVersions) { + EnvScope s(runtime_.get()); + + napi_value a_global = nullptr; + napi_value b_global = nullptr; + unofficial_napi_realm a = FreshRealm(s.env, &a_global); + unofficial_napi_realm b = FreshRealm(s.env, &b_global); + ASSERT_NE(a, nullptr); + ASSERT_NE(b, nullptr); + napi_value env_syntax = RunIn(s.env, nullptr, "SyntaxError.prototype"); + napi_value a_syntax = RunIn(s.env, a, "SyntaxError.prototype"); + napi_value b_syntax = RunIn(s.env, b, "SyntaxError.prototype"); + ASSERT_FALSE(StrictEquals(s.env, a_syntax, env_syntax)); + + MainBytecodeOpenOptionsV1 v1 = MainBytecodeOptions(s.env, "("); + EXPECT_TRUE(StrictEquals(s.env, SyntaxErrorPrototype(s.env, &v1), env_syntax)); + { + EnteredRealm entered(s.env, a); + EXPECT_TRUE(StrictEquals(s.env, SyntaxErrorPrototype(s.env, &v1), a_syntax)); + } + MainBytecodeOpenOptionsV1 ok_v1 = MainBytecodeOptions(s.env, "1 + 1"); + unofficial_napi_bytecode_open_result opened{}; + ASSERT_EQ(unofficial_napi_bytecode_open( + s.env, reinterpret_cast(&ok_v1), + &opened), + napi_ok); + ASSERT_NE(opened.bytecode, nullptr); + EXPECT_EQ(unofficial_napi_bytecode_release(s.env, opened.bytecode), napi_ok); + MainBytecodeOpenOptionsV1 short_v1 = v1; + short_v1.size -= 1; + EXPECT_EQ(unofficial_napi_bytecode_open( + s.env, reinterpret_cast(&short_v1), + &opened), + napi_invalid_arg); + + unofficial_napi_bytecode_open_options v2{}; + std::memcpy(&v2, &v1, sizeof(v1)); + v2.size = sizeof(v2); + v2.version = UNOFFICIAL_NAPI_BYTECODE_OPEN_OPTIONS_VERSION; + v2.realm_or_null = b; + EXPECT_TRUE(StrictEquals(s.env, SyntaxErrorPrototype(s.env, &v2), b_syntax)); + v2.realm_or_null = nullptr; + { + EnteredRealm entered(s.env, a); + EXPECT_TRUE(StrictEquals(s.env, SyntaxErrorPrototype(s.env, &v2), env_syntax)); + } + // A version 1 struct ends before the realm, which is not read even when the + // struct is long enough to have one. + unofficial_napi_bytecode_open_options long_v1 = v2; + long_v1.version = 1; + long_v1.realm_or_null = b; + EXPECT_TRUE(StrictEquals(s.env, SyntaxErrorPrototype(s.env, &long_v1), env_syntax)); + + unofficial_napi_bytecode_open_options invalid = v2; + invalid.size = UNOFFICIAL_NAPI_BYTECODE_OPEN_OPTIONS_V1_SIZE; + EXPECT_EQ(unofficial_napi_bytecode_open(s.env, &invalid, &opened), napi_invalid_arg); + for (uint32_t version : {0u, 3u}) { + invalid = v2; + invalid.version = version; + EXPECT_EQ(unofficial_napi_bytecode_open(s.env, &invalid, &opened), napi_invalid_arg); + } +} + +// Version 1 of the module options (main's layout) takes a context, nothing +// being the current realm. Version 2 takes `realm_or_null`, or still the +// deprecated context, nothing being the env's realm then. +TEST_F(Test71ContextifyCompat, ModuleOptionsOfBothVersions) { + EnvScope s(runtime_.get()); + + napi_value env_global = Global(s.env); + napi_value a_global = nullptr; + napi_value b_global = nullptr; + unofficial_napi_realm a = FreshRealm(s.env, &a_global); + unofficial_napi_realm b = FreshRealm(s.env, &b_global); + ASSERT_NE(a, nullptr); + ASSERT_NE(b, nullptr); + napi_status status = napi_generic_failure; + + EXPECT_TRUE(StrictEquals(s.env, ModuleGlobal(s.env, MainModuleOptions(a_global), &status), + a_global)); + EXPECT_TRUE(StrictEquals(s.env, ModuleGlobal(s.env, MainModuleOptions(env_global), &status), + env_global)); + for (napi_value nothing : {static_cast(nullptr), Undefined(s.env)}) { + EXPECT_TRUE(StrictEquals(s.env, ModuleGlobal(s.env, MainModuleOptions(nothing), &status), + env_global)); + EnteredRealm entered(s.env, a); + EXPECT_TRUE(StrictEquals(s.env, ModuleGlobal(s.env, MainModuleOptions(nothing), &status), + a_global)); + } + EXPECT_EQ(ModuleGlobal(s.env, MainModuleOptions(Object(s.env)), &status), nullptr); + EXPECT_EQ(status, napi_invalid_arg); + MainModuleCreateOptionsV1 short_v1 = MainModuleOptions(nullptr); + short_v1.size -= 1; + EXPECT_EQ(ModuleGlobal(s.env, short_v1, &status), nullptr); + EXPECT_EQ(status, napi_invalid_arg); + { + // A version 1 struct ends before the realm, which is not read even when + // the struct is long enough to have one. + unofficial_napi_module_create_options long_v1 = ModuleOptions(b, Undefined(s.env)); + long_v1.version = 1; + EnteredRealm entered(s.env, a); + EXPECT_TRUE(StrictEquals(s.env, ModuleGlobal(s.env, long_v1, &status), a_global)); + } + + EXPECT_TRUE(StrictEquals(s.env, ModuleGlobal(s.env, ModuleOptions(a, nullptr), &status), + a_global)); + EXPECT_TRUE(StrictEquals(s.env, ModuleGlobal(s.env, ModuleOptions(a, Undefined(s.env)), &status), + a_global)); + // Old source built against this header: the version macro with a context. + EXPECT_TRUE(StrictEquals(s.env, ModuleGlobal(s.env, ModuleOptions(nullptr, a_global), &status), + a_global)); + { + EnteredRealm entered(s.env, a); + EXPECT_TRUE(StrictEquals( + s.env, ModuleGlobal(s.env, ModuleOptions(nullptr, Undefined(s.env)), &status), + env_global)); + } + // A realm and a context together are ambiguous. + EXPECT_EQ(ModuleGlobal(s.env, ModuleOptions(a, b_global), &status), nullptr); + EXPECT_EQ(status, napi_invalid_arg); + EXPECT_EQ(ModuleGlobal(s.env, ModuleOptions(nullptr, Object(s.env)), &status), nullptr); + EXPECT_EQ(status, napi_invalid_arg); + unofficial_napi_module_create_options short_v2 = ModuleOptions(a, nullptr); + short_v2.size = UNOFFICIAL_NAPI_MODULE_CREATE_OPTIONS_V1_SIZE; + EXPECT_EQ(ModuleGlobal(s.env, short_v2, &status), nullptr); + EXPECT_EQ(status, napi_invalid_arg); +} + +namespace { + +struct TokenLog { + napi_env env = nullptr; + // 'a' assign, 'u' unassign, 'c' the cleanup hook. + std::vector> events; + bool wrong_env = false; +}; + +void AssignToken(napi_env env, void* token, void* data) { + auto* log = static_cast(data); + log->wrong_env |= env != log->env; + log->events.emplace_back('a', token); +} + +void UnassignToken(napi_env env, void* token, void* data) { + auto* log = static_cast(data); + log->wrong_env |= env != log->env; + log->events.emplace_back('u', token); +} + +void RecordCleanup(void* data) { + static_cast(data)->events.emplace_back('c', nullptr); +} + +void MakeRealmInCleanup(void* data) { + napi_env env = static_cast(data)->env; + napi_handle_scope scope = nullptr; + if (napi_open_handle_scope(env, &scope) != napi_ok) return; + napi_value global = nullptr; + FreshRealm(env, &global); + napi_close_handle_scope(env, scope); +} + +} // namespace + +// The deprecated context-token hooks: V8 assigns a token when a realm is +// created and unassigns it once, when the collected realm's record is freed or +// when the env is released. QuickJS does not accept them, as in main. +TEST_F(Test71ContextifyCompat, ContextTokensFollowRealms) { + napi_env env = nullptr; + unofficial_napi_env_owner owner = nullptr; + unofficial_napi_env_create_options create_options{}; + InitializeTestEnvCreateOptions(&create_options); + ASSERT_EQ(unofficial_napi_create_env(NAPI_TEST_MODULE_API_VERSION, &create_options, &env, &owner), + napi_ok); + TokenLog log; + log.env = env; + + // A realm made before the hooks are attached gets no token. + napi_ref early = nullptr; + { + napi_handle_scope scope = nullptr; + ASSERT_EQ(napi_open_handle_scope(env, &scope), napi_ok); + napi_value global = nullptr; + ASSERT_NE(FreshRealm(env, &global), nullptr); + ASSERT_EQ(napi_create_reference(env, global, 1, &early), napi_ok); + ASSERT_EQ(napi_close_handle_scope(env, scope), napi_ok); + } + + unofficial_napi_env_hooks hooks{}; + hooks.size = sizeof(hooks); + hooks.version = UNOFFICIAL_NAPI_ENV_HOOKS_VERSION; + hooks.data = &log; + hooks.context_token_assign_callback = AssignToken; + hooks.context_token_unassign_callback = UnassignToken; + uint64_t accepted = 0; + unofficial_napi_env_hooks invalid = hooks; + invalid.size -= 1; + EXPECT_EQ(unofficial_napi_attach_env(env, &invalid, &accepted), napi_invalid_arg); + invalid = hooks; + invalid.version = 2; + EXPECT_EQ(unofficial_napi_attach_env(env, &invalid, &accepted), napi_invalid_arg); + ASSERT_EQ(unofficial_napi_attach_env(env, &hooks, &accepted), napi_ok); +#if defined(NAPI_TEST_ENGINE_V8) + EXPECT_EQ(accepted, static_cast(unofficial_napi_env_hook_context_token_assign | + unofficial_napi_env_hook_context_token_unassign)); +#else + EXPECT_EQ(accepted, 0u); +#endif + ASSERT_EQ(napi_add_env_cleanup_hook(env, RecordCleanup, &log), napi_ok); + ASSERT_EQ(napi_add_env_cleanup_hook(env, MakeRealmInCleanup, &log), napi_ok); + + // A realm that nothing keeps, and one from make_context kept until release. + { + napi_handle_scope scope = nullptr; + ASSERT_EQ(napi_open_handle_scope(env, &scope), napi_ok); + napi_value global = nullptr; + ASSERT_NE(FreshRealm(env, &global), nullptr); + ASSERT_EQ(napi_close_handle_scope(env, scope), napi_ok); + } + napi_ref kept = nullptr; + { + napi_handle_scope scope = nullptr; + ASSERT_EQ(napi_open_handle_scope(env, &scope), napi_ok); + napi_value global = nullptr; + ASSERT_EQ(MakeContext(env, Sym(env, "DONT_CONTEXTIFY"), &global), napi_ok); + ASSERT_EQ(napi_create_reference(env, global, 1, &kept), napi_ok); + ASSERT_EQ(napi_close_handle_scope(env, scope), napi_ok); + } + +#if defined(NAPI_TEST_ENGINE_V8) + ASSERT_EQ(log.events.size(), 2u); + EXPECT_EQ(log.events[0].first, 'a'); + EXPECT_EQ(log.events[1].first, 'a'); + void* collected_token = log.events[0].second; + void* kept_token = log.events[1].second; + EXPECT_NE(collected_token, nullptr); + EXPECT_NE(kept_token, nullptr); + EXPECT_NE(collected_token, kept_token); + + // Collection frees the first realm's record, and with it its token. + ASSERT_EQ(unofficial_napi_collect_garbage(env), napi_ok); + ASSERT_EQ(log.events.size(), 3u); + EXPECT_EQ(log.events[2], std::make_pair('u', collected_token)); +#else + ASSERT_EQ(unofficial_napi_collect_garbage(env), napi_ok); + EXPECT_TRUE(log.events.empty()); +#endif + + // Release unassigns the realm still alive before the cleanup hooks run, and + // a realm a cleanup hook makes after them. + ASSERT_EQ(unofficial_napi_release_env(owner, nullptr), napi_ok); +#if defined(NAPI_TEST_ENGINE_V8) + ASSERT_EQ(log.events.size(), 7u); + EXPECT_EQ(log.events[3], std::make_pair('u', kept_token)); + EXPECT_EQ(log.events[4].first, 'a'); + EXPECT_EQ(log.events[5].first, 'c'); + EXPECT_EQ(log.events[6], std::make_pair('u', log.events[4].second)); +#else + ASSERT_EQ(log.events.size(), 1u); + EXPECT_EQ(log.events[0].first, 'c'); +#endif + EXPECT_FALSE(log.wrong_env); +} From b5cc2c712b39a0442a6f21fd4a4376f91c5d67f4 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 15:03:12 -0800 Subject: [PATCH 065/150] Document the deprecated compatibility API docs/realms.md said the old imports were gone and version-1 structs rejected. It now has a section on the deprecated API: what replaces each call and struct, what a context argument and its absence mean, how the structs grow, the context tokens on realms, where main's QuickJS differed, and the guest imports. Co-Authored-By: Claude Opus 5.5 --- docs/realms.md | 82 ++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 70 insertions(+), 12 deletions(-) diff --git a/docs/realms.md b/docs/realms.md index 226a4d680a..b0b33097e9 100644 --- a/docs/realms.md +++ b/docs/realms.md @@ -112,21 +112,76 @@ napi_status unofficial_napi_compile_function(napi_env env, unofficial_napi_realm run their callbacks in the realm that made them, the embedder keeps a reference to the global `napi_get_global` returns when they are made, and enters `get_realm` of that global around each callback. -- **Changed from `main`:** - - `unofficial_napi_contextify_make_context` is replaced by `create_realm`. - - `unofficial_napi_contextify_run_script` and - `unofficial_napi_contextify_compile_function` become `run_script` and - `compile_function`. They take a realm instead of a sandbox or parsing - context. - - The module options' `context_or_undefined` becomes `realm_or_null`. - - The context-token hooks are gone (env hooks are version 2). +- **Changed from `main`:** the realm API replaces the contextify calls, the + module options' `context_or_undefined` and the context-token hooks. They + still work, deprecated, on top of realms: see + [Deprecated compatibility API](#deprecated-compatibility-api). - **Guest ABI:** a realm id is the value id of the realm's global or sandbox, and 0 is the env's realm. The bridge keeps no realm table: it resolves the id again with `get_realm` on each call, so the id lives exactly as long as - its value id. Version 1 structs are rejected and the old imports are gone. - The scope imports are `unofficial_napi_enter_realm(env, realm_id, - scope_out_ptr) -> status` and `unofficial_napi_leave_realm(env, scope: i64) - -> status`; the token is the provider's, passed through as a u64. + its value id. The scope imports are `unofficial_napi_enter_realm(env, + realm_id, scope_out_ptr) -> status` and `unofficial_napi_leave_realm(env, + scope: i64) -> status`; the token is the provider's, passed through as a + u64. + +## Deprecated compatibility API + +Code written against `main`, EdgeJS's included, builds and runs unchanged, +from source or as a binary. The API it uses is marked deprecated in +`unofficial_napi.h` (`UNOFFICIAL_NAPI_DEPRECATED`; define +`UNOFFICIAL_NAPI_NO_DEPRECATION_WARNINGS` to silence it) and is removed in a +future major release. It is a thin layer over realms, the same for V8 and +QuickJS (`lib/src/napi_compat.cc`), so contextified objects and realms mix: +`get_realm` finds the realm of a contextified object, and the deprecated +calls take a realm's global or sandbox. + +| Deprecated | Use instead | How it maps | +|---|---|---| +| `unofficial_napi_contextify_make_context` | `create_realm` | An object or function sandbox becomes `sandbox_or_null`; a symbol (`vm.constants.DONT_CONTEXTIFY`) makes a fresh global. The other arguments become the realm options of the same names. Returns the realm's global: the sandbox, or the fresh global. | +| `unofficial_napi_contextify_run_script` | `run_script` | The sandbox names the realm, as below. | +| `unofficial_napi_contextify_compile_function` | `compile_function` | The parsing context names the realm, as below. | +| Bytecode-open options version 1 | Version 2, `realm_or_null` | Compiles for the current realm. | +| Module-create options version 1, and `context_or_undefined` in version 2 | Version 2, `realm_or_null` | The context names the realm, as below. | +| The env hooks' `context_token_assign_callback` and `context_token_unassign_callback` | Per-realm state keyed by the realm's global | Tokens on realms, as below. | + +- **A context argument** (sandbox, parsing context, `context_or_undefined`) + is a contextified object, naming its realm, the env's own global, naming + the env's realm, or nothing. Anything else fails with `napi_invalid_arg`. +- **Nothing** (NULL, `undefined` or `null`) means what the env's context + meant on `main`: the current realm. That is the env's own realm unless the + embedder enters a realm or a native function of another realm is running. + Version 2 of the module options is the exception: there nothing means the + env's realm, as a NULL `realm_or_null` does. The realm API's NULL is + always the env's realm. +- **Structs grow at the end.** Version 1 of the bytecode-open and + module-create options keeps `main`'s layout, and version 2 appends + `realm_or_null`. A provider reads a version 1 struct only up to + `UNOFFICIAL_NAPI_*_V1_SIZE`. A version 2 module struct sets + `realm_or_null` or the deprecated `context_or_undefined`, not both + (`napi_invalid_arg`). The env hooks are version 1 again, `main`'s layout. +- **Context tokens.** V8 accepts the token callbacks, as on `main`. A realm's + token is its record, which outlives the assignment. V8 assigns it when + `create_realm` (and so `make_context`) makes the realm, and unassigns it + once: when it frees the record of the collected realm (in the next + `create_realm` or in `collect_garbage`), or, for a realm still alive, at + env release before the cleanup hooks run (and after them for realms they + made). Realms made before the hooks were attached get no token. Both + hooks run in the env's realm. On `main` a context lived until release, so + tokens were only unassigned then. QuickJS does not accept the hooks and + never calls them, as on `main`. +- **Statuses are `main`'s V8 ones.** `main`'s QuickJS differed: it took a + NULL `name`, refused a symbol sandbox, returned an already contextified + sandbox again, compiled in the env's context for a parsing context that + was not contextified, and ignored `context_or_undefined`. It now behaves + as V8 does. +- **Guest ABI.** The wasm32 layouts of version 1 are `main`'s, and version 2 + appends a u32 realm id. The guest imports + `unofficial_napi_contextify_make_context`, `…_run_script` and + `…_compile_function` keep `main`'s names and signatures, on the bridge's + realm calls. A sandbox id is the value id of a realm's global or sandbox, + as on `main`, and 0 is the current realm. With a host-JS native Worker + realm (#125), `make_context` fails as `create_realm` does, and + `run_script` with id 0 goes to `evaluate()`. ## How the current realm works @@ -222,3 +277,6 @@ and interrupt callbacks push the env's realm. one realm per document, and its bindings must create objects in the document's realm and run there. Native code now acts in a current realm, with ECMAScript's rules. +- **The deprecated API** came back on top of realms, with its structs grown + at the end instead of changed in place, so that code built against `main` + keeps working until a major release removes it. From dd28ef11666057b2fcdf9ba716db63e7d92c5b9c Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 15:39:02 -0800 Subject: [PATCH 066/150] Bring back the contextify guest imports, on realms Guests built against main import unofficial_napi_contextify_make_context, _run_script and _compile_function, so they failed to instantiate on next. The three imports are back with main's names and wasm signatures, in the WASIX and the host-JS guest layers. They need no new bridge calls: they use create_realm, get_realm, run_script and compile_function. A context id is the value id of a realm's global or sandbox, which is also its realm id, so the ids make_context returned on main still work. 0, undefined or null is the current realm. make_context takes an object or function sandbox, or a symbol for a fresh global, and returns the realm's global; other sandboxes and a missing name are napi_invalid_arg, as with main's V8. In a host-JS native Worker realm, make_context fails with the pending TypeError of create_realm, and run_script with no sandbox runs in the env's realm, which goes to the bridge's evaluate(). The WAT guest of the concurrency tests imports unofficial_napi_contextify_run_script again, and its script does not block other envs. A host-JS test drives the three imports from a guest: a sandbox's realm, the current realm while a realm is entered, the env's global, and the refused cases. Co-Authored-By: Claude Opus 5.5 --- src/guest/compat.rs | 50 +++++++++++- src/guest/napi.rs | 120 ++++++++++++++++++++++++++++ src/guest/napi_js.rs | 121 ++++++++++++++++++++++++++++ src/snapi_js.rs | 167 ++++++++++++++++++++++++++++++++++++++- tests/concurrent_envs.rs | 8 ++ tests/wat_guest/mod.rs | 19 +++++ 6 files changed, 480 insertions(+), 5 deletions(-) diff --git a/src/guest/compat.rs b/src/guest/compat.rs index 13e47e4fab..d7d5df523a 100644 --- a/src/guest/compat.rs +++ b/src/guest/compat.rs @@ -1,7 +1,8 @@ -//! The deprecated guest API (version 1 of the option structs) on the bridge's -//! realm calls, for both guest backends, as lib/src/napi_compat.cc does for -//! native code. Ids are guest value ids, 0 is NULL, and a realm id is the -//! value id of the realm's global or sandbox, 0 for the env's own realm. +//! The deprecated guest API (the contextify imports and version 1 of the +//! option structs) on the bridge's realm calls, for both guest backends, as +//! lib/src/napi_compat.cc does for native code. Ids are guest value ids, 0 is +//! NULL, and a realm id is the value id of the realm's global or sandbox, 0 +//! for the env's own realm. use crate::snapi::*; @@ -11,6 +12,7 @@ const NAPI_INVALID_ARG: i32 = 1; // napi_valuetype. const NAPI_UNDEFINED: i32 = 0; const NAPI_NULL: i32 = 1; +const NAPI_SYMBOL: i32 = 5; const NAPI_OBJECT: i32 = 6; const NAPI_FUNCTION: i32 = 7; @@ -133,3 +135,43 @@ pub(crate) fn module_create_realm( } realm_from_context(env, context_or_undefined, version == 1) } + +/// unofficial_napi_contextify_make_context: an object or function sandbox +/// becomes the realm's sandbox, a symbol makes a fresh global. Returns the +/// realm's global: the sandbox, or the fresh global. +#[allow(clippy::too_many_arguments)] +pub(crate) fn make_context( + env: SnapiEnv, + sandbox_or_symbol: u32, + name: u32, + origin_or_undefined: u32, + allow_code_gen_strings: i32, + allow_code_gen_wasm: i32, + own_microtask_queue: i32, + host_defined_option_id: u32, +) -> Result { + if name == 0 { + return Err(NAPI_INVALID_ARG); + } + let sandbox = match type_of(env, sandbox_or_symbol) { + Some(NAPI_SYMBOL) => 0, + Some(NAPI_OBJECT | NAPI_FUNCTION) => sandbox_or_symbol, + _ => return Err(NAPI_INVALID_ARG), + }; + let (mut realm, mut global) = (0u32, 0u32); + check(unsafe { + snapi_bridge_unofficial_create_realm( + env, + sandbox, + name, + origin_or_undefined, + host_defined_option_id, + i32::from(allow_code_gen_strings != 0), + i32::from(allow_code_gen_wasm != 0), + i32::from(own_microtask_queue != 0), + &mut realm, + &mut global, + ) + })?; + Ok(global) +} diff --git a/src/guest/napi.rs b/src/guest/napi.rs index b839fba6a5..b5d86567fd 100644 --- a/src/guest/napi.rs +++ b/src/guest/napi.rs @@ -1123,6 +1123,123 @@ fn guest_unofficial_napi_contextify_contains_module_syntax( status } +/// Deprecated (use create_realm), kept for older guests. Makes a realm over +/// the sandbox, or with a fresh global for a symbol, and writes its global, +/// which is also its realm id. +#[allow(clippy::too_many_arguments)] +fn guest_unofficial_napi_contextify_make_context( + mut env: FunctionEnvMut, + napi_env: u32, + sandbox_or_symbol: u32, + name: u32, + origin_or_undefined: u32, + allow_code_gen_strings: i32, + allow_code_gen_wasm: i32, + own_microtask_queue: i32, + host_defined_option_id: u32, + result_ptr: u32, +) -> i32 { + let env_handle = snapi_env(&env, napi_env); + match compat::make_context( + env_handle, + sandbox_or_symbol, + name, + origin_or_undefined, + allow_code_gen_strings, + allow_code_gen_wasm, + own_microtask_queue, + host_defined_option_id, + ) { + Ok(global) => { + if result_ptr != 0 { + write_guest_u32(&mut env, result_ptr, global); + } + 0 + } + Err(status) => status, + } +} + +/// Deprecated (use unofficial_napi_run_script), kept for older guests. The +/// sandbox names the realm; 0, undefined or null is the current realm. +#[allow(clippy::too_many_arguments)] +#[allow(clippy::result_large_err)] +fn guest_unofficial_napi_contextify_run_script( + env: FunctionEnvMut, + napi_env: u32, + sandbox_or_null: u32, + source: u32, + filename: u32, + line_offset: i32, + column_offset: i32, + timeout: i64, + display_errors: i32, + break_on_sigint: i32, + break_on_first_line: i32, + host_defined_option_id: u32, + result_ptr: u32, +) -> Result { + let realm = match compat::realm_from_context(snapi_env(&env, napi_env), sandbox_or_null, true) { + Ok(realm) => realm, + Err(status) => return Ok(status), + }; + guest_unofficial_napi_run_script( + env, + napi_env, + realm, + source, + filename, + line_offset, + column_offset, + timeout, + display_errors, + break_on_sigint, + break_on_first_line, + host_defined_option_id, + result_ptr, + ) +} + +/// Deprecated (use unofficial_napi_compile_function), kept for older +/// guests. The parsing context names the realm; 0, undefined or null is the +/// current realm. +#[allow(clippy::too_many_arguments)] +fn guest_unofficial_napi_contextify_compile_function( + env: FunctionEnvMut, + napi_env: u32, + source: u32, + filename: u32, + line_offset: i32, + column_offset: i32, + parsing_context_or_undefined: u32, + context_extensions_or_undefined: u32, + params_or_undefined: u32, + host_defined_option_id: u32, + result_ptr: u32, +) -> i32 { + let realm = match compat::realm_from_context( + snapi_env(&env, napi_env), + parsing_context_or_undefined, + true, + ) { + Ok(realm) => realm, + Err(status) => return status, + }; + guest_unofficial_napi_compile_function( + env, + napi_env, + realm, + source, + filename, + line_offset, + column_offset, + context_extensions_or_undefined, + params_or_undefined, + host_defined_option_id, + result_ptr, + ) +} + /// A guest realm id is the value id of the realm's global (or sandbox); 0 is /// the env's own realm. See `snapi_bridge_unofficial_create_realm`. fn guest_unofficial_napi_create_realm( @@ -4995,6 +5112,9 @@ pub fn register_napi_imports( "unofficial_napi_take_heap_snapshot" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_take_heap_snapshot), "unofficial_napi_create_serdes_binding" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_create_serdes_binding), "unofficial_napi_contextify_contains_module_syntax" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_contextify_contains_module_syntax), + "unofficial_napi_contextify_make_context" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_contextify_make_context), + "unofficial_napi_contextify_run_script" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_contextify_run_script), + "unofficial_napi_contextify_compile_function" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_contextify_compile_function), "unofficial_napi_create_realm" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_create_realm), "unofficial_napi_get_realm" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_get_realm), "unofficial_napi_enter_realm" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_enter_realm), diff --git a/src/guest/napi_js.rs b/src/guest/napi_js.rs index 1e0eff8a07..ddf1a07dbd 100644 --- a/src/guest/napi_js.rs +++ b/src/guest/napi_js.rs @@ -1564,6 +1564,124 @@ fn guest_unofficial_napi_contextify_contains_module_syntax( status } +/// Deprecated (use create_realm), kept for older guests. Makes a realm over +/// the sandbox, or with a fresh global for a symbol, and writes its global, +/// which is also its realm id. A native Worker realm refuses it as it +/// refuses create_realm. +#[allow(clippy::too_many_arguments)] +fn guest_unofficial_napi_contextify_make_context( + mut env: FunctionEnvMut, + napi_env: u32, + sandbox_or_symbol: u32, + name: u32, + origin_or_undefined: u32, + allow_code_gen_strings: i32, + allow_code_gen_wasm: i32, + own_microtask_queue: i32, + host_defined_option_id: u32, + result_ptr: u32, +) -> i32 { + let env_handle = snapi_env(&env, napi_env); + match compat::make_context( + env_handle, + sandbox_or_symbol, + name, + origin_or_undefined, + allow_code_gen_strings, + allow_code_gen_wasm, + own_microtask_queue, + host_defined_option_id, + ) { + Ok(global) => { + if result_ptr != 0 { + write_guest_u32(&mut env, result_ptr, global); + } + 0 + } + Err(status) => status, + } +} + +/// Deprecated (use unofficial_napi_run_script), kept for older guests. The +/// sandbox names the realm; 0, undefined or null is the current realm, so in +/// a native Worker realm the script goes to its evaluate(). +#[allow(clippy::too_many_arguments)] +fn guest_unofficial_napi_contextify_run_script( + env: FunctionEnvMut, + napi_env: u32, + sandbox_or_null: u32, + source_ptr: u32, + filename: u32, + line_offset: i32, + column_offset: i32, + timeout: i64, + display_errors: i32, + break_on_sigint: i32, + break_on_first_line: i32, + host_defined_option_id: u32, + result_ptr: u32, +) -> i32 { + let realm = match compat::realm_from_context(snapi_env(&env, napi_env), sandbox_or_null, true) { + Ok(realm) => realm, + Err(status) => return status, + }; + guest_unofficial_napi_run_script( + env, + napi_env, + realm, + source_ptr, + filename, + line_offset, + column_offset, + timeout, + display_errors, + break_on_sigint, + break_on_first_line, + host_defined_option_id, + result_ptr, + ) +} + +/// Deprecated (use unofficial_napi_compile_function), kept for older +/// guests. The parsing context names the realm; 0, undefined or null is the +/// current realm. +#[allow(clippy::too_many_arguments)] +fn guest_unofficial_napi_contextify_compile_function( + env: FunctionEnvMut, + napi_env: u32, + source_ptr: u32, + filename: u32, + line_offset: i32, + column_offset: i32, + parsing_context_or_undefined: u32, + context_extensions_or_undefined: u32, + params_or_undefined: u32, + host_defined_option_id: u32, + result_ptr: u32, +) -> i32 { + let realm = match compat::realm_from_context( + snapi_env(&env, napi_env), + parsing_context_or_undefined, + true, + ) { + Ok(realm) => realm, + Err(status) => return status, + }; + guest_unofficial_napi_compile_function( + env, + napi_env, + realm, + source_ptr, + filename, + line_offset, + column_offset, + context_extensions_or_undefined, + params_or_undefined, + host_defined_option_id, + result_ptr, + ) +} + // A guest realm id is the value id of the realm's global (its sandbox, when it // has one); 0 means the env's own realm. @@ -5774,6 +5892,9 @@ pub fn register_napi_imports( "unofficial_napi_take_heap_snapshot" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_take_heap_snapshot), "unofficial_napi_create_serdes_binding" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_create_serdes_binding), "unofficial_napi_contextify_contains_module_syntax" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_contextify_contains_module_syntax), + "unofficial_napi_contextify_make_context" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_contextify_make_context), + "unofficial_napi_contextify_run_script" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_contextify_run_script), + "unofficial_napi_contextify_compile_function" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_contextify_compile_function), "unofficial_napi_create_realm" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_create_realm), "unofficial_napi_get_realm" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_get_realm), "unofficial_napi_enter_realm" => Function::new_typed_with_env(store, fe, guest_unofficial_napi_enter_realm), diff --git a/src/snapi_js.rs b/src/snapi_js.rs index d97bd87066..10bc7f74b2 100644 --- a/src/snapi_js.rs +++ b/src/snapi_js.rs @@ -231,7 +231,7 @@ export function wasmer_napi_console_error(message) { // module captures it and deletes the global, so author code can't reach it. // No untrusted code may run in that global before then. The bridge has: // evaluate(source, filename, lineOffset, columnOffset): runs a classic script -// (unofficial_napi_contextify_run_script); its return value is the result. +// (unofficial_napi_run_script); its return value is the result. // binding(source): runs source text in the global scope and returns its // completion value (napi_run_script). // enterCallback() / leaveCallback(): bracket all guest code the environment @@ -8982,4 +8982,169 @@ mod tests { } assert_eq!(current_realm(env), 0); } + + /// A guest built against older headers: the deprecated contextify imports + /// take a realm's global or sandbox as a context, and 0 for the current + /// realm. + const CONTEXTIFY_GUEST: &str = r#" + (module + (import "env" "memory" (memory 1)) + (import "napi_extension_wasmer_v0" "unofficial_napi_contextify_make_context" + (func $make_context (param i32 i32 i32 i32 i32 i32 i32 i32 i32) (result i32))) + (import "napi_extension_wasmer_v0" "unofficial_napi_contextify_run_script" + (func $run_script + (param i32 i32 i32 i32 i32 i32 i64 i32 i32 i32 i32 i32) (result i32))) + (import "napi_extension_wasmer_v0" "unofficial_napi_contextify_compile_function" + (func $compile_function + (param i32 i32 i32 i32 i32 i32 i32 i32 i32 i32) (result i32))) + ;; (env, sandbox_or_symbol, name, result_ptr) + (func (export "make_context") (param i32 i32 i32 i32) (result i32) + (call $make_context (local.get 0) (local.get 1) (local.get 2) (i32.const 0) + (i32.const 1) (i32.const 1) (i32.const 0) (i32.const 0) (local.get 3))) + ;; (env, sandbox_or_null, source_ptr, filename, result_ptr) + (func (export "run_script") (param i32 i32 i32 i32 i32) (result i32) + (call $run_script (local.get 0) (local.get 1) (local.get 2) (local.get 3) + (i32.const 0) (i32.const 0) (i64.const -1) (i32.const 1) (i32.const 0) + (i32.const 0) (i32.const 0) (local.get 4))) + ;; (env, source_ptr, filename, parsing_context, result_ptr) + (func (export "compile_function") (param i32 i32 i32 i32 i32) (result i32) + (call $compile_function (local.get 0) (local.get 1) (local.get 2) (i32.const 0) + (i32.const 0) (local.get 3) (i32.const 0) (i32.const 0) (i32.const 0) + (local.get 4)))) + "#; + + #[wasm_bindgen_test] + fn guest_contextify_imports_resolve_contexts_to_realms() { + use wasmer::{FunctionEnv, Imports, Instance, Memory, MemoryType, Module, Store}; + + const SOURCE: u32 = 16; + const RESULT: u32 = 32; + let mut store = Store::default(); + let memory = Memory::new(&mut store, MemoryType::new(1, None, false)).unwrap(); + let env = new_env(); + let mut napi_env = crate::env::NapiEnv::new( + crate::budget::ResourceBudget::unlimited(), + None, + std::sync::Arc::default(), + std::sync::Arc::default(), + ); + napi_env.memory = Some(memory.clone()); + // Dropping the store releases the env. + let (guest_env, _) = napi_env.register_napi_env(env); + let function_env = FunctionEnv::new(&mut store, napi_env); + let mut imports = Imports::new(); + crate::guest::napi::register_napi_imports(&mut store, &function_env, &mut imports); + imports.define("env", "memory", memory.clone()); + let module = Module::new(&store, wat::parse_str(CONTEXTIFY_GUEST).unwrap()).unwrap(); + let instance = Instance::new(&mut store, &module, &imports).unwrap(); + let make_context = instance + .exports + .get_typed_function::<(u32, u32, u32, u32), i32>(&store, "make_context") + .unwrap(); + let run_script = instance + .exports + .get_typed_function::<(u32, u32, u32, u32, u32), i32>(&store, "run_script") + .unwrap(); + let compile_function = instance + .exports + .get_typed_function::<(u32, u32, u32, u32, u32), i32>(&store, "compile_function") + .unwrap(); + let read_u32 = |store: &Store| { + let mut bytes = [0; 4]; + memory.view(store).read(RESULT.into(), &mut bytes).unwrap(); + u32::from_le_bytes(bytes) + }; + // A text unofficial_napi_js_source at SOURCE. + let set_source = |store: &Store, text: u32| { + let mut bytes = [0; 12]; + bytes[4..8].copy_from_slice(&text.to_le_bytes()); + memory.view(store).write(SOURCE.into(), &bytes).unwrap(); + }; + let state = unsafe { env_mut(env) }.unwrap(); + let name = state.agent.insert_primitive("compat".into()); + let filename = state.agent.insert_primitive("compat.js".into()); + let script = state + .agent + .insert_primitive("typeof marker === 'number' ? marker : 0".into()); + let body = state + .agent + .insert_primitive("return typeof marker === 'number' ? marker : 0;".into()); + let sandbox_object = Object::new(); + Reflect::set(&sandbox_object, &"marker".into(), &73.into()).unwrap(); + let sandbox = state.agent.insert(sandbox_object.into()); + let plain = state.agent.insert(Object::new().into()); + let symbol = state.agent.insert(js_sys::Symbol::for_("compat").into()); + let number = state.agent.insert_primitive(1.into()); + set_source(&store, script); + let run = |store: &mut Store, context: u32| -> Result { + match run_script + .call(store, guest_env, context, SOURCE, filename, RESULT) + .unwrap() + { + NAPI_OK => Ok(value(env, read_u32(store))), + status => Err(status), + } + }; + + // make_context makes the sandbox a realm's global, and its id names + // that realm. + assert_eq!( + make_context + .call(&mut store, guest_env, sandbox, name, RESULT) + .unwrap(), + NAPI_OK + ); + let context = read_u32(&store); + assert!(Object::is(&value(env, context), &value(env, sandbox))); + assert_eq!(realm_of(env, context), Ok(context)); + assert_eq!(run(&mut store, context), Ok(73.into())); + + // 0 is the current realm, the env's unless a realm is entered. The + // env's own global names the env's realm; other objects nothing. + assert_eq!(run(&mut store, 0), Ok(0.into())); + let scope = enter(env, context).unwrap(); + assert_eq!(run(&mut store, 0), Ok(73.into())); + set_source(&store, body); + assert_eq!( + compile_function + .call(&mut store, guest_env, SOURCE, filename, 0, RESULT) + .unwrap(), + NAPI_OK + ); + let compiled = value(env, read_u32(&store)); + let function: js_sys::Function = Reflect::get(&compiled, &"function".into()) + .unwrap() + .unchecked_into(); + assert_eq!(function.call0(&JsValue::UNDEFINED), Ok(73.into())); + set_source(&store, script); + let env_global = { + let inner = enter(env, 0).unwrap(); + let global = global_id(env); + assert_eq!(leave(env, inner), NAPI_OK); + global + }; + assert_eq!(run(&mut store, env_global), Ok(0.into())); + assert_eq!(leave(env, scope), NAPI_OK); + assert_eq!(run(&mut store, plain), Err(NAPI_INVALID_ARG)); + + // A symbol makes a fresh global; other values and a missing name are + // refused. + assert_eq!( + make_context + .call(&mut store, guest_env, symbol, name, RESULT) + .unwrap(), + NAPI_OK + ); + let fresh = read_u32(&store); + assert_ne!(realm_of(env, fresh), Ok(0)); + assert_eq!(run(&mut store, fresh), Ok(0.into())); + for (sandbox, name) in [(number, name), (0, name), (symbol, 0)] { + assert_eq!( + make_context + .call(&mut store, guest_env, sandbox, name, RESULT) + .unwrap(), + NAPI_INVALID_ARG + ); + } + } } diff --git a/tests/concurrent_envs.rs b/tests/concurrent_envs.rs index 4e46d70ce5..7bb2f68688 100644 --- a/tests/concurrent_envs.rs +++ b/tests/concurrent_envs.rs @@ -36,6 +36,7 @@ const TIMEOUT: Duration = Duration::from_secs(10); #[derive(Clone, Copy, Debug)] enum Entry { RunScriptInRealm, + ContextifyRunScript, ModuleEvaluate, MicrotaskCheckpoint, SerializerGetter, @@ -64,6 +65,7 @@ fn wait_in_one_env_and_notify_from_another(engine: &Engine, module: &Module, ent assert_eq!(guest.install(), 0); match entry { Entry::RunScriptInRealm => assert_eq!(guest.run_script_in_realm(WAIT_SCRIPT), 0), + Entry::ContextifyRunScript => assert_eq!(guest.eval_contextify(WAIT_SCRIPT), 0), Entry::ModuleEvaluate => assert_eq!(guest.eval_module(WAIT_SCRIPT), 0), Entry::MicrotaskCheckpoint => { let queued = format!("Promise.resolve().then(() => {{ {WAIT_SCRIPT} }})"); @@ -122,6 +124,12 @@ fn a_realm_script_does_not_block_other_envs() { wait_in_one_env_and_notify_from_another(&engine, &module, Entry::RunScriptInRealm); } +#[test] +fn a_contextified_script_does_not_block_other_envs() { + let (engine, module) = compile(); + wait_in_one_env_and_notify_from_another(&engine, &module, Entry::ContextifyRunScript); +} + #[test] fn a_module_evaluation_does_not_block_other_envs() { let (engine, module) = compile(); diff --git a/tests/wat_guest/mod.rs b/tests/wat_guest/mod.rs index 3b296d7e51..3d5ec553a6 100644 --- a/tests/wat_guest/mod.rs +++ b/tests/wat_guest/mod.rs @@ -36,6 +36,10 @@ const WAT: &str = r#"(module (import "napi_extension_wasmer_v0" "unofficial_napi_run_script" (func $realm_run_script (param i32 i32 i32 i32 i32 i32 i64 i32 i32 i32 i32 i32) (result i32))) + ;; Deprecated, kept for guests built against older headers. + (import "napi_extension_wasmer_v0" "unofficial_napi_contextify_run_script" + (func $contextify_run_script + (param i32 i32 i32 i32 i32 i32 i64 i32 i32 i32 i32 i32) (result i32))) (import "napi_extension_wasmer_v0" "unofficial_napi_event_loop_checkpoint" (func $checkpoint (param i32 i32 i32 i32) (result i32))) (import "napi_extension_wasmer_v0" "unofficial_napi_collect_garbage" @@ -150,6 +154,15 @@ const WAT: &str = r#"(module (call $realm_run_script (global.get $env) (i32.const 0) (i32.const 16) (i32.load (i32.const 56)) (i32.const 0) (i32.const 0) (i64.const -1) (i32.const 1) (i32.const 0) (i32.const 0) (i32.const 0) (i32.const 32))) + ;; The deprecated import with no sandbox: the current realm. + (func (export "eval_contextify") (param $ptr i32) (param $len i32) (result i32) + (i32.store (i32.const 16) (i32.const 0)) + (i32.store (i32.const 20) (call $string (local.get $ptr) (local.get $len))) + (i32.store (i32.const 24) (i32.const 0)) + (i32.store (i32.const 56) (call $string (i32.const 116) (i32.const 7))) + (call $contextify_run_script (global.get $env) (i32.const 0) (i32.const 16) + (i32.load (i32.const 56)) (i32.const 0) (i32.const 0) (i64.const -1) + (i32.const 1) (i32.const 0) (i32.const 0) (i32.const 0) (i32.const 32))) ;; Creates, links, instantiates, evaluates and destroys a source text ;; module. Returns 0, or 1000 * step + status for the first failing step. ;; The options are version 1, as a guest built against older headers @@ -374,6 +387,12 @@ impl Guest { self.call_with_source("run_script_in_realm", source) } + /// The deprecated `unofficial_napi_contextify_run_script` with no + /// sandbox, which is the current realm; returns its status. + pub fn eval_contextify(&mut self, source: &str) -> i32 { + self.call_with_source("eval_contextify", source) + } + /// Creates, links, instantiates, evaluates and destroys a source text /// module. Returns 0, or `1000 * step + status` for the first failing /// step (1 create, 2 link, 3 instantiate, 4 evaluate, 5 destroy). From c352f38e170ffc77009a6a9f836086e04860439f Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 15:39:12 -0800 Subject: [PATCH 067/150] Run main's run_script_test through the deprecated API run_script_compat_test is main's run_script_test.c, which uses the contextify calls and module options with context_or_undefined. It builds against the current headers with deprecation warnings off and passes natively and as a WASIX guest. Two of its modules send version 1 options, laid out as a guest built against main's header sends them; the others are old source on the new header, which sends version 2 with context_or_undefined. New checks cover what the old calls resolve to. With no context they run in the current realm, which is the contextified object's while its realm is entered: scripts, functions, version 1 modules and version 1 bytecode. The env's global names the env's realm, and a plain object nothing. Version 2 module options with no realm use the env's realm and may not name both a realm and a context. make_context takes a symbol for a fresh global and refuses a number or a missing name. main's env hooks attach: natively V8 accepts the token callbacks and calls them, and a guest has none accepted, as on main. Co-Authored-By: Claude Opus 5.5 --- tests/programs/manifest.json | 5 + tests/programs/run_script_compat_test.c | 1168 +++++++++++++++++++++++ 2 files changed, 1173 insertions(+) create mode 100644 tests/programs/run_script_compat_test.c diff --git a/tests/programs/manifest.json b/tests/programs/manifest.json index 6716b6277b..d3565a7032 100644 --- a/tests/programs/manifest.json +++ b/tests/programs/manifest.json @@ -180,6 +180,11 @@ "description": "Guest pointers >= 2 GiB are read from and written to, not rejected or skipped", "expected_stdout": "TEST_HIGH_GUEST_POINTERS_OK=1\n" }, + { + "name": "run_script_compat_test", + "description": "main's run_script_test through the deprecated contextify calls and version 1 module and bytecode options: they still build and run, and resolve to the right realm", + "expected_stdout": "RUN_SCRIPT_COMPAT_TEST_OK=1\n" + }, { "name": "test_realm", "description": "Realms: own globals, shared values, native functions in the env's realm, get_realm, sandbox realms, scripts, functions, modules and bytecode in a realm, entering a realm, collection of dropped realms, release with live realms", diff --git a/tests/programs/run_script_compat_test.c b/tests/programs/run_script_compat_test.c new file mode 100644 index 0000000000..ee11bff5f2 --- /dev/null +++ b/tests/programs/run_script_compat_test.c @@ -0,0 +1,1168 @@ +// main's run_script_test.c, from before realms: it uses the deprecated +// contextify calls and module options with context_or_undefined, to show that +// such code still builds and runs. Changes from main: +// - Deprecation warnings are off. +// - CreateSourceModule and the contextified module send version 1 options, +// laid out as a guest built against main's header sends them. The other +// modules are old source built against this header, which sends version 2 +// with context_or_undefined. +// - CheckMakeContext, CheckCurrentRealm and CheckEnvHooks are new: they +// check the realm each deprecated call resolves to, and main's env hooks. +// - It reports RUN_SCRIPT_COMPAT_TEST, not RUN_SCRIPT_TEST. +#define UNOFFICIAL_NAPI_NO_DEPRECATION_WARNINGS + +#include +#include +#include + +#include "napi_test_helpers.h" +#include "node_api.h" +#include "unofficial_napi.h" + +static int wrap_finalizer_count = 0; +static int add_finalizer_count = 0; +static int facade_evaluation_count = 0; + +typedef struct { + napi_value proxy; + int own_keys_count; +} nested_property_names_context; + +static napi_value NAPI_CDECL NestedOwnKeys(napi_env env, + napi_callback_info info) { + size_t argc = 0; + void* data = NULL; + if (napi_get_cb_info(env, info, &argc, NULL, NULL, &data) != napi_ok) { + return NULL; + } + + nested_property_names_context* context = + (nested_property_names_context*)data; + context->own_keys_count++; + + napi_value keys; + napi_value key; + if (napi_create_array_with_length(env, 1, &keys) != napi_ok || + napi_create_string_utf8(env, "nestedKey", NAPI_AUTO_LENGTH, &key) != + napi_ok || + napi_set_element(env, keys, 0, key) != napi_ok) { + return NULL; + } + return keys; +} + +static napi_value NAPI_CDECL EnumerateNestedProxy(napi_env env, + napi_callback_info info) { + size_t argc = 0; + void* data = NULL; + if (napi_get_cb_info(env, info, &argc, NULL, NULL, &data) != napi_ok) { + return NULL; + } + + nested_property_names_context* context = + (nested_property_names_context*)data; + napi_value names; + napi_value all_names; + uint32_t names_length = 0; + uint32_t all_names_length = 0; + if (napi_get_property_names(env, context->proxy, &names) != napi_ok || + napi_get_array_length(env, names, &names_length) != napi_ok || + napi_get_all_property_names(env, + context->proxy, + napi_key_own_only, + napi_key_all_properties, + napi_key_keep_numbers, + &all_names) != napi_ok || + napi_get_array_length(env, all_names, &all_names_length) != napi_ok) { + return NULL; + } + + napi_value result; + if (napi_create_uint32(env, names_length + all_names_length, &result) != + napi_ok) { + return NULL; + } + return result; +} + +static napi_value NAPI_CDECL CountFacadeEvaluation(napi_env env, + napi_callback_info info) { + (void)info; + facade_evaluation_count++; + napi_value result = NULL; + if (napi_get_undefined(env, &result) != napi_ok) return NULL; + return result; +} + +static void NAPI_CDECL CountWrapFinalizer(napi_env env, + void* data, + void* hint) { + (void)env; + if ((uintptr_t)data == 0x11 && (uintptr_t)hint == 0x12) { + wrap_finalizer_count++; + } +} + +static void NAPI_CDECL CountAddedFinalizer(napi_env env, + void* data, + void* hint) { + (void)env; + if ((uintptr_t)data == 0x21 && (uintptr_t)hint == 0x22) { + add_finalizer_count++; + } +} + +static int RunInt32Script(napi_env env, const char* source, int32_t* result_out) { + napi_value script; + napi_value result; + napi_status status = napi_create_string_utf8( + env, source, NAPI_AUTO_LENGTH, &script); + if (status != napi_ok) return status; + status = napi_run_script(env, script, &result); + if (status != napi_ok) return status; + return napi_get_value_int32(env, result, result_out); +} + +static int RunStringScript(napi_env env, + const char* source, + char* result_out, + size_t result_capacity) { + napi_value script; + napi_value result; + size_t result_length = 0; + napi_status status = napi_create_string_utf8( + env, source, NAPI_AUTO_LENGTH, &script); + if (status != napi_ok) return status; + status = napi_run_script(env, script, &result); + if (status != napi_ok) return status; + return napi_get_value_string_utf8( + env, result, result_out, result_capacity, &result_length); +} + +static int CreateSourceModule(napi_env env, const char* url, const char* text, + unofficial_napi_module* module_out) { + napi_value wrapper, url_value, source_value, undefined; + NAPI_CALL(env, napi_create_object(env, &wrapper)); + NAPI_CALL(env, napi_create_string_utf8(env, url, NAPI_AUTO_LENGTH, &url_value)); + NAPI_CALL(env, napi_create_string_utf8(env, text, NAPI_AUTO_LENGTH, &source_value)); + NAPI_CALL(env, napi_get_undefined(env, &undefined)); + const unofficial_napi_js_source source = unofficial_napi_js_source_from_text(source_value); + unofficial_napi_module_create_options options = {0}; + options.size = UNOFFICIAL_NAPI_MODULE_CREATE_OPTIONS_V1_SIZE; + options.version = 1; + options.kind = unofficial_napi_module_source_text; + options.wrapper = wrapper; + options.url = url_value; + options.context_or_undefined = undefined; + options.payload.source_text.source = &source; + options.payload.source_text.host_defined_option_id = undefined; + unofficial_napi_module_create_result result = {0}; + NAPI_CALL(env, unofficial_napi_module_wrap_create(env, &options, &result)); + *module_out = result.module; + return 0; +} + +static napi_value Str(napi_env env, const char* text) { + napi_value value = NULL; + napi_create_string_utf8(env, text, NAPI_AUTO_LENGTH, &value); + return value; +} + +// What a script, function, module or bytecode reads from the global it runs +// with: 73 in the contextified sandbox's realm, 0 elsewhere. +#define OBSERVED_MARKER "(globalThis.__napi_context_marker ?? 0)" + +static napi_status ContextifyRun(napi_env env, napi_value sandbox, + const unofficial_napi_js_source* source, + int32_t* result_out) { + napi_value result = NULL; + napi_status status = unofficial_napi_contextify_run_script( + env, sandbox, source, Str(env, "current.js"), 0, 0, -1, true, false, + false, NULL, &result); + if (status != napi_ok) return status; + return napi_get_value_int32(env, result, result_out); +} + +static napi_status ContextifyRunText(napi_env env, napi_value sandbox, + int32_t* result_out) { + const unofficial_napi_js_source source = + unofficial_napi_js_source_from_text(Str(env, OBSERVED_MARKER)); + return ContextifyRun(env, sandbox, &source, result_out); +} + +static napi_status ContextifyCall(napi_env env, napi_value parsing_context, + int32_t* result_out) { + const unofficial_napi_js_source source = unofficial_napi_js_source_from_text( + Str(env, "return " OBSERVED_MARKER ";")); + napi_value compiled = NULL, function = NULL, undefined = NULL, result = NULL; + napi_status status = napi_get_undefined(env, &undefined); + if (status != napi_ok) return status; + status = unofficial_napi_contextify_compile_function( + env, &source, Str(env, "current.js"), 0, 0, parsing_context, undefined, + undefined, undefined, &compiled); + if (status != napi_ok) return status; + status = napi_get_named_property(env, compiled, "function", &function); + if (status != napi_ok) return status; + status = napi_call_function(env, undefined, function, 0, NULL, &result); + if (status != napi_ok) return status; + return napi_get_value_int32(env, result, result_out); +} + +// Makes, evaluates and destroys a module with options of `version`, and +// reads what it observed. +static napi_status ModuleObserved(napi_env env, uint32_t version, + napi_value context, + unofficial_napi_realm realm, + int32_t* result_out) { + napi_value wrapper = NULL, undefined = NULL, ns = NULL, observed = NULL; + napi_status status = napi_create_object(env, &wrapper); + if (status != napi_ok) return status; + status = napi_get_undefined(env, &undefined); + if (status != napi_ok) return status; + const unofficial_napi_js_source source = unofficial_napi_js_source_from_text( + Str(env, "export const observed = " OBSERVED_MARKER ";")); + unofficial_napi_module_create_options options = {0}; + options.size = version == 1 ? UNOFFICIAL_NAPI_MODULE_CREATE_OPTIONS_V1_SIZE + : sizeof(options); + options.version = version; + options.kind = unofficial_napi_module_source_text; + options.wrapper = wrapper; + options.url = Str(env, "file:///current.mjs"); + options.context_or_undefined = context; + if (version >= 2) options.realm_or_null = realm; + options.payload.source_text.source = &source; + options.payload.source_text.host_defined_option_id = undefined; + unofficial_napi_module_create_result created = {0}; + status = unofficial_napi_module_wrap_create(env, &options, &created); + if (status != napi_ok) return status; + status = unofficial_napi_module_wrap_link(env, created.module, 0, NULL); + if (status == napi_ok) { + status = unofficial_napi_module_wrap_instantiate(env, created.module); + } + if (status == napi_ok) { + status = unofficial_napi_module_wrap_evaluate_sync(env, created.module, + NULL, NULL, &ns); + } + if (status == napi_ok) { + status = unofficial_napi_module_wrap_get_namespace(env, created.module, &ns); + } + if (status == napi_ok) { + status = napi_get_named_property(env, ns, "observed", &observed); + } + if (status == napi_ok) status = napi_get_value_int32(env, observed, result_out); + napi_status destroyed = unofficial_napi_module_wrap_destroy(env, created.module); + return status != napi_ok ? status : destroyed; +} + +// Opens version 1 bytecode, which compiles for the current realm, and runs +// it there. +static napi_status BytecodeV1Observed(napi_env env, int32_t* result_out) { + napi_value undefined = NULL; + napi_status status = napi_get_undefined(env, &undefined); + if (status != napi_ok) return status; + unofficial_napi_bytecode_open_options options = {0}; + options.size = UNOFFICIAL_NAPI_BYTECODE_OPEN_OPTIONS_V1_SIZE; + options.version = 1; + options.source_text = Str(env, OBSERVED_MARKER); + options.filename = Str(env, "current.js"); + options.shape = unofficial_napi_bytecode_shape_script; + options.params_or_undefined = undefined; + options.host_defined_option_id = undefined; + unofficial_napi_bytecode_open_result opened = {0}; + status = unofficial_napi_bytecode_open(env, &options, &opened); + if (status != napi_ok) return status; + const unofficial_napi_js_source source = + unofficial_napi_js_source_from_bytecode(opened.bytecode); + status = ContextifyRun(env, NULL, &source, result_out); + napi_status released = unofficial_napi_bytecode_release(env, opened.bytecode); + return status != napi_ok ? status : released; +} + +// make_context takes an object or a symbol (a fresh global) and a name. +static int CheckMakeContext(napi_env env) { + napi_value name = Str(env, "compat"); + napi_value symbol = NULL, global = NULL, env_global = NULL, number = NULL; + NAPI_CALL(env, napi_create_symbol(env, name, &symbol)); + NAPI_CALL(env, unofficial_napi_contextify_make_context( + env, symbol, name, NULL, true, true, false, NULL, &global)); + napi_valuetype type = napi_undefined; + NAPI_CALL(env, napi_typeof(env, global, &type)); + unofficial_napi_realm realm = NULL; + NAPI_CALL(env, unofficial_napi_get_realm(env, global, &realm)); + NAPI_CALL(env, napi_get_global(env, &env_global)); + bool same = true; + NAPI_CALL(env, napi_strict_equals(env, global, env_global, &same)); + CHECK_OR_FAIL(type == napi_object && realm != NULL && !same, + "make_context(symbol) did not make a fresh global"); + NAPI_CALL(env, napi_create_int32(env, 1, &number)); + CHECK_OR_FAIL(unofficial_napi_contextify_make_context( + env, number, name, NULL, true, true, false, NULL, + &global) == napi_invalid_arg, + "make_context took a number as its sandbox"); + CHECK_OR_FAIL(unofficial_napi_contextify_make_context( + env, symbol, NULL, NULL, true, true, false, NULL, + &global) == napi_invalid_arg, + "make_context took a NULL name"); + return 0; +} + +// Where nothing names a context, the deprecated calls and version 1 options +// use the current realm: the env's, or the contextified object's while the +// embedder has entered its realm. Version 2 options with no realm use the +// env's realm, and may not name both a realm and a context. +static int CheckCurrentRealm(napi_env env, napi_value context) { + unofficial_napi_realm realm = NULL; + NAPI_CALL(env, unofficial_napi_get_realm(env, context, &realm)); + CHECK_OR_FAIL(realm != NULL, "make_context's result has no realm"); + napi_value undefined = NULL, env_global = NULL, plain = NULL; + NAPI_CALL(env, napi_get_undefined(env, &undefined)); + NAPI_CALL(env, napi_get_global(env, &env_global)); + NAPI_CALL(env, napi_create_object(env, &plain)); + + int32_t observed = -1; + NAPI_CALL(env, ContextifyRunText(env, NULL, &observed)); + CHECK_OR_FAIL(observed == 0, "a NULL sandbox left the env's realm"); + NAPI_CALL(env, ContextifyRunText(env, context, &observed)); + CHECK_OR_FAIL(observed == 73, "the contextified object named another realm"); + CHECK_OR_FAIL(ContextifyRunText(env, plain, &observed) == napi_invalid_arg, + "an object that is no context named a realm"); + + unofficial_napi_realm_scope scope = 0; + NAPI_CALL(env, unofficial_napi_enter_realm(env, realm, &scope)); + int32_t ran = -1, ran_undefined = -1, ran_env = -1, called = -1; + int32_t module_v1 = -1, module_v1_env = -1, module_v2 = -1; + int32_t module_v2_realm = -1, bytecode = -1; + NAPI_CALL(env, ContextifyRunText(env, NULL, &ran)); + NAPI_CALL(env, ContextifyRunText(env, undefined, &ran_undefined)); + NAPI_CALL(env, ContextifyRunText(env, env_global, &ran_env)); + NAPI_CALL(env, ContextifyCall(env, undefined, &called)); + NAPI_CALL(env, ModuleObserved(env, 1, NULL, NULL, &module_v1)); + NAPI_CALL(env, ModuleObserved(env, 1, env_global, NULL, &module_v1_env)); + NAPI_CALL(env, ModuleObserved(env, 2, undefined, NULL, &module_v2)); + NAPI_CALL(env, ModuleObserved(env, 2, undefined, realm, &module_v2_realm)); + napi_status both = ModuleObserved(env, 2, context, realm, &observed); + NAPI_CALL(env, BytecodeV1Observed(env, &bytecode)); + NAPI_CALL(env, unofficial_napi_leave_realm(env, scope)); + CHECK_OR_FAIL(ran == 73 && ran_undefined == 73 && called == 73, + "a script or function with no context left the current realm"); + CHECK_OR_FAIL(ran_env == 0 && module_v1_env == 0, + "the env's global did not name the env's realm"); + CHECK_OR_FAIL(module_v1 == 73 && bytecode == 73, + "version 1 options left the current realm"); + CHECK_OR_FAIL(module_v2 == 0 && module_v2_realm == 73, + "version 2 module options used the wrong realm"); + CHECK_OR_FAIL(both == napi_invalid_arg, + "version 2 module options took both a realm and a context"); + return 0; +} + +static int token_hook_calls = 0; + +static void NAPI_CDECL CountTokenHook(napi_env env, void* token, void* data) { + (void)env; + (void)token; + (void)data; + token_hook_calls++; +} + +// main's env hooks, token callbacks included, are accepted. Natively V8 takes +// the token callbacks: a realm made in the env is assigned a token, and +// unassigned at release. A guest's bridge gives the provider none of its +// hooks, as on main, so a guest has none accepted and none called. +static int CheckEnvHooks(napi_env env) { + napi_env hooked = NULL; + unofficial_napi_env_owner owner = NULL; + NAPI_CALL(env, unofficial_napi_create_env(8, NULL, &hooked, &owner)); + unofficial_napi_env_hooks hooks = {0}; + hooks.size = sizeof(hooks); + hooks.version = UNOFFICIAL_NAPI_ENV_HOOKS_VERSION; + hooks.context_token_assign_callback = CountTokenHook; + hooks.context_token_unassign_callback = CountTokenHook; + uint64_t accepted = ~(uint64_t)0; + NAPI_CALL(hooked, unofficial_napi_attach_env(hooked, &hooks, &accepted)); + napi_value sandbox = NULL, context = NULL; + NAPI_CALL(hooked, napi_create_object(hooked, &sandbox)); + NAPI_CALL(hooked, unofficial_napi_contextify_make_context( + hooked, sandbox, Str(hooked, "hooked"), NULL, true, + true, false, NULL, &context)); + NAPI_CALL(env, unofficial_napi_release_env(owner, NULL)); +#ifdef __wasm__ + const uint64_t expected = 0; + const int expected_calls = 0; +#else + const uint64_t expected = unofficial_napi_env_hook_context_token_assign | + unofficial_napi_env_hook_context_token_unassign; + const int expected_calls = 2; +#endif + CHECK_OR_FAIL(accepted == expected, "attach_env accepted the wrong hooks"); + CHECK_OR_FAIL(token_hook_calls == expected_calls, + "the token hooks ran the wrong number of times"); + return 0; +} + +static int CheckModuleEvaluation(napi_env env) { + int32_t count = 0; + NAPI_CALL(env, RunInt32Script(env, "globalThis.__napi_module_runs = 0", &count)); + unofficial_napi_module leaf, root; + CHECK_OR_FAIL(CreateSourceModule(env, "file:///leaf.mjs", + "#!/usr/bin/env node\n" + "globalThis.__napi_module_runs++; export const answer = 42;", &leaf) == 0, + "failed to compile hashbang module"); + CHECK_OR_FAIL(CreateSourceModule(env, "file:///root.mjs", + "import {answer} from './leaf.mjs'; export const result = answer + 1;", &root) == 0, + "failed to compile root module"); + NAPI_CALL(env, unofficial_napi_module_wrap_link(env, leaf, 0, NULL)); + NAPI_CALL(env, unofficial_napi_module_wrap_link(env, root, 1, &leaf)); + NAPI_CALL(env, unofficial_napi_module_wrap_instantiate(env, root)); + int32_t dependency_status = -1; + NAPI_CALL(env, unofficial_napi_module_wrap_get_state(env, leaf, &dependency_status, NULL, NULL)); + CHECK_OR_FAIL(dependency_status == 2, "Instantiate did not instantiate the dependency graph"); + napi_value promise, namespace; + NAPI_CALL(env, unofficial_napi_module_wrap_evaluate(env, root, -1, false, &promise)); + int32_t status = -1; + NAPI_CALL(env, unofficial_napi_module_wrap_get_state(env, root, &status, NULL, NULL)); + CHECK_OR_FAIL(status == 4, "Evaluate left synchronous graph pending"); + NAPI_CALL(env, unofficial_napi_module_wrap_get_state(env, leaf, &status, NULL, NULL)); + CHECK_OR_FAIL(status == 4, "Evaluate left synchronous dependency pending"); + int32_t promise_state = -1; + NAPI_CALL(env, unofficial_napi_get_promise_details(env, promise, &promise_state, NULL, NULL)); + CHECK_OR_FAIL(promise_state == 1, "synchronous evaluation promise was not immediately fulfilled"); + NAPI_CALL(env, unofficial_napi_module_wrap_evaluate_sync(env, leaf, NULL, NULL, &namespace)); + NAPI_CALL(env, unofficial_napi_module_wrap_evaluate_sync(env, root, NULL, NULL, &namespace)); + napi_value answer; + NAPI_CALL(env, napi_get_named_property(env, namespace, "result", &answer)); + NAPI_CALL(env, napi_get_value_int32(env, answer, &count)); + CHECK_OR_FAIL(count == 43, "dependency namespace was not ready before root evaluation"); + NAPI_CALL(env, RunInt32Script(env, "globalThis.__napi_module_runs", &count)); + CHECK_OR_FAIL(count == 1, "evaluated module executed more than once"); + NAPI_CALL(env, unofficial_napi_module_wrap_destroy(env, root)); + NAPI_CALL(env, unofficial_napi_module_wrap_destroy(env, leaf)); + + // A static cycle is legal and must evaluate each body exactly once. + CHECK_OR_FAIL(CreateSourceModule(env, "file:///cycle-a.mjs", + "import './cycle-b.mjs'; globalThis.__napi_module_runs++;", &root) == 0, + "failed to compile cycle root"); + CHECK_OR_FAIL(CreateSourceModule(env, "file:///cycle-b.mjs", + "import './cycle-a.mjs'; globalThis.__napi_module_runs++;", &leaf) == 0, + "failed to compile cycle dependency"); + NAPI_CALL(env, unofficial_napi_module_wrap_link(env, root, 1, &leaf)); + NAPI_CALL(env, unofficial_napi_module_wrap_link(env, leaf, 1, &root)); + NAPI_CALL(env, unofficial_napi_module_wrap_instantiate(env, root)); + NAPI_CALL(env, unofficial_napi_module_wrap_evaluate(env, root, -1, false, &promise)); + NAPI_CALL(env, unofficial_napi_module_wrap_get_state(env, root, &status, NULL, NULL)); + CHECK_OR_FAIL(status == 4, "static module cycle did not finish synchronously"); + NAPI_CALL(env, RunInt32Script(env, "globalThis.__napi_module_runs", &count)); + CHECK_OR_FAIL(count == 3, "static module cycle did not execute exactly once"); + NAPI_CALL(env, unofficial_napi_module_wrap_destroy(env, root)); + NAPI_CALL(env, unofficial_napi_module_wrap_destroy(env, leaf)); + + // Cache failures on both the failing dependency and its dependent. + CHECK_OR_FAIL(CreateSourceModule(env, "file:///throwing.mjs", + "globalThis.__napi_module_runs++; throw new Error('module failure');", &leaf) == 0, + "failed to compile throwing module"); + CHECK_OR_FAIL(CreateSourceModule(env, "file:///throwing-parent.mjs", + "import './throwing.mjs';", &root) == 0, + "failed to compile throwing module parent"); + NAPI_CALL(env, unofficial_napi_module_wrap_link(env, leaf, 0, NULL)); + NAPI_CALL(env, unofficial_napi_module_wrap_link(env, root, 1, &leaf)); + NAPI_CALL(env, unofficial_napi_module_wrap_instantiate(env, root)); + CHECK_OR_FAIL(unofficial_napi_module_wrap_evaluate_sync(env, root, NULL, NULL, &namespace) + == napi_pending_exception, "throwing graph did not throw"); + napi_value first_error, second_error; + NAPI_CALL(env, napi_get_and_clear_last_exception(env, &first_error)); + NAPI_CALL(env, unofficial_napi_module_wrap_get_state(env, leaf, &status, NULL, NULL)); + CHECK_OR_FAIL(status == 5, "failed dependency did not cache its error"); + CHECK_OR_FAIL(unofficial_napi_module_wrap_evaluate_sync(env, leaf, NULL, NULL, &namespace) + == napi_pending_exception, "failed dependency did not rethrow"); + NAPI_CALL(env, napi_get_and_clear_last_exception(env, &second_error)); + bool same_error = false; + NAPI_CALL(env, napi_strict_equals(env, first_error, second_error, &same_error)); + CHECK_OR_FAIL(same_error, "cached evaluation failure lost error identity"); + NAPI_CALL(env, RunInt32Script(env, "globalThis.__napi_module_runs", &count)); + CHECK_OR_FAIL(count == 4, "failed dependency was evaluated a second time"); + NAPI_CALL(env, unofficial_napi_module_wrap_destroy(env, root)); + NAPI_CALL(env, unofficial_napi_module_wrap_destroy(env, leaf)); + return 0; +} + +// Node's ESM loader rejects JSON modules whose request lost its +// `with { type: 'json' }` attributes (ERR_IMPORT_ATTRIBUTE_MISSING), so every +// provider must surface parsed import attributes on the created requests. +static int CheckModuleRequestAttributes(napi_env env) { + napi_value wrapper, url_value, source_value, undefined; + NAPI_CALL(env, napi_create_object(env, &wrapper)); + NAPI_CALL(env, napi_create_string_utf8( + env, "file:///attributed.mjs", NAPI_AUTO_LENGTH, &url_value)); + NAPI_CALL(env, napi_create_string_utf8(env, + "import data from './data.json' with { type: 'json' };\n" + "export const ok = data;", + NAPI_AUTO_LENGTH, &source_value)); + NAPI_CALL(env, napi_get_undefined(env, &undefined)); + const unofficial_napi_js_source source = + unofficial_napi_js_source_from_text(source_value); + unofficial_napi_module_create_options options = {0}; + options.size = sizeof(options); + options.version = UNOFFICIAL_NAPI_MODULE_CREATE_OPTIONS_VERSION; + options.kind = unofficial_napi_module_source_text; + options.wrapper = wrapper; + options.url = url_value; + options.context_or_undefined = undefined; + options.payload.source_text.source = &source; + options.payload.source_text.host_defined_option_id = undefined; + unofficial_napi_module_create_result result = {0}; + NAPI_CALL(env, unofficial_napi_module_wrap_create(env, &options, &result)); + CHECK_OR_FAIL(result.module != NULL, + "attributed module compilation did not return a handle"); + CHECK_OR_FAIL(result.module_requests != NULL, + "attributed module compilation did not return requests"); + + bool is_array = false; + NAPI_CALL(env, napi_is_array(env, result.module_requests, &is_array)); + CHECK_OR_FAIL(is_array, "module requests was not an array"); + uint32_t request_count = 0; + NAPI_CALL(env, napi_get_array_length( + env, result.module_requests, &request_count)); + CHECK_OR_FAIL(request_count == 1, + "attributed module reported the wrong request count"); + + napi_value request, specifier, attributes, type_value, phase_value; + char text[64]; + size_t text_length = 0; + NAPI_CALL(env, napi_get_element(env, result.module_requests, 0, &request)); + NAPI_CALL(env, napi_get_named_property(env, request, "specifier", &specifier)); + NAPI_CALL(env, napi_get_value_string_utf8( + env, specifier, text, sizeof(text), &text_length)); + CHECK_OR_FAIL(strcmp(text, "./data.json") == 0, + "attributed request reported the wrong specifier"); + NAPI_CALL(env, napi_get_named_property(env, request, "attributes", &attributes)); + napi_valuetype attributes_type = napi_undefined; + NAPI_CALL(env, napi_typeof(env, attributes, &attributes_type)); + CHECK_OR_FAIL(attributes_type == napi_object, + "attributed request attributes was not an object"); + NAPI_CALL(env, napi_get_named_property(env, attributes, "type", &type_value)); + NAPI_CALL(env, napi_get_value_string_utf8( + env, type_value, text, sizeof(text), &text_length)); + CHECK_OR_FAIL(strcmp(text, "json") == 0, + "import attribute 'type: json' was not preserved"); + NAPI_CALL(env, napi_get_named_property(env, request, "phase", &phase_value)); + int32_t phase = 0; + NAPI_CALL(env, napi_get_value_int32(env, phase_value, &phase)); + CHECK_OR_FAIL(phase == 2, + "attributed request did not report the evaluation phase"); + NAPI_CALL(env, unofficial_napi_module_wrap_destroy(env, result.module)); + return 0; +} + +int main(void) { + napi_env env = napi_wasm_init_env(); + CHECK_OR_FAIL(env != NULL, "napi_wasm_init_env returned NULL"); + + // Run a simple script that returns a string + napi_value script_str; + NAPI_CALL(env, napi_create_string_utf8(env, "'Hello' + ', World!'", + NAPI_AUTO_LENGTH, &script_str)); + napi_value result; + NAPI_CALL(env, napi_run_script(env, script_str, &result)); + + // Check the result + char buf[256]; + size_t len; + NAPI_CALL(env, napi_get_value_string_utf8(env, result, buf, sizeof(buf), &len)); + CHECK_OR_FAIL(strcmp(buf, "Hello, World!") == 0, "script result mismatch"); + + // Run a script that returns a number + napi_value num_script; + NAPI_CALL(env, napi_create_string_utf8(env, "2 + 3 * 4", + NAPI_AUTO_LENGTH, &num_script)); + napi_value num_result; + NAPI_CALL(env, napi_run_script(env, num_script, &num_result)); + + double num; + NAPI_CALL(env, napi_get_value_double(env, num_result, &num)); + CHECK_OR_FAIL(num > 13.9 && num < 14.1, "expected 14"); + + // Property-name enumeration is a host-to-JS boundary: a Proxy can invoke a + // guest ownKeys callback while an outer guest callback still owns the store. + // Both enumeration APIs must lend the store for that nested callback. + nested_property_names_context nested_names = {0}; + napi_value nested_global; + napi_value proxy_constructor; + napi_value proxy_target; + napi_value proxy_handler; + napi_value own_keys_function; + napi_value nested_key_value; + NAPI_CALL(env, napi_get_global(env, &nested_global)); + NAPI_CALL(env, napi_get_named_property( + env, nested_global, "Proxy", &proxy_constructor)); + NAPI_CALL(env, napi_create_object(env, &proxy_target)); + NAPI_CALL(env, napi_create_int32(env, 1, &nested_key_value)); + NAPI_CALL(env, napi_set_named_property( + env, proxy_target, "nestedKey", nested_key_value)); + NAPI_CALL(env, napi_create_object(env, &proxy_handler)); + NAPI_CALL(env, napi_create_function(env, + "nestedOwnKeys", + NAPI_AUTO_LENGTH, + NestedOwnKeys, + &nested_names, + &own_keys_function)); + NAPI_CALL(env, napi_set_named_property( + env, proxy_handler, "ownKeys", own_keys_function)); + napi_value proxy_args[] = {proxy_target, proxy_handler}; + NAPI_CALL(env, napi_new_instance(env, + proxy_constructor, + 2, + proxy_args, + &nested_names.proxy)); + + napi_value enumerate_function; + napi_value enumeration_result; + uint32_t enumeration_count = 0; + NAPI_CALL(env, napi_create_function(env, + "enumerateNestedProxy", + NAPI_AUTO_LENGTH, + EnumerateNestedProxy, + &nested_names, + &enumerate_function)); + NAPI_CALL(env, napi_call_function(env, + nested_global, + enumerate_function, + 0, + NULL, + &enumeration_result)); + NAPI_CALL(env, napi_get_value_uint32( + env, enumeration_result, &enumeration_count)); + CHECK_OR_FAIL(enumeration_count == 2 && nested_names.own_keys_count == 2, + "property enumeration did not re-enter the guest ownKeys trap"); + + // Each N-API environment owns its global context. This is also a control + // plane boundary: evaluating in the host worker's real global would leak the + // marker into env2 and allow Edge bootstrap code to replace Wasmer's timers, + // Promise, console, and worker bridge. + int32_t marker = 0; + NAPI_CALL(env, RunInt32Script( + env, "globalThis.__napi_env_isolation_marker = 41", &marker)); + CHECK_OR_FAIL(marker == 41, "failed to set the first environment marker"); + + napi_env env2 = NULL; + unofficial_napi_env_owner env2_scope = NULL; + NAPI_CALL(env, unofficial_napi_create_env(8, NULL, &env2, &env2_scope)); + CHECK_OR_FAIL(env2 != NULL && env2_scope != NULL, + "failed to create the second N-API environment"); + + char marker_type[32] = {0}; + NAPI_CALL(env2, RunStringScript(env2, + "typeof globalThis.__napi_env_isolation_marker", + marker_type, + sizeof(marker_type))); + CHECK_OR_FAIL(strcmp(marker_type, "undefined") == 0, + "napi_run_script leaked state between environments"); + + NAPI_CALL(env2, RunInt32Script( + env2, "globalThis.__napi_env_isolation_marker = 99", &marker)); + CHECK_OR_FAIL(marker == 99, "failed to set the second environment marker"); + NAPI_CALL(env, RunInt32Script( + env, "globalThis.__napi_env_isolation_marker", &marker)); + CHECK_OR_FAIL(marker == 41, "the second environment mutated the first global"); + NAPI_CALL(env, unofficial_napi_release_env(env2_scope, NULL)); + + // Every code-generation path must select its execution scope explicitly. + // In particular, vm compile-function and module compilation must honor the + // supplied context rather than falling back to the active environment or + // the Wasmer worker's control-plane global. + napi_value undefined_value; + NAPI_CALL(env, napi_get_undefined(env, &undefined_value)); + napi_value sandbox; + NAPI_CALL(env, napi_create_object(env, &sandbox)); + napi_value context_marker; + NAPI_CALL(env, napi_create_int32(env, 73, &context_marker)); + NAPI_CALL(env, napi_set_named_property( + env, sandbox, "__napi_context_marker", context_marker)); + napi_value context; + NAPI_CALL(env, unofficial_napi_contextify_make_context( + env, + sandbox, + undefined_value, + undefined_value, + true, + true, + true, + undefined_value, + &context)); + + napi_value context_source_text; + NAPI_CALL(env, napi_create_string_utf8( + env, + "globalThis.__napi_context_marker", + NAPI_AUTO_LENGTH, + &context_source_text)); + const unofficial_napi_js_source context_source = + unofficial_napi_js_source_from_text(context_source_text); + napi_value context_result; + NAPI_CALL(env, unofficial_napi_contextify_run_script( + env, + context, + &context_source, + undefined_value, + 0, + 0, + -1, + true, + false, + false, + undefined_value, + &context_result)); + NAPI_CALL(env, napi_get_value_int32(env, context_result, &marker)); + CHECK_OR_FAIL(marker == 73, + "contextify_run_script escaped its explicit context"); + + napi_value parameters; + napi_value context_extensions; + NAPI_CALL(env, napi_create_array_with_length(env, 0, ¶meters)); + NAPI_CALL(env, napi_create_array_with_length(env, 1, &context_extensions)); + napi_value context_extension; + napi_value extension_marker; + NAPI_CALL(env, napi_create_object(env, &context_extension)); + NAPI_CALL(env, napi_create_int32(env, 74, &extension_marker)); + NAPI_CALL(env, napi_set_named_property( + env, + context_extension, + "__napi_context_extension_marker", + extension_marker)); + NAPI_CALL(env, napi_set_element( + env, context_extensions, 0, context_extension)); + napi_value function_source_text; + NAPI_CALL(env, napi_create_string_utf8( + env, + "return globalThis.__napi_context_marker + " + "__napi_context_extension_marker;", + NAPI_AUTO_LENGTH, + &function_source_text)); + const unofficial_napi_js_source function_source = + unofficial_napi_js_source_from_text(function_source_text); + napi_value compiled; + NAPI_CALL(env, unofficial_napi_contextify_compile_function( + env, + &function_source, + undefined_value, + 0, + 0, + context, + context_extensions, + parameters, + undefined_value, + &compiled)); + napi_value compiled_function; + NAPI_CALL(env, napi_get_named_property( + env, compiled, "function", &compiled_function)); + napi_value env_global; + NAPI_CALL(env, napi_get_global(env, &env_global)); + napi_value function_result; + NAPI_CALL(env, napi_call_function( + env, + env_global, + compiled_function, + 0, + NULL, + &function_result)); + NAPI_CALL(env, napi_get_value_int32(env, function_result, &marker)); + CHECK_OR_FAIL(marker == 147, + "compile_function escaped its parsing context"); + + napi_value module_wrapper; + napi_value module_url; + napi_value module_source_text; + NAPI_CALL(env, napi_create_object(env, &module_wrapper)); + NAPI_CALL(env, napi_create_string_utf8( + env, + "file:///context-module.mjs", + NAPI_AUTO_LENGTH, + &module_url)); + NAPI_CALL(env, napi_create_string_utf8( + env, + "export const observed = " + "globalThis.__napi_context_marker;", + NAPI_AUTO_LENGTH, + &module_source_text)); + const unofficial_napi_js_source module_source = + unofficial_napi_js_source_from_text(module_source_text); + unofficial_napi_module_create_options module_options = {0}; + module_options.size = UNOFFICIAL_NAPI_MODULE_CREATE_OPTIONS_V1_SIZE; + module_options.version = 1; + module_options.kind = unofficial_napi_module_source_text; + module_options.wrapper = module_wrapper; + module_options.url = module_url; + module_options.context_or_undefined = context; + module_options.payload.source_text.source = &module_source; + module_options.payload.source_text.host_defined_option_id = undefined_value; + unofficial_napi_module_create_result module_create_result = {0}; + NAPI_CALL(env, unofficial_napi_module_wrap_create( + env, &module_options, &module_create_result)); + unofficial_napi_module module = module_create_result.module; + CHECK_OR_FAIL(module != NULL, + "module compilation did not return a handle"); + CHECK_OR_FAIL(module_create_result.module_requests != NULL, + "module compilation did not return requests"); + CHECK_OR_FAIL(!module_create_result.has_top_level_await, + "synchronous module reported top-level await at creation"); + int32_t module_status = -1; + napi_value module_error = NULL; + bool module_has_async_graph = false; + NAPI_CALL(env, unofficial_napi_module_wrap_get_state( + env, + module, + &module_status, + &module_error, + &module_has_async_graph)); + CHECK_OR_FAIL(module_status == 0, + "new module snapshot did not report uninstantiated status"); + CHECK_OR_FAIL(module_error != NULL, + "module snapshot did not return an undefined error value"); + CHECK_OR_FAIL(!module_has_async_graph, + "uninstantiated module reported an async graph"); + NAPI_CALL(env, unofficial_napi_module_wrap_link( + env, module, 0, NULL)); + NAPI_CALL(env, unofficial_napi_module_wrap_instantiate(env, module)); + module_status = -1; + module_has_async_graph = true; + NAPI_CALL(env, unofficial_napi_module_wrap_get_state( + env, + module, + &module_status, + NULL, + &module_has_async_graph)); + CHECK_OR_FAIL(module_status == 2, + "instantiated module snapshot reported the wrong status"); + CHECK_OR_FAIL(!module_has_async_graph, + "synchronous module reported an async graph"); + napi_value module_result; + NAPI_CALL(env, unofficial_napi_module_wrap_evaluate_sync( + env, + module, + module_url, + module_url, + &module_result)); + napi_value module_namespace; + napi_value module_observed; + NAPI_CALL(env, unofficial_napi_module_wrap_get_namespace( + env, module, &module_namespace)); + NAPI_CALL(env, napi_get_named_property( + env, module_namespace, "observed", &module_observed)); + NAPI_CALL(env, napi_get_value_int32(env, module_observed, &marker)); + CHECK_OR_FAIL(marker == 73, + "module evaluation escaped its explicit context"); + NAPI_CALL(env, unofficial_napi_module_wrap_destroy(env, module)); + CHECK_OR_FAIL(CheckMakeContext(env) == 0, "make_context regressions failed"); + CHECK_OR_FAIL(CheckCurrentRealm(env, context) == 0, + "current realm regressions failed"); + CHECK_OR_FAIL(CheckEnvHooks(env) == 0, "env hook regressions failed"); + + // Creating the CommonJS facade evaluates the original module internally, + // so a synthetic module's guest evaluation callback must be able to re-enter + // while the facade is built. + napi_value facade_exports; + napi_value facade_default_export; + napi_value facade_named_export; + napi_value facade_evaluation_steps; + NAPI_CALL(env, napi_create_array_with_length(env, 2, &facade_exports)); + NAPI_CALL(env, napi_create_string_utf8( + env, "default", NAPI_AUTO_LENGTH, &facade_default_export)); + NAPI_CALL(env, napi_create_string_utf8( + env, "named", NAPI_AUTO_LENGTH, &facade_named_export)); + NAPI_CALL(env, napi_set_element( + env, facade_exports, 0, facade_default_export)); + NAPI_CALL(env, napi_set_element( + env, facade_exports, 1, facade_named_export)); + NAPI_CALL(env, napi_create_function(env, + "evaluateFacadeSource", + NAPI_AUTO_LENGTH, + CountFacadeEvaluation, + NULL, + &facade_evaluation_steps)); + unofficial_napi_module_create_options synthetic_options = {0}; + synthetic_options.size = sizeof(synthetic_options); + synthetic_options.version = UNOFFICIAL_NAPI_MODULE_CREATE_OPTIONS_VERSION; + synthetic_options.kind = unofficial_napi_module_synthetic; + synthetic_options.wrapper = module_wrapper; + synthetic_options.url = module_url; + synthetic_options.context_or_undefined = undefined_value; + synthetic_options.payload.synthetic.export_names = facade_exports; + synthetic_options.payload.synthetic.synthetic_evaluation_steps = + facade_evaluation_steps; + unofficial_napi_module_create_result synthetic_create_result = {0}; + NAPI_CALL(env, unofficial_napi_module_wrap_create( + env, &synthetic_options, &synthetic_create_result)); + unofficial_napi_module synthetic_module = synthetic_create_result.module; + CHECK_OR_FAIL(synthetic_module != NULL, + "synthetic module creation did not return a handle"); + NAPI_CALL(env, unofficial_napi_module_wrap_link( + env, synthetic_module, 0, NULL)); + NAPI_CALL(env, unofficial_napi_module_wrap_instantiate( + env, synthetic_module)); + napi_value facade_namespace; + NAPI_CALL(env, unofficial_napi_module_wrap_create_required_module_facade( + env, synthetic_module, &facade_namespace)); + CHECK_OR_FAIL(facade_namespace != NULL && facade_evaluation_count == 1, + "required-module facade did not run its guest evaluation callback"); + napi_value facade_marker; + bool is_es_module = false; + NAPI_CALL(env, napi_get_named_property(env, facade_namespace, "__esModule", &facade_marker)); + NAPI_CALL(env, napi_get_value_bool(env, facade_marker, &is_es_module)); + CHECK_OR_FAIL(is_es_module, "required-module facade did not expose __esModule"); + NAPI_CALL(env, unofficial_napi_module_wrap_create_required_module_facade( + env, synthetic_module, &facade_namespace)); + CHECK_OR_FAIL(facade_evaluation_count == 1, "required-module facade reevaluated its source"); + NAPI_CALL(env, unofficial_napi_module_wrap_destroy(env, synthetic_module)); + + // A memory lease, rather than a scope-bound napi_value or its data pointer, + // owns the value and copy-back. Releasing after the handle scope closes is + // the contract retained native users such as zlib and async fs require. + napi_handle_scope lease_scope = NULL; + NAPI_CALL(env, napi_open_handle_scope(env, &lease_scope)); + napi_value lease_script; + napi_value lease_value; + NAPI_CALL(env, + napi_create_string_utf8( + env, + "globalThis.__napi_lease_value = new Uint8Array([10, 20, 30, 40])", + NAPI_AUTO_LENGTH, + &lease_script)); + NAPI_CALL(env, napi_run_script(env, lease_script, &lease_value)); + + unofficial_napi_buffer_lease lease = NULL; + uint8_t* lease_data = NULL; + NAPI_CALL(env, + unofficial_napi_acquire_buffer_lease( + env, + lease_value, + 1, + 2, + unofficial_napi_buffer_access_readwrite, + &lease, + (void**)&lease_data)); + CHECK_OR_FAIL(lease != NULL && lease_data != NULL, + "buffer lease did not return ownership and data"); + CHECK_OR_FAIL(lease_data[0] == 20 && lease_data[1] == 30, + "buffer lease copied the wrong range"); + lease_data[0] = 21; + lease_data[1] = 31; + NAPI_CALL(env, napi_close_handle_scope(env, lease_scope)); + NAPI_CALL(env, unofficial_napi_release_buffer_lease(env, lease, true)); + + NAPI_CALL(env, + RunInt32Script(env, + "__napi_lease_value[1] * 100 + __napi_lease_value[2]", + &marker)); + CHECK_OR_FAIL(marker == 2131, + "buffer lease did not publish writes after scope closure"); + + napi_value shared_script; + napi_value shared_value; + NAPI_CALL(env, + napi_create_string_utf8( + env, + "globalThis.__napi_shared_lease = new SharedArrayBuffer(4); " + "new Uint8Array(__napi_shared_lease).set([5, 6, 7, 8]); " + "__napi_shared_lease", + NAPI_AUTO_LENGTH, + &shared_script)); + NAPI_CALL(env, napi_run_script(env, shared_script, &shared_value)); + unofficial_napi_buffer_lease shared_lease = NULL; + uint8_t* shared_data = NULL; + NAPI_CALL(env, + unofficial_napi_acquire_buffer_lease( + env, + shared_value, + 1, + 2, + unofficial_napi_buffer_access_readwrite, + &shared_lease, + (void**)&shared_data)); + CHECK_OR_FAIL(shared_lease != NULL && shared_data != NULL && + shared_data[0] == 6 && shared_data[1] == 7, + "buffer lease did not expose a SharedArrayBuffer range"); + shared_data[0] = 16; + shared_data[1] = 17; + NAPI_CALL(env, + unofficial_napi_release_buffer_lease(env, shared_lease, true)); + NAPI_CALL(env, + RunInt32Script(env, + "new Uint8Array(__napi_shared_lease)[1] * 100 + " + "new Uint8Array(__napi_shared_lease)[2]", + &marker)); + CHECK_OR_FAIL(marker == 1617, + "buffer lease did not publish SharedArrayBuffer writes"); + + // The host-JS bridge must preserve the public typed-array enum and exact + // byte width. Float32 used to be treated as an 8-byte element, over-reading + // the backing store when a guest requested its data pointer. + napi_value typed_backing; + void* typed_backing_data = NULL; + NAPI_CALL(env, + napi_create_arraybuffer( + env, 16, &typed_backing_data, &typed_backing)); + CHECK_OR_FAIL(typed_backing_data != NULL, + "typed-array backing did not expose guest memory"); + napi_value float32_view; + NAPI_CALL(env, + napi_create_typedarray( + env, napi_float32_array, 2, typed_backing, 4, &float32_view)); + napi_typedarray_type float32_kind; + size_t float32_length = 0; + size_t float32_offset = 0; + void* float32_data = NULL; + NAPI_CALL(env, + napi_get_typedarray_info(env, + float32_view, + &float32_kind, + &float32_length, + &float32_data, + NULL, + &float32_offset)); + CHECK_OR_FAIL(float32_kind == napi_float32_array && + float32_length == 2 && + float32_offset == 4 && + float32_data == (uint8_t*)typed_backing_data + 4, + "Float32Array guest range used the wrong element width"); + + // External-buffer ABI order is length before data. Swapping the two makes + // the bridge interpret a byte count as a guest pointer. + uint8_t external_bytes[4] = {9, 8, 7, 6}; + napi_value external_buffer; + NAPI_CALL(env, + napi_create_external_buffer(env, + sizeof(external_bytes), + external_bytes, + NULL, + NULL, + &external_buffer)); + void* external_buffer_data = NULL; + size_t external_buffer_length = 0; + NAPI_CALL(env, + napi_get_buffer_info(env, + external_buffer, + &external_buffer_data, + &external_buffer_length)); + CHECK_OR_FAIL(external_buffer_length == sizeof(external_bytes) && + external_buffer_data != NULL && + memcmp(external_buffer_data, + external_bytes, + sizeof(external_bytes)) == 0, + "external buffer ABI order corrupted its guest range"); + + napi_value external_value; + napi_valuetype external_type = napi_undefined; + NAPI_CALL(env, + napi_create_external(env, + (void*)(uintptr_t)0x1234, + NULL, + NULL, + &external_value)); + NAPI_CALL(env, napi_typeof(env, external_value, &external_type)); + CHECK_OR_FAIL(external_type == napi_external, + "napi_typeof classified an external as an object"); + + // Escaping the first explicit scope transfers ownership into the env's root + // frame. It must not remove the value from every frame and leak an unowned + // handle. + napi_escapable_handle_scope escape_scope = NULL; + NAPI_CALL(env, napi_open_escapable_handle_scope(env, &escape_scope)); + napi_value scoped_value; + napi_value escaped_value; + NAPI_CALL(env, napi_create_object(env, &scoped_value)); + NAPI_CALL(env, + napi_escape_handle(env, + escape_scope, + scoped_value, + &escaped_value)); + NAPI_CALL(env, napi_close_escapable_handle_scope(env, escape_scope)); + napi_value escaped_marker; + NAPI_CALL(env, napi_create_int32(env, 55, &escaped_marker)); + NAPI_CALL(env, + napi_set_named_property( + env, escaped_value, "marker", escaped_marker)); + NAPI_CALL(env, + napi_get_named_property( + env, escaped_value, "marker", &escaped_marker)); + NAPI_CALL(env, napi_get_value_int32(env, escaped_marker, &marker)); + CHECK_OR_FAIL(marker == 55, + "outermost escaped handle lost root-frame ownership"); + + // Forged guest lengths are rejected before allocating a host scratch + // buffer. This call must return an error rather than aborting the host. +#if defined(__wasm__) + napi_status oversized_string_status = + napi_get_value_string_utf8(env, + result, + buf, + (size_t)INT32_MAX, + &len); + CHECK_OR_FAIL(oversized_string_status != napi_ok, + "oversized guest string length was not rejected"); +#endif + + // Guest wrap/add-finalizer callbacks are dispatched at an explicit provider + // checkpoint; environment teardown force-drains remaining live records. + napi_env finalizer_env = NULL; + unofficial_napi_env_owner finalizer_env_scope = NULL; + NAPI_CALL(env, + unofficial_napi_create_env( + 8, NULL, &finalizer_env, &finalizer_env_scope)); + napi_value wrapped_object; + napi_value finalized_object; + NAPI_CALL(finalizer_env, + napi_create_object(finalizer_env, &wrapped_object)); + NAPI_CALL(finalizer_env, + napi_wrap(finalizer_env, + wrapped_object, + (void*)(uintptr_t)0x11, + CountWrapFinalizer, + (void*)(uintptr_t)0x12, + NULL)); + NAPI_CALL(finalizer_env, + napi_create_object(finalizer_env, &finalized_object)); + NAPI_CALL(finalizer_env, + napi_add_finalizer(finalizer_env, + finalized_object, + (void*)(uintptr_t)0x21, + CountAddedFinalizer, + (void*)(uintptr_t)0x22, + NULL)); + NAPI_CALL(env, unofficial_napi_release_env(finalizer_env_scope, NULL)); + CHECK_OR_FAIL(wrap_finalizer_count == 1 && add_finalizer_count == 1, + "guest finalizers were not dispatched exactly once"); + + // Environment teardown owns the failure/cancellation path for outstanding + // leases. It must discard the snapshot and host reference without requiring + // a scope-bound value or an explicit release from already-destroyed Edge + // state. + napi_env lease_env = NULL; + unofficial_napi_env_owner lease_env_scope = NULL; + NAPI_CALL(env, unofficial_napi_create_env(8, NULL, &lease_env, &lease_env_scope)); + napi_value abandoned_script; + napi_value abandoned_value; + NAPI_CALL(lease_env, + napi_create_string_utf8(lease_env, + "new Uint8Array([1, 2, 3, 4])", + NAPI_AUTO_LENGTH, + &abandoned_script)); + NAPI_CALL(lease_env, + napi_run_script(lease_env, abandoned_script, &abandoned_value)); + unofficial_napi_buffer_lease abandoned_lease = NULL; + void* abandoned_data = NULL; + NAPI_CALL(lease_env, + unofficial_napi_acquire_buffer_lease( + lease_env, + abandoned_value, + 0, + 4, + unofficial_napi_buffer_access_read, + &abandoned_lease, + &abandoned_data)); + CHECK_OR_FAIL(abandoned_lease != NULL && abandoned_data != NULL, + "failed to acquire teardown lease"); + NAPI_CALL(env, unofficial_napi_release_env(lease_env_scope, NULL)); + + CHECK_OR_FAIL(CheckModuleEvaluation(env) == 0, "module evaluation regressions failed"); + CHECK_OR_FAIL(CheckModuleRequestAttributes(env) == 0, "module request attribute regressions failed"); + return PrintSuccess("RUN_SCRIPT_COMPAT_TEST"); +} From f90dcc16a24177862c0f6be3e4f3e074d74b72f4 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 15:39:19 -0800 Subject: [PATCH 068/150] Document the deprecated guest API The guest ABI notes now say where context ids are mapped to realms, that a call with no context can add up to two value ids to the handle scope, that a guest's env hooks are main's and none are accepted, and which tests cover the old imports and structs. Co-Authored-By: Claude Opus 5.5 --- docs/realms.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/docs/realms.md b/docs/realms.md index b0b33097e9..4847c11167 100644 --- a/docs/realms.md +++ b/docs/realms.md @@ -182,6 +182,20 @@ calls take a realm's global or sandbox. as on `main`, and 0 is the current realm. With a host-JS native Worker realm (#125), `make_context` fails as `create_realm` does, and `run_script` with id 0 goes to `evaluate()`. + - One layer (`src/guest/compat.rs`) maps a context id to a realm id for + both guest backends, as `lib/src/napi_compat.cc` does natively. The + current realm takes the id of `napi_get_global` and maps it with + `get_realm`, so a call with no context can add up to two value ids to + the current handle scope. + - Guest env hooks are version 1, `main`'s 32 bytes. As on `main`, the + bridge gives the provider none of them, so a guest's token callbacks + are reported as not accepted and never called. + - `tests/programs/run_script_compat_test.c` is `main`'s + `run_script_test.c`, run natively and as a WASIX guest, with version 1 + module and bytecode options and checks of the current realm. The WAT + guest of the concurrency tests calls `…_contextify_run_script` and + sends version 1 module options, and a host-JS test drives the three + imports from a guest. ## How the current realm works From 46b75212409b8428fe89c020451cac0e5305b5df Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 16:37:00 -0800 Subject: [PATCH 069/150] Find a deprecated call's realm leaving no values in the caller's scope The deprecated calls found the realm a context names with napi_get_global, and with the env's own global to compare against, in the caller's handle scope. Each call with no context, with the env's global, or with version 1 of the bytecode or module options left one to four handles there (V8 left none for the option structs, which it wrapped in a V8 handle scope), and the guest layer stored one or two value ids, which a guest at its root frame never frees. main left none. napi::compat now makes those values in a handle scope of its own. The realm it returns stays valid after the scope closes: on V8 and QuickJS a realm handle is the provider's record, freed only by a later create_realm or collect_garbage once the realm is collected, and the context value, the entered scope or the running callback keeps the realm alive. V8's bytecode_open and module_wrap_create no longer need their own scopes for it. The guest layer does the same with the bridge's handle scopes. With the env's realm current it stores no id. With another realm current it stores one, the current global's, which names that realm and must outlive the lookup; a guest built against main is there only inside a callback. Tests count what the calls leave against the realm calls they stand for: handles natively (napi::testing::open_value_count, a new test-only hook in both providers), and value ids in a WAT guest on the native bridge and with the host-JS backend, which already reused an object's live id and passes before and after. Co-Authored-By: Claude Opus 5.5 --- docs/realms.md | 13 +- lib/src/napi_compat.cc | 34 +- lib/src/napi_compat.h | 3 +- lib/src/napi_testing.h | 17 + quickjs/src/unofficial_napi.cc | 15 + src/guest/compat.rs | 388 ++++++++++++++++++++- src/snapi_js.rs | 16 + tests/runners/test_71_contextify_compat.cc | 130 +++++++ v8/src/unofficial_napi.cc | 11 + v8/src/unofficial_napi_contextify.cc | 9 +- 10 files changed, 613 insertions(+), 23 deletions(-) create mode 100644 lib/src/napi_testing.h diff --git a/docs/realms.md b/docs/realms.md index 4847c11167..bdfb74b34c 100644 --- a/docs/realms.md +++ b/docs/realms.md @@ -183,10 +183,15 @@ calls take a realm's global or sandbox. realm (#125), `make_context` fails as `create_realm` does, and `run_script` with id 0 goes to `evaluate()`. - One layer (`src/guest/compat.rs`) maps a context id to a realm id for - both guest backends, as `lib/src/napi_compat.cc` does natively. The - current realm takes the id of `napi_get_global` and maps it with - `get_realm`, so a call with no context can add up to two value ids to - the current handle scope. + both guest backends, as `lib/src/napi_compat.cc` does natively. It + makes the ids of its lookups (the current global, the env's global) in + a handle scope of its own, as the native layer makes its values, so a + deprecated call leaves in the guest's current handle scope only what + the realm call it stands for leaves there. The one exception: with a + realm other than the env's current, the call also stores the id of the + current global, which names that realm, once per call. A guest built + against `main` can be in that case only inside a callback, whose scope + frees the id when it returns. - Guest env hooks are version 1, `main`'s 32 bytes. As on `main`, the bridge gives the provider none of them, so a guest's token callbacks are reported as not accepted and never called. diff --git a/lib/src/napi_compat.cc b/lib/src/napi_compat.cc index 9ae02da98e..25b5bb59de 100644 --- a/lib/src/napi_compat.cc +++ b/lib/src/napi_compat.cc @@ -15,6 +15,24 @@ bool is_nullish(napi_env env, napi_value value, napi_valuetype* type_out) { return *type_out == napi_undefined || *type_out == napi_null; } +// Runs `lookup` in a handle scope of its own, so that the values it makes +// (globals, mostly) are not left in the caller's scope, which may be one that +// never closes. The realm it finds stays valid after the scope closes: on V8 +// and QuickJS a realm handle is the provider's record of the realm, freed only +// by a later unofficial_napi_create_realm or unofficial_napi_collect_garbage +// once the realm is collected, and what named the realm keeps it alive (the +// caller's context value, or the entered scope or running callback of the +// current realm). +template +napi_status in_lookup_scope(napi_env env, Lookup lookup) { + napi_handle_scope scope = nullptr; + napi_status status = napi_open_handle_scope(env, &scope); + if (status != napi_ok) return status; + status = lookup(); + const napi_status closed = napi_close_handle_scope(env, scope); + return status != napi_ok ? status : closed; +} + // The env's own global, whichever realm is current. napi_status env_global(napi_env env, napi_value* global_out) { unofficial_napi_realm_scope scope = 0; @@ -32,10 +50,8 @@ napi_status is_env_global(napi_env env, napi_value value, bool* result_out) { return napi_strict_equals(env, value, global, result_out); } -} // namespace - -napi_status current_realm(napi_env env, unofficial_napi_realm* realm_out) { - *realm_out = nullptr; +// current_realm, making values in the caller's scope. +napi_status find_current_realm(napi_env env, unofficial_napi_realm* realm_out) { napi_value global = nullptr; napi_status status = napi_get_global(env, &global); if (status != napi_ok) return status; @@ -49,6 +65,13 @@ napi_status current_realm(napi_env env, unofficial_napi_realm* realm_out) { return napi_ok; } +} // namespace + +napi_status current_realm(napi_env env, unofficial_napi_realm* realm_out) { + *realm_out = nullptr; + return in_lookup_scope(env, [&] { return find_current_realm(env, realm_out); }); +} + napi_status realm_from_context(napi_env env, napi_value context, bool nullish_is_current, @@ -62,7 +85,8 @@ napi_status realm_from_context(napi_env env, if (unofficial_napi_get_realm(env, context, realm_out) != napi_ok) return napi_invalid_arg; if (*realm_out != nullptr) return napi_ok; bool env_own = false; - const napi_status status = is_env_global(env, context, &env_own); + const napi_status status = + in_lookup_scope(env, [&] { return is_env_global(env, context, &env_own); }); if (status != napi_ok) return status; return env_own ? napi_ok : napi_invalid_arg; } diff --git a/lib/src/napi_compat.h b/lib/src/napi_compat.h index 95328b4a5f..884f92bf56 100644 --- a/lib/src/napi_compat.h +++ b/lib/src/napi_compat.h @@ -6,7 +6,8 @@ // The deprecated API (the contextify calls and version 1 of the option // structs) on the public realm API, the same for every provider. Where it // named a context it named a contextified object, the env's own global, or -// nothing for the current context, which is the current realm now. +// nothing for the current context, which is the current realm now. Finding +// the realm leaves no value in the caller's handle scope. namespace napi::compat { // The current realm: NULL for the env's own. The env's own global means the diff --git a/lib/src/napi_testing.h b/lib/src/napi_testing.h new file mode 100644 index 0000000000..47f84d109a --- /dev/null +++ b/lib/src/napi_testing.h @@ -0,0 +1,17 @@ +#ifndef NAPI_TESTING_H_ +#define NAPI_TESTING_H_ + +#include + +#include "js_native_api.h" + +// For tests only: what the public API cannot observe. Each provider +// implements it. +namespace napi::testing { + +// The number of napi_values the open handle scopes of `env` hold. +size_t open_value_count(napi_env env); + +} // namespace napi::testing + +#endif // NAPI_TESTING_H_ diff --git a/quickjs/src/unofficial_napi.cc b/quickjs/src/unofficial_napi.cc index 04ca443c9c..8a7ff0ca5c 100644 --- a/quickjs/src/unofficial_napi.cc +++ b/quickjs/src/unofficial_napi.cc @@ -9,6 +9,7 @@ #include "internal/napi_shared_array_buffer.h" #include "internal/quickjs_trace.h" #include "napi_compat.h" +#include "napi_testing.h" #include "node_api.h" #include @@ -1575,3 +1576,17 @@ extern "C" } } // extern "C" + +namespace napi::testing +{ + size_t open_value_count(napi_env env) + { + if (!napi_util__::check_env(env)) + return 0; + size_t count = 0; + for (napi_scope__ *scope = env->scope_from_handle(env->current_scope()); scope != nullptr; + scope = scope->parent()) + count += scope->active_value_count(); + return count; + } +} // namespace napi::testing diff --git a/src/guest/compat.rs b/src/guest/compat.rs index d7d5df523a..9b19e9fd8f 100644 --- a/src/guest/compat.rs +++ b/src/guest/compat.rs @@ -2,7 +2,9 @@ //! option structs) on the bridge's realm calls, for both guest backends, as //! lib/src/napi_compat.cc does for native code. Ids are guest value ids, 0 is //! NULL, and a realm id is the value id of the realm's global or sandbox, 0 -//! for the env's own realm. +//! for the env's own realm. The lookups store their ids in a handle scope of +//! their own, as a guest at its root frame keeps every id stored in its +//! current scope. use crate::snapi::*; @@ -63,16 +65,37 @@ fn realm_of(env: SnapiEnv, value: u32) -> Result { Ok(realm) } +/// Runs `lookup` in a handle scope of its own, so that the value ids it +/// stores (globals) do not stay in the guest's current scope, which at a +/// guest's root frame is never closed. Ids it returns die with the scope. +fn in_lookup_scope(env: SnapiEnv, lookup: impl FnOnce() -> Result) -> Result { + let mut scope = 0u32; + check(unsafe { snapi_bridge_open_handle_scope(env, &mut scope) })?; + let result = lookup(); + let closed = check(unsafe { snapi_bridge_close_handle_scope(env, scope) }); + let value = result?; + closed?; + Ok(value) +} + /// The current realm, which the env's context meant before realms. The env's /// own global means the env's realm even when it is also a realm's sandbox. +/// With the env's realm current no id is stored; with another, one: the id of +/// the current global, which names that realm. pub(crate) fn current_realm(env: SnapiEnv) -> Result { - let mut global = 0u32; - check(unsafe { snapi_bridge_get_global(env, &mut global) })?; - let realm = realm_of(env, global)?; - if realm == 0 || is_env_global(env, global)? { + let other_realm = in_lookup_scope(env, || { + let mut global = 0u32; + check(unsafe { snapi_bridge_get_global(env, &mut global) })?; + Ok(realm_of(env, global)? != 0 && !is_env_global(env, global)?) + })?; + if !other_realm { return Ok(0); } - Ok(realm) + // The id must outlive the call it names the realm for, so it is made + // again outside the lookup's scope. + let mut global = 0u32; + check(unsafe { snapi_bridge_get_global(env, &mut global) })?; + Ok(global) } /// The realm a context argument names: a contextified object's, the env's @@ -89,7 +112,7 @@ pub(crate) fn realm_from_context( Some(NAPI_UNDEFINED | NAPI_NULL) => {} Some(NAPI_OBJECT | NAPI_FUNCTION) => { let realm = realm_of(env, context).map_err(|_| NAPI_INVALID_ARG)?; - if realm != 0 || is_env_global(env, context)? { + if realm != 0 || in_lookup_scope(env, || is_env_global(env, context))? { return Ok(realm); } return Err(NAPI_INVALID_ARG); @@ -175,3 +198,354 @@ pub(crate) fn make_context( })?; Ok(global) } + +#[cfg(all(test, not(all(target_arch = "wasm32", feature = "js"))))] +mod tests { + use std::sync::Arc; + + use wasmer::{FunctionEnv, Imports, Instance, Memory, MemoryType, Module, Store}; + + use super::*; + use crate::budget::ResourceBudget; + + unsafe extern "C" { + fn snapi_bridge_unofficial_get_live_value_count(env: SnapiEnv) -> u64; + } + + /// Forwards to the deprecated imports, which a guest built against older + /// headers calls, and to the realm imports they stand for. + const GUEST: &str = r#"(module + (import "env" "memory" (memory 1)) + (import "napi" "napi_wasm_init_env" (func $init (result i32))) + (import "napi_extension_wasmer_v0" "unofficial_napi_contextify_run_script" + (func $contextify_run_script + (param i32 i32 i32 i32 i32 i32 i64 i32 i32 i32 i32 i32) (result i32))) + (import "napi_extension_wasmer_v0" "unofficial_napi_run_script" + (func $run_script + (param i32 i32 i32 i32 i32 i32 i64 i32 i32 i32 i32 i32) (result i32))) + (import "napi_extension_wasmer_v0" "unofficial_napi_contextify_compile_function" + (func $contextify_compile_function + (param i32 i32 i32 i32 i32 i32 i32 i32 i32 i32) (result i32))) + (import "napi_extension_wasmer_v0" "unofficial_napi_compile_function" + (func $compile_function + (param i32 i32 i32 i32 i32 i32 i32 i32 i32 i32) (result i32))) + (import "napi_extension_wasmer_v0" "unofficial_napi_bytecode_open" + (func $bytecode_open (param i32 i32 i32) (result i32))) + (import "napi_extension_wasmer_v0" "unofficial_napi_bytecode_release" + (func $bytecode_release (param i32 i32) (result i32))) + (import "napi_extension_wasmer_v0" "unofficial_napi_module_wrap_create" + (func $module_create (param i32 i32 i32) (result i32))) + (import "napi_extension_wasmer_v0" "unofficial_napi_module_wrap_destroy" + (func $module_destroy (param i32 i32) (result i32))) + (func (export "init") (result i32) (call $init)) + ;; (env, context or realm, source_ptr, filename, result_ptr) + (func (export "contextify_run_script") (param i32 i32 i32 i32 i32) (result i32) + (call $contextify_run_script (local.get 0) (local.get 1) (local.get 2) (local.get 3) + (i32.const 0) (i32.const 0) (i64.const -1) (i32.const 1) (i32.const 0) + (i32.const 0) (i32.const 0) (local.get 4))) + (func (export "run_script") (param i32 i32 i32 i32 i32) (result i32) + (call $run_script (local.get 0) (local.get 1) (local.get 2) (local.get 3) + (i32.const 0) (i32.const 0) (i64.const -1) (i32.const 1) (i32.const 0) + (i32.const 0) (i32.const 0) (local.get 4))) + (func (export "contextify_compile_function") (param i32 i32 i32 i32 i32) (result i32) + (call $contextify_compile_function (local.get 0) (local.get 2) (local.get 3) + (i32.const 0) (i32.const 0) (local.get 1) (i32.const 0) (i32.const 0) + (i32.const 0) (local.get 4))) + (func (export "compile_function") (param i32 i32 i32 i32 i32) (result i32) + (call $compile_function (local.get 0) (local.get 1) (local.get 2) (local.get 3) + (i32.const 0) (i32.const 0) (i32.const 0) (i32.const 0) (i32.const 0) + (local.get 4))) + ;; (env, options_ptr, result_ptr): opens bytecode and releases it. + (func (export "bytecode") (param i32 i32 i32) (result i32) + (local $status i32) + (local.set $status (call $bytecode_open (local.get 0) (local.get 1) (local.get 2))) + (if (local.get $status) (then (return (local.get $status)))) + (call $bytecode_release (local.get 0) (i32.load (local.get 2)))) + ;; (env, options_ptr, result_ptr): creates a module and destroys it. + (func (export "module") (param i32 i32 i32) (result i32) + (local $status i32) + (local.set $status (call $module_create (local.get 0) (local.get 1) (local.get 2))) + (if (local.get $status) (then (return (local.get $status)))) + (call $module_destroy (local.get 0) (i32.load (local.get 2)))))"#; + + const SCRIPT: u32 = 16; + const BODY: u32 = 32; + const MODULE_SOURCE: u32 = 48; + const BYTECODE: u32 = 64; + const MODULE: u32 = 128; + const RESULT: u32 = 256; + const CALLS: u64 = 16; + + fn status(code: i32) -> Result<(), i32> { + check(code) + } + + fn new_id(make: impl FnOnce(*mut u32) -> i32) -> u32 { + let mut id = 0; + assert_eq!(status(make(&mut id)), Ok(())); + id + } + + fn string(env: SnapiEnv, text: &str) -> u32 { + new_id(|out| unsafe { + snapi_bridge_create_string_utf8(env, text.as_ptr().cast(), text.len() as u32, out) + }) + } + + fn le(words: &[u32]) -> Vec { + words.iter().flat_map(|word| word.to_le_bytes()).collect() + } + + // A guest at its root frame keeps every value id it is given, so a + // deprecated call must store no more ids than the realm call it stands + // for: its result. + #[test] + fn deprecated_imports_store_only_their_results() { + let mut store = Store::default(); + let memory = Memory::new(&mut store, MemoryType::new(1, None, false)).unwrap(); + let mut napi_env = crate::env::NapiEnv::new( + ResourceBudget::unlimited(), + None, + Arc::default(), + Arc::default(), + ); + napi_env.memory = Some(memory.clone()); + // Dropping the store releases the env. + let function_env = FunctionEnv::new(&mut store, napi_env); + let mut imports = Imports::new(); + crate::guest::napi::register_napi_imports(&mut store, &function_env, &mut imports); + imports.define("env", "memory", memory.clone()); + let module = Module::new(&store, wat::parse_str(GUEST).unwrap()).unwrap(); + let instance = Instance::new(&mut store, &module, &imports).unwrap(); + let call5 = |name: &str| { + instance + .exports + .get_typed_function::<(u32, u32, u32, u32, u32), i32>(&store, name) + .unwrap() + }; + let call3 = |name: &str| { + instance + .exports + .get_typed_function::<(u32, u32, u32), i32>(&store, name) + .unwrap() + }; + let (contextify_run_script, run_script) = + (call5("contextify_run_script"), call5("run_script")); + let (contextify_compile_function, compile_function) = ( + call5("contextify_compile_function"), + call5("compile_function"), + ); + let (bytecode, module_call) = (call3("bytecode"), call3("module")); + let guest_env = instance + .exports + .get_typed_function::<(), u32>(&store, "init") + .unwrap() + .call(&mut store) + .unwrap(); + assert_ne!(guest_env, 0); + let env = function_env.as_ref(&store).resolve_napi_env(guest_env); + + let filename = string(env, "count.js"); + let undefined = new_id(|out| unsafe { snapi_bridge_get_undefined(env, out) }); + let env_global = new_id(|out| unsafe { snapi_bridge_get_global(env, out) }); + let name = string(env, "count"); + let (mut realm, mut realm_global) = (0, 0); + assert_eq!( + status(unsafe { + snapi_bridge_unofficial_create_realm( + env, + 0, + name, + 0, + 0, + 1, + 1, + 0, + &mut realm, + &mut realm_global, + ) + }), + Ok(()) + ); + let wrapper = new_id(|out| unsafe { snapi_bridge_create_object(env, out) }); + let url = string(env, "count.mjs"); + let source_text = string(env, "1 + 1"); + let write = |store: &Store, at: u32, bytes: &[u8]| { + memory.view(store).write(at.into(), bytes).unwrap(); + }; + // Three text unofficial_napi_js_source structs. + for (at, text) in [ + (SCRIPT, "1"), + (BODY, "return 1;"), + (MODULE_SOURCE, "export const one = 1;"), + ] { + write(&store, at, &le(&[0, string(env, text), 0])); + } + // Bytecode-open options of either version, for `realm` in version 2. + let bytecode_options = |version: u32, realm: u32| { + let mut words = vec![ + if version == 1 { 48 } else { 52 }, + version, + source_text, + filename, + 0, + undefined, + undefined, + 0, + 0, + 0, + 0, + 0, + ]; + if version != 1 { + words.push(realm); + } + le(&words) + }; + // Module-create options of either version, for `context` and, in + // version 2, `realm`. + let module_options = |version: u32, context: u32, realm: u32| { + let mut words = vec![ + if version == 1 { 40 } else { 44 }, + version, + 1, + wrapper, + url, + context, + MODULE_SOURCE, + 0, + 0, + undefined, + ]; + if version != 1 { + words.push(realm); + } + le(&words) + }; + + // Checks that `CALLS` calls of `deprecated` store `extra` more value + // ids than as many calls of `replacement`. + let live = || unsafe { snapi_bridge_unofficial_get_live_value_count(env) }; + let stored = |store: &mut Store, call: &dyn Fn(&mut Store) -> i32| { + let before = live(); + for _ in 0..CALLS { + assert_eq!(call(store), 0); + } + live() - before + }; + let check_pair = |store: &mut Store, + deprecated: &dyn Fn(&mut Store) -> i32, + replacement: &dyn Fn(&mut Store) -> i32, + extra: u64| { + let deprecated = stored(store, deprecated); + let replacement = stored(store, replacement); + assert_eq!(deprecated, replacement + extra); + }; + + // With the env's realm current, no context, the env's global or a + // realm's global. + for (context, realm_id) in [ + (0, 0), + (undefined, 0), + (env_global, 0), + (realm_global, realm), + ] { + check_pair( + &mut store, + &|store| { + contextify_run_script + .call(store, guest_env, context, SCRIPT, filename, RESULT) + .unwrap() + }, + &|store| { + run_script + .call(store, guest_env, realm_id, SCRIPT, filename, RESULT) + .unwrap() + }, + 0, + ); + check_pair( + &mut store, + &|store| { + contextify_compile_function + .call(store, guest_env, context, BODY, filename, RESULT) + .unwrap() + }, + &|store| { + compile_function + .call(store, guest_env, realm_id, BODY, filename, RESULT) + .unwrap() + }, + 0, + ); + let (v1, v2) = ( + module_options(1, context, 0), + module_options(2, 0, realm_id), + ); + check_pair( + &mut store, + &|store| { + write(store, MODULE, &v1); + module_call.call(store, guest_env, MODULE, RESULT).unwrap() + }, + &|store| { + write(store, MODULE, &v2); + module_call.call(store, guest_env, MODULE, RESULT).unwrap() + }, + 0, + ); + } + let (v1, v2) = (bytecode_options(1, 0), bytecode_options(2, 0)); + check_pair( + &mut store, + &|store| { + write(store, BYTECODE, &v1); + bytecode.call(store, guest_env, BYTECODE, RESULT).unwrap() + }, + &|store| { + write(store, BYTECODE, &v2); + bytecode.call(store, guest_env, BYTECODE, RESULT).unwrap() + }, + 0, + ); + + // With another realm current, the deprecated call also stores the + // id that names that realm, once per call. + let mut scope = 0u64; + assert_eq!( + status(unsafe { snapi_bridge_unofficial_enter_realm(env, realm, &mut scope) }), + Ok(()) + ); + check_pair( + &mut store, + &|store| { + contextify_run_script + .call(store, guest_env, 0, SCRIPT, filename, RESULT) + .unwrap() + }, + &|store| { + run_script + .call(store, guest_env, realm, SCRIPT, filename, RESULT) + .unwrap() + }, + CALLS, + ); + let (v1, v2) = (bytecode_options(1, 0), bytecode_options(2, realm)); + check_pair( + &mut store, + &|store| { + write(store, BYTECODE, &v1); + bytecode.call(store, guest_env, BYTECODE, RESULT).unwrap() + }, + &|store| { + write(store, BYTECODE, &v2); + bytecode.call(store, guest_env, BYTECODE, RESULT).unwrap() + }, + CALLS, + ); + assert_eq!( + status(unsafe { snapi_bridge_unofficial_leave_realm(env, scope) }), + Ok(()) + ); + } +} diff --git a/src/snapi_js.rs b/src/snapi_js.rs index 10bc7f74b2..4a3c03bad1 100644 --- a/src/snapi_js.rs +++ b/src/snapi_js.rs @@ -9146,5 +9146,21 @@ mod tests { NAPI_INVALID_ARG ); } + + // A call stores its result and no other id, whatever names the + // realm, also with a realm entered. + const CALLS: usize = 16; + let live = || unsafe { env_mut(env) }.unwrap().agent.value_handles.len(); + for (context, entered) in [(0, 0), (env_global, 0), (fresh, 0), (0, fresh)] { + let scope = (entered != 0).then(|| enter(env, entered).unwrap()); + let before = live(); + for _ in 0..CALLS { + assert_eq!(run(&mut store, context), Ok(0.into())); + } + assert_eq!(live() - before, CALLS); + if let Some(scope) = scope { + assert_eq!(leave(env, scope), NAPI_OK); + } + } } } diff --git a/tests/runners/test_71_contextify_compat.cc b/tests/runners/test_71_contextify_compat.cc index fd61274990..4fa8f9db25 100644 --- a/tests/runners/test_71_contextify_compat.cc +++ b/tests/runners/test_71_contextify_compat.cc @@ -10,6 +10,7 @@ #include "test_env.h" +#include "napi_testing.h" #include "unofficial_napi.h" #include @@ -1529,6 +1530,135 @@ TEST_F(Test71ContextifyCompat, ModuleOptionsOfBothVersions) { namespace { +// How many napi_values `n` calls of `call` leave in the handle scope they +// run in. Whatever `call` uses is made before. +template +size_t ValuesLeft(napi_env env, Call call) { + constexpr int kCalls = 16; + napi_handle_scope scope = nullptr; + EXPECT_EQ(napi_open_handle_scope(env, &scope), napi_ok); + const size_t before = napi::testing::open_value_count(env); + for (int i = 0; i < kCalls; ++i) call(); + const size_t after = napi::testing::open_value_count(env); + EXPECT_EQ(napi_close_handle_scope(env, scope), napi_ok); + return after - before; +} + +} // namespace + +// Finding the realm a deprecated call names leaves no value behind: each +// call leaves in the caller's handle scope only what the realm API call it +// stands for leaves there (its result). +TEST_F(Test71ContextifyCompat, DeprecatedCallsLeaveOnlyTheirResults) { + EnvScope s(runtime_.get()); + + napi_value env_global = Global(s.env); + napi_value undefined = Undefined(s.env); + napi_value a_global = nullptr; + unofficial_napi_realm a = FreshRealm(s.env, &a_global); + ASSERT_NE(a, nullptr); + napi_value filename = Str(s.env, "count.js"); + const unofficial_napi_js_source script = + unofficial_napi_js_source_from_text(Str(s.env, "1")); + const unofficial_napi_js_source body = + unofficial_napi_js_source_from_text(Str(s.env, "return 1;")); + auto run_in_context = [&](napi_value context) { + return [&s, &script, filename, context] { + napi_value result = nullptr; + EXPECT_EQ(unofficial_napi_contextify_run_script(s.env, context, &script, filename, 0, 0, -1, + true, false, false, nullptr, &result), + napi_ok); + }; + }; + auto run_in_realm = [&](unofficial_napi_realm realm) { + return [&s, &script, filename, realm] { + napi_value result = nullptr; + EXPECT_EQ(unofficial_napi_run_script(s.env, realm, &script, filename, 0, 0, -1, true, false, + false, nullptr, &result), + napi_ok); + }; + }; + auto compile_in_context = [&](napi_value context) { + return [&s, &body, filename, context] { + napi_value result = nullptr; + EXPECT_EQ(unofficial_napi_contextify_compile_function(s.env, &body, filename, 0, 0, context, + nullptr, nullptr, nullptr, &result), + napi_ok); + }; + }; + auto compile_in_realm = [&](unofficial_napi_realm realm) { + return [&s, &body, filename, realm] { + napi_value result = nullptr; + EXPECT_EQ(unofficial_napi_compile_function(s.env, realm, &body, filename, 0, 0, nullptr, + nullptr, nullptr, &result), + napi_ok); + }; + }; + MainBytecodeOpenOptionsV1 bytecode_v1 = MainBytecodeOptions(s.env, "1 + 1"); + unofficial_napi_bytecode_open_options bytecode_v2{}; + std::memcpy(&bytecode_v2, &bytecode_v1, sizeof(bytecode_v1)); + bytecode_v2.size = sizeof(bytecode_v2); + bytecode_v2.version = UNOFFICIAL_NAPI_BYTECODE_OPEN_OPTIONS_VERSION; + auto open_bytecode = [&](const void* options) { + return [&s, options] { + unofficial_napi_bytecode_open_result opened{}; + EXPECT_EQ(unofficial_napi_bytecode_open( + s.env, static_cast(options), + &opened), + napi_ok); + EXPECT_EQ(unofficial_napi_bytecode_release(s.env, opened.bytecode), napi_ok); + }; + }; + const unofficial_napi_js_source module_source = + unofficial_napi_js_source_from_text(Str(s.env, "export const one = 1;")); + napi_value wrapper = Object(s.env); + napi_value url = Str(s.env, "count.mjs"); + auto create_module = [&](auto options) { + options.kind = unofficial_napi_module_source_text; + options.wrapper = wrapper; + options.url = url; + options.payload.source_text.source = &module_source; + options.payload.source_text.host_defined_option_id = undefined; + return [&s, options] { + unofficial_napi_module_create_result created{}; + EXPECT_EQ(unofficial_napi_module_wrap_create( + s.env, reinterpret_cast(&options), + &created), + napi_ok); + EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, created.module), napi_ok); + }; + }; + + // The env's realm current: no context, the env's global, a realm's global. + for (napi_value context : {static_cast(nullptr), undefined, env_global}) { + EXPECT_EQ(ValuesLeft(s.env, run_in_context(context)), ValuesLeft(s.env, run_in_realm(nullptr))); + EXPECT_EQ(ValuesLeft(s.env, compile_in_context(context)), + ValuesLeft(s.env, compile_in_realm(nullptr))); + } + EXPECT_EQ(ValuesLeft(s.env, run_in_context(a_global)), ValuesLeft(s.env, run_in_realm(a))); + EXPECT_EQ(ValuesLeft(s.env, compile_in_context(a_global)), ValuesLeft(s.env, compile_in_realm(a))); + EXPECT_EQ(ValuesLeft(s.env, open_bytecode(&bytecode_v1)), + ValuesLeft(s.env, open_bytecode(&bytecode_v2))); + EXPECT_EQ(ValuesLeft(s.env, create_module(MainModuleOptions(nullptr))), + ValuesLeft(s.env, create_module(ModuleOptions(nullptr, nullptr)))); + EXPECT_EQ(ValuesLeft(s.env, create_module(MainModuleOptions(env_global))), + ValuesLeft(s.env, create_module(ModuleOptions(nullptr, nullptr)))); + EXPECT_EQ(ValuesLeft(s.env, create_module(MainModuleOptions(a_global))), + ValuesLeft(s.env, create_module(ModuleOptions(a, nullptr)))); + + // Another realm current. + EnteredRealm entered(s.env, a); + bytecode_v2.realm_or_null = a; + EXPECT_EQ(ValuesLeft(s.env, run_in_context(nullptr)), ValuesLeft(s.env, run_in_realm(a))); + EXPECT_EQ(ValuesLeft(s.env, compile_in_context(nullptr)), ValuesLeft(s.env, compile_in_realm(a))); + EXPECT_EQ(ValuesLeft(s.env, open_bytecode(&bytecode_v1)), + ValuesLeft(s.env, open_bytecode(&bytecode_v2))); + EXPECT_EQ(ValuesLeft(s.env, create_module(MainModuleOptions(nullptr))), + ValuesLeft(s.env, create_module(ModuleOptions(a, nullptr)))); +} + +namespace { + struct TokenLog { napi_env env = nullptr; // 'a' assign, 'u' unassign, 'c' the cleanup hook. diff --git a/v8/src/unofficial_napi.cc b/v8/src/unofficial_napi.cc index 1969db36a3..2a712ac7b3 100644 --- a/v8/src/unofficial_napi.cc +++ b/v8/src/unofficial_napi.cc @@ -28,6 +28,7 @@ #include "internal/napi_v8_env.h" #include "internal/napi_serdes_context.h" #include "internal/unofficial_napi_bridge.h" +#include "napi_testing.h" #include "unofficial_napi_error_utils.h" #include "edge_v8_platform.h" @@ -2923,3 +2924,13 @@ napi_status NAPI_CDECL unofficial_napi_create_serdes_binding(napi_env env, } } // extern "C" + +namespace napi::testing { + +// napi_values are V8 handles, held by the handle scopes V8 has open. +size_t open_value_count(napi_env env) { + if (env == nullptr || env->isolate == nullptr) return 0; + return static_cast(v8::HandleScope::NumberOfHandles(env->isolate)); +} + +} // namespace napi::testing diff --git a/v8/src/unofficial_napi_contextify.cc b/v8/src/unofficial_napi_contextify.cc index 8a945ff0b9..d75bda38d1 100644 --- a/v8/src/unofficial_napi_contextify.cc +++ b/v8/src/unofficial_napi_contextify.cc @@ -1967,7 +1967,6 @@ napi_status NAPI_CDECL unofficial_napi_bytecode_open( const unofficial_napi_bytecode_open_options* options, unofficial_napi_bytecode_open_result* result) { if (env == nullptr || options == nullptr || result == nullptr) return napi_invalid_arg; - v8::HandleScope handle_scope(env->isolate); unofficial_napi_realm realm = nullptr; const napi_status realm_status = napi::compat::bytecode_open_realm(env, options, &realm); if (realm_status != napi_ok) return realm_status; @@ -1977,6 +1976,7 @@ napi_status NAPI_CDECL unofficial_napi_bytecode_open( return napi_invalid_arg; } *result = {}; + v8::HandleScope handle_scope(env->isolate); v8::Local context = RealmContext(env, realm); if (context.IsEmpty()) return napi_invalid_arg; @@ -2626,11 +2626,8 @@ napi_status NAPI_CDECL unofficial_napi_module_wrap_create( unofficial_napi_module_create_result* result_out) { if (env == nullptr || options == nullptr || result_out == nullptr) return napi_invalid_arg; unofficial_napi_realm realm = nullptr; - { - v8::HandleScope handle_scope(env->isolate); - const napi_status realm_status = napi::compat::module_create_realm(env, options, &realm); - if (realm_status != napi_ok) return realm_status; - } + const napi_status realm_status = napi::compat::module_create_realm(env, options, &realm); + if (realm_status != napi_ok) return realm_status; *result_out = {}; napi_status status = napi_invalid_arg; switch (options->kind) { From 870be923758b0adb55f103bd50c4c14dcef218a3 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 16:37:28 -0800 Subject: [PATCH 070/150] Document the env's own global as a realm's sandbox in the deprecated API The env's own global may be a realm's sandbox, as with vm.createContext(globalThis). Named as a context it names that realm on both providers, as on main's V8, though the header said it named the env's realm. With no context and the env's realm current, both take the env's realm. While that realm is current, V8 takes the realm, but QuickJS and the host-JS guest imports take the env's realm: their napi_get_global returns the sandbox there, the env's own global, which the deprecated layer maps to the env's realm on purpose. Telling the two apart needs a current-realm query in every provider and the host-JS bridge, so the difference is documented in the header, napi_compat.h and docs/realms.md, and pinned by a test on each engine and one for the host-JS backend. Co-Authored-By: Claude Opus 5.5 --- docs/realms.md | 9 +++++ include/unofficial_napi.h | 29 ++++++++++------- lib/src/napi_compat.h | 16 +++++---- src/snapi_js.rs | 21 ++++++++++++ tests/runners/test_71_contextify_compat.cc | 38 ++++++++++++++++++++++ 5 files changed, 96 insertions(+), 17 deletions(-) diff --git a/docs/realms.md b/docs/realms.md index bdfb74b34c..40806fd212 100644 --- a/docs/realms.md +++ b/docs/realms.md @@ -147,12 +147,21 @@ calls take a realm's global or sandbox. - **A context argument** (sandbox, parsing context, `context_or_undefined`) is a contextified object, naming its realm, the env's own global, naming the env's realm, or nothing. Anything else fails with `napi_invalid_arg`. + The env's own global can also be a realm's sandbox + (`vm.createContext(globalThis)`). It is then a contextified object and + names that realm, as on `main`'s V8. - **Nothing** (NULL, `undefined` or `null`) means what the env's context meant on `main`: the current realm. That is the env's own realm unless the embedder enters a realm or a native function of another realm is running. Version 2 of the module options is the exception: there nothing means the env's realm, as a NULL `realm_or_null` does. The realm API's NULL is always the env's realm. + - The current realm is found from the global `napi_get_global` returns, + and the env's own global means the env's realm even when it is a realm's + sandbox. So while the realm whose sandbox is the env's own global is + current, nothing means that realm on V8, but the env's realm on QuickJS + and with the host-JS guest imports: there `napi_get_global` returns the + sandbox, the env's own global. - **Structs grow at the end.** Version 1 of the bytecode-open and module-create options keeps `main`'s layout, and version 2 appends `realm_or_null`. A provider reads a version 1 struct only up to diff --git a/include/unofficial_napi.h b/include/unofficial_napi.h index 7ad9401a0f..094afbd179 100644 --- a/include/unofficial_napi.h +++ b/include/unofficial_napi.h @@ -1044,12 +1044,18 @@ NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_contextify_make_context napi_value* result_out); // Deprecated: use unofficial_napi_run_script. The script runs in the realm -// `sandbox_or_null` names: the realm of a contextified object (a realm's -// global or sandbox), the env's realm for the env's own global, or the -// current realm for NULL, undefined or null. Unlike unofficial_napi_run_script -// with a NULL realm, that is the realm entered or of the running callback, -// which is the env's own unless the embedder enters realms. Any other value -// fails with napi_invalid_arg. +// `sandbox_or_null` names: +// - A contextified object (a realm's global or sandbox): its realm. The env's +// own global is one when it is a realm's sandbox (vm.createContext with +// globalThis), and then names that realm, as on main's V8. +// - The env's own global otherwise: the env's realm. +// - NULL, undefined or null: the current realm. Unlike +// unofficial_napi_run_script with a NULL realm, that is the realm entered or +// of the running callback, which is the env's own unless the embedder +// enters realms. While a realm whose sandbox is the env's own global is +// current, QuickJS takes the env's realm instead: napi_get_global returns +// that sandbox there, and the env's own global names the env's realm. +// Any other value fails with napi_invalid_arg. UNOFFICIAL_NAPI_DEPRECATED("use unofficial_napi_run_script") NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_contextify_run_script( napi_env env, @@ -1103,11 +1109,12 @@ typedef struct unofficial_napi_module__* unofficial_napi_module; // accepted. The realm is: // - version 2 with `realm_or_null` set: that realm. `context_or_undefined` // must then be NULL, undefined or null, else napi_invalid_arg. -// - otherwise, from the deprecated `context_or_undefined`: the realm of a -// contextified object (a realm's global or sandbox), the env's realm for -// the env's own global, and for NULL, undefined or null the env's realm -// (version 2) or the current realm (version 1). Any other value is -// napi_invalid_arg. +// - otherwise, from the deprecated `context_or_undefined`, as +// unofficial_napi_contextify_run_script's `sandbox_or_null`: the realm of a +// contextified object (a realm's global or sandbox, which the env's own +// global may be), the env's realm for the env's own global otherwise, and +// for NULL, undefined or null the env's realm (version 2) or the current +// realm (version 1). Any other value is napi_invalid_arg. #define UNOFFICIAL_NAPI_MODULE_CREATE_OPTIONS_VERSION 2u typedef enum { diff --git a/lib/src/napi_compat.h b/lib/src/napi_compat.h index 884f92bf56..dc32a67ab7 100644 --- a/lib/src/napi_compat.h +++ b/lib/src/napi_compat.h @@ -10,15 +10,19 @@ // the realm leaves no value in the caller's handle scope. namespace napi::compat { -// The current realm: NULL for the env's own. The env's own global means the -// env's realm even when it is also a realm's sandbox, as the env's context -// did before realms existed. +// The current realm: NULL for the env's own. It is the realm of the global +// napi_get_global returns, except that the env's own global means the env's +// realm even when it is also a realm's sandbox, as the env's context did +// before realms existed. (So on QuickJS, where napi_get_global returns a +// sandbox realm's sandbox, it is the env's realm also while the realm whose +// sandbox is the env's own global is current.) napi_status current_realm(napi_env env, unofficial_napi_realm* realm_out); // The realm `context` names: a contextified object's (a realm's global or -// sandbox), the env's (NULL) for the env's own global, and for NULL, undefined -// or null the current realm, or the env's when `nullish_is_current` is false. -// Any other value fails with napi_invalid_arg. +// sandbox, which the env's own global may be), the env's (NULL) for the env's +// own global otherwise, and for NULL, undefined or null the current realm, or +// the env's when `nullish_is_current` is false. Any other value fails with +// napi_invalid_arg. napi_status realm_from_context(napi_env env, napi_value context, bool nullish_is_current, diff --git a/src/snapi_js.rs b/src/snapi_js.rs index 4a3c03bad1..394901132b 100644 --- a/src/snapi_js.rs +++ b/src/snapi_js.rs @@ -8410,6 +8410,27 @@ mod tests { }); } + /// The env's own global as a realm's sandbox, for the deprecated + /// imports: named, it names that realm. Nothing names the env's realm, + /// also while that realm is entered, since napi_get_global returns the + /// sandbox there, the env's own global (as on QuickJS; V8 takes the + /// realm). + #[wasm_bindgen_test] + fn the_env_global_as_a_sandbox_for_the_deprecated_imports() { + use crate::guest::compat::{current_realm, realm_from_context}; + with_env(|env, _| { + let env_global = global_id(env); + let realm = new_realm(env, env_global).unwrap(); + assert_ne!(realm, 0); + assert_eq!(realm_from_context(env, env_global, true), Ok(realm)); + assert_eq!(current_realm(env), Ok(0)); + let scope = enter(env, realm).unwrap(); + assert_eq!(realm_from_context(env, env_global, true), Ok(realm)); + assert_eq!(current_realm(env), Ok(0)); + assert_eq!(leave(env, scope), NAPI_OK); + }); + } + #[wasm_bindgen_test] fn functions_and_bytecode_compile_for_their_realm() { with_env(|env, state| { diff --git a/tests/runners/test_71_contextify_compat.cc b/tests/runners/test_71_contextify_compat.cc index 4fa8f9db25..252aeb0990 100644 --- a/tests/runners/test_71_contextify_compat.cc +++ b/tests/runners/test_71_contextify_compat.cc @@ -1398,6 +1398,44 @@ TEST_F(Test71ContextifyCompat, NoContextMeansTheCurrentRealm) { ASSERT_EQ(napi_delete_reference(s.env, callback.seen), napi_ok); } +// The env's own global may be a realm's sandbox (vm.createContext with +// globalThis). Named as a context it names that realm, as on main's V8, and +// nothing still means the env's realm while that is current. While the +// realm is current, nothing means the realm on V8, but the env's realm on +// QuickJS, whose napi_get_global returns the sandbox there: the env's own +// global. (An array literal shows the realm a script ran in; a sandbox realm +// resolves global names such as Array through the sandbox.) +TEST_F(Test71ContextifyCompat, TheEnvsGlobalAsASandbox) { + EnvScope s(runtime_.get()); + + napi_value env_global = Global(s.env); + unofficial_napi_realm_options options; + unofficial_napi_realm_options_init(&options); + options.sandbox_or_null = env_global; + unofficial_napi_realm realm = nullptr; + ASSERT_EQ(unofficial_napi_create_realm(s.env, &options, &realm, nullptr), napi_ok); + napi_value env_array = Prototype(s.env, RunIn(s.env, nullptr, "[]")); + napi_value realm_array = Prototype(s.env, RunIn(s.env, realm, "[]")); + ASSERT_NE(env_array, nullptr); + ASSERT_NE(realm_array, nullptr); + ASSERT_FALSE(StrictEquals(s.env, env_array, realm_array)); + auto array_in = [&](napi_value context) { + napi_value array = nullptr; + EXPECT_EQ(RunInContext(s.env, context, "[]", &array), napi_ok); + return Prototype(s.env, array); + }; + + EXPECT_TRUE(StrictEquals(s.env, array_in(env_global), realm_array)); + EXPECT_TRUE(StrictEquals(s.env, array_in(nullptr), env_array)); + EnteredRealm entered(s.env, realm); + EXPECT_TRUE(StrictEquals(s.env, array_in(env_global), realm_array)); +#if defined(NAPI_TEST_ENGINE_QUICKJS) + EXPECT_TRUE(StrictEquals(s.env, array_in(nullptr), env_array)); +#else + EXPECT_TRUE(StrictEquals(s.env, array_in(nullptr), realm_array)); +#endif +} + // Version 1 of the bytecode options (main's layout) compiles for the current // realm; version 2 for its `realm_or_null`, NULL being the env's own. TEST_F(Test71ContextifyCompat, BytecodeOptionsOfBothVersions) { From 5e65386e671f5b2a5d5d03c70ed025ee5f945678 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 16:37:36 -0800 Subject: [PATCH 071/150] Document that host-JS contextify imports now refuse what main's accepted main's host-JS bridge ignored the context's name, made a fresh object for sandbox id 0 or an id that named no value, and ran a script with no sandbox for such an id. The guest imports now share one layer with the native bridge and return main's V8 and native-bridge statuses. Say so with the other status differences in docs/realms.md. Co-Authored-By: Claude Opus 5.5 --- docs/realms.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/realms.md b/docs/realms.md index 40806fd212..353f4b0306 100644 --- a/docs/realms.md +++ b/docs/realms.md @@ -182,7 +182,11 @@ calls take a realm's global or sandbox. NULL `name`, refused a symbol sandbox, returned an already contextified sandbox again, compiled in the env's context for a parsing context that was not contextified, and ignored `context_or_undefined`. It now behaves - as V8 does. + as V8 does. So do the host-JS guest imports, which are stricter than + `main`'s host-JS was: it ignored `name`, made a fresh object for sandbox + id 0 or an id that named no value, and ran with no sandbox for such an + id. They now return `main`'s V8 and native-bridge statuses + (`napi_invalid_arg`). - **Guest ABI.** The wasm32 layouts of version 1 are `main`'s, and version 2 appends a u32 realm id. The guest imports `unofficial_napi_contextify_make_context`, `…_run_script` and From 2d7424aa1b00dd33ccb975eb6f35a8927e651ae9 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 16:37:52 -0800 Subject: [PATCH 072/150] Say the bytecode-open and module-create options must be zero-initialized Version 2 of both structs appends realm_or_null. Source written before it that sets size to sizeof, version to the version macro and only the fields it knew sends version 2 with whatever realm_or_null holds. EdgeJS, main's tests and the bridge zero-initialize the structs; say that every caller must, in both structs' header comments and in docs/realms.md. Co-Authored-By: Claude Opus 5.5 --- docs/realms.md | 4 ++++ include/unofficial_napi.h | 10 ++++++++++ 2 files changed, 14 insertions(+) diff --git a/docs/realms.md b/docs/realms.md index 353f4b0306..2b47a1a3d7 100644 --- a/docs/realms.md +++ b/docs/realms.md @@ -187,6 +187,10 @@ calls take a realm's global or sandbox. id 0 or an id that named no value, and ran with no sandbox for such an id. They now return `main`'s V8 and native-bridge statuses (`napi_invalid_arg`). +- **Zero-initialize the option structs** (`= {0}` in C, `{}` in C++) + before setting their fields. Source written against `main` that sets + `size` to `sizeof`, `version` to the version macro and only the fields it + knew sends version 2 with an indeterminate `realm_or_null`. - **Guest ABI.** The wasm32 layouts of version 1 are `main`'s, and version 2 appends a u32 realm id. The guest imports `unofficial_napi_contextify_make_context`, `…_run_script` and diff --git a/include/unofficial_napi.h b/include/unofficial_napi.h index 094afbd179..914b3cfae5 100644 --- a/include/unofficial_napi.h +++ b/include/unofficial_napi.h @@ -943,6 +943,11 @@ typedef enum { // the env's own). Version 1, which ends before it (`size` at least // UNOFFICIAL_NAPI_BYTECODE_OPEN_OPTIONS_V1_SIZE), is deprecated but still // accepted: it compiles for the current realm. +// +// Zero-initialize the struct (`= {0}` in C, `{}` in C++) before setting its +// fields. Source written before version 2 that sets `size` to sizeof, +// `version` to UNOFFICIAL_NAPI_BYTECODE_OPEN_OPTIONS_VERSION and only the +// fields it knew sends version 2 with an indeterminate `realm_or_null`. #define UNOFFICIAL_NAPI_BYTECODE_OPEN_OPTIONS_VERSION 2u typedef struct unofficial_napi_bytecode_open_options { uint32_t size; @@ -1115,6 +1120,11 @@ typedef struct unofficial_napi_module__* unofficial_napi_module; // global may be), the env's realm for the env's own global otherwise, and // for NULL, undefined or null the env's realm (version 2) or the current // realm (version 1). Any other value is napi_invalid_arg. +// +// Zero-initialize the struct (`= {0}` in C, `{}` in C++) before setting its +// fields. Source written before version 2 that sets `size` to sizeof, +// `version` to UNOFFICIAL_NAPI_MODULE_CREATE_OPTIONS_VERSION and only the +// fields it knew sends version 2 with an indeterminate `realm_or_null`. #define UNOFFICIAL_NAPI_MODULE_CREATE_OPTIONS_VERSION 2u typedef enum { From 34a22d54384ad198101b5f91692a14713f053500 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 18:33:45 -0800 Subject: [PATCH 073/150] Say host-JS guests store at most one id for the current realm's global docs/realms.md said that with a realm other than the env's current, a deprecated guest call stores the id of the current global once per call, on both guest backends. That holds for the WASIX native bridge, which stores a new id each time. The host-JS backend gives an object the id it already has while that id is live, so it stores none while the guest holds an id of the realm's global, and else one, which later calls reuse. Say so in docs/realms.md and in src/guest/compat.rs, and make the host-JS count test pin it: no extra id for a realm entered by its global's id, and one in all for a realm whose global's id was freed with its handle scope. Co-Authored-By: Claude Opus 5.5 --- docs/realms.md | 12 ++++++++---- src/guest/compat.rs | 6 ++++-- src/snapi_js.rs | 36 +++++++++++++++++++++++++++++++++--- 3 files changed, 45 insertions(+), 9 deletions(-) diff --git a/docs/realms.md b/docs/realms.md index 2b47a1a3d7..ecdfcc2230 100644 --- a/docs/realms.md +++ b/docs/realms.md @@ -205,10 +205,14 @@ calls take a realm's global or sandbox. a handle scope of its own, as the native layer makes its values, so a deprecated call leaves in the guest's current handle scope only what the realm call it stands for leaves there. The one exception: with a - realm other than the env's current, the call also stores the id of the - current global, which names that realm, once per call. A guest built - against `main` can be in that case only inside a callback, whose scope - frees the id when it returns. + realm other than the env's current, the call also needs an id of the + current global, which names that realm, outside that scope. The WASIX + native bridge stores a new one on each call. The host-JS backend gives + an object the id it already has while that id is live, so it stores at + most one: none while the guest holds an id of the realm's global, else + one, which later calls reuse while it lives. A guest built against + `main` can be in that case only inside a callback, whose scope frees + the id when it returns. - Guest env hooks are version 1, `main`'s 32 bytes. As on `main`, the bridge gives the provider none of them, so a guest's token callbacks are reported as not accepted and never called. diff --git a/src/guest/compat.rs b/src/guest/compat.rs index 9b19e9fd8f..5c1c721485 100644 --- a/src/guest/compat.rs +++ b/src/guest/compat.rs @@ -81,7 +81,9 @@ fn in_lookup_scope(env: SnapiEnv, lookup: impl FnOnce() -> Result) -> /// The current realm, which the env's context meant before realms. The env's /// own global means the env's realm even when it is also a realm's sandbox. /// With the env's realm current no id is stored; with another, one: the id of -/// the current global, which names that realm. +/// the current global, which names that realm. The native bridge stores a new +/// one each call; the host-JS backend hands out the global's live id when it +/// has one, so there it stores at most one across calls. pub(crate) fn current_realm(env: SnapiEnv) -> Result { let other_realm = in_lookup_scope(env, || { let mut global = 0u32; @@ -510,7 +512,7 @@ mod tests { ); // With another realm current, the deprecated call also stores the - // id that names that realm, once per call. + // id that names that realm, once per call on the native bridge. let mut scope = 0u64; assert_eq!( status(unsafe { snapi_bridge_unofficial_enter_realm(env, realm, &mut scope) }), diff --git a/src/snapi_js.rs b/src/snapi_js.rs index 394901132b..61724dca03 100644 --- a/src/snapi_js.rs +++ b/src/snapi_js.rs @@ -9168,20 +9168,50 @@ mod tests { ); } - // A call stores its result and no other id, whatever names the - // realm, also with a realm entered. + // The ids `CALLS` calls store, whatever names the realm, also with a + // realm entered. const CALLS: usize = 16; let live = || unsafe { env_mut(env) }.unwrap().agent.value_handles.len(); + let mut stored = Vec::new(); for (context, entered) in [(0, 0), (env_global, 0), (fresh, 0), (0, fresh)] { let scope = (entered != 0).then(|| enter(env, entered).unwrap()); let before = live(); for _ in 0..CALLS { assert_eq!(run(&mut store, context), Ok(0.into())); } - assert_eq!(live() - before, CALLS); + stored.push(live() - before); if let Some(scope) = scope { assert_eq!(leave(env, scope), NAPI_OK); } } + // A realm entered whose global has no live id: its id is freed with + // the handle scope it was made in. + let mut frame = 0u32; + assert_eq!( + unsafe { snapi_bridge_open_handle_scope(env, &mut frame) }, + NAPI_OK + ); + assert_eq!( + make_context + .call(&mut store, guest_env, symbol, name, RESULT) + .unwrap(), + NAPI_OK + ); + let scope = enter(env, read_u32(&store)).unwrap(); + assert_eq!( + unsafe { snapi_bridge_close_handle_scope(env, frame) }, + NAPI_OK + ); + let before = live(); + for _ in 0..CALLS { + assert_eq!(run(&mut store, 0), Ok(0.into())); + } + stored.push(live() - before); + assert_eq!(leave(env, scope), NAPI_OK); + // Each call stores its result. With another realm current it also + // needs an id of the realm's global, and this backend gives an object + // its live id: none is stored while the guest holds one, else one in + // all, which the later calls reuse. + assert_eq!(stored, [CALLS, CALLS, CALLS, CALLS, CALLS + 1]); } } From fe7880193daf2961596cd2e9efaaaa5b67ef42d7 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 18:34:15 -0800 Subject: [PATCH 074/150] Point v1 bytecode and module options at run_script's QuickJS note Version 1 of the bytecode-open options compiles for the current realm, and version 1 of the module-create options takes it for a nullish context. Both find it as unofficial_napi_contextify_run_script does for NULL, so the QuickJS note there applies to them too: while the realm whose sandbox is the env's own global is current, QuickJS takes the env's realm, V8 that realm. The header said only "the current realm" for them. Say where it comes from in both structs' comments, napi_compat.h and docs/realms.md, and pin both structs in that realm on each engine. Co-Authored-By: Claude Opus 5.5 --- docs/realms.md | 5 +- include/unofficial_napi.h | 7 ++- lib/src/napi_compat.h | 2 +- tests/runners/test_71_contextify_compat.cc | 65 ++++++++++++++++++++-- 4 files changed, 68 insertions(+), 11 deletions(-) diff --git a/docs/realms.md b/docs/realms.md index ecdfcc2230..dfa252accd 100644 --- a/docs/realms.md +++ b/docs/realms.md @@ -140,7 +140,7 @@ calls take a realm's global or sandbox. | `unofficial_napi_contextify_make_context` | `create_realm` | An object or function sandbox becomes `sandbox_or_null`; a symbol (`vm.constants.DONT_CONTEXTIFY`) makes a fresh global. The other arguments become the realm options of the same names. Returns the realm's global: the sandbox, or the fresh global. | | `unofficial_napi_contextify_run_script` | `run_script` | The sandbox names the realm, as below. | | `unofficial_napi_contextify_compile_function` | `compile_function` | The parsing context names the realm, as below. | -| Bytecode-open options version 1 | Version 2, `realm_or_null` | Compiles for the current realm. | +| Bytecode-open options version 1 | Version 2, `realm_or_null` | Compiles for the current realm, as nothing means below. | | Module-create options version 1, and `context_or_undefined` in version 2 | Version 2, `realm_or_null` | The context names the realm, as below. | | The env hooks' `context_token_assign_callback` and `context_token_unassign_callback` | Per-realm state keyed by the realm's global | Tokens on realms, as below. | @@ -161,7 +161,8 @@ calls take a realm's global or sandbox. sandbox. So while the realm whose sandbox is the env's own global is current, nothing means that realm on V8, but the env's realm on QuickJS and with the host-JS guest imports: there `napi_get_global` returns the - sandbox, the env's own global. + sandbox, the env's own global. That holds for version 1 of the + bytecode-open and module-create options too. - **Structs grow at the end.** Version 1 of the bytecode-open and module-create options keeps `main`'s layout, and version 2 appends `realm_or_null`. A provider reads a version 1 struct only up to diff --git a/include/unofficial_napi.h b/include/unofficial_napi.h index 914b3cfae5..05a6a05be7 100644 --- a/include/unofficial_napi.h +++ b/include/unofficial_napi.h @@ -942,7 +942,9 @@ typedef enum { // Version 2 appended `realm_or_null`, the realm the code is compiled for (NULL: // the env's own). Version 1, which ends before it (`size` at least // UNOFFICIAL_NAPI_BYTECODE_OPEN_OPTIONS_V1_SIZE), is deprecated but still -// accepted: it compiles for the current realm. +// accepted: it compiles for the current realm, as +// unofficial_napi_contextify_run_script finds it for a NULL `sandbox_or_null` +// (see its QuickJS note). // // Zero-initialize the struct (`= {0}` in C, `{}` in C++) before setting its // fields. Source written before version 2 that sets `size` to sizeof, @@ -1119,7 +1121,8 @@ typedef struct unofficial_napi_module__* unofficial_napi_module; // contextified object (a realm's global or sandbox, which the env's own // global may be), the env's realm for the env's own global otherwise, and // for NULL, undefined or null the env's realm (version 2) or the current -// realm (version 1). Any other value is napi_invalid_arg. +// realm as that call finds it, QuickJS note included (version 1). Any +// other value is napi_invalid_arg. // // Zero-initialize the struct (`= {0}` in C, `{}` in C++) before setting its // fields. Source written before version 2 that sets `size` to sizeof, diff --git a/lib/src/napi_compat.h b/lib/src/napi_compat.h index dc32a67ab7..6e82fab601 100644 --- a/lib/src/napi_compat.h +++ b/lib/src/napi_compat.h @@ -29,7 +29,7 @@ napi_status realm_from_context(napi_env env, unofficial_napi_realm* realm_out); // Checks the size and version of bytecode-open options (version 1 or 2) and -// returns the realm to compile for: version 1 compiles for the current realm. +// returns the realm to compile for: version 1 compiles for current_realm's. napi_status bytecode_open_realm(napi_env env, const unofficial_napi_bytecode_open_options* options, unofficial_napi_realm* realm_out); diff --git a/tests/runners/test_71_contextify_compat.cc b/tests/runners/test_71_contextify_compat.cc index 252aeb0990..8fed71e514 100644 --- a/tests/runners/test_71_contextify_compat.cc +++ b/tests/runners/test_71_contextify_compat.cc @@ -1165,13 +1165,13 @@ napi_value SyntaxErrorPrototype(napi_env env, const void* options) { return Prototype(env, error); } -// Creates "export const g = globalThis;" from `options` (main's version-1 -// layout or the current one), evaluates it and returns g. `status_out` -// receives module_wrap_create's status. +// Creates `code` ("export const g = globalThis;" unless given) from `options` +// (main's version-1 layout or the current one), evaluates it and returns g. +// `status_out` receives module_wrap_create's status. template -napi_value ModuleGlobal(napi_env env, Options options, napi_status* status_out) { - const unofficial_napi_js_source source = - unofficial_napi_js_source_from_text(Str(env, "export const g = globalThis;")); +napi_value ModuleGlobal(napi_env env, Options options, napi_status* status_out, + const char* code = "export const g = globalThis;") { + const unofficial_napi_js_source source = unofficial_napi_js_source_from_text(Str(env, code)); options.kind = unofficial_napi_module_source_text; options.wrapper = Object(env); options.url = Str(env, "compat.mjs"); @@ -1436,6 +1436,59 @@ TEST_F(Test71ContextifyCompat, TheEnvsGlobalAsASandbox) { #endif } +// Version 1 of the bytecode and module options takes the current realm as +// unofficial_napi_contextify_run_script finds it for nothing: while the realm +// whose sandbox is the env's own global is current, that realm on V8, but the +// env's realm on QuickJS (see TheEnvsGlobalAsASandbox). +TEST_F(Test71ContextifyCompat, VersionOneOptionsInTheEnvsGlobalAsASandbox) { + EnvScope s(runtime_.get()); + + napi_value env_global = Global(s.env); + unofficial_napi_realm_options options; + unofficial_napi_realm_options_init(&options); + options.sandbox_or_null = env_global; + unofficial_napi_realm realm = nullptr; + ASSERT_EQ(unofficial_napi_create_realm(s.env, &options, &realm, nullptr), napi_ok); + + MainBytecodeOpenOptionsV1 bytecode_v1 = MainBytecodeOptions(s.env, "("); + unofficial_napi_bytecode_open_options bytecode_v2{}; + std::memcpy(&bytecode_v2, &bytecode_v1, sizeof(bytecode_v1)); + bytecode_v2.size = sizeof(bytecode_v2); + bytecode_v2.version = UNOFFICIAL_NAPI_BYTECODE_OPEN_OPTIONS_VERSION; + napi_value env_syntax = SyntaxErrorPrototype(s.env, &bytecode_v2); + bytecode_v2.realm_or_null = realm; + napi_value realm_syntax = SyntaxErrorPrototype(s.env, &bytecode_v2); + ASSERT_NE(env_syntax, nullptr); + ASSERT_NE(realm_syntax, nullptr); + ASSERT_FALSE(StrictEquals(s.env, env_syntax, realm_syntax)); + + napi_status status = napi_generic_failure; + const char* const array_module = "export const g = [];"; + napi_value env_array = + Prototype(s.env, ModuleGlobal(s.env, ModuleOptions(nullptr, nullptr), &status, array_module)); + napi_value realm_array = + Prototype(s.env, ModuleGlobal(s.env, ModuleOptions(realm, nullptr), &status, array_module)); + ASSERT_NE(env_array, nullptr); + ASSERT_NE(realm_array, nullptr); + ASSERT_FALSE(StrictEquals(s.env, env_array, realm_array)); + auto module_array = [&](napi_value context) { + return Prototype(s.env, ModuleGlobal(s.env, MainModuleOptions(context), &status, array_module)); + }; + + EXPECT_TRUE(StrictEquals(s.env, SyntaxErrorPrototype(s.env, &bytecode_v1), env_syntax)); + EXPECT_TRUE(StrictEquals(s.env, module_array(nullptr), env_array)); + EXPECT_TRUE(StrictEquals(s.env, module_array(env_global), realm_array)); + EnteredRealm entered(s.env, realm); + EXPECT_TRUE(StrictEquals(s.env, module_array(env_global), realm_array)); +#if defined(NAPI_TEST_ENGINE_QUICKJS) + EXPECT_TRUE(StrictEquals(s.env, SyntaxErrorPrototype(s.env, &bytecode_v1), env_syntax)); + EXPECT_TRUE(StrictEquals(s.env, module_array(nullptr), env_array)); +#else + EXPECT_TRUE(StrictEquals(s.env, SyntaxErrorPrototype(s.env, &bytecode_v1), realm_syntax)); + EXPECT_TRUE(StrictEquals(s.env, module_array(nullptr), realm_array)); +#endif +} + // Version 1 of the bytecode options (main's layout) compiles for the current // realm; version 2 for its `realm_or_null`, NULL being the env's own. TEST_F(Test71ContextifyCompat, BytecodeOptionsOfBothVersions) { From 20a906fcdc047044faa026c63f9e3a9896f3eece Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 19:00:23 -0800 Subject: [PATCH 075/150] Unassign the context token of every realm made during the env's release The release unassigned the tokens of the realms alive when it began, before the cleanup hooks ran, and of the realms the hooks made, after them. A realm that a reference's, a wrap's or an external buffer's finalizer made in the last pass was given a token and never had it taken back: the embedder kept its per-token state, and was never told the realm's record was freed. Taking the tokens back is now part of the release rounds in ~napi_env__. Each round begins by unassigning the token of every realm that has one, and a realm with a token is pending, as a hook or a value with a finalizer is, so the rounds repeat until no token is left assigned, before the env is freed. The first round still unassigns the realms alive when the release begins before any cleanup hook runs, as on main. What an unassign callback makes (values, hooks, realms, instance data) is released as the rest; a realm it makes is unassigned in the same sweep. At release a token callback now runs as a finalizer does there: with no exception pending, and what it throws is dropped. The exception of the code it runs inside (a hook whose create_realm or collect_garbage frees a collected realm) is kept. QuickJS accepts no token callbacks and calls none, unchanged; the new tests check that on it too. Tests (test_71): realms made at release by a reference's finalizer, a wrap's, an external ArrayBuffer's, the instance-data finalizer, a cleanup hook a finalizer adds, and unassign callbacks; and all of them in one release. Each assign has exactly one unassign, during the release, in the env's realm, and no token is assigned again while assigned. A token callback's exception at release is dropped, and a hook's survives an unassign run inside it. Before the fix the reference, wrap and external buffer cases each had 1 assign and 0 unassigns, and 3 hooks found an exception pending in the exception test. The header and docs/realms.md describe the token callbacks at release. Co-Authored-By: Claude Opus 5.5 --- docs/realms.md | 20 +- include/unofficial_napi.h | 36 +- tests/runners/test_71_contextify_compat.cc | 362 +++++++++++++++++++++ v8/src/internal/unofficial_napi_bridge.h | 5 +- v8/src/js_native_api_v8.cc | 28 +- v8/src/unofficial_napi_contextify.cc | 31 +- 6 files changed, 448 insertions(+), 34 deletions(-) diff --git a/docs/realms.md b/docs/realms.md index dfa252accd..7c949a54d8 100644 --- a/docs/realms.md +++ b/docs/realms.md @@ -172,13 +172,19 @@ calls take a realm's global or sandbox. - **Context tokens.** V8 accepts the token callbacks, as on `main`. A realm's token is its record, which outlives the assignment. V8 assigns it when `create_realm` (and so `make_context`) makes the realm, and unassigns it - once: when it frees the record of the collected realm (in the next - `create_realm` or in `collect_garbage`), or, for a realm still alive, at - env release before the cleanup hooks run (and after them for realms they - made). Realms made before the hooks were attached get no token. Both - hooks run in the env's realm. On `main` a context lived until release, so - tokens were only unassigned then. QuickJS does not accept the hooks and - never calls them, as on `main`. + exactly once, before the env is freed: when it frees the record of the + collected realm (in the next `create_realm` or in `collect_garbage`), or, + for a realm still alive, during env release. The release unassigns the + tokens of the realms alive when it begins before the cleanup hooks run, + as `main` did, and a realm made while it runs (by a cleanup hook, a + finalizer, the instance-data finalizer or an unassign callback) is pending + until the release's next pass unassigns its token; what an unassign + callback makes is released as the rest (see `unofficial_napi_release_env` + in the header). Realms made before the hooks were attached get no token. + Both hooks run in the env's realm; at release what they throw is dropped, + as for the other hooks and finalizers. On `main` a context lived until + release, so tokens were only unassigned then. QuickJS does not accept the + hooks and never calls them, as on `main`. - **Statuses are `main`'s V8 ones.** `main`'s QuickJS differed: it took a NULL `name`, refused a symbol sandbox, returned an already contextified sandbox again, compiled in the env's context for a parsing context that diff --git a/include/unofficial_napi.h b/include/unofficial_napi.h index 05a6a05be7..dd026f495e 100644 --- a/include/unofficial_napi.h +++ b/include/unofficial_napi.h @@ -163,13 +163,15 @@ enum { UNOFFICIAL_NAPI_ENV_HOOKS_VERSION = 1 }; // for the realm and is not reused while assigned. It calls // `context_token_assign_callback(env, token, data)` when the realm is created // (unofficial_napi_create_realm, and so unofficial_napi_contextify_make_context), -// and `context_token_unassign_callback(env, token, data)` once for each -// token: when the provider frees the record of a collected realm (in -// unofficial_napi_create_realm and unofficial_napi_collect_garbage), or, for a -// realm still alive, when the env is released, before its cleanup hooks run -// (and after them for realms they made). Both run in the env's realm. Realms -// made before the hooks were attached get no token. QuickJS does not accept -// them and never calls them. +// and `context_token_unassign_callback(env, token, data)` exactly once for +// each token, before the env is freed: when the provider frees the record of +// a collected realm (in unofficial_napi_create_realm and +// unofficial_napi_collect_garbage), or, for a realm still alive, during the +// env's release (unofficial_napi_release_env), which unassigns the tokens of +// the realms alive when it begins before the cleanup hooks run, and those of +// realms made while it runs too. Both run in the env's realm. Realms made +// before the hooks were attached get no token. QuickJS does not accept them +// and never calls them. UNOFFICIAL_NAPI_SUPPRESS_DEPRECATED_BEGIN typedef struct { uint32_t size; @@ -247,10 +249,22 @@ NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_attach_env( // empty. An addon that makes a new value in every finalizer never // finishes, as in Node. // -// After each hook and finalizer, an exception it left pending is dropped: -// nothing can catch it then (Node's CallIntoModule drops it too once JS can -// no longer run). An engine may run a finalizer in the middle of other code, -// when that code frees the last reference to a value (QuickJS does): there +// With the deprecated context-token callbacks (unofficial_napi_env_hooks; +// only V8 accepts them), each pass of 1 and 2 begins by unassigning the token +// of every realm that has one: in the first pass the realms alive when the +// release begins, before any cleanup hook runs, as main did. A realm made +// while releasing (by a hook, a finalizer, the instance-data finalizer or an +// unassign callback) is pending until its token is unassigned, in the next +// pass, so every token is unassigned once before the env is freed. What an +// unassign callback makes (values, hooks, realms, instance data) is released +// as the rest. +// +// After each hook, token callback and finalizer, an exception it left +// pending is dropped: nothing can catch it then (Node's CallIntoModule drops +// it too once JS can no longer run). An engine may run a finalizer in the +// middle of other code, when that code frees the last reference to a value +// (QuickJS does; V8 runs the unassign callback of a collected realm inside +// unofficial_napi_create_realm and unofficial_napi_collect_garbage): there // only the finalizer's own exception is dropped, and one that JS is throwing, // or that a hook has pending, is kept. Each runs on the env's thread, in the // env's realm (also when another realm was entered when the release began), diff --git a/tests/runners/test_71_contextify_compat.cc b/tests/runners/test_71_contextify_compat.cc index 8fed71e514..ca1c1c965c 100644 --- a/tests/runners/test_71_contextify_compat.cc +++ b/tests/runners/test_71_contextify_compat.cc @@ -13,6 +13,7 @@ #include "napi_testing.h" #include "unofficial_napi.h" +#include #include #include #include @@ -1883,3 +1884,364 @@ TEST_F(Test71ContextifyCompat, ContextTokensFollowRealms) { #endif EXPECT_FALSE(log.wrong_env); } + +namespace { + +// The context-token hooks at release, for realms made while the env is +// released. Each assign must have exactly one unassign, before the env is +// freed, and both run in the env's realm. A token stays the same for its realm +// and is not reused while assigned. +struct ReleaseTokens { + napi_env env = nullptr; + // The env's own global: a hook runs in the env's realm if it is the global. + napi_ref env_global = nullptr; + // 'a' assign, 'u' unassign, in order. + std::vector> events; + // Tokens assigned and not yet unassigned. + std::vector live; + // Realms the test made, with the token each was given (its handle). + std::vector made; + int failed_makes = 0; + bool wrong_env = false; + bool wrong_realm = false; + bool reused = false; + bool unassigned_unknown = false; + // Hooks that found an exception pending when they began. + int pending_at_hook = 0; + // How many more realms the unassign hook makes, one per call. + int unassign_makes = 0; + // How many more unassign hooks throw, one per call. + int unassign_throws = 0; +}; + +void CheckHookRealm(napi_env env, ReleaseTokens* log) { + log->wrong_env |= env != log->env; + bool pending = false; + if (napi_is_exception_pending(env, &pending) == napi_ok && pending) ++log->pending_at_hook; + napi_handle_scope scope = nullptr; + if (napi_open_handle_scope(env, &scope) != napi_ok) { + log->wrong_realm = true; + return; + } + napi_value global = nullptr; + napi_value env_global = nullptr; + bool same = false; + log->wrong_realm |= napi_get_global(env, &global) != napi_ok || + napi_get_reference_value(env, log->env_global, &env_global) != napi_ok || + env_global == nullptr || + napi_strict_equals(env, global, env_global, &same) != napi_ok || !same; + napi_close_handle_scope(env, scope); +} + +void MakeReleaseRealm(ReleaseTokens* log) { + napi_handle_scope scope = nullptr; + if (napi_open_handle_scope(log->env, &scope) != napi_ok) { + ++log->failed_makes; + return; + } + unofficial_napi_realm realm = nullptr; + napi_value global = nullptr; + if (unofficial_napi_create_realm(log->env, nullptr, &realm, &global) == napi_ok && + realm != nullptr) { + log->made.push_back(realm); + } else { + ++log->failed_makes; + } + napi_close_handle_scope(log->env, scope); +} + +void AssignReleaseToken(napi_env env, void* token, void* data) { + auto* log = static_cast(data); + CheckHookRealm(env, log); + log->reused |= std::find(log->live.begin(), log->live.end(), token) != log->live.end(); + log->live.push_back(token); + log->events.emplace_back('a', token); +} + +void UnassignReleaseToken(napi_env env, void* token, void* data) { + auto* log = static_cast(data); + CheckHookRealm(env, log); + auto it = std::find(log->live.begin(), log->live.end(), token); + if (it == log->live.end()) { + log->unassigned_unknown = true; + } else { + log->live.erase(it); + } + log->events.emplace_back('u', token); + if (log->unassign_makes > 0) { + --log->unassign_makes; + MakeReleaseRealm(log); + } + if (log->unassign_throws > 0) { + --log->unassign_throws; + napi_throw_error(env, nullptr, "unassign"); + } +} + +void MakeRealmHook(void* data) { + MakeReleaseRealm(static_cast(data)); +} + +void FinalizeMakingRealm(node_api_basic_env, void*, void* hint) { + MakeReleaseRealm(static_cast(hint)); +} + +void FinalizeAddingRealmHook(node_api_basic_env basic_env, void*, void* hint) { + napi_add_env_cleanup_hook(const_cast(basic_env), MakeRealmHook, hint); +} + +void FinalizeInstanceDataMakingRealm(napi_env, void* data, void*) { + MakeReleaseRealm(static_cast(data)); +} + +// Makes an env whose token hooks record into `log`. +void AttachReleaseTokens(EnvScope& s, ReleaseTokens* log) { + log->env = s.env; + napi_value global = nullptr; + ASSERT_EQ(napi_get_global(s.env, &global), napi_ok); + ASSERT_EQ(napi_create_reference(s.env, global, 1, &log->env_global), napi_ok); + unofficial_napi_env_hooks hooks{}; + hooks.size = sizeof(hooks); + hooks.version = UNOFFICIAL_NAPI_ENV_HOOKS_VERSION; + hooks.data = log; + hooks.context_token_assign_callback = AssignReleaseToken; + hooks.context_token_unassign_callback = UnassignReleaseToken; + uint64_t accepted = 0; + ASSERT_EQ(unofficial_napi_attach_env(s.env, &hooks, &accepted), napi_ok); +#if defined(NAPI_TEST_ENGINE_V8) + EXPECT_EQ(accepted, static_cast(unofficial_napi_env_hook_context_token_assign | + unofficial_napi_env_hook_context_token_unassign)); +#else + EXPECT_EQ(accepted, 0u); +#endif +} + +// Sets `name` on the env's global, which keeps `value` until the release. +void KeepOnGlobal(napi_env env, const char* name, napi_value value) { + napi_value global = nullptr; + ASSERT_EQ(napi_get_global(env, &global), napi_ok); + ASSERT_EQ(napi_set_named_property(env, global, name, value), napi_ok); +} + +void KeepFinalizedObject(napi_env env, napi_finalize finalize, ReleaseTokens* log) { + napi_value object = nullptr; + ASSERT_EQ(napi_create_object(env, &object), napi_ok); + ASSERT_EQ(napi_add_finalizer(env, object, nullptr, finalize, log, nullptr), napi_ok); + KeepOnGlobal(env, "finalized", object); +} + +void KeepWrappedObject(napi_env env, napi_finalize finalize, ReleaseTokens* log) { + static int native = 0; + napi_value object = nullptr; + ASSERT_EQ(napi_create_object(env, &object), napi_ok); + ASSERT_EQ(napi_wrap(env, object, &native, finalize, log, nullptr), napi_ok); + KeepOnGlobal(env, "wrapped", object); +} + +void KeepExternalArrayBuffer(napi_env env, napi_finalize finalize, ReleaseTokens* log) { + static char bytes[16] = {}; + napi_value array_buffer = nullptr; + ASSERT_EQ(napi_create_external_arraybuffer(env, bytes, sizeof(bytes), finalize, log, + &array_buffer), + napi_ok); + KeepOnGlobal(env, "external", array_buffer); +} + +void ReleaseTokensEnv(EnvScope& s) { + ASSERT_EQ(unofficial_napi_release_env(s.scope, nullptr), napi_ok); + s.scope = nullptr; + s.env = nullptr; +} + +// V8: every token assigned was unassigned once, before the release returned, +// in the env's realm, and was the handle of a realm the test made. QuickJS +// calls neither hook. +void ExpectEveryTokenUnassignedOnce(const ReleaseTokens& log, size_t realms) { + EXPECT_EQ(log.failed_makes, 0); + EXPECT_EQ(log.made.size(), realms); +#if defined(NAPI_TEST_ENGINE_V8) + size_t assigned = 0; + size_t unassigned = 0; + std::vector live; + for (const auto& event : log.events) { + if (event.first == 'a') { + ++assigned; + EXPECT_EQ(std::count(live.begin(), live.end(), event.second), 0); + live.push_back(event.second); + } else { + ++unassigned; + auto it = std::find(live.begin(), live.end(), event.second); + ASSERT_NE(it, live.end()); + live.erase(it); + } + } + EXPECT_EQ(assigned, realms); + EXPECT_EQ(unassigned, realms); + EXPECT_TRUE(live.empty()); + EXPECT_TRUE(log.live.empty()); + for (void* token : log.made) { + EXPECT_NE(std::find_if(log.events.begin(), log.events.end(), + [&](const auto& event) { + return event.first == 'a' && event.second == token; + }), + log.events.end()); + } + EXPECT_FALSE(log.reused); + EXPECT_FALSE(log.unassigned_unknown); + EXPECT_FALSE(log.wrong_env); + EXPECT_FALSE(log.wrong_realm); +#else + EXPECT_TRUE(log.events.empty()); +#endif +} + +} // namespace + +TEST_F(Test71ContextifyCompat, TokenOfARealmARefFinalizerMakesAtReleaseIsUnassigned) { + EnvScope s(runtime_.get()); + ReleaseTokens log; + AttachReleaseTokens(s, &log); + KeepFinalizedObject(s.env, FinalizeMakingRealm, &log); + ReleaseTokensEnv(s); + ExpectEveryTokenUnassignedOnce(log, 1); +} + +TEST_F(Test71ContextifyCompat, TokenOfARealmAWrapFinalizerMakesAtReleaseIsUnassigned) { + EnvScope s(runtime_.get()); + ReleaseTokens log; + AttachReleaseTokens(s, &log); + KeepWrappedObject(s.env, FinalizeMakingRealm, &log); + ReleaseTokensEnv(s); + ExpectEveryTokenUnassignedOnce(log, 1); +} + +TEST_F(Test71ContextifyCompat, TokenOfARealmAnExternalBufferFinalizerMakesAtReleaseIsUnassigned) { + EnvScope s(runtime_.get()); + ReleaseTokens log; + AttachReleaseTokens(s, &log); + KeepExternalArrayBuffer(s.env, FinalizeMakingRealm, &log); + ReleaseTokensEnv(s); + ExpectEveryTokenUnassignedOnce(log, 1); +} + +TEST_F(Test71ContextifyCompat, TokenOfARealmTheInstanceDataFinalizerMakesAtReleaseIsUnassigned) { + EnvScope s(runtime_.get()); + ReleaseTokens log; + AttachReleaseTokens(s, &log); + ASSERT_EQ(napi_set_instance_data(s.env, &log, FinalizeInstanceDataMakingRealm, nullptr), + napi_ok); + ReleaseTokensEnv(s); + ExpectEveryTokenUnassignedOnce(log, 1); +} + +// A hook a finalizer adds at release runs in a later round of the release. +TEST_F(Test71ContextifyCompat, TokenOfARealmALateHookMakesAtReleaseIsUnassigned) { + EnvScope s(runtime_.get()); + ReleaseTokens log; + AttachReleaseTokens(s, &log); + KeepFinalizedObject(s.env, FinalizeAddingRealmHook, &log); + ReleaseTokensEnv(s); + ExpectEveryTokenUnassignedOnce(log, 1); +} + +// The unassign hook of a realm alive at release makes a realm, and so does +// the unassign hook of that one. +TEST_F(Test71ContextifyCompat, TokenOfARealmAnUnassignHookMakesAtReleaseIsUnassigned) { + EnvScope s(runtime_.get()); + ReleaseTokens log; + AttachReleaseTokens(s, &log); + MakeReleaseRealm(&log); + log.unassign_makes = 2; + ReleaseTokensEnv(s); +#if defined(NAPI_TEST_ENGINE_V8) + ExpectEveryTokenUnassignedOnce(log, 3); + EXPECT_EQ(log.unassign_makes, 0); +#else + ExpectEveryTokenUnassignedOnce(log, 1); +#endif +} + +// All of them in one release, with what each makes handled in turn: a realm +// alive when the release begins, one a cleanup hook makes, and those values' +// finalizers, a late hook, the instance-data finalizer and unassign hooks +// make. +TEST_F(Test71ContextifyCompat, TokensOfRealmsMadeThroughoutTheReleaseAreUnassignedOnce) { + EnvScope s(runtime_.get()); + ReleaseTokens log; + AttachReleaseTokens(s, &log); + MakeReleaseRealm(&log); + ASSERT_EQ(napi_add_env_cleanup_hook(s.env, MakeRealmHook, &log), napi_ok); + KeepFinalizedObject(s.env, FinalizeMakingRealm, &log); + KeepWrappedObject(s.env, FinalizeMakingRealm, &log); + KeepExternalArrayBuffer(s.env, FinalizeMakingRealm, &log); + napi_value late = nullptr; + ASSERT_EQ(napi_create_object(s.env, &late), napi_ok); + ASSERT_EQ(napi_add_finalizer(s.env, late, nullptr, FinalizeAddingRealmHook, &log, nullptr), + napi_ok); + KeepOnGlobal(s.env, "late", late); + ASSERT_EQ(napi_set_instance_data(s.env, &log, FinalizeInstanceDataMakingRealm, nullptr), + napi_ok); + log.unassign_makes = 3; + ReleaseTokensEnv(s); +#if defined(NAPI_TEST_ENGINE_V8) + ExpectEveryTokenUnassignedOnce(log, 10); + EXPECT_EQ(log.unassign_makes, 0); +#else + ExpectEveryTokenUnassignedOnce(log, 7); +#endif + // The realm alive when the release began gave up its token first, before + // the cleanup hooks ran. + if (!log.events.empty()) { + EXPECT_EQ(log.events[1], std::make_pair('u', log.made[0])); + } +} + +namespace { + +// A cleanup hook with an exception pending makes a realm the collector frees +// at once, so its unassign hook runs inside the cleanup hook. +struct ThrowThenFree { + ReleaseTokens* log = nullptr; + bool pending_after_free = false; + size_t events_before = 0; + size_t events_after = 0; +}; + +void HookThrowingThenFreeingARealm(void* data) { + auto* state = static_cast(data); + napi_env env = state->log->env; + MakeReleaseRealm(state->log); + napi_throw_error(env, nullptr, "hook"); + state->events_before = state->log->events.size(); + unofficial_napi_collect_garbage(env); + state->events_after = state->log->events.size(); + napi_is_exception_pending(env, &state->pending_after_free); +} + +} // namespace + +// What a token hook throws at release is dropped, as what a cleanup hook or a +// finalizer throws: nothing can catch it. A hook that runs inside other code +// (here collect_garbage, freeing a collected realm, in a cleanup hook) runs +// with no exception pending, and the one that code has pending is kept. +TEST_F(Test71ContextifyCompat, TokenHookExceptionsAtReleaseAreDropped) { + EnvScope s(runtime_.get()); + ReleaseTokens log; + AttachReleaseTokens(s, &log); + MakeReleaseRealm(&log); + MakeReleaseRealm(&log); + log.unassign_throws = 1; + ThrowThenFree state; + state.log = &log; + ASSERT_EQ(napi_add_env_cleanup_hook(s.env, HookThrowingThenFreeingARealm, &state), napi_ok); + ReleaseTokensEnv(s); + ExpectEveryTokenUnassignedOnce(log, 3); + EXPECT_TRUE(state.pending_after_free); + // The second unassign hook did not find the first one's exception, and the + // one inside the cleanup hook ran with none pending either. + EXPECT_EQ(log.pending_at_hook, 0); +#if defined(NAPI_TEST_ENGINE_V8) + EXPECT_EQ(log.unassign_throws, 0); + EXPECT_EQ(state.events_after, state.events_before + 1); +#endif +} diff --git a/v8/src/internal/unofficial_napi_bridge.h b/v8/src/internal/unofficial_napi_bridge.h index a579fd12bf..e910b2ae19 100644 --- a/v8/src/internal/unofficial_napi_bridge.h +++ b/v8/src/internal/unofficial_napi_bridge.h @@ -13,8 +13,11 @@ void NapiV8ApplyPromiseHooksToContext(napi_env env, v8::Local conte void NapiV8ApplyPromiseHooksToContextifyContexts(napi_env env); // Frees the records of collected realms, unassigning their context tokens. void NapiV8ReleaseCollectedRealms(napi_env env); -// Unassigns the context token of every realm that still has one. +// Unassigns the context token of every realm that still has one, also of +// realms the unassign hooks make. void NapiV8UnassignRealmTokens(napi_env env); +// True while a realm of the env has a context token. +bool NapiV8HasRealmTokens(napi_env env); void NapiV8TrackProviderPromise(v8::Isolate* isolate, v8::Local promise); bool NapiV8HasPendingProviderWork(napi_env env); diff --git a/v8/src/js_native_api_v8.cc b/v8/src/js_native_api_v8.cc index 1e16783895..66bb9e6803 100644 --- a/v8/src/js_native_api_v8.cc +++ b/v8/src/js_native_api_v8.cc @@ -986,26 +986,28 @@ napi_env__::~napi_env__() { // Every scope closes. Cleanup hooks and finalizers each run in the env's // realm, and a scope one leaves open closes when it returns. PopRealmFrames(0); - // The release contract (unofficial_napi_release_env): the cleanup hooks - // run, then the finalizers of the values still pending (references with a - // finalizer most recent first, as Node's FinalizeAll, then external - // buffers, each detached first), until neither is left; then the instance - // data's finalizer; and all of it again for what that finalizer leaves - // pending, until nothing is, so no hint is left pointing at the env. The - // callback is cleared before it runs, so instance data is finalized once. - // Realms still alive give up their context tokens before the cleanup hooks - // run, while the embedder's state is intact, and so do realms the hooks - // make. - NapiV8UnassignRealmTokens(this); + // The release contract (unofficial_napi_release_env), in rounds: the + // realms that have a context token give it up (the deprecated token hooks; + // in the first round the realms still alive, before the cleanup hooks run, + // while the embedder's state is intact); the cleanup hooks run; then the + // finalizers of the values still pending (references with a finalizer most + // recent first, as Node's FinalizeAll, then external buffers, each + // detached first). Rounds repeat while any of them has something left: a + // realm a hook or finalizer makes keeps its token until the next round. + // Then the instance data's finalizer; and all of it again for what that + // finalizer leaves pending, until nothing is, so no hint is left pointing + // at the env and no token is left assigned. The callback is cleared before + // it runs, so instance data is finalized once. for (;;) { do { - RunEnvCleanupHooks(this); NapiV8UnassignRealmTokens(this); + RunEnvCleanupHooks(this); napi_ref_tracker__::FinalizeAll(&finalizing_reflist); pending_finalizers.clear(); pending_buffer_finalizers.clear(); FinalizeExternalBackingStoreHints(this); - } while (!env_cleanup_hooks.empty() || !napi_ref_tracker__::IsEmpty(&finalizing_reflist)); + } while (!env_cleanup_hooks.empty() || !napi_ref_tracker__::IsEmpty(&finalizing_reflist) || + NapiV8HasRealmTokens(this)); if (instance_data_finalize_cb == nullptr) break; napi_finalize finalize_cb = instance_data_finalize_cb; instance_data_finalize_cb = nullptr; diff --git a/v8/src/unofficial_napi_contextify.cc b/v8/src/unofficial_napi_contextify.cc index d75bda38d1..66cc35d8d7 100644 --- a/v8/src/unofficial_napi_contextify.cc +++ b/v8/src/unofficial_napi_contextify.cc @@ -1316,7 +1316,11 @@ v8::Local RealmContext(napi_env env, unofficial_napi_realm realm) { } // Calls a deprecated context-token hook for `realm`, in the env's realm as -// every env hook runs. +// every env hook runs. At the release, as a finalizer there, it runs with no +// exception pending, and what it throws is dropped: nothing can catch it. It +// may run inside other code then (create_realm and collect_garbage free the +// records of collected realms), and the exception that code has pending is +// kept. void CallContextTokenHook(napi_env env, unofficial_napi_context_token_callback hook, unofficial_napi_realm realm) { @@ -1324,7 +1328,24 @@ void CallContextTokenHook(napi_env env, v8::HandleScope handle_scope(env->isolate); v8::Context::Scope context_scope(env->main_context()); napi_realm_frame_scope__ realm_frame(env, nullptr); - hook(env, realm, env->agent->context_token_data); + if (!env->releasing) { + hook(env, realm, env->agent->context_token_data); + return; + } + v8::Global exception = std::move(env->last_exception); + v8::Global message = std::move(env->last_exception_message); + std::string source_line; + std::string thrown_at; + source_line.swap(env->last_exception_source_line); + thrown_at.swap(env->last_exception_thrown_at); + { + v8::TryCatch try_catch(env->isolate); + hook(env, realm, env->agent->context_token_data); + } + env->last_exception = std::move(exception); + env->last_exception_message = std::move(message); + env->last_exception_source_line.swap(source_line); + env->last_exception_thrown_at.swap(thrown_at); } // A realm has a token while either hook is attached, as each context did. @@ -1669,6 +1690,12 @@ void NapiV8UnassignRealmTokens(napi_env env) { } } +bool NapiV8HasRealmTokens(napi_env env) { + if (env == nullptr || env->isolate == nullptr) return false; + return std::any_of(env->realms.begin(), env->realms.end(), + [](const auto& realm) { return realm->token_assigned; }); +} + extern "C" { napi_status NAPI_CDECL unofficial_napi_create_realm( From 71305355d54db875b07474ff989ec3c9820c39ef Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 19:07:27 -0800 Subject: [PATCH 076/150] Say a realm an unassign callback makes is unassigned in the same sweep The header and docs/realms.md said a realm made during the release, by an unassign callback too, is unassigned in the release's next pass. The sweep looks for tokens again after each callback, so a realm an unassign callback makes is unassigned in that same sweep, before the pass goes on (and before the cleanup hooks in the first pass). Only realms that hooks and finalizers make wait for the next pass. Found in review. Co-Authored-By: Claude Opus 5.5 --- docs/realms.md | 19 ++++++++++--------- include/unofficial_napi.h | 11 ++++++----- 2 files changed, 16 insertions(+), 14 deletions(-) diff --git a/docs/realms.md b/docs/realms.md index 7c949a54d8..ac7e9d19df 100644 --- a/docs/realms.md +++ b/docs/realms.md @@ -176,15 +176,16 @@ calls take a realm's global or sandbox. collected realm (in the next `create_realm` or in `collect_garbage`), or, for a realm still alive, during env release. The release unassigns the tokens of the realms alive when it begins before the cleanup hooks run, - as `main` did, and a realm made while it runs (by a cleanup hook, a - finalizer, the instance-data finalizer or an unassign callback) is pending - until the release's next pass unassigns its token; what an unassign - callback makes is released as the rest (see `unofficial_napi_release_env` - in the header). Realms made before the hooks were attached get no token. - Both hooks run in the env's realm; at release what they throw is dropped, - as for the other hooks and finalizers. On `main` a context lived until - release, so tokens were only unassigned then. QuickJS does not accept the - hooks and never calls them, as on `main`. + as `main` did. A realm a cleanup hook or a finalizer (the instance-data + finalizer too) makes while it runs is pending until the release's next + pass unassigns its token; one an unassign callback makes is unassigned in + the same sweep, and what else that callback makes is released as the rest + (see `unofficial_napi_release_env` in the header). Realms made before the + hooks were attached get no token. Both hooks run in the env's realm; at + release what they throw is dropped, as for the other hooks and + finalizers. On `main` a context lived until release, so tokens were only + unassigned then. QuickJS does not accept the hooks and never calls them, + as on `main`. - **Statuses are `main`'s V8 ones.** `main`'s QuickJS differed: it took a NULL `name`, refused a symbol sandbox, returned an already contextified sandbox again, compiled in the env's context for a parsing context that diff --git a/include/unofficial_napi.h b/include/unofficial_napi.h index dd026f495e..8469ecac0c 100644 --- a/include/unofficial_napi.h +++ b/include/unofficial_napi.h @@ -252,11 +252,12 @@ NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_attach_env( // With the deprecated context-token callbacks (unofficial_napi_env_hooks; // only V8 accepts them), each pass of 1 and 2 begins by unassigning the token // of every realm that has one: in the first pass the realms alive when the -// release begins, before any cleanup hook runs, as main did. A realm made -// while releasing (by a hook, a finalizer, the instance-data finalizer or an -// unassign callback) is pending until its token is unassigned, in the next -// pass, so every token is unassigned once before the env is freed. What an -// unassign callback makes (values, hooks, realms, instance data) is released +// release begins, before any cleanup hook runs, as main did. A realm a hook +// or a finalizer (the instance-data finalizer too) makes while releasing is +// pending until its token is unassigned, in the next pass; one an unassign +// callback makes is unassigned in the same sweep, before the pass goes on. +// So every token is unassigned once before the env is freed. What an +// unassign callback makes besides (values, hooks, instance data) is released // as the rest. // // After each hook, token callback and finalizer, an exception it left From c711e505dc67ac96e83cd221bae6d24ededbb6cd Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 20:01:04 -0800 Subject: [PATCH 077/150] Unassign a realm a cleanup hook makes at release before finalizers run On main, a context a cleanup hook made at release was unassigned among the cleanup hooks, before the finalizers: the contexts' own cleanup hook unassigned it, or registered itself again and ran after. "Restore the context-token hooks, as tokens on realms" kept that order with a second token sweep right after RunEnvCleanupHooks. "Unassign the context token of every realm made during the env's release" made the sweep the first step of each release pass and dropped the second one, so such a realm kept its token through that pass's reference, wrap and external buffer finalizers, and was unassigned only when the next pass began. Found in review. Each pass in ~napi_env__ sweeps again after the cleanup hooks, before the finalizers. Nothing else changes: the realms alive when the release begins are still unassigned before any cleanup hook runs, a realm a finalizer or the instance-data finalizer makes is still unassigned when the next pass begins, one an unassign callback makes in the same sweep, and every token once. Test (test_71, both engines): a cleanup hook makes a realm, and the finalizer of a kept value adds a hook that makes another realm and a value with a finalizer, which runs in the second pass. On V8 each finalizer now sees both token events of its pass's realm (2, then 4). Before this change they saw 1 and 3: each realm was unassigned only in the next pass. QuickJS calls no token hooks; both finalizers see none. The comment in ~napi_env__, the release contract in include/unofficial_napi.h and the Context tokens bullet in docs/realms.md say so, and that the finalizers after one that makes a realm still see that realm's token assigned. Co-Authored-By: Claude Opus 5.5 --- docs/realms.md | 13 ++-- include/unofficial_napi.h | 20 +++--- tests/runners/test_71_contextify_compat.cc | 74 ++++++++++++++++++++++ v8/src/js_native_api_v8.cc | 20 +++--- 4 files changed, 104 insertions(+), 23 deletions(-) diff --git a/docs/realms.md b/docs/realms.md index ac7e9d19df..c36a976424 100644 --- a/docs/realms.md +++ b/docs/realms.md @@ -176,11 +176,14 @@ calls take a realm's global or sandbox. collected realm (in the next `create_realm` or in `collect_garbage`), or, for a realm still alive, during env release. The release unassigns the tokens of the realms alive when it begins before the cleanup hooks run, - as `main` did. A realm a cleanup hook or a finalizer (the instance-data - finalizer too) makes while it runs is pending until the release's next - pass unassigns its token; one an unassign callback makes is unassigned in - the same sweep, and what else that callback makes is released as the rest - (see `unofficial_napi_release_env` in the header). Realms made before the + and those of the realms the hooks make after them, before the finalizers + run, as `main` did (its contexts' own cleanup hook unassigned them). A + realm a finalizer (the instance-data finalizer too) makes while the + release runs is pending until the release's next pass unassigns its + token, so the finalizers after it in its pass still see the token + assigned; one an unassign callback makes is unassigned in the same sweep, + and what else that callback makes is released as the rest (see + `unofficial_napi_release_env` in the header). Realms made before the hooks were attached get no token. Both hooks run in the env's realm; at release what they throw is dropped, as for the other hooks and finalizers. On `main` a context lived until release, so tokens were only diff --git a/include/unofficial_napi.h b/include/unofficial_napi.h index 8469ecac0c..2be7a0a971 100644 --- a/include/unofficial_napi.h +++ b/include/unofficial_napi.h @@ -250,15 +250,17 @@ NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_attach_env( // finishes, as in Node. // // With the deprecated context-token callbacks (unofficial_napi_env_hooks; -// only V8 accepts them), each pass of 1 and 2 begins by unassigning the token -// of every realm that has one: in the first pass the realms alive when the -// release begins, before any cleanup hook runs, as main did. A realm a hook -// or a finalizer (the instance-data finalizer too) makes while releasing is -// pending until its token is unassigned, in the next pass; one an unassign -// callback makes is unassigned in the same sweep, before the pass goes on. -// So every token is unassigned once before the env is freed. What an -// unassign callback makes besides (values, hooks, instance data) is released -// as the rest. +// only V8 accepts them), each pass of 1 and 2 unassigns the token of every +// realm that has one when it begins, and again between 1 and 2. So the +// realms alive when the release begins are unassigned before any cleanup +// hook runs, and a realm a cleanup hook makes is unassigned before the +// finalizers of 2 run, as main did. A realm a finalizer (the instance-data +// finalizer too) makes while releasing is pending until its token is +// unassigned, when the next pass begins: the finalizers after it in its pass +// see the token still assigned. One an unassign callback makes is unassigned +// in the same sweep, before the pass goes on. So every token is unassigned +// once before the env is freed. What an unassign callback makes besides +// (values, hooks, instance data) is released as the rest. // // After each hook, token callback and finalizer, an exception it left // pending is dropped: nothing can catch it then (Node's CallIntoModule drops diff --git a/tests/runners/test_71_contextify_compat.cc b/tests/runners/test_71_contextify_compat.cc index ca1c1c965c..3f5e425a15 100644 --- a/tests/runners/test_71_contextify_compat.cc +++ b/tests/runners/test_71_contextify_compat.cc @@ -2198,6 +2198,80 @@ TEST_F(Test71ContextifyCompat, TokensOfRealmsMadeThroughoutTheReleaseAreUnassign namespace { +// How many token events had happened when each finalizer ran. +struct EventsAtFinalizers { + ReleaseTokens* log = nullptr; + std::vector seen; +}; + +void RecordEventsAtFinalizer(node_api_basic_env, void*, void* hint) { + auto* state = static_cast(hint); + state->seen.push_back(state->log->events.size()); +} + +// A cleanup hook of the release's second pass: makes a realm, and a value +// whose finalizer runs in that pass. +void HookMakingRealmAndFinalizedValue(void* data) { + auto* state = static_cast(data); + MakeReleaseRealm(state->log); + napi_env env = state->log->env; + napi_handle_scope scope = nullptr; + if (napi_open_handle_scope(env, &scope) != napi_ok) return; + napi_value object = nullptr; + napi_value global = nullptr; + if (napi_create_object(env, &object) == napi_ok && + napi_add_finalizer(env, object, nullptr, RecordEventsAtFinalizer, state, nullptr) == + napi_ok && + napi_get_global(env, &global) == napi_ok) { + napi_set_named_property(env, global, "finalized_late", object); + } + napi_close_handle_scope(env, scope); +} + +void RecordEventsThenAddHook(node_api_basic_env basic_env, void* data, void* hint) { + RecordEventsAtFinalizer(basic_env, data, hint); + napi_add_env_cleanup_hook(const_cast(basic_env), HookMakingRealmAndFinalizedValue, + hint); +} + +} // namespace + +// A realm a cleanup hook makes at release gives up its token after the hooks +// of that pass, before the pass's finalizers run, as on main (whose contexts' +// own cleanup hook unassigned them), and in a later pass too. +TEST_F(Test71ContextifyCompat, TokenOfARealmACleanupHookMakesIsUnassignedBeforeTheFinalizers) { + EnvScope s(runtime_.get()); + ReleaseTokens log; + AttachReleaseTokens(s, &log); + EventsAtFinalizers state; + state.log = &log; + ASSERT_EQ(napi_add_env_cleanup_hook(s.env, MakeRealmHook, &log), napi_ok); + napi_value object = nullptr; + ASSERT_EQ(napi_create_object(s.env, &object), napi_ok); + ASSERT_EQ(napi_add_finalizer(s.env, object, nullptr, RecordEventsThenAddHook, &state, nullptr), + napi_ok); + KeepOnGlobal(s.env, "finalized", object); + ReleaseTokensEnv(s); + ExpectEveryTokenUnassignedOnce(log, 2); + ASSERT_EQ(state.seen.size(), 2u); +#if defined(NAPI_TEST_ENGINE_V8) + // First pass: the hook's realm is assigned and unassigned, then the + // finalizer runs. Second pass: the same for the late hook's realm. + ASSERT_EQ(log.events.size(), 4u); + EXPECT_EQ(log.events[0], std::make_pair('a', log.made[0])); + EXPECT_EQ(log.events[1], std::make_pair('u', log.made[0])); + EXPECT_EQ(log.events[2], std::make_pair('a', log.made[1])); + EXPECT_EQ(log.events[3], std::make_pair('u', log.made[1])); + EXPECT_EQ(state.seen[0], 2u); + EXPECT_EQ(state.seen[1], 4u); +#else + EXPECT_EQ(state.seen[0], 0u); + EXPECT_EQ(state.seen[1], 0u); +#endif +} + +namespace { + // A cleanup hook with an exception pending makes a realm the collector frees // at once, so its unassign hook runs inside the cleanup hook. struct ThrowThenFree { diff --git a/v8/src/js_native_api_v8.cc b/v8/src/js_native_api_v8.cc index 66bb9e6803..2ec3638c2b 100644 --- a/v8/src/js_native_api_v8.cc +++ b/v8/src/js_native_api_v8.cc @@ -989,19 +989,21 @@ napi_env__::~napi_env__() { // The release contract (unofficial_napi_release_env), in rounds: the // realms that have a context token give it up (the deprecated token hooks; // in the first round the realms still alive, before the cleanup hooks run, - // while the embedder's state is intact); the cleanup hooks run; then the - // finalizers of the values still pending (references with a finalizer most - // recent first, as Node's FinalizeAll, then external buffers, each - // detached first). Rounds repeat while any of them has something left: a - // realm a hook or finalizer makes keeps its token until the next round. - // Then the instance data's finalizer; and all of it again for what that - // finalizer leaves pending, until nothing is, so no hint is left pointing - // at the env and no token is left assigned. The callback is cleared before - // it runs, so instance data is finalized once. + // while the embedder's state is intact); the cleanup hooks run, and the + // realms they made give up their tokens before the round's finalizers, as + // on main; then the finalizers of the values still pending (references + // with a finalizer most recent first, as Node's FinalizeAll, then external + // buffers, each detached first). Rounds repeat while any of them has + // something left: a realm a finalizer makes keeps its token until the next + // round. Then the instance data's finalizer; and all of it again for what + // that finalizer leaves pending, until nothing is, so no hint is left + // pointing at the env and no token is left assigned. The callback is + // cleared before it runs, so instance data is finalized once. for (;;) { do { NapiV8UnassignRealmTokens(this); RunEnvCleanupHooks(this); + NapiV8UnassignRealmTokens(this); napi_ref_tracker__::FinalizeAll(&finalizing_reflist); pending_finalizers.clear(); pending_buffer_finalizers.clear(); From 00309cd12b86ac9ef23d7f94b5edb13e644257eb Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 20:10:29 -0800 Subject: [PATCH 078/150] Say which finalizers' realms keep tokens until the next release pass The header, docs/realms.md and the comment in ~napi_env__ said that a realm any finalizer makes at release keeps its token until the next pass. A finalizer can also run inside a cleanup hook (a hook that runs unofficial_napi_event_loop_checkpoint drains the finalizers of collected values), and the realm it makes is unassigned by the sweep after the hooks, in the same pass, as a realm the hook made itself. Only a realm made by the pass's own finalizers or the instance-data finalizer waits for the next pass, and any realm made at release is unassigned earlier if it is collected and its record freed first. The text now says so: a realm made while releasing is unassigned by the first sweep after it is made. Found in review. Text only. Co-Authored-By: Claude Opus 5.5 --- docs/realms.md | 16 +++++++++------- include/unofficial_napi.h | 23 +++++++++++++---------- v8/src/js_native_api_v8.cc | 18 +++++++++--------- 3 files changed, 31 insertions(+), 26 deletions(-) diff --git a/docs/realms.md b/docs/realms.md index c36a976424..26ce85f63b 100644 --- a/docs/realms.md +++ b/docs/realms.md @@ -176,13 +176,15 @@ calls take a realm's global or sandbox. collected realm (in the next `create_realm` or in `collect_garbage`), or, for a realm still alive, during env release. The release unassigns the tokens of the realms alive when it begins before the cleanup hooks run, - and those of the realms the hooks make after them, before the finalizers - run, as `main` did (its contexts' own cleanup hook unassigned them). A - realm a finalizer (the instance-data finalizer too) makes while the - release runs is pending until the release's next pass unassigns its - token, so the finalizers after it in its pass still see the token - assigned; one an unassign callback makes is unassigned in the same sweep, - and what else that callback makes is released as the rest (see + and those of the realms made while the hooks run (by a hook, or by a + finalizer that runs inside one) after them, before the release's + finalizers run, as `main` did (its contexts' own cleanup hook unassigned + them). A realm one of the release's finalizers (the instance-data + finalizer too) makes is pending until the release's next pass unassigns + its token, so the finalizers after it in its pass still see the token + assigned, unless the realm is collected and its record freed first. One + an unassign callback makes is unassigned in the same sweep, and what else + that callback makes is released as the rest (see `unofficial_napi_release_env` in the header). Realms made before the hooks were attached get no token. Both hooks run in the env's realm; at release what they throw is dropped, as for the other hooks and diff --git a/include/unofficial_napi.h b/include/unofficial_napi.h index 2be7a0a971..126147de73 100644 --- a/include/unofficial_napi.h +++ b/include/unofficial_napi.h @@ -251,16 +251,19 @@ NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_attach_env( // // With the deprecated context-token callbacks (unofficial_napi_env_hooks; // only V8 accepts them), each pass of 1 and 2 unassigns the token of every -// realm that has one when it begins, and again between 1 and 2. So the -// realms alive when the release begins are unassigned before any cleanup -// hook runs, and a realm a cleanup hook makes is unassigned before the -// finalizers of 2 run, as main did. A realm a finalizer (the instance-data -// finalizer too) makes while releasing is pending until its token is -// unassigned, when the next pass begins: the finalizers after it in its pass -// see the token still assigned. One an unassign callback makes is unassigned -// in the same sweep, before the pass goes on. So every token is unassigned -// once before the env is freed. What an unassign callback makes besides -// (values, hooks, instance data) is released as the rest. +// realm that has one when it begins, and again between 1 and 2. A realm made +// while releasing is pending until the first of these sweeps after it is +// made unassigns its token (or earlier, if it is collected and its record +// freed first). So the realms alive when the release begins are unassigned +// before any cleanup hook runs, and a realm made during 1 (by a cleanup hook, +// or by a finalizer that runs inside one) is unassigned before the +// finalizers of 2 run, as main did. A realm a finalizer of 2 or the +// instance-data finalizer makes is unassigned when the next pass begins: the +// finalizers after it in 2 see its token still assigned. One an unassign +// callback makes is unassigned in the same sweep, before the pass goes on. +// So every token is unassigned once before the env is freed. What an +// unassign callback makes besides (values, hooks, instance data) is released +// as the rest. // // After each hook, token callback and finalizer, an exception it left // pending is dropped: nothing can catch it then (Node's CallIntoModule drops diff --git a/v8/src/js_native_api_v8.cc b/v8/src/js_native_api_v8.cc index 2ec3638c2b..efde99b824 100644 --- a/v8/src/js_native_api_v8.cc +++ b/v8/src/js_native_api_v8.cc @@ -990,15 +990,15 @@ napi_env__::~napi_env__() { // realms that have a context token give it up (the deprecated token hooks; // in the first round the realms still alive, before the cleanup hooks run, // while the embedder's state is intact); the cleanup hooks run, and the - // realms they made give up their tokens before the round's finalizers, as - // on main; then the finalizers of the values still pending (references - // with a finalizer most recent first, as Node's FinalizeAll, then external - // buffers, each detached first). Rounds repeat while any of them has - // something left: a realm a finalizer makes keeps its token until the next - // round. Then the instance data's finalizer; and all of it again for what - // that finalizer leaves pending, until nothing is, so no hint is left - // pointing at the env and no token is left assigned. The callback is - // cleared before it runs, so instance data is finalized once. + // realms made while they ran give up their tokens before the round's + // finalizers, as on main; then the finalizers of the values still pending + // (references with a finalizer most recent first, as Node's FinalizeAll, + // then external buffers, each detached first). Rounds repeat while any of + // them has something left: a realm one of these finalizers makes keeps its + // token until the next round. Then the instance data's finalizer; and all + // of it again for what that finalizer leaves pending, until nothing is, so + // no hint is left pointing at the env and no token is left assigned. The + // callback is cleared before it runs, so instance data is finalized once. for (;;) { do { NapiV8UnassignRealmTokens(this); From 14708451ce86837fa65fd8a2ea28591a7c8a37de Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 18:36:22 -0800 Subject: [PATCH 079/150] QuickJS: read a view's length and offset from its slots napi_get_dataview_info read a DataView's byteLength and byteOffset through its properties, which a page script can redefine on the view or on its realm's DataView.prototype. A script that made them return 1 << 30 got native code a length of 1 GiB and a data pointer 1 GiB past the buffer: an out-of-bounds read or write for the addon (the buffer lease copies through it), in the env's realm and in an entered one. napi_get_typedarray_info and napi_get_buffer_info used JS_GetTypedArrayBuffer, which runs no script but reports the length a length-tracking typed array had when it was made. Over a resizable ArrayBuffer that shrank from 16 to 8 bytes, a Uint8Array at offset 4 reported 12 bytes, 8 of them past the buffer; after the buffer grew to 24 it still reported 12, not 20. A fixed-length typed array, Buffer or DataView that its shrunk buffer left out of bounds failed with a pending TypeError (napi_get_buffer_info with napi_invalid_arg, and napi_is_buffer said such a Buffer was none), where V8 and Node report a length of 0. The env now keeps the getters of buffer, byteOffset and byteLength on %TypedArray%.prototype and DataView.prototype, read when it is made (as "QuickJS: read a view's buffer through the intrinsic getters" kept the two buffer getters), and napi_env__::view_layout calls them. They read the view's internal slots, whatever realm made it, and run no script. A view over a detached buffer, or out of bounds, has no bytes and an offset of 0; a length and offset that do not fit the buffer are taken as out of bounds. napi_get_typedarray_info, napi_get_dataview_info, napi_get_buffer_info and napi_is_buffer use it. QuickJS polls its interrupt handler on calls, so during a termination request one getter call in many thousands threw; before this commit, 6 of 20000 DataView info calls failed while terminating. A getter that throws uncatchably is now called once more (the poll restarted its countdown). Tests, on both engines: views in the env's realm and in an entered realm, with buffer, byteOffset, byteLength and length redefined as counting getters on the views and on the prototypes, report their own layout and run none of the getters; views over a resizable buffer report its current size as it shrinks and grows (the offset of an out-of-bounds view is left unchecked: V8 reports the view's, QuickJS cannot read it and reports 0); the layout holds 20000 times during a termination request. Co-Authored-By: Claude Opus 5.5 --- quickjs/src/internal/napi_buffer.cc | 59 ++----- quickjs/src/internal/napi_env.cc | 127 ++++++++++----- quickjs/src/internal/napi_env.h | 47 ++++-- quickjs/src/js_native_api_quickjs.cc | 97 +++-------- tests/runners/test_33_typedarray.cc | 233 +++++++++++++++++++++++++++ 5 files changed, 388 insertions(+), 175 deletions(-) diff --git a/quickjs/src/internal/napi_buffer.cc b/quickjs/src/internal/napi_buffer.cc index f2de406a90..fb47960a4b 100644 --- a/quickjs/src/internal/napi_buffer.cc +++ b/quickjs/src/internal/napi_buffer.cc @@ -115,22 +115,10 @@ void napi_buffer__::clear_pending_exception_if_any() const bool napi_buffer__::has_typed_array_backing(JSValueConst value) const { - if (context_ == nullptr || !JS_IsObject(value)) - return false; - - JSValue arraybuffer = JS_GetTypedArrayBuffer(context_, value, nullptr, nullptr, nullptr); - // QuickJS throws for a view over a detached buffer, which is still one. - if (JS_IsException(arraybuffer)) - arraybuffer = env_->detached_view_buffer(value); - if (JS_IsUndefined(arraybuffer)) - { - clear_pending_exception_if_any(); - return false; - } - - const bool has_backing = !JS_IsUndefined(arraybuffer) && !JS_IsNull(arraybuffer); - JS_FreeValue(context_, arraybuffer); - return has_backing; + // Every typed array has its ArrayBuffer, also one over a detached buffer + // or out of bounds of a shrunk resizable one (QuickJS's accessors throw for + // these). + return context_ != nullptr && JS_GetTypedArrayType(value) >= 0; } bool napi_buffer__::prototype_chain_contains_cached_prototype(JSValueConst value) const @@ -246,39 +234,16 @@ napi_status napi_buffer__::get_buffer_info(JSValueConst value, void **data, size if (!is_buffer(value)) return napi_quickjs_set_last_error(env_, napi_invalid_arg, "Invalid argument"); - size_t offset = 0; - size_t byte_len = 0; - JSValue arraybuffer = JS_GetTypedArrayBuffer(context_, value, &offset, &byte_len, nullptr); - if (JS_IsException(arraybuffer)) - { - // QuickJS throws for a Buffer over a detached ArrayBuffer. Node reports - // it as one with no data and a length of 0. - JSValue detached = env_->detached_view_buffer(value); - if (!JS_IsUndefined(detached)) - { - JS_FreeValue(context_, detached); - if (data != nullptr) - *data = nullptr; - if (length != nullptr) - *length = 0; - return napi_quickjs_clear_last_error(env_); - } - clear_pending_exception_if_any(); + // Its own layout, never what its properties say. As in Node, a Buffer over + // a detached ArrayBuffer, or out of bounds of a shrunk resizable one, has + // no data and a length of 0. + napi_view_layout__ layout; + if (!env_->view_layout(value, &layout)) return napi_quickjs_set_last_error(env_, napi_invalid_arg, "Invalid argument"); - } - - size_t arraybuffer_len = 0; - uint8_t *arraybuffer_data = JS_GetArrayBuffer(context_, &arraybuffer_len, arraybuffer); - JS_FreeValue(context_, arraybuffer); - if (arraybuffer_data == nullptr && JS_HasException(context_)) - { - clear_pending_exception_if_any(); - return napi_quickjs_set_last_error(env_, napi_invalid_arg, "Invalid argument"); - } - + JS_FreeValue(context_, layout.buffer); if (data != nullptr) - *data = arraybuffer_data == nullptr ? nullptr : arraybuffer_data + offset; + *data = layout.data; if (length != nullptr) - *length = byte_len; + *length = layout.byte_length; return napi_quickjs_clear_last_error(env_); } diff --git a/quickjs/src/internal/napi_env.cc b/quickjs/src/internal/napi_env.cc index 80f31631a4..13021e0ba6 100644 --- a/quickjs/src/internal/napi_env.cc +++ b/quickjs/src/internal/napi_env.cc @@ -2,7 +2,6 @@ #include "internal/napi_external.h" #include "internal/napi_lifetime_macros.h" -#include "internal/napi_util.h" #include #include @@ -67,10 +66,11 @@ JSValue own_getter(JSContext *ctx, JSValueConst object, const char *name) return JS_UNDEFINED; } -// The getter of `name` on the prototype of `constructor_name` in the global -// (or on that prototype's own prototype, with `inherited`). -JSValue prototype_getter(JSContext *ctx, JSValueConst global, const char *constructor_name, - bool inherited, const char *name) +// The getters of `buffer`, `byteOffset` and `byteLength` on the prototype of +// `constructor_name` in the global (or on that prototype's own prototype, with +// `inherited`). +void view_getters(JSContext *ctx, JSValueConst global, const char *constructor_name, + bool inherited, JSValue *buffer, JSValue *byte_offset, JSValue *byte_length) { JSValue constructor = JS_GetPropertyStr(ctx, global, constructor_name); JSValue prototype = JS_IsObject(constructor) @@ -82,12 +82,36 @@ JSValue prototype_getter(JSContext *ctx, JSValueConst global, const char *constr JS_FreeValue(ctx, prototype); prototype = parent; } - JSValue getter = JS_IsException(prototype) ? JS_UNDEFINED : own_getter(ctx, prototype, name); + if (!JS_IsException(prototype)) + { + *buffer = own_getter(ctx, prototype, "buffer"); + *byte_offset = own_getter(ctx, prototype, "byteOffset"); + *byte_length = own_getter(ctx, prototype, "byteLength"); + } JS_FreeValue(ctx, prototype); JS_FreeValue(ctx, constructor); if (JS_HasException(ctx)) JS_FreeValue(ctx, JS_GetException(ctx)); - return getter; +} + +// Calls an intrinsic getter of a view. Such a getter runs no script, but +// QuickJS may poll its interrupt handler on the call and throw for a +// termination request (which the env keeps and raises again itself); the +// getter is then called again, as the poll restarted its countdown. +JSValue call_view_getter(JSContext *ctx, JSValueConst getter, JSValueConst view) +{ + JSValue value = JS_Call(ctx, getter, view, 0, nullptr); + if (!JS_IsException(value)) + return value; + JSValue exception = JS_GetException(ctx); + const bool interrupted = JS_IsUncatchableError(exception); + JS_FreeValue(ctx, exception); + if (!interrupted) + return JS_EXCEPTION; + value = JS_Call(ctx, getter, view, 0, nullptr); + if (JS_IsException(value)) + JS_FreeValue(ctx, JS_GetException(ctx)); + return value; } napi_runtime_interrupts__ *installed_runtime_interrupts(JSRuntime *rt) @@ -158,10 +182,12 @@ napi_env__::napi_env__(napi_agent__ *agent, JSContext *context, int32_t module_a agent_->open_root_scope(this); JSValue global = JS_GetGlobalObject(context_); JSValue data_view = JS_GetPropertyStr(context_, global, "DataView"); - // Typed arrays of any realm share these getters' behaviour: they read the - // view's internal slot, whatever realm made it. - typed_array_buffer_getter_ = prototype_getter(context_, global, "Uint8Array", true, "buffer"); - data_view_buffer_getter_ = prototype_getter(context_, global, "DataView", false, "buffer"); + // Views of any realm share these getters' behaviour: they read the view's + // internal slots, whatever realm made it. + view_getters(context_, global, "Uint8Array", true, &typed_array_getters_.buffer, + &typed_array_getters_.byte_offset, &typed_array_getters_.byte_length); + view_getters(context_, global, "DataView", false, &data_view_getters_.buffer, + &data_view_getters_.byte_offset, &data_view_getters_.byte_length); JS_FreeValue(context_, global); if (JS_IsConstructor(context_, data_view)) data_view_constructor_ = data_view; @@ -239,12 +265,16 @@ void napi_env__::prepare_teardown() if (context_ != nullptr) { JS_FreeValue(context_, data_view_constructor_); - JS_FreeValue(context_, typed_array_buffer_getter_); - JS_FreeValue(context_, data_view_buffer_getter_); + for (view_getters__ *getters : {&typed_array_getters_, &data_view_getters_}) + { + JS_FreeValue(context_, getters->buffer); + JS_FreeValue(context_, getters->byte_offset); + JS_FreeValue(context_, getters->byte_length); + } } data_view_constructor_ = JS_UNDEFINED; - typed_array_buffer_getter_ = JS_UNDEFINED; - data_view_buffer_getter_ = JS_UNDEFINED; + typed_array_getters_ = {}; + data_view_getters_ = {}; if (principal) agent_->clear_promise_hooks(); promises_.teardown(); @@ -389,35 +419,56 @@ JSContext *napi_env__::main_context() const return context_; } -JSValue napi_env__::view_buffer(JSValueConst view) const +bool napi_env__::view_layout(JSValueConst view, napi_view_layout__ *layout) const { - JSValueConst getter = JS_IsDataView(view) ? data_view_buffer_getter_ - : JS_GetTypedArrayType(view) >= 0 ? typed_array_buffer_getter_ - : JS_UNDEFINED; - if (context_ == nullptr || JS_IsUndefined(getter)) - return JS_UNDEFINED; + const view_getters__ *getters = JS_IsDataView(view) ? &data_view_getters_ + : JS_GetTypedArrayType(view) >= 0 ? &typed_array_getters_ + : nullptr; + if (context_ == nullptr || layout == nullptr || getters == nullptr || + !JS_IsFunction(context_, getters->buffer) || !JS_IsFunction(context_, getters->byte_offset) || + !JS_IsFunction(context_, getters->byte_length)) + return false; JSValue earlier = JS_GetException(context_); - JSValue buffer = JS_Call(context_, getter, view, 0, nullptr); - if (JS_IsException(buffer)) - { + *layout = {}; + layout->buffer = call_view_getter(context_, getters->buffer, view); + bool found = JS_IsObject(layout->buffer); + size_t buffer_length = 0; + // JS_GetArrayBuffer throws for a detached buffer only. + if (found) + layout->data = JS_GetArrayBuffer(context_, &buffer_length, layout->buffer); + if (layout->data == nullptr && JS_HasException(context_)) JS_FreeValue(context_, JS_GetException(context_)); - buffer = JS_UNDEFINED; + if (layout->data != nullptr) + { + // The typed array getters report 0 for a view out of bounds; the DataView + // ones throw. + JSValue offset_value = call_view_getter(context_, getters->byte_offset, view); + JSValue length_value = call_view_getter(context_, getters->byte_length, view); + int64_t offset = 0; + int64_t length = 0; + if (!JS_IsException(offset_value) && !JS_IsException(length_value) && + JS_ToInt64(context_, &offset, offset_value) == 0 && + JS_ToInt64(context_, &length, length_value) == 0 && offset >= 0 && length >= 0 && + static_cast(offset) <= buffer_length && + static_cast(length) <= buffer_length - static_cast(offset)) + { + layout->byte_offset = static_cast(offset); + layout->byte_length = static_cast(length); + layout->data += layout->byte_offset; + } + JS_FreeValue(context_, offset_value); + JS_FreeValue(context_, length_value); + if (JS_HasException(context_)) + JS_FreeValue(context_, JS_GetException(context_)); } - if (!JS_IsUninitialized(earlier)) - JS_Throw(context_, earlier); - return buffer; -} - -JSValue napi_env__::detached_view_buffer(JSValueConst view) const -{ - JSValue buffer = view_buffer(view); - if (napi_util__::is_detached_array_buffer(context_, buffer)) + if (!found) { - JS_FreeValue(context_, JS_GetException(context_)); - return buffer; + JS_FreeValue(context_, layout->buffer); + layout->buffer = JS_UNDEFINED; } - JS_FreeValue(context_, buffer); - return JS_UNDEFINED; + if (!JS_IsUninitialized(earlier)) + JS_Throw(context_, earlier); + return found; } JSValueConst napi_env__::data_view_constructor() const diff --git a/quickjs/src/internal/napi_env.h b/quickjs/src/internal/napi_env.h index b97bdb837a..cc0c4b1d07 100644 --- a/quickjs/src/internal/napi_env.h +++ b/quickjs/src/internal/napi_env.h @@ -30,6 +30,17 @@ struct napi_external_backing_store_hint__; struct napi_runtime_interrupts__; +// Where a typed array or DataView keeps its bytes, as its internal slots say. +// The receiver owns `buffer`. +struct napi_view_layout__ +{ + JSValue buffer = JS_UNDEFINED; + // Null when the buffer is detached. + uint8_t *data = nullptr; + size_t byte_offset = 0; + size_t byte_length = 0; +}; + // A realm N-API acts in: a scope opened with unofficial_napi_enter_realm, or // a native callback that is running. The innermost frame is the current // realm. @@ -74,17 +85,16 @@ struct napi_env__ // The env realm's DataView constructor, read when the env was made, before // any script could replace it; undefined if there was none. JSValueConst data_view_constructor() const; - // The ArrayBuffer a typed array or DataView views, read through the - // intrinsic buffer getters as the env was made, never through the view's - // own `buffer` property, which scripts can redefine. JS_UNDEFINED for - // anything else. Leaves any pending exception as it was. - JSValue view_buffer(JSValueConst view) const; - // After an accessor of a typed array or DataView threw: the view's - // ArrayBuffer if it is detached (QuickJS's accessors throw for it; Node - // reports such a view as having no data and a length of 0), with that - // exception cleared. Otherwise JS_UNDEFINED, with the exception still - // pending. - JSValue detached_view_buffer(JSValueConst view) const; + // The layout of a typed array or DataView: its ArrayBuffer, byte offset and + // byte length, read through the intrinsic getters as the env was made, + // never through the view's properties, which scripts can redefine on the + // view or on its realm's prototypes. These getters read the view's internal + // slots, whatever realm made it, and run no script. A view over a detached + // ArrayBuffer, or out of bounds of a resizable one that shrank, has no + // bytes (as in Node; QuickJS's accessors throw for some of these), and an + // offset of 0. False for anything else. Leaves any pending exception as it + // was. + bool view_layout(JSValueConst view, napi_view_layout__ *layout) const; // A function of the current realm that keeps it alive; undefined for the // env's own realm. JSValueConst current_realm_anchor() const; @@ -212,10 +222,17 @@ struct napi_env__ JSContext *context_; int32_t module_api_version_ = 8; JSValue data_view_constructor_ = JS_UNDEFINED; - // The getters of %TypedArray%.prototype.buffer and DataView.prototype.buffer, - // read when the env was made; undefined if there were none. - JSValue typed_array_buffer_getter_ = JS_UNDEFINED; - JSValue data_view_buffer_getter_ = JS_UNDEFINED; + // The getters of the buffer, byteOffset and byteLength properties of + // %TypedArray%.prototype and DataView.prototype, read when the env was made; + // undefined if there were none. + struct view_getters__ + { + JSValue buffer = JS_UNDEFINED; + JSValue byte_offset = JS_UNDEFINED; + JSValue byte_length = JS_UNDEFINED; + }; + view_getters__ typed_array_getters_; + view_getters__ data_view_getters_; // The realms N-API acts in, innermost last. Empty means the env's own. std::vector realm_frames_; diff --git a/quickjs/src/js_native_api_quickjs.cc b/quickjs/src/js_native_api_quickjs.cc index cde17423a1..c644962eab 100644 --- a/quickjs/src/js_native_api_quickjs.cc +++ b/quickjs/src/js_native_api_quickjs.cc @@ -517,21 +517,14 @@ extern "C" return napi_invalid_arg; } - size_t byte_len; - size_t offset; - JSValue abuf = JS_GetTypedArrayBuffer(env->context(), local, &offset, &byte_len, nullptr); - // QuickJS throws for a typed array over a detached buffer. Node reports - // it as one with no data and a length and offset of 0. - bool detached = false; - if (JS_IsException(abuf)) - { - abuf = env->detached_view_buffer(local); - if (JS_IsUndefined(abuf)) - return napi_util__::return_pending_if_caught(env, "Failed to get typed array info"); - detached = true; - byte_len = 0; - offset = 0; - } + // Its own layout, never what its properties say. As in Node, a typed + // array over a detached buffer, or out of bounds of a shrunk resizable + // one, has no elements. + napi_view_layout__ layout; + if (!env->view_layout(local, &layout)) + return napi_quickjs_set_last_error(env, napi_generic_failure, "Failed to get typed array info"); + const size_t byte_len = layout.byte_length; + JSValue abuf = layout.buffer; if (length != nullptr) { @@ -566,23 +559,12 @@ extern "C" if (byte_offset != nullptr) { - *byte_offset = offset; + *byte_offset = layout.byte_offset; } - if (data != nullptr && detached) + if (data != nullptr) { - *data = nullptr; - } - else if (data != nullptr) - { - size_t ab_len; - uint8_t *ab_data = JS_GetArrayBuffer(env->context(), &ab_len, abuf); - if (ab_data == nullptr) - { - JS_FreeValue(env->context(), abuf); - return napi_util__::return_pending_if_caught(env, "Failed to get array buffer data"); - } - *data = ab_data + offset; + *data = layout.data; } if (arraybuffer != nullptr) @@ -1455,54 +1437,19 @@ extern "C" if (!JS_IsDataView(view)) return napi_util__::invalid_arg(env); - // The view's own buffer, never what its `buffer` property says. - JSValue buffer_val = env->view_buffer(view); - if (JS_IsUndefined(buffer_val)) - buffer_val = JS_GetPropertyStr(env->context(), view, "buffer"); - if (JS_IsException(buffer_val)) - return napi_util__::return_pending_if_caught(env, "Failed to get DataView info"); - // QuickJS's byteLength and byteOffset getters throw for a DataView over a - // detached buffer. Node reports it as one with no data and a length and - // offset of 0. - const bool detached = napi_util__::is_detached_array_buffer(env->context(), buffer_val); - uint32_t len = 0; - uint32_t offset = 0; - if (!detached) - { - JSValue len_val = JS_GetPropertyStr(env->context(), view, "byteLength"); - JSValue offset_val = JS_GetPropertyStr(env->context(), view, "byteOffset"); - if (JS_IsException(len_val) || JS_IsException(offset_val)) - { - JS_FreeValue(env->context(), len_val); - JS_FreeValue(env->context(), offset_val); - JS_FreeValue(env->context(), buffer_val); - return napi_util__::return_pending_if_caught(env, "Failed to get DataView info"); - } - JS_ToUint32(env->context(), &len, len_val); - JS_ToUint32(env->context(), &offset, offset_val); - JS_FreeValue(env->context(), len_val); - JS_FreeValue(env->context(), offset_val); - } - + // Its own layout, never what its properties say. As in Node, a DataView + // over a detached buffer, or out of bounds of a shrunk resizable one, has + // no bytes. + napi_view_layout__ layout; + if (!env->view_layout(view, &layout)) + return napi_quickjs_set_last_error(env, napi_generic_failure, "Failed to get DataView info"); + JSValue buffer_val = layout.buffer; if (byte_length != nullptr) - *byte_length = len; + *byte_length = layout.byte_length; if (byte_offset != nullptr) - *byte_offset = offset; - if (data != nullptr && detached) - { - *data = nullptr; - } - else if (data != nullptr) - { - size_t ab_len = 0; - uint8_t *ab_data = JS_GetArrayBuffer(env->context(), &ab_len, buffer_val); - if (ab_data == nullptr && ab_len == 0 && JS_HasException(env->context())) - { - JS_FreeValue(env->context(), buffer_val); - return napi_util__::return_pending_if_caught(env, "Failed to get DataView ArrayBuffer"); - } - *data = ab_data + offset; - } + *byte_offset = layout.byte_offset; + if (data != nullptr) + *data = layout.data; if (arraybuffer != nullptr) { *arraybuffer = env->wrap_value_in_current_scope(buffer_val, true); diff --git a/tests/runners/test_33_typedarray.cc b/tests/runners/test_33_typedarray.cc index 7dbc7e6d4c..148d681fb9 100644 --- a/tests/runners/test_33_typedarray.cc +++ b/tests/runners/test_33_typedarray.cc @@ -6,6 +6,8 @@ #include "test_env.h" #include "upstream_js_test.h" +#include + extern "C" napi_value Init(napi_env env, napi_value exports); // node_api.h declares it from NAPI_VERSION 10; this target builds at 8. extern "C" napi_status NAPI_CDECL node_api_create_buffer_from_arraybuffer( @@ -377,6 +379,237 @@ TEST_F(Test33TypedArray, ViewInfoIgnoresARedefinedBufferProperty) { EXPECT_TRUE(same) << "the DataView's own ArrayBuffer"; } +namespace { + +napi_value NamedGlobal(napi_env env, const char* name) { + napi_value global = nullptr; + napi_value value = nullptr; + EXPECT_EQ(napi_get_global(env, &global), napi_ok); + EXPECT_EQ(napi_get_named_property(env, global, name, &value), napi_ok) << name; + return value; +} + +void SetGlobal(napi_env env, const char* name, napi_value value) { + napi_value global = nullptr; + ASSERT_EQ(napi_get_global(env, &global), napi_ok); + ASSERT_EQ(napi_set_named_property(env, global, name, value), napi_ok) << name; +} + +int32_t GlobalInt(napi_env env, const char* name) { + int32_t out = -1; + EXPECT_EQ(napi_get_value_int32(env, NamedGlobal(env, name), &out), napi_ok) << name; + return out; +} + +uint8_t* ArrayBufferData(napi_env env, napi_value array_buffer) { + void* data = nullptr; + size_t length = 0; + EXPECT_EQ(napi_get_arraybuffer_info(env, array_buffer, &data, &length), napi_ok); + return static_cast(data); +} + +void ExpectNothingPending(napi_env env, const char* what) { + bool pending = true; + ASSERT_EQ(napi_is_exception_pending(env, &pending), napi_ok); + EXPECT_FALSE(pending) << what; + napi_value exception = nullptr; + if (pending) napi_get_and_clear_last_exception(env, &exception); +} + +struct ViewLayout { + napi_status status = napi_generic_failure; + size_t length = 99; // elements for a typed array, bytes for a DataView + size_t offset = 99; + void* data = nullptr; + napi_value buffer = nullptr; +}; + +ViewLayout TypedArrayLayout(napi_env env, napi_value view) { + ViewLayout out; + out.status = napi_get_typedarray_info(env, view, nullptr, &out.length, &out.data, &out.buffer, + &out.offset); + return out; +} + +ViewLayout DataViewLayout(napi_env env, napi_value view) { + ViewLayout out; + out.status = napi_get_dataview_info(env, view, &out.length, &out.data, &out.buffer, &out.offset); + return out; +} + +ViewLayout BufferLayout(napi_env env, napi_value view) { + ViewLayout out; + out.status = napi_get_buffer_info(env, view, &out.data, &out.length); + return out; +} + +// A script redefines, on views and on the prototypes they inherit from, every +// property that tells a view's layout, as getters that count their calls. The +// layout N-API reports still is the view's own, and no getter runs. +void ExpectLayoutFromTheViewsSlots(napi_env env, const char* where) { + SCOPED_TRACE(where); + napi_value backing = RunBufferScript(env, "new ArrayBuffer(32)"); + ASSERT_NE(backing, nullptr); + SetGlobal(env, "backing", backing); + napi_value buffer = nullptr; + ASSERT_EQ(node_api_create_buffer_from_arraybuffer(env, backing, 12, 8, &buffer), napi_ok); + SetGlobal(env, "buf", buffer); + RunBufferScript(env, + "globalThis.calls = 0;" + "globalThis.typed = new Uint16Array(backing, 4, 6);" + "globalThis.view = new DataView(backing, 2, 8);" + "globalThis.ownTyped = new Uint16Array(backing, 8, 4);" + "globalThis.ownView = new DataView(backing, 6, 4);" + "globalThis.other = new ArrayBuffer(4);" + "{" + " const lie = (name) => ({ configurable: true," + " get() { calls++; return name === 'buffer' ? other : 1 << 30; } });" + " const names = ['length', 'byteLength', 'byteOffset', 'buffer'];" + " for (const target of [ownTyped, ownView, buf])" + " for (const name of names) Object.defineProperty(target, name, lie(name));" + " const typedArrayPrototype = Object.getPrototypeOf(Uint8Array.prototype);" + " for (const target of [typedArrayPrototype, DataView.prototype])" + " for (const name of names) Object.defineProperty(target, name, lie(name));" + "}" + "0"); + uint8_t* base = ArrayBufferData(env, backing); + auto expect_layout = [&](const ViewLayout& layout, size_t length, size_t offset, + const char* what) { + EXPECT_EQ(layout.status, napi_ok) << what; + EXPECT_EQ(layout.length, length) << what; + EXPECT_EQ(layout.data, base + offset) << what; + if (layout.offset != 99) { + EXPECT_EQ(layout.offset, offset) << what; + } + if (layout.buffer != nullptr) { + bool same = false; + ASSERT_EQ(napi_strict_equals(env, layout.buffer, backing, &same), napi_ok); + EXPECT_TRUE(same) << what << ": its own ArrayBuffer"; + } + ExpectNothingPending(env, what); + }; + expect_layout(TypedArrayLayout(env, NamedGlobal(env, "typed")), 6, 4, "typed array"); + expect_layout(TypedArrayLayout(env, NamedGlobal(env, "ownTyped")), 4, 8, "own typed array"); + expect_layout(TypedArrayLayout(env, buffer), 8, 12, "buffer as a typed array"); + expect_layout(BufferLayout(env, buffer), 8, 12, "buffer"); + expect_layout(DataViewLayout(env, NamedGlobal(env, "view")), 8, 2, "data view"); + expect_layout(DataViewLayout(env, NamedGlobal(env, "ownView")), 4, 6, "own data view"); + + EXPECT_EQ(GlobalInt(env, "calls"), 0) << "a getter the script defined ran"; +} + +} // namespace + +// A typed array's, DataView's or Buffer's length, offset and ArrayBuffer are +// the ones in its internal slots. Page scripts control their realm's +// prototypes and can redefine those properties on any view: a length or +// offset read from them would let a script make native code read or write +// out of bounds. +TEST_F(Test33TypedArray, ViewLayoutComesFromItsSlotsInAnyRealm) { + EnvScope s(runtime_.get()); + ExpectLayoutFromTheViewsSlots(s.env, "the env's realm"); + + unofficial_napi_realm_options options; + unofficial_napi_realm_options_init(&options); + unofficial_napi_realm realm = nullptr; + ASSERT_EQ(unofficial_napi_create_realm(s.env, &options, &realm, nullptr), napi_ok); + unofficial_napi_realm_scope scope = 0; + ASSERT_EQ(unofficial_napi_enter_realm(s.env, realm, &scope), napi_ok); + ExpectLayoutFromTheViewsSlots(s.env, "a realm the env entered"); + ASSERT_EQ(unofficial_napi_leave_realm(s.env, scope), napi_ok); +} + +// As in Node, a view over a resizable ArrayBuffer follows the buffer's size: a +// length-tracking view reports what of the buffer is past its offset now, and +// a fixed-length view the buffer shrank under reports a length of 0 (and +// reports its length again once the buffer grows back), with no exception. +// Such an out-of-bounds view's offset is left unchecked: V8 reports the view's +// own, QuickJS 0, as it has no way to read it (its accessors report 0 or +// throw). +TEST_F(Test33TypedArray, ViewsOfAResizedBufferReportItsCurrentSize) { + EnvScope s(runtime_.get()); + RunBufferScript(s.env, + "globalThis.rab = new ArrayBuffer(16, { maxByteLength: 32 });" + "globalThis.tracking = new Uint8Array(rab, 4);" + "globalThis.fixed = new Uint16Array(rab, 4, 4);" + "globalThis.trackingView = new DataView(rab, 2);" + "globalThis.fixedView = new DataView(rab, 2, 8);" + "0"); + napi_value rab = NamedGlobal(s.env, "rab"); + napi_value buffer = nullptr; + ASSERT_EQ(node_api_create_buffer_from_arraybuffer(s.env, rab, 4, 8, &buffer), napi_ok); + napi_value tracking = NamedGlobal(s.env, "tracking"); + napi_value fixed = NamedGlobal(s.env, "fixed"); + napi_value tracking_view = NamedGlobal(s.env, "trackingView"); + napi_value fixed_view = NamedGlobal(s.env, "fixedView"); + + auto expect_layout = [&](const ViewLayout& layout, size_t length, const char* what) { + EXPECT_EQ(layout.status, napi_ok) << what; + EXPECT_EQ(layout.length, length) << what; + if (layout.buffer != nullptr) { + bool same = false; + ASSERT_EQ(napi_strict_equals(s.env, layout.buffer, rab, &same), napi_ok); + EXPECT_TRUE(same) << what << ": its own ArrayBuffer"; + } + ExpectNothingPending(s.env, what); + }; + // In bounds, also the data and offset. + auto expect_in_bounds = [&](const ViewLayout& layout, size_t length, size_t offset, + const char* what) { + expect_layout(layout, length, what); + EXPECT_EQ(layout.data, ArrayBufferData(s.env, rab) + offset) << what; + if (layout.offset != 99) { + EXPECT_EQ(layout.offset, offset) << what; + } + }; + + RunBufferScript(s.env, "rab.resize(8); 0"); + expect_in_bounds(TypedArrayLayout(s.env, tracking), 4, 4, "shrunk: tracking typed array"); + expect_layout(TypedArrayLayout(s.env, fixed), 0, "shrunk: fixed typed array"); + expect_layout(TypedArrayLayout(s.env, buffer), 0, "shrunk: buffer as a typed array"); + expect_layout(BufferLayout(s.env, buffer), 0, "shrunk: buffer"); + expect_in_bounds(DataViewLayout(s.env, tracking_view), 6, 2, "shrunk: tracking data view"); + expect_layout(DataViewLayout(s.env, fixed_view), 0, "shrunk: fixed data view"); + bool is_buffer = false; + EXPECT_EQ(napi_is_buffer(s.env, buffer, &is_buffer), napi_ok); + EXPECT_TRUE(is_buffer) << "a Buffer out of bounds is still a Buffer"; + + RunBufferScript(s.env, "rab.resize(24); 0"); + expect_in_bounds(TypedArrayLayout(s.env, tracking), 20, 4, "grown: tracking typed array"); + expect_in_bounds(TypedArrayLayout(s.env, fixed), 4, 4, "grown: fixed typed array"); + expect_in_bounds(TypedArrayLayout(s.env, buffer), 8, 4, "grown: buffer as a typed array"); + expect_in_bounds(BufferLayout(s.env, buffer), 8, 4, "grown: buffer"); + expect_in_bounds(DataViewLayout(s.env, tracking_view), 22, 2, "grown: tracking data view"); + expect_in_bounds(DataViewLayout(s.env, fixed_view), 8, 2, "grown: fixed data view"); +} + +// A termination request leaves a view's layout as it is (QuickJS polls its +// interrupt handler, now and then, on the calls that read it). +TEST_F(Test33TypedArray, ViewLayoutHoldsWhileTerminating) { + EnvScope s(runtime_.get()); + RunBufferScript(s.env, + "globalThis.typed = new Uint16Array(new ArrayBuffer(32), 4, 6);" + "globalThis.view = new DataView(new ArrayBuffer(32), 2, 8);" + "0"); + napi_value typed = NamedGlobal(s.env, "typed"); + napi_value view = NamedGlobal(s.env, "view"); + ASSERT_EQ(unofficial_napi_terminate_execution(s.env), napi_ok); + int wrong = 0; + for (int i = 0; i < 20000; ++i) { + napi_handle_scope scope = nullptr; + ASSERT_EQ(napi_open_handle_scope(s.env, &scope), napi_ok); + const ViewLayout typed_layout = TypedArrayLayout(s.env, typed); + const ViewLayout view_layout = DataViewLayout(s.env, view); + if (typed_layout.status != napi_ok || typed_layout.length != 6 || typed_layout.offset != 4 || + view_layout.status != napi_ok || view_layout.length != 8 || view_layout.offset != 2) { + ++wrong; + } + ASSERT_EQ(napi_close_handle_scope(s.env, scope), napi_ok); + } + EXPECT_EQ(wrong, 0); + ASSERT_EQ(unofficial_napi_cancel_terminate_execution(s.env), napi_ok); +} + #if defined(NAPI_TEST_ENGINE_QUICKJS) TEST_F(Test33TypedArray, ExternalArrayBufferResizeFailurePreservesBackingStore) { ExternalBufferState state; From a23b155890923950947b055750a26ecc6a3c799b Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 18:36:43 -0800 Subject: [PATCH 080/150] QuickJS: keep the pending exception in napi_is_detached_arraybuffer For a detached ArrayBuffer, napi_is_detached_arraybuffer let JS_GetArrayBuffer throw its TypeError into the engine and then cleared the env's pending exception instead of that TypeError. An exception that native code had pending before the call was lost (napi_get_and_clear_last_exception then failed with napi_generic_failure), and the TypeError stayed in the engine, where napi_is_exception_pending reported it after a call made with nothing pending. For anything that is not an ArrayBuffer it read the value's byteLength property, running whatever getter a script put there, and said a value with one, such as any typed array or DataView, was a detached ArrayBuffer. It now returns napi_arraybuffer_expected for those without reading anything, as the V8 provider does. It now asks napi_util__::is_detached_array_buffer, which leaves an earlier exception as it was and adds none. Tests, on both engines: napi_is_detached_arraybuffer, napi_get_arraybuffer_info and the typed array, Buffer and DataView info calls over a detached or out-of-bounds buffer leave nothing pending when nothing was, and leave exactly the earlier exception pending when one was; napi_is_detached_arraybuffer on a typed array or DataView with byteLength redefined returns napi_arraybuffer_expected and runs no getter, in the env's realm and in an entered one. Co-Authored-By: Claude Opus 5.5 --- quickjs/src/js_native_api_quickjs.cc | 36 ++----------- tests/runners/test_33_typedarray.cc | 80 ++++++++++++++++++++++++++++ 2 files changed, 84 insertions(+), 32 deletions(-) diff --git a/quickjs/src/js_native_api_quickjs.cc b/quickjs/src/js_native_api_quickjs.cc index c644962eab..f52a08fcdc 100644 --- a/quickjs/src/js_native_api_quickjs.cc +++ b/quickjs/src/js_native_api_quickjs.cc @@ -611,41 +611,13 @@ extern "C" return napi_ok; } + // Anything else is not an ArrayBuffer, whatever its byteLength property + // says (a script can define one on any object). if (!JS_IsArrayBuffer(local)) - { - if (JS_IsObject(local)) - { - JSValue byte_len = JS_GetPropertyStr(env->context(), local, "byteLength"); - if (JS_IsException(byte_len)) - { - JSValue exc = JS_GetException(env->context()); - JS_FreeValue(env->context(), exc); - } - else if (!JS_IsUndefined(byte_len)) - { - JS_FreeValue(env->context(), byte_len); - *result = true; - return napi_ok; - } - else - { - JS_FreeValue(env->context(), byte_len); - } - } return napi_arraybuffer_expected; - } - - size_t ab_len = 0; - uint8_t *data = JS_GetArrayBuffer(env->context(), &ab_len, local); - if (data == nullptr && JS_HasException(env->context())) - { - napi_util__::clear_last_exception(env); - *result = true; - return napi_ok; - } - - *result = false; + // Leaves an exception that was pending as it was, and adds none. + *result = napi_util__::is_detached_array_buffer(env->context(), local); return napi_ok; } diff --git a/tests/runners/test_33_typedarray.cc b/tests/runners/test_33_typedarray.cc index 148d681fb9..4ad675f973 100644 --- a/tests/runners/test_33_typedarray.cc +++ b/tests/runners/test_33_typedarray.cc @@ -7,6 +7,8 @@ #include "upstream_js_test.h" #include +#include +#include extern "C" napi_value Init(napi_env env, napi_value exports); // node_api.h declares it from NAPI_VERSION 10; this target builds at 8. @@ -495,6 +497,13 @@ void ExpectLayoutFromTheViewsSlots(napi_env env, const char* where) { expect_layout(DataViewLayout(env, NamedGlobal(env, "view")), 8, 2, "data view"); expect_layout(DataViewLayout(env, NamedGlobal(env, "ownView")), 4, 6, "own data view"); + // A view is not an ArrayBuffer, whatever its byteLength says. + bool detached = true; + EXPECT_EQ(napi_is_detached_arraybuffer(env, NamedGlobal(env, "typed"), &detached), + napi_arraybuffer_expected); + EXPECT_EQ(napi_is_detached_arraybuffer(env, NamedGlobal(env, "ownView"), &detached), + napi_arraybuffer_expected); + ExpectNothingPending(env, "napi_is_detached_arraybuffer"); EXPECT_EQ(GlobalInt(env, "calls"), 0) << "a getter the script defined ran"; } @@ -610,6 +619,77 @@ TEST_F(Test33TypedArray, ViewLayoutHoldsWhileTerminating) { ASSERT_EQ(unofficial_napi_cancel_terminate_execution(s.env), napi_ok); } +// napi_is_detached_arraybuffer, like the other info calls over a detached or +// out-of-bounds buffer, leaves an exception that was pending as it was and +// adds none. +TEST_F(Test33TypedArray, InfoCallsKeepThePendingException) { + EnvScope s(runtime_.get()); + RunBufferScript(s.env, + "globalThis.detached = new ArrayBuffer(8);" + "globalThis.overDetached = new Uint8Array(detached, 2, 4);" + "globalThis.viewOverDetached = new DataView(detached, 2, 4);" + "globalThis.rab = new ArrayBuffer(16, { maxByteLength: 16 });" + "globalThis.outOfBounds = new Uint8Array(rab, 4, 8);" + "globalThis.viewOutOfBounds = new DataView(rab, 4, 8);" + "rab.resize(4);" + "0"); + napi_value detached = NamedGlobal(s.env, "detached"); + napi_value buffer = nullptr; + ASSERT_EQ(node_api_create_buffer_from_arraybuffer(s.env, detached, 0, 8, &buffer), napi_ok); + ASSERT_EQ(napi_detach_arraybuffer(s.env, detached), napi_ok); + napi_value over_detached = NamedGlobal(s.env, "overDetached"); + napi_value view_over_detached = NamedGlobal(s.env, "viewOverDetached"); + napi_value out_of_bounds = NamedGlobal(s.env, "outOfBounds"); + napi_value view_out_of_bounds = NamedGlobal(s.env, "viewOutOfBounds"); + + bool is_detached = false; + void* data = nullptr; + size_t length = 99; + const std::pair> calls[] = { + {"napi_is_detached_arraybuffer", + [&] { + is_detached = false; + napi_status status = napi_is_detached_arraybuffer(s.env, detached, &is_detached); + EXPECT_TRUE(is_detached); + return status; + }}, + {"napi_get_arraybuffer_info", + [&] { return napi_get_arraybuffer_info(s.env, detached, &data, &length); }}, + {"typed array over a detached buffer", + [&] { return TypedArrayLayout(s.env, over_detached).status; }}, + {"typed array out of bounds", [&] { return TypedArrayLayout(s.env, out_of_bounds).status; }}, + {"buffer over a detached buffer, as a typed array", + [&] { return TypedArrayLayout(s.env, buffer).status; }}, + {"buffer over a detached buffer", [&] { return BufferLayout(s.env, buffer).status; }}, + {"data view over a detached buffer", + [&] { return DataViewLayout(s.env, view_over_detached).status; }}, + {"data view out of bounds", + [&] { return DataViewLayout(s.env, view_out_of_bounds).status; }}, + }; + for (const auto& [what, call] : calls) { + SCOPED_TRACE(what); + // With nothing pending, nothing is pending afterwards. + EXPECT_EQ(call(), napi_ok); + ExpectNothingPending(s.env, "with nothing pending before"); + + // With an exception pending, it is the one pending afterwards. + napi_throw_error(s.env, nullptr, "earlier"); + EXPECT_EQ(call(), napi_ok); + napi_value exception = nullptr; + EXPECT_EQ(napi_get_and_clear_last_exception(s.env, &exception), napi_ok) + << "the earlier exception is no longer pending"; + char text[64] = {}; + size_t text_length = 0; + napi_value message = nullptr; + if (exception != nullptr && + napi_get_named_property(s.env, exception, "message", &message) == napi_ok) { + napi_get_value_string_utf8(s.env, message, text, sizeof(text), &text_length); + } + EXPECT_STREQ(text, "earlier"); + ExpectNothingPending(s.env, "after the earlier exception was taken"); + } +} + #if defined(NAPI_TEST_ENGINE_QUICKJS) TEST_F(Test33TypedArray, ExternalArrayBufferResizeFailurePreservesBackingStore) { ExternalBufferState state; From 57d17eb701a5aa4cdeea46599ab16ec75ab0cb65 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 18:37:05 -0800 Subject: [PATCH 081/150] V8: return the serdes binding from outside its handle scope unofficial_napi_create_serdes_binding made the binding object inside a v8::HandleScope and returned its handle after that scope had closed. The next handles the caller made took the slot, so the napi_value no longer was the binding: after napi_get_global and napi_set_named_property, a script saw `typeof serdes.Serializer` as "undefined" and `new serdes.Serializer()` threw "not a constructor". The scope is now an EscapableHandleScope, and the binding escapes into the caller's scope. Found by the QuickJS serdes test of the next commit, which runs on both engines. Test: the binding set on the global still has its Serializer and Deserializer functions for a script. Co-Authored-By: Claude Opus 5.5 --- tests/runners/test_33_typedarray.cc | 15 +++++++++++++++ v8/src/unofficial_napi.cc | 6 ++++-- 2 files changed, 19 insertions(+), 2 deletions(-) diff --git a/tests/runners/test_33_typedarray.cc b/tests/runners/test_33_typedarray.cc index 4ad675f973..fee80520b4 100644 --- a/tests/runners/test_33_typedarray.cc +++ b/tests/runners/test_33_typedarray.cc @@ -619,6 +619,21 @@ TEST_F(Test33TypedArray, ViewLayoutHoldsWhileTerminating) { ASSERT_EQ(unofficial_napi_cancel_terminate_execution(s.env), napi_ok); } +// The serdes binding unofficial_napi_create_serdes_binding returns is still +// the binding while the caller makes more values. +TEST_F(Test33TypedArray, SerdesBindingOutlivesTheCallThatMadeIt) { + EnvScope s(runtime_.get()); + napi_value serdes = nullptr; + ASSERT_EQ(unofficial_napi_create_serdes_binding(s.env, &serdes), napi_ok); + SetGlobal(s.env, "serdes", serdes); + napi_value kinds = + RunBufferScript(s.env, "typeof serdes.Serializer + ' ' + typeof serdes.Deserializer"); + char text[64] = {}; + size_t length = 0; + ASSERT_EQ(napi_get_value_string_utf8(s.env, kinds, text, sizeof(text), &length), napi_ok); + EXPECT_STREQ(text, "function function"); +} + // napi_is_detached_arraybuffer, like the other info calls over a detached or // out-of-bounds buffer, leaves an exception that was pending as it was and // adds none. diff --git a/v8/src/unofficial_napi.cc b/v8/src/unofficial_napi.cc index 2a712ac7b3..69a5649470 100644 --- a/v8/src/unofficial_napi.cc +++ b/v8/src/unofficial_napi.cc @@ -2871,7 +2871,9 @@ napi_status NAPI_CDECL unofficial_napi_create_serdes_binding(napi_env env, if (env == nullptr || env->isolate == nullptr || result_out == nullptr) return napi_invalid_arg; v8::Isolate* isolate = env->isolate; - v8::HandleScope handle_scope(isolate); + // The binding is returned past this scope: escaped, it lives in the + // caller's. + v8::EscapableHandleScope handle_scope(isolate); v8::Local context = env->context(); v8::Context::Scope context_scope(context); @@ -2919,7 +2921,7 @@ napi_status NAPI_CDECL unofficial_napi_create_serdes_binding(napi_env env, return napi_generic_failure; } - *result_out = napi_v8_wrap_value(env, target); + *result_out = napi_v8_wrap_value(env, handle_scope.Escape(target)); return (*result_out == nullptr) ? napi_generic_failure : napi_ok; } From 8f988514d750d4e4847f7c3a19f5f6da47300e20 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 18:37:38 -0800 Subject: [PATCH 082/150] QuickJS: copy a view's own bytes in the serdes binding The serdes binding's Serializer.writeRawBytes and the Deserializer constructor read a DataView's buffer, byteOffset and byteLength through its properties, which a page script can redefine on DataView.prototype: the bytes written came from whatever buffer and range the script named (the range was checked against that buffer, so they stayed in bounds of it). A length-tracking typed array was copied with the length it had when it was made: one over a resizable buffer that grew from 4 to 8 bytes, at offset 1, gave 3 bytes instead of 7. A view over a detached buffer failed with a TypeError left in the engine. Both now copy what napi_env__::view_layout reports: the view's own buffer and range, read through the intrinsic getters. A view over a detached or out-of-bounds buffer gives no bytes, as with V8. Test, on both engines: with DataView.prototype's buffer, byteOffset and byteLength redefined as counting getters, writeRawBytes of a DataView and of a grown length-tracking Uint8Array writes their own bytes, and no getter runs. Co-Authored-By: Claude Opus 5.5 --- quickjs/src/internal/napi_serdes.cc | 52 ++++------------------------- tests/runners/test_33_typedarray.cc | 39 ++++++++++++++++++++++ 2 files changed, 46 insertions(+), 45 deletions(-) diff --git a/quickjs/src/internal/napi_serdes.cc b/quickjs/src/internal/napi_serdes.cc index d9cb1cb965..2cf28c6544 100644 --- a/quickjs/src/internal/napi_serdes.cc +++ b/quickjs/src/internal/napi_serdes.cc @@ -1,5 +1,6 @@ #include "internal/napi_serdes.h" +#include "internal/napi_env.h" #include "internal/napi_shared_array_buffer.h" #include "internal/napi_util.h" #include "internal/napi_value.h" @@ -60,54 +61,15 @@ namespace quickjs::detail return true; } - if (JS_GetTypedArrayType(input) >= 0) + // A view's own bytes, never what its properties say. + napi_view_layout__ layout; + if (env->view_layout(input, &layout)) { - size_t offset = 0; - JSValue array_buffer = JS_GetTypedArrayBuffer(ctx, input, &offset, &length, nullptr); - if (JS_IsException(array_buffer)) - return false; - size_t array_buffer_length = 0; - data = JS_GetArrayBuffer(ctx, &array_buffer_length, array_buffer); - JS_FreeValue(ctx, array_buffer); - if (data == nullptr && JS_HasException(ctx)) - return false; - if (offset > array_buffer_length || length > array_buffer_length - offset) - return false; - if (length == 0) - bytes_out->clear(); - else - bytes_out->assign(data + offset, data + offset + length); - return true; - } - - if (JS_IsDataView(input)) - { - JSValue buffer = JS_GetPropertyStr(ctx, input, "buffer"); - JSValue byte_offset = JS_GetPropertyStr(ctx, input, "byteOffset"); - JSValue byte_length = JS_GetPropertyStr(ctx, input, "byteLength"); - uint32_t offset = 0; - uint32_t view_length = 0; - bool ok = !JS_IsException(buffer) && - JS_ToUint32(ctx, &offset, byte_offset) == 0 && - JS_ToUint32(ctx, &view_length, byte_length) == 0; - JS_FreeValue(ctx, byte_offset); - JS_FreeValue(ctx, byte_length); - if (!ok) - { - JS_FreeValue(ctx, buffer); - return false; - } - size_t array_buffer_length = 0; - data = JS_GetArrayBuffer(ctx, &array_buffer_length, buffer); - JS_FreeValue(ctx, buffer); - if (data == nullptr && JS_HasException(ctx)) - return false; - if (offset > array_buffer_length || view_length > array_buffer_length - offset) - return false; - if (view_length == 0) + JS_FreeValue(ctx, layout.buffer); + if (layout.byte_length == 0) bytes_out->clear(); else - bytes_out->assign(data + offset, data + offset + view_length); + bytes_out->assign(layout.data, layout.data + layout.byte_length); return true; } diff --git a/tests/runners/test_33_typedarray.cc b/tests/runners/test_33_typedarray.cc index fee80520b4..7624302f42 100644 --- a/tests/runners/test_33_typedarray.cc +++ b/tests/runners/test_33_typedarray.cc @@ -9,6 +9,7 @@ #include #include #include +#include extern "C" napi_value Init(napi_env env, napi_value exports); // node_api.h declares it from NAPI_VERSION 10; this target builds at 8. @@ -634,6 +635,44 @@ TEST_F(Test33TypedArray, SerdesBindingOutlivesTheCallThatMadeIt) { EXPECT_STREQ(text, "function function"); } +// The serdes binding's Serializer copies a view's own bytes: neither what a +// script redefined on DataView.prototype nor a length-tracking view's length +// from before its buffer grew. +TEST_F(Test33TypedArray, SerializerWritesAViewsOwnBytes) { + EnvScope s(runtime_.get()); + napi_value serdes = nullptr; + ASSERT_EQ(unofficial_napi_create_serdes_binding(s.env, &serdes), napi_ok); + SetGlobal(s.env, "serdes", serdes); + napi_value released = RunBufferScript( + s.env, + "(() => {" + " globalThis.calls = 0;" + " const backing = new ArrayBuffer(16);" + " new Uint8Array(backing).forEach((_, i, a) => { a[i] = i; });" + " const view = new DataView(backing, 2, 4);" + " const rab = new ArrayBuffer(4, { maxByteLength: 16 });" + " const tracking = new Uint8Array(rab, 1);" + " rab.resize(8);" + " new Uint8Array(rab).forEach((_, i, a) => { a[i] = 100 + i; });" + " const other = new ArrayBuffer(64);" + " for (const name of ['byteLength', 'byteOffset', 'buffer'])" + " Object.defineProperty(DataView.prototype, name, { configurable: true," + " get() { calls++; return name === 'buffer' ? other : 1; } });" + " const serializer = new serdes.Serializer();" + " serializer.writeRawBytes(view);" + " serializer.writeRawBytes(tracking);" + " return serializer.releaseBuffer();" + "})()"); + ASSERT_NE(released, nullptr); + void* data = nullptr; + size_t length = 0; + ASSERT_EQ(napi_get_buffer_info(s.env, released, &data, &length), napi_ok); + const std::vector expected = {2, 3, 4, 5, 101, 102, 103, 104, 105, 106, 107}; + const auto* bytes = static_cast(data); + EXPECT_EQ(std::vector(bytes, bytes + length), expected); + EXPECT_EQ(GlobalInt(s.env, "calls"), 0) << "a getter the script defined ran"; +} + // napi_is_detached_arraybuffer, like the other info calls over a detached or // out-of-bounds buffer, leaves an exception that was pending as it was and // adds none. From 9653cb27e30ece546f6c38d477f6c9b424e34340 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 18:45:33 -0800 Subject: [PATCH 083/150] QuickJS: read a view's data after the getters that can run script Found by the Codex review of these commits. The napi_env__::view_layout of "QuickJS: read a view's length and offset from its slots" read the buffer's data pointer and size before calling the byteOffset and byteLength getters. The getters run no script, but an error thrown in them does: QuickJS gives every error its stack through Error.prepareStackTrace, a getter a script can define. That happens for a DataView out of bounds, and for the interrupt error QuickJS throws on its periodic poll during a termination request. A script that resized the buffer there moved its bytes, and the info call handed native code the freed old pointer with a nonzero length, checked against the old size. With such a getter flipping a resizable buffer between 16 bytes and 1 MiB, 3 of 20000 napi_get_typedarray_info calls during a termination request returned the freed pointer. The data pointer and size are now read last, with JS_GetArrayBuffer, which runs no script when it succeeds; when it throws, the buffer is detached for good and the view has no bytes. The offset and length the getters reported are checked against that size. Test, on both engines: with that getter in place, 20000 typed array info calls during a termination request each report the buffer's current data. On QuickJS the test also checks that the getter ran; V8 runs no script to read a view. Co-Authored-By: Claude Opus 5.5 --- quickjs/src/internal/napi_env.cc | 43 +++++++++++++++------------ quickjs/src/internal/napi_env.h | 11 +++---- tests/runners/test_33_typedarray.cc | 45 +++++++++++++++++++++++++++++ 3 files changed, 75 insertions(+), 24 deletions(-) diff --git a/quickjs/src/internal/napi_env.cc b/quickjs/src/internal/napi_env.cc index 13021e0ba6..2868c25547 100644 --- a/quickjs/src/internal/napi_env.cc +++ b/quickjs/src/internal/napi_env.cc @@ -431,24 +431,33 @@ bool napi_env__::view_layout(JSValueConst view, napi_view_layout__ *layout) cons JSValue earlier = JS_GetException(context_); *layout = {}; layout->buffer = call_view_getter(context_, getters->buffer, view); - bool found = JS_IsObject(layout->buffer); - size_t buffer_length = 0; - // JS_GetArrayBuffer throws for a detached buffer only. + const bool found = JS_IsObject(layout->buffer); if (found) - layout->data = JS_GetArrayBuffer(context_, &buffer_length, layout->buffer); - if (layout->data == nullptr && JS_HasException(context_)) - JS_FreeValue(context_, JS_GetException(context_)); - if (layout->data != nullptr) { - // The typed array getters report 0 for a view out of bounds; the DataView - // ones throw. + // The typed array getters report 0 for a view over a detached buffer or + // out of bounds; the DataView ones throw. A thrown error (also an + // interrupt's) gets its stack through Error.prepareStackTrace, which can + // run script that resizes, transfers or detaches the buffer. So the + // buffer's data and size are read last: JS_GetArrayBuffer runs no script + // when it succeeds, and when it throws the buffer is detached for good. JSValue offset_value = call_view_getter(context_, getters->byte_offset, view); JSValue length_value = call_view_getter(context_, getters->byte_length, view); - int64_t offset = 0; - int64_t length = 0; - if (!JS_IsException(offset_value) && !JS_IsException(length_value) && - JS_ToInt64(context_, &offset, offset_value) == 0 && - JS_ToInt64(context_, &length, length_value) == 0 && offset >= 0 && length >= 0 && + int64_t offset = -1; + int64_t length = -1; + if (JS_IsException(offset_value) || JS_ToInt64(context_, &offset, offset_value) != 0) + offset = -1; + if (JS_IsException(length_value) || JS_ToInt64(context_, &length, length_value) != 0) + length = -1; + JS_FreeValue(context_, offset_value); + JS_FreeValue(context_, length_value); + if (JS_HasException(context_)) + JS_FreeValue(context_, JS_GetException(context_)); + size_t buffer_length = 0; + // Throws for a detached buffer only. + layout->data = JS_GetArrayBuffer(context_, &buffer_length, layout->buffer); + if (layout->data == nullptr && JS_HasException(context_)) + JS_FreeValue(context_, JS_GetException(context_)); + if (layout->data != nullptr && offset >= 0 && length >= 0 && static_cast(offset) <= buffer_length && static_cast(length) <= buffer_length - static_cast(offset)) { @@ -456,12 +465,8 @@ bool napi_env__::view_layout(JSValueConst view, napi_view_layout__ *layout) cons layout->byte_length = static_cast(length); layout->data += layout->byte_offset; } - JS_FreeValue(context_, offset_value); - JS_FreeValue(context_, length_value); - if (JS_HasException(context_)) - JS_FreeValue(context_, JS_GetException(context_)); } - if (!found) + else { JS_FreeValue(context_, layout->buffer); layout->buffer = JS_UNDEFINED; diff --git a/quickjs/src/internal/napi_env.h b/quickjs/src/internal/napi_env.h index cc0c4b1d07..52552d01b1 100644 --- a/quickjs/src/internal/napi_env.h +++ b/quickjs/src/internal/napi_env.h @@ -89,11 +89,12 @@ struct napi_env__ // byte length, read through the intrinsic getters as the env was made, // never through the view's properties, which scripts can redefine on the // view or on its realm's prototypes. These getters read the view's internal - // slots, whatever realm made it, and run no script. A view over a detached - // ArrayBuffer, or out of bounds of a resizable one that shrank, has no - // bytes (as in Node; QuickJS's accessors throw for some of these), and an - // offset of 0. False for anything else. Leaves any pending exception as it - // was. + // slots, whatever realm made it, and run no script themselves (an error one + // throws can, through Error.prepareStackTrace; the data pointer is read + // after them). A view over a detached ArrayBuffer, or out of bounds of a + // resizable one that shrank, has no bytes (as in Node; QuickJS's accessors + // throw for some of these), and an offset of 0. False for anything else. + // Leaves any pending exception as it was. bool view_layout(JSValueConst view, napi_view_layout__ *layout) const; // A function of the current realm that keeps it alive; undefined for the // env's own realm. diff --git a/tests/runners/test_33_typedarray.cc b/tests/runners/test_33_typedarray.cc index 7624302f42..cae866eec7 100644 --- a/tests/runners/test_33_typedarray.cc +++ b/tests/runners/test_33_typedarray.cc @@ -620,6 +620,51 @@ TEST_F(Test33TypedArray, ViewLayoutHoldsWhileTerminating) { ASSERT_EQ(unofficial_napi_cancel_terminate_execution(s.env), napi_ok); } +// Reading a view's layout can run script on QuickJS: the error of an +// interrupt poll (during a termination request) or of a DataView out of +// bounds gets its stack through Error.prepareStackTrace, which a script can +// define as a getter. Here that getter resizes the view's buffer, which moves +// its bytes; the data reported is still where they are now. +TEST_F(Test33TypedArray, ViewDataIsCurrentAfterScriptRunsDuringTheRead) { + EnvScope s(runtime_.get()); + RunBufferScript(s.env, + "globalThis.rab = new ArrayBuffer(16, { maxByteLength: 1 << 20 });" + "globalThis.typed = new Uint8Array(rab, 4, 4);" + "globalThis.resizes = 0;" + "Object.defineProperty(Error, 'prepareStackTrace', { configurable: true," + " get() {" + " resizes++;" + " rab.resize(rab.byteLength === 16 ? 1 << 20 : 16);" + " return undefined;" + " } });" + "0"); + napi_value rab = NamedGlobal(s.env, "rab"); + napi_value typed = NamedGlobal(s.env, "typed"); + ASSERT_EQ(unofficial_napi_terminate_execution(s.env), napi_ok); + int wrong = 0; + unsigned sum = 0; + for (int i = 0; i < 20000; ++i) { + napi_handle_scope scope = nullptr; + ASSERT_EQ(napi_open_handle_scope(s.env, &scope), napi_ok); + const ViewLayout layout = TypedArrayLayout(s.env, typed); + if (layout.status != napi_ok || layout.length != 4 || layout.offset != 4 || + layout.data != ArrayBufferData(s.env, rab) + 4) { + ++wrong; + } else { + // Under ASan, reading stale data would be a use after free. + for (size_t j = 0; j < layout.length; ++j) sum += static_cast(layout.data)[j]; + } + ASSERT_EQ(napi_close_handle_scope(s.env, scope), napi_ok); + } + EXPECT_EQ(wrong, 0); + EXPECT_EQ(sum, 0u); + ASSERT_EQ(unofficial_napi_cancel_terminate_execution(s.env), napi_ok); +#if defined(NAPI_TEST_ENGINE_QUICKJS) + // V8 runs no script to read a view, so only QuickJS gets here at all. + EXPECT_GT(GlobalInt(s.env, "resizes"), 0) << "the getter never ran: nothing was tested"; +#endif +} + // The serdes binding unofficial_napi_create_serdes_binding returns is still // the binding while the caller makes more values. TEST_F(Test33TypedArray, SerdesBindingOutlivesTheCallThatMadeIt) { From 4067980d3c3e662209e99724953133f81875082a Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 18:34:03 -0800 Subject: [PATCH 084/150] V8: let a drain the hook runs after the release find no env The finalizer drains the provider posts to the embedder's enqueue_foreground_task hook (for finalizers the collector queued, and for external buffers freed on another thread) carried the env itself as their data, with no cleanup. The hook may run a task later, on the env's thread, and nothing says before the release: the release waits for the engine's own tasks, but not for these. An embedder that still held a drain and ran it after unofficial_napi_release_env returned, passing the env it was attached to, ran DrainFinalizerQueue on the freed env (V8 ASan: heap-use-after-free, WRITE of size 1, in napi_env__::DrainFinalizerQueue, the env freed by ReleaseEnvScope). A drain now holds a reference to a token the env shares, not the env, and releases it with a cleanup the hook calls as it already must for every task. The token names the env until the end of its release, which clears it after waiting for posts in flight; a drain run later finds no env and does nothing. The hook ABI is unchanged; drains now come with a cleanup. Test: test_66 ADrainRunAfterTheReleaseLeavesTheEnvAlone. A queueing hook keeps the drains posted for a detached external buffer freed on another thread and for a value the collector found dead, releases the engine's tasks and refuses more, as at shutdown; after the release it runs the drains it kept. Before the fix the V8 ASan build reported the use-after-free above; the Release build passed without noticing. Co-Authored-By: Claude Opus 5.5 --- .../test_66_foreground_task_handoff.cc | 62 ++++++++++++++++++- v8/src/internal/napi_v8_env.h | 5 ++ v8/src/js_native_api_v8.cc | 48 +++++++++++--- 3 files changed, 105 insertions(+), 10 deletions(-) diff --git a/tests/runners/test_66_foreground_task_handoff.cc b/tests/runners/test_66_foreground_task_handoff.cc index c72f9ac459..d9e642a438 100644 --- a/tests/runners/test_66_foreground_task_handoff.cc +++ b/tests/runners/test_66_foreground_task_handoff.cc @@ -59,6 +59,8 @@ struct HookedTask { unofficial_napi_foreground_task_callback callback = nullptr; void* data = nullptr; unofficial_napi_foreground_task_cleanup cleanup = nullptr; + // The thread that posted it. + std::thread::id poster; }; enum class HookMode { @@ -122,7 +124,7 @@ napi_status EnqueueHook(void* target, uint64_t /*delay_millis*/) { auto* state = static_cast(target); if (state == nullptr || callback == nullptr) return napi_invalid_arg; - const HookedTask task{callback, data, cleanup}; + const HookedTask task{callback, data, cleanup, std::this_thread::get_id()}; state->enqueued.fetch_add(1); switch (state->mode) { @@ -556,6 +558,64 @@ TEST_F(Test66ForegroundTaskHandoff, EXPECT_EQ(hook.released.load(), hook.enqueued.load()); } +// An embedder whose loop outlives the env may still hold a drain the provider +// posted, and run it after the env is released: the release does not wait for +// the drains it posted, as it does for the engine's tasks. Run then, a drain +// finds the env gone and leaves it alone. +TEST_F(Test66ForegroundTaskHandoff, ADrainRunAfterTheReleaseLeavesTheEnvAlone) { + ExternalFinalizerCounts counts; + HookState hook(HookMode::kQueue); + std::deque kept; + { + HookedEnv env(&hook); + ASSERT_NE(env.env(), nullptr); + ASSERT_TRUE(env.attached()); + // A store freed on another thread: its deleter posts a drain from there. + std::shared_ptr store; + ASSERT_NO_FATAL_FAILURE(MakeDetachedExternalBuffer(env.env(), &counts, &store)); + std::thread dropper([&store] { store.reset(); }); + const std::thread::id dropper_id = dropper.get_id(); + dropper.join(); + // A value the collector finds dead: the drain for its finalizer is posted + // from this thread. + napi_handle_scope handles = nullptr; + ASSERT_EQ(napi_open_handle_scope(env.env(), &handles), napi_ok); + napi_value external = nullptr; + ASSERT_EQ(napi_create_external(env.env(), new uint8_t[1](), CountExternalFinalizer, &counts, + &external), + napi_ok); + ASSERT_EQ(napi_close_handle_scope(env.env(), handles), napi_ok); + ASSERT_EQ(unofficial_napi_collect_garbage(env.env()), napi_ok); + EXPECT_EQ(counts.calls.load(), 0); + + // Keeps the drains (the task posted from the dropper's thread, and those + // with its callback). Releases the engine's tasks and refuses more, as an + // embedder does at shutdown: the release waits for those. + std::deque engine; + { + std::lock_guard lock(hook.mutex); + auto drain = std::find_if(hook.queue.begin(), hook.queue.end(), + [&](const HookedTask& task) { return task.poster == dropper_id; }); + const unofficial_napi_foreground_task_callback drain_callback = + drain != hook.queue.end() ? drain->callback : nullptr; + for (const HookedTask& task : hook.queue) { + (task.callback == drain_callback ? kept : engine).push_back(task); + } + hook.queue.clear(); + } + for (const HookedTask& task : engine) ReleaseTask(&hook, task); + CloseQueue(&hook); + ASSERT_FALSE(kept.empty()) << "the deleter posted no drain"; + env.Release(); + } + // The release ran both finalizers. + EXPECT_EQ(counts.calls.load(), 2); + for (const HookedTask& task : kept) RunTask(&hook, task); + EXPECT_EQ(counts.calls.load(), 2); + EXPECT_EQ(counts.off_thread.load(), 0); + EXPECT_EQ(hook.released.load(), hook.enqueued.load()); +} + struct InstanceDataSignal { ExternalFinalizerCounts* counts = nullptr; std::mutex mutex; diff --git a/v8/src/internal/napi_v8_env.h b/v8/src/internal/napi_v8_env.h index 77f4583e3d..da7ecfa4e7 100644 --- a/v8/src/internal/napi_v8_env.h +++ b/v8/src/internal/napi_v8_env.h @@ -32,6 +32,7 @@ struct napi_callback_payload__; struct napi_deferred__; struct napi_env__; struct napi_env_cleanup_hook__; +struct napi_env_drain_token__; struct napi_escapable_handle_scope__; struct napi_external_backing_store_hint__; struct napi_external_wrapper__; @@ -188,6 +189,10 @@ struct napi_env__ { std::unordered_set pending_finalizers; std::unordered_set pending_buffer_finalizers; bool finalization_scheduled = false; + // What each drain the env posts to the embedder's hook holds instead of the + // env: the hook may keep a drain past the release and run it then. The + // release clears the token's env, so such a drain does nothing. + napi_env_drain_token__* drain_token = nullptr; // External backing-store finalizers their deleters queued for the env's // thread. Deleters run on any thread, so the fields below are guarded by // NapiV8ExternalHintsMutex(); `has_external_finalizers` is also read diff --git a/v8/src/js_native_api_v8.cc b/v8/src/js_native_api_v8.cc index efde99b824..fbfbd49d3a 100644 --- a/v8/src/js_native_api_v8.cc +++ b/v8/src/js_native_api_v8.cc @@ -50,26 +50,51 @@ std::mutex& NapiV8ExternalHintsMutex() { return mutex; } +// Shared by an env and the drains it posts. `env` is the env until its +// release ends, then null; the last reference frees the token. Each drain +// releases its reference with its cleanup, on any thread. +struct napi_env_drain_token__ { + explicit napi_env_drain_token__(napi_env env_in) : env(env_in) {} + + std::atomic env; + std::atomic refs{1}; +}; + namespace { +void ReleaseDrainToken(napi_env /*env*/, void* data) { + auto* token = static_cast(data); + if (token->refs.fetch_sub(1, std::memory_order_acq_rel) == 1) delete token; +} + +// Runs on the env's thread, as its release does, so the env it reads is alive +// or null. void DrainFinalizerQueueForegroundTask(napi_env env, void* data) { - auto* target_env = static_cast(data); + auto* token = static_cast(data); + napi_env target_env = token->env.load(std::memory_order_acquire); if (target_env == nullptr || target_env != env) return; target_env->DrainFinalizerQueue(); } +// Hands the hook a drain of `env`'s finalizer queues, holding the env's token +// rather than the env. The hook owns the task from the call on, whatever it +// returns: its cleanup releases the reference. +napi_status PostFinalizerQueueDrain(napi_env env, + unofficial_napi_enqueue_foreground_task_callback enqueue, + void* target) { + napi_env_drain_token__* token = env->drain_token; + token->refs.fetch_add(1, std::memory_order_relaxed); + return enqueue(target, DrainFinalizerQueueForegroundTask, token, ReleaseDrainToken, 0); +} + void ScheduleFinalizerQueueDrain(napi_env env) { if (env == nullptr || env->finalization_scheduled) return; env->finalization_scheduled = true; napi_agent__* agent = env->agent; if (agent != nullptr && agent->enqueue_foreground_task_callback != nullptr) { - napi_status status = agent->enqueue_foreground_task_callback( - agent->enqueue_foreground_task_target, - DrainFinalizerQueueForegroundTask, - env, - nullptr, - 0); + napi_status status = PostFinalizerQueueDrain( + env, agent->enqueue_foreground_task_callback, agent->enqueue_foreground_task_target); if (status == napi_ok) return; } @@ -271,8 +296,7 @@ bool QueueExternalFinalizer(napi_env env, const napi_external_finalizer__& final void PostExternalFinalizerDrain(napi_env env, unofficial_napi_enqueue_foreground_task_callback enqueue, void* target) { - const bool posted = - enqueue(target, DrainFinalizerQueueForegroundTask, env, nullptr, 0) == napi_ok; + const bool posted = PostFinalizerQueueDrain(env, enqueue, target) == napi_ok; std::lock_guard lock(NapiV8ExternalHintsMutex()); // Refused: another deleter may post, or the next checkpoint drains. if (!posted) env->external_finalizer_drain_posted = false; @@ -972,6 +996,7 @@ napi_env__::napi_env__(v8::Local context, int32_t module_api_versio if (agent->principal_env == nullptr) { agent->principal_env = this; } + drain_token = new napi_env_drain_token__(this); napi_v8_clear_last_error(this); } @@ -1039,6 +1064,11 @@ napi_env__::~napi_env__() { std::unique_lock lock(NapiV8ExternalHintsMutex()); external_drain_posts_done.wait(lock, [this] { return external_drain_posts_in_flight == 0; }); } + // The hook may still hold drains, and run them after the env is gone: they + // find no env in the token. + drain_token->env.store(nullptr, std::memory_order_release); + ReleaseDrainToken(nullptr, drain_token); + drain_token = nullptr; NAPI_V8_LIFETIME_DUMP(this, "napi_env__ teardown end"); } From e2a9232002beb662bade00e6503ab084f009dd5e Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 18:34:19 -0800 Subject: [PATCH 085/150] V8: forget the module loader's state at the end of an env's release The module loader keeps each env's state (module records, the dynamic import hooks, provider promises it tracks) in g_module_wrap_states, keyed by the env's address, and drops it in a cleanup hook it adds with the first module. Lookups make the state again when it is missing, without the hook: a hook that runs after the loader's at release (added earlier, so it runs later) and asks about a module by handle, as unofficial_napi_module_wrap_check_unsettled_top_level_await does (Node checks the entry module's top-level await at exit), made it; a dynamic import then tracked its promise there, with a v8::Global. Nothing dropped the entry. An env made later at the same address found it, and the loader's hook, at that env's release, reset the Global of an isolate already disposed: the V8 Release build aborted with "Check failed: node->IsInUse()" in GlobalHandles::NodeSpace::Release under CleanupModuleWrapState. The ASan build, which does not reuse the address, crashed at exit instead, destroying the map's leftover entries (SEGV in GlobalHandles::NodeSpace::Release). ForgetEnvState, which the end of ~napi_env__ calls once no hook or finalizer is left, now also drops the env's loader state and its hook mark (ForgetModuleWrapState); the records and references there are the env's, which frees them with it. DestroyEnvInstance, which calls it before the release runs its hooks, keeps dropping only the error formatting and prepare-stack-trace state there, so the loader's hook still finds its state. g_error_formatting_states and g_prepare_stack_trace_callbacks were the other maps keyed by an env's address (see "V8: forget an env's error formatting state after its release"); the platform keys its state by isolate. Test: test_65 ModuleStateMadeAtReleaseGoesWithTheEnv, 32 envs in a row, each with a module and a hook, added before it, that at release checks the module's top-level await and imports dynamically. Before the fix both failures above. Co-Authored-By: Claude Opus 5.5 --- .../runners/test_65_unofficial_contextify.cc | 60 +++++++++++++++++++ v8/src/js_native_api_v8.cc | 5 +- v8/src/unofficial_napi.cc | 16 ++++- v8/src/unofficial_napi_contextify.cc | 14 +++++ v8/src/unofficial_napi_error_utils.h | 5 +- 5 files changed, 95 insertions(+), 5 deletions(-) diff --git a/tests/runners/test_65_unofficial_contextify.cc b/tests/runners/test_65_unofficial_contextify.cc index 78ecc2cbdd..2b5291b7dd 100644 --- a/tests/runners/test_65_unofficial_contextify.cc +++ b/tests/runners/test_65_unofficial_contextify.cc @@ -1,5 +1,6 @@ #include "test_env.h" +#include "node_api.h" #include "unofficial_napi.h" class Test65UnofficialContextify : public FixtureTestBase {}; @@ -1058,3 +1059,62 @@ TEST_F(Test65UnofficialContextify, PrepareStackTraceResultIsNotRewritten) { napi_ok); } #endif + +namespace { + +struct LoaderAtRelease { + napi_env env = nullptr; + unofficial_napi_module module = nullptr; +}; + +// A cleanup hook that runs after the module loader has let go of its modules: +// it asks about the entry module's top-level await, as Node does at exit, by +// a handle the loader no longer knows, then imports dynamically. +void UseTheLoaderAtRelease(void* arg) { + auto* loader = static_cast(arg); + bool settled = false; + (void)unofficial_napi_module_wrap_check_unsettled_top_level_await( + loader->env, loader->module, false, &settled); + napi_value ignored = nullptr; + (void)napi_run_script(loader->env, + Str(loader->env, "globalThis.process = {};\n" + "import('gone').catch(() => {});"), + &ignored); +} + +} // namespace + +// What the module loader keeps for an env, made while its release runs (here +// after the loader's own cleanup), goes with the env: envs made later, which +// may reuse its address, start without it. +TEST_F(Test65UnofficialContextify, ModuleStateMadeAtReleaseGoesWithTheEnv) { + for (int i = 0; i < 32; ++i) { + EnvScope s(runtime_.get()); + LoaderAtRelease loader; + loader.env = s.env; + // Added before the module below, so it runs after the loader's cleanup. + ASSERT_EQ(napi_add_env_cleanup_hook(s.env, UseTheLoaderAtRelease, &loader), napi_ok); + + napi_value wrapper = nullptr; + napi_value undefined = nullptr; + ASSERT_EQ(napi_create_object(s.env, &wrapper), napi_ok); + ASSERT_EQ(napi_get_undefined(s.env, &undefined), napi_ok); + const unofficial_napi_js_source source = + unofficial_napi_js_source_from_text(Str(s.env, "export const value = 1;")); + unofficial_napi_module_create_options options{}; + options.size = sizeof(options); + options.version = UNOFFICIAL_NAPI_MODULE_CREATE_OPTIONS_VERSION; + options.kind = unofficial_napi_module_source_text; + options.wrapper = wrapper; + options.url = Str(s.env, "entry.mjs"); + options.payload.source_text.source = &source; + options.payload.source_text.host_defined_option_id = undefined; + unofficial_napi_module_create_result created{}; + ASSERT_EQ(unofficial_napi_module_wrap_create(s.env, &options, &created), napi_ok); + loader.module = created.module; + + ASSERT_EQ(unofficial_napi_release_env(s.scope, nullptr), napi_ok); + s.scope = nullptr; + s.env = nullptr; + } +} diff --git a/v8/src/js_native_api_v8.cc b/v8/src/js_native_api_v8.cc index fbfbd49d3a..e8a972b35e 100644 --- a/v8/src/js_native_api_v8.cc +++ b/v8/src/js_native_api_v8.cc @@ -1050,8 +1050,9 @@ napi_env__::~napi_env__() { PopRealmFrames(0); // The hooks and finalizers above can make state the runtime keeps by the // env's address (napi_get_and_clear_last_exception keeps the error's - // formatting). Left behind, an env made later at the same address would - // find it, and reset handles of an isolate already disposed. + // formatting; a module lookup after the loader's cleanup hook makes the + // loader's state again). Left behind, an env made later at the same address + // would find it, and reset handles of an isolate already disposed. unofficial_napi_internal::ForgetEnvState(this); if (agent != nullptr && agent->principal_env == this) { agent->principal_env = nullptr; diff --git a/v8/src/unofficial_napi.cc b/v8/src/unofficial_napi.cc index 69a5649470..648182126e 100644 --- a/v8/src/unofficial_napi.cc +++ b/v8/src/unofficial_napi.cc @@ -1651,7 +1651,10 @@ void NapiV8ApplyPromiseHooksToContext(napi_env env, v8::Local conte namespace unofficial_napi_internal { -void ForgetEnvState(napi_env env) { +namespace { + +// The env's error formatting and prepare-stack-trace state. +void ForgetErrorFormattingState(napi_env env) { std::lock_guard lock(g_runtime_mu); auto prepare_it = g_prepare_stack_trace_callbacks.find(env); if (prepare_it != g_prepare_stack_trace_callbacks.end()) { @@ -1661,6 +1664,13 @@ void ForgetEnvState(napi_env env) { ResetErrorFormattingState(env); } +} // namespace + +void ForgetEnvState(napi_env env) { + ForgetErrorFormattingState(env); + ForgetModuleWrapState(env); +} + } // namespace unofficial_napi_internal extern "C" { @@ -1764,7 +1774,9 @@ static napi_status DestroyEnvInstance(napi_env env) { g_runtime.platform->ClearForegroundTaskTarget(env->isolate, env); } } - unofficial_napi_internal::ForgetEnvState(env); + // The module loader's state stays for its cleanup hook, which the release + // runs; the release's end drops whatever is left (ForgetEnvState). + unofficial_napi_internal::ForgetErrorFormattingState(env); env->promise_reject_callback.Reset(); for (auto& hook : env->promise_hooks) { hook.Reset(); diff --git a/v8/src/unofficial_napi_contextify.cc b/v8/src/unofficial_napi_contextify.cc index 66cc35d8d7..2245ed5af4 100644 --- a/v8/src/unofficial_napi_contextify.cc +++ b/v8/src/unofficial_napi_contextify.cc @@ -1661,6 +1661,20 @@ bool CompileBytecodeRecord(napi_env env, } // namespace +namespace unofficial_napi_internal { + +// The loader's cleanup hook drops an env's state when the release runs it, but +// a lookup after that (unofficial_napi_module_wrap_check_unsettled_top_level_await, +// a dynamic import) makes it again, without the hook. Its records and +// references are the env's, which frees them with it. +void ForgetModuleWrapState(napi_env env) { + std::lock_guard lock(g_module_wrap_mu); + g_module_wrap_cleanup_hooks.erase(env); + g_module_wrap_states.erase(env); +} + +} // namespace unofficial_napi_internal + bool NapiV8IsContextifyContext(napi_env env, v8::Local context) { unofficial_napi_realm realm = RealmForContext(context); return realm != nullptr && realm->env == env; diff --git a/v8/src/unofficial_napi_error_utils.h b/v8/src/unofficial_napi_error_utils.h index 9628abbf6d..ebbd8732d1 100644 --- a/v8/src/unofficial_napi_error_utils.h +++ b/v8/src/unofficial_napi_error_utils.h @@ -42,8 +42,11 @@ napi_status GetErrorMetadata(napi_env env, unofficial_napi_error_metadata_mode mode, unofficial_napi_error_metadata* out); void ResetErrorFormattingState(napi_env env); +// Drops the module loader's state for `env` (unofficial_napi_contextify.cc). +void ForgetModuleWrapState(napi_env env); // Drops what the runtime keeps for `env` outside it, keyed by its address: -// its error formatting and prepare-stack-trace state. Takes the runtime lock. +// its error formatting, prepare-stack-trace and module loader state. The end +// of the env's release calls it, once no hook or finalizer is left to run. void ForgetEnvState(napi_env env); } // namespace unofficial_napi_internal From 8f3621e79b59762665dce66357bb2510d6665499 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 19:41:18 -0800 Subject: [PATCH 086/150] QuickJS: keep native code's pending exception from a callback it reaches On QuickJS an N-API call that makes an error formats it through Error.prepareStackTrace, and a page can define that as a getter that calls native code. napi_is_detached_arraybuffer, napi_get_arraybuffer_info and the typed array, Buffer and DataView info calls make one over a detached buffer or a DataView out of bounds, and an addon may make them with an exception pending. The callback the getter reached then started with that exception pending (napi_is_exception_pending said so), and when it returned the trampoline threw it into the getter as the callback's own; making the error dropped it. The info call returned napi_ok with nothing pending: the exception native code had thrown was gone, and its caller went on as if nothing had been thrown. "QuickJS: keep the pending exception in napi_is_detached_arraybuffer" kept the engine's exception across these calls, not the provider's. V8 makes no error for any of them and was not affected. The trampoline now sets aside an exception pending when a callback starts, and makes it the pending one again once the callback's own, if any, has been thrown. It covers every N-API call that can run script this way, not only the info calls. Test: test_33 InfoCallsKeepThePendingExceptionWhenErrorFormattingCallsNativeCode runs InfoCallsKeepThePendingException's calls (now a shared helper) with a prepareStackTrace getter that calls a native function, which checks that nothing is pending when it starts. Before this commit, on QuickJS, 7 of the 8 calls lost the earlier exception (napi_get_and_clear_last_exception then failed with napi_generic_failure: nothing was pending), and the callback found it pending when it started; the eighth, a typed array out of bounds, makes no error. V8 passed. Co-Authored-By: Claude Opus 5.5 --- quickjs/src/internal/napi_function.cc | 31 +++++++++ tests/runners/test_33_typedarray.cc | 90 ++++++++++++++++++++------- 2 files changed, 97 insertions(+), 24 deletions(-) diff --git a/quickjs/src/internal/napi_function.cc b/quickjs/src/internal/napi_function.cc index d011148953..3499399eb8 100644 --- a/quickjs/src/internal/napi_function.cc +++ b/quickjs/src/internal/napi_function.cc @@ -42,6 +42,36 @@ class quickjs_callback_handle_scope__ napi_handle_scope parent_ = nullptr; napi_handle_scope scope_ = nullptr; }; + +// Native code up the stack can have an exception pending when JS calls a +// native callback: an N-API call that makes an error (one over a detached +// buffer, say) formats it through Error.prepareStackTrace, which a page can +// define as a getter that calls native code. That exception is not the +// callback's to see or to throw. It is set aside while the callback runs, and +// is the one pending again once the callback's own has been thrown. +class quickjs_outer_exception_scope__ +{ +public: + explicit quickjs_outer_exception_scope__(napi_env env) : env_{env} + { + if (env_->has_last_exception()) + { + held_ = true; + exception_ = env_->take_last_exception(); + } + } + + ~quickjs_outer_exception_scope__() + { + if (held_) + env_->set_last_exception(exception_); + } + +private: + napi_env env_ = nullptr; + bool held_ = false; + JSValue exception_ = JS_UNDEFINED; +}; } // namespace JSValue napi_function__::create_internal(napi_env env, @@ -111,6 +141,7 @@ JSValue invoke_callback(JSContext *caller_ctx, new_target = this_val; } + quickjs_outer_exception_scope__ outer_exception{env}; auto info = napi_callback_info__{env, effective_this, new_target, argc, argv, user_data}; auto result = cb(env, reinterpret_cast(&info)); diff --git a/tests/runners/test_33_typedarray.cc b/tests/runners/test_33_typedarray.cc index cae866eec7..2cbab3d462 100644 --- a/tests/runners/test_33_typedarray.cc +++ b/tests/runners/test_33_typedarray.cc @@ -718,12 +718,13 @@ TEST_F(Test33TypedArray, SerializerWritesAViewsOwnBytes) { EXPECT_EQ(GlobalInt(s.env, "calls"), 0) << "a getter the script defined ran"; } +namespace { + // napi_is_detached_arraybuffer, like the other info calls over a detached or // out-of-bounds buffer, leaves an exception that was pending as it was and // adds none. -TEST_F(Test33TypedArray, InfoCallsKeepThePendingException) { - EnvScope s(runtime_.get()); - RunBufferScript(s.env, +void ExpectInfoCallsKeepThePendingException(napi_env env) { + RunBufferScript(env, "globalThis.detached = new ArrayBuffer(8);" "globalThis.overDetached = new Uint8Array(detached, 2, 4);" "globalThis.viewOverDetached = new DataView(detached, 2, 4);" @@ -732,14 +733,14 @@ TEST_F(Test33TypedArray, InfoCallsKeepThePendingException) { "globalThis.viewOutOfBounds = new DataView(rab, 4, 8);" "rab.resize(4);" "0"); - napi_value detached = NamedGlobal(s.env, "detached"); + napi_value detached = NamedGlobal(env, "detached"); napi_value buffer = nullptr; - ASSERT_EQ(node_api_create_buffer_from_arraybuffer(s.env, detached, 0, 8, &buffer), napi_ok); - ASSERT_EQ(napi_detach_arraybuffer(s.env, detached), napi_ok); - napi_value over_detached = NamedGlobal(s.env, "overDetached"); - napi_value view_over_detached = NamedGlobal(s.env, "viewOverDetached"); - napi_value out_of_bounds = NamedGlobal(s.env, "outOfBounds"); - napi_value view_out_of_bounds = NamedGlobal(s.env, "viewOutOfBounds"); + ASSERT_EQ(node_api_create_buffer_from_arraybuffer(env, detached, 0, 8, &buffer), napi_ok); + ASSERT_EQ(napi_detach_arraybuffer(env, detached), napi_ok); + napi_value over_detached = NamedGlobal(env, "overDetached"); + napi_value view_over_detached = NamedGlobal(env, "viewOverDetached"); + napi_value out_of_bounds = NamedGlobal(env, "outOfBounds"); + napi_value view_out_of_bounds = NamedGlobal(env, "viewOutOfBounds"); bool is_detached = false; void* data = nullptr; @@ -748,47 +749,88 @@ TEST_F(Test33TypedArray, InfoCallsKeepThePendingException) { {"napi_is_detached_arraybuffer", [&] { is_detached = false; - napi_status status = napi_is_detached_arraybuffer(s.env, detached, &is_detached); + napi_status status = napi_is_detached_arraybuffer(env, detached, &is_detached); EXPECT_TRUE(is_detached); return status; }}, {"napi_get_arraybuffer_info", - [&] { return napi_get_arraybuffer_info(s.env, detached, &data, &length); }}, + [&] { return napi_get_arraybuffer_info(env, detached, &data, &length); }}, {"typed array over a detached buffer", - [&] { return TypedArrayLayout(s.env, over_detached).status; }}, - {"typed array out of bounds", [&] { return TypedArrayLayout(s.env, out_of_bounds).status; }}, + [&] { return TypedArrayLayout(env, over_detached).status; }}, + {"typed array out of bounds", [&] { return TypedArrayLayout(env, out_of_bounds).status; }}, {"buffer over a detached buffer, as a typed array", - [&] { return TypedArrayLayout(s.env, buffer).status; }}, - {"buffer over a detached buffer", [&] { return BufferLayout(s.env, buffer).status; }}, + [&] { return TypedArrayLayout(env, buffer).status; }}, + {"buffer over a detached buffer", [&] { return BufferLayout(env, buffer).status; }}, {"data view over a detached buffer", - [&] { return DataViewLayout(s.env, view_over_detached).status; }}, + [&] { return DataViewLayout(env, view_over_detached).status; }}, {"data view out of bounds", - [&] { return DataViewLayout(s.env, view_out_of_bounds).status; }}, + [&] { return DataViewLayout(env, view_out_of_bounds).status; }}, }; for (const auto& [what, call] : calls) { SCOPED_TRACE(what); // With nothing pending, nothing is pending afterwards. EXPECT_EQ(call(), napi_ok); - ExpectNothingPending(s.env, "with nothing pending before"); + ExpectNothingPending(env, "with nothing pending before"); // With an exception pending, it is the one pending afterwards. - napi_throw_error(s.env, nullptr, "earlier"); + napi_throw_error(env, nullptr, "earlier"); EXPECT_EQ(call(), napi_ok); napi_value exception = nullptr; - EXPECT_EQ(napi_get_and_clear_last_exception(s.env, &exception), napi_ok) + EXPECT_EQ(napi_get_and_clear_last_exception(env, &exception), napi_ok) << "the earlier exception is no longer pending"; char text[64] = {}; size_t text_length = 0; napi_value message = nullptr; if (exception != nullptr && - napi_get_named_property(s.env, exception, "message", &message) == napi_ok) { - napi_get_value_string_utf8(s.env, message, text, sizeof(text), &text_length); + napi_get_named_property(env, exception, "message", &message) == napi_ok) { + napi_get_value_string_utf8(env, message, text, sizeof(text), &text_length); } EXPECT_STREQ(text, "earlier"); - ExpectNothingPending(s.env, "after the earlier exception was taken"); + ExpectNothingPending(env, "after the earlier exception was taken"); } } +napi_value CountNativeCall(napi_env env, napi_callback_info info) { + void* data = nullptr; + EXPECT_EQ(napi_get_cb_info(env, info, nullptr, nullptr, nullptr, &data), napi_ok); + ++*static_cast(data); + bool pending = true; + EXPECT_EQ(napi_is_exception_pending(env, &pending), napi_ok); + EXPECT_FALSE(pending) << "a native callback started with another's exception pending"; + return nullptr; +} + +} // namespace + +TEST_F(Test33TypedArray, InfoCallsKeepThePendingException) { + EnvScope s(runtime_.get()); + ExpectInfoCallsKeepThePendingException(s.env); +} + +// On QuickJS an info call over a detached or out-of-bounds buffer makes an +// error, and formats it through Error.prepareStackTrace, which a page can +// define as a getter that calls native code. The exception native code up the +// stack has pending is not that callback's: it neither sees it nor throws it +// into the getter, and it is still the one pending when the info call returns. +TEST_F(Test33TypedArray, InfoCallsKeepThePendingExceptionWhenErrorFormattingCallsNativeCode) { + EnvScope s(runtime_.get()); + int native_calls = 0; + napi_value fn = nullptr; + ASSERT_EQ(napi_create_function(s.env, "countNativeCall", NAPI_AUTO_LENGTH, CountNativeCall, + &native_calls, &fn), + napi_ok); + SetGlobal(s.env, "countNativeCall", fn); + RunBufferScript(s.env, + "Object.defineProperty(Error, 'prepareStackTrace', { configurable: true," + " get() { countNativeCall(); return undefined; } });" + "0"); + ExpectInfoCallsKeepThePendingException(s.env); +#if defined(NAPI_TEST_ENGINE_QUICKJS) + // V8 makes no error to read a buffer or a view, so only QuickJS gets here. + EXPECT_GT(native_calls, 0) << "the getter never ran: nothing was tested"; +#endif +} + #if defined(NAPI_TEST_ENGINE_QUICKJS) TEST_F(Test33TypedArray, ExternalArrayBufferResizeFailurePreservesBackingStore) { ExternalBufferState state; From 3079c0df0415c605da8da017f6bdb82f0b38cf4f Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 19:41:29 -0800 Subject: [PATCH 087/150] QuickJS: read a view's offset and length from one state of its buffer napi_env__::view_layout reads a view's byteOffset and then its byteLength through the intrinsic getters. During a termination request QuickJS polls its interrupt handler on calls, now and then on one of these: the getter throws, the error gets its stack through Error.prepareStackTrace, which a page can define as a getter, and call_view_getter calls the getter again. If the page's getter resized the buffer, the offset came from before it and the length from after. A Uint8Array(rab, 8, 4) that a shrunk rab had left out of bounds read offset 0; the getter grew rab back to 16 bytes; the length read 4. The bounds check against the buffer's current size passed, and native code got the buffer's first 4 bytes as the view's (the page's own memory, but not the view's bytes). This came with "QuickJS: read a view's length and offset from its slots", which reads typed arrays through the getters; before it, one JS_GetTypedArrayBuffer call read both. When a read of the offset or length throws (so script may have run) and both were still read, view_layout now reads the two again, three times at most, until no read throws; if one still does, the view is taken as out of bounds. A view's buffer never changes, and its data and size are read after the loop, as before. Test: test_33 ViewOffsetAndLengthComeFromOneStateOfTheBuffer, during a termination request, 40000 reads of that view, with a prepareStackTrace getter that grows or shrinks rab each time it runs and makes 0, 1 or 2 more calls (one run each), which moves the poll from one read to another. Before this commit, QuickJS reported offset 0 and length 4 in 2, 6 and 2 of the 40000 reads. V8 reads no view through script and passed; the test checks that the getter ran on QuickJS only, for that reason. Co-Authored-By: Claude Opus 5.5 --- quickjs/src/internal/napi_env.cc | 33 +++++++++++---- tests/runners/test_33_typedarray.cc | 64 +++++++++++++++++++++++++++++ 2 files changed, 89 insertions(+), 8 deletions(-) diff --git a/quickjs/src/internal/napi_env.cc b/quickjs/src/internal/napi_env.cc index 2868c25547..d2c7266778 100644 --- a/quickjs/src/internal/napi_env.cc +++ b/quickjs/src/internal/napi_env.cc @@ -97,12 +97,17 @@ void view_getters(JSContext *ctx, JSValueConst global, const char *constructor_n // Calls an intrinsic getter of a view. Such a getter runs no script, but // QuickJS may poll its interrupt handler on the call and throw for a // termination request (which the env keeps and raises again itself); the -// getter is then called again, as the poll restarted its countdown. -JSValue call_view_getter(JSContext *ctx, JSValueConst getter, JSValueConst view) +// getter is then called again, as the poll restarted its countdown. Sets +// `*threw` (if given) when the call threw: making the error may have run +// script. +JSValue call_view_getter(JSContext *ctx, JSValueConst getter, JSValueConst view, + bool *threw = nullptr) { JSValue value = JS_Call(ctx, getter, view, 0, nullptr); if (!JS_IsException(value)) return value; + if (threw != nullptr) + *threw = true; JSValue exception = JS_GetException(ctx); const bool interrupted = JS_IsUncatchableError(exception); JS_FreeValue(ctx, exception); @@ -440,16 +445,28 @@ bool napi_env__::view_layout(JSValueConst view, napi_view_layout__ *layout) cons // run script that resizes, transfers or detaches the buffer. So the // buffer's data and size are read last: JS_GetArrayBuffer runs no script // when it succeeds, and when it throws the buffer is detached for good. - JSValue offset_value = call_view_getter(context_, getters->byte_offset, view); - JSValue length_value = call_view_getter(context_, getters->byte_length, view); + // And when a read of the offset or length threw but both were read, the + // two may come from different states of the buffer: they are read again, + // a few times at most, until no read throws; failing that, the view is + // taken as out of bounds. int64_t offset = -1; int64_t length = -1; - if (JS_IsException(offset_value) || JS_ToInt64(context_, &offset, offset_value) != 0) + for (int reads = 0; reads < 3; ++reads) + { + bool threw = false; + JSValue offset_value = call_view_getter(context_, getters->byte_offset, view, &threw); + JSValue length_value = call_view_getter(context_, getters->byte_length, view, &threw); + if (JS_IsException(offset_value) || JS_ToInt64(context_, &offset, offset_value) != 0) + offset = -1; + if (JS_IsException(length_value) || JS_ToInt64(context_, &length, length_value) != 0) + length = -1; + JS_FreeValue(context_, offset_value); + JS_FreeValue(context_, length_value); + if (!threw || offset < 0 || length < 0) + break; offset = -1; - if (JS_IsException(length_value) || JS_ToInt64(context_, &length, length_value) != 0) length = -1; - JS_FreeValue(context_, offset_value); - JS_FreeValue(context_, length_value); + } if (JS_HasException(context_)) JS_FreeValue(context_, JS_GetException(context_)); size_t buffer_length = 0; diff --git a/tests/runners/test_33_typedarray.cc b/tests/runners/test_33_typedarray.cc index 2cbab3d462..3b2b9f689e 100644 --- a/tests/runners/test_33_typedarray.cc +++ b/tests/runners/test_33_typedarray.cc @@ -665,6 +665,70 @@ TEST_F(Test33TypedArray, ViewDataIsCurrentAfterScriptRunsDuringTheRead) { #endif } +// A view's offset and length come from one state of its buffer. On QuickJS +// they are read one after the other, and the error of an interrupt poll +// during a termination request runs the page's Error.prepareStackTrace getter +// in between. Here that getter grows the buffer of a view it had left out of +// bounds (offset 0, length 0) back to hold it (offset 8, length 4), or shrinks +// it again; an offset from before the getter with a length from after it +// would give native code the buffer's first 4 bytes as the view's. The getter +// makes `extra` more calls each time, which moves the poll from one read to +// the next; the test runs with each of 0, 1 and 2. +TEST_F(Test33TypedArray, ViewOffsetAndLengthComeFromOneStateOfTheBuffer) { + EnvScope s(runtime_.get()); + RunBufferScript(s.env, + "globalThis.rab = new ArrayBuffer(16, { maxByteLength: 16 });" + "globalThis.typed = new Uint8Array(rab, 8, 4);" + "globalThis.polls = 0;" + "globalThis.extra = 0;" + "globalThis.noop = () => {};" + "Object.defineProperty(Error, 'prepareStackTrace', { configurable: true," + " get() {" + " polls++;" + " if (extra > 0) noop();" + " if (extra > 1) noop();" + " rab.resize(rab.byteLength === 4 ? 16 : 4);" + " return undefined;" + " } });" + "0"); + napi_value rab = NamedGlobal(s.env, "rab"); + napi_value typed = NamedGlobal(s.env, "typed"); + for (int extra = 0; extra < 3; ++extra) { + SCOPED_TRACE(extra); + napi_value value = nullptr; + ASSERT_EQ(napi_create_int32(s.env, extra, &value), napi_ok); + SetGlobal(s.env, "extra", value); + RunBufferScript(s.env, "rab.resize(4); 0"); + ASSERT_EQ(unofficial_napi_terminate_execution(s.env), napi_ok); + int mixed = 0; + int wrong = 0; + for (int i = 0; i < 40000; ++i) { + napi_handle_scope scope = nullptr; + ASSERT_EQ(napi_open_handle_scope(s.env, &scope), napi_ok); + const ViewLayout layout = TypedArrayLayout(s.env, typed); + uint8_t* base = ArrayBufferData(s.env, rab); + if (layout.status == napi_ok && layout.length == 0) { + // Out of bounds. + } else if (layout.status == napi_ok && layout.length == 4 && layout.offset == 8 && + layout.data == base + 8) { + // In bounds. + } else if (layout.status == napi_ok && layout.length == 4 && layout.offset == 0) { + ++mixed; + } else { + ++wrong; + } + ASSERT_EQ(napi_close_handle_scope(s.env, scope), napi_ok); + } + ASSERT_EQ(unofficial_napi_cancel_terminate_execution(s.env), napi_ok); + EXPECT_EQ(mixed, 0) << "an offset from one state of the buffer, a length from another"; + EXPECT_EQ(wrong, 0); + } +#if defined(NAPI_TEST_ENGINE_QUICKJS) + // V8 runs no script to read a view, so only QuickJS gets here at all. + EXPECT_GE(GlobalInt(s.env, "polls"), 18) << "the getter ran too seldom to test every read"; +#endif +} + // The serdes binding unofficial_napi_create_serdes_binding returns is still // the binding while the caller makes more values. TEST_F(Test33TypedArray, SerdesBindingOutlivesTheCallThatMadeIt) { From 7fd65a68ec8e65d63b035462943ea71f9775f786 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 19:41:40 -0800 Subject: [PATCH 088/150] Reject an import() that nothing can load, on both engines V8: NapiHostImportModuleDynamically, the dynamic import callback the provider installs on each isolate, looks for its helper on globalThis.process and then on the global. helper_value was left empty when `process` was not an object, and the check that followed called IsFunction() on it: a NULL dereference. Any script's import() in an env with no `process` object crashed the process, unless the embedder had set module hooks, which replace this callback. The code dates from the initial import (b4d08c6). helper_value now starts as undefined, so such an import() takes the existing path: its promise rejects with "Not supported". QuickJS threw from the import() expression instead of rejecting: the provider's dynamic import hook returned the exception ("Dynamic import callback is not registered", or whatever the embedder's callback threw) and QuickJS passes the hook's result through. The hook now rejects the promise with it, as V8 does and as import() must; a termination still unwinds. Test: test_65 DynamicImportWithNoLoaderRejects, import('missing') in a plain env, then a microtask checkpoint: the promise rejected. Before this commit, V8 crashed (exit 139; under ASan, SEGV on address 0 in v8::Value::IsFunction() under RunHostImportModuleDynamicallyCallback), and QuickJS's napi_run_script returned napi_pending_exception with the TypeError. Co-Authored-By: Claude Opus 5.5 --- quickjs/src/internal/napi_agent.cc | 33 ++++++++++++++++--- .../runners/test_65_unofficial_contextify.cc | 25 ++++++++++++++ v8/src/js_native_api_v8.cc | 3 +- 3 files changed, 56 insertions(+), 5 deletions(-) diff --git a/quickjs/src/internal/napi_agent.cc b/quickjs/src/internal/napi_agent.cc index 58cc3e0d4e..ef76ae8381 100644 --- a/quickjs/src/internal/napi_agent.cc +++ b/quickjs/src/internal/napi_agent.cc @@ -398,8 +398,33 @@ JSValue napi_agent__::dynamic_import(JSContext *ctx, { auto *agent = static_cast(opaque); napi_env env = agent == nullptr ? nullptr : agent->env_for_context(ctx); - if (!napi_util__::check_env(env)) - return JS_ThrowTypeError(ctx, "Dynamic import callback is not registered"); - return env->module_wrap().import_module_dynamically(referrer, referrer_name, specifier, - attributes, phase); + JSValue promise = napi_util__::check_env(env) + ? env->module_wrap().import_module_dynamically( + referrer, referrer_name, specifier, attributes, phase) + : JS_ThrowTypeError(ctx, "Dynamic import callback is not registered"); + if (!JS_IsException(promise)) + return promise; + // import() rejects what failed, as V8 does; QuickJS would throw it from + // the import() expression instead. Termination still unwinds. + JSValue error = JS_GetException(ctx); + if (JS_IsUncatchableError(error)) + return JS_Throw(ctx, error); + JSValue resolving_funcs[2]; + promise = JS_NewPromiseCapability(ctx, resolving_funcs); + if (JS_IsException(promise)) + { + JS_FreeValue(ctx, error); + return promise; + } + JSValue rejected = JS_Call(ctx, resolving_funcs[1], JS_UNDEFINED, 1, &error); + JS_FreeValue(ctx, error); + JS_FreeValue(ctx, resolving_funcs[0]); + JS_FreeValue(ctx, resolving_funcs[1]); + if (JS_IsException(rejected)) + { + JS_FreeValue(ctx, promise); + return JS_EXCEPTION; + } + JS_FreeValue(ctx, rejected); + return promise; } diff --git a/tests/runners/test_65_unofficial_contextify.cc b/tests/runners/test_65_unofficial_contextify.cc index 2b5291b7dd..0397ba6635 100644 --- a/tests/runners/test_65_unofficial_contextify.cc +++ b/tests/runners/test_65_unofficial_contextify.cc @@ -1118,3 +1118,28 @@ TEST_F(Test65UnofficialContextify, ModuleStateMadeAtReleaseGoesWithTheEnv) { s.env = nullptr; } } + +// A script's import() in an env with no module loader and no `process` +// object, so nothing to load the module with, rejects. +TEST_F(Test65UnofficialContextify, DynamicImportWithNoLoaderRejects) { + EnvScope s(runtime_.get()); + napi_value result = nullptr; + ASSERT_EQ(napi_run_script(s.env, + Str(s.env, + "globalThis.outcome = 'pending';" + "import('missing').then(() => { outcome = 'resolved'; }," + " () => { outcome = 'rejected'; });" + "typeof process"), + &result), + napi_ok); + char text[32] = {}; + size_t length = 0; + ASSERT_EQ(napi_get_value_string_utf8(s.env, result, text, sizeof(text), &length), napi_ok); + EXPECT_STREQ(text, "undefined"); + ASSERT_EQ(unofficial_napi_event_loop_checkpoint( + s.env, unofficial_napi_event_loop_checkpoint_microtasks, true, nullptr), + napi_ok); + ASSERT_EQ(napi_run_script(s.env, Str(s.env, "outcome"), &result), napi_ok); + ASSERT_EQ(napi_get_value_string_utf8(s.env, result, text, sizeof(text), &length), napi_ok); + EXPECT_STREQ(text, "rejected"); +} diff --git a/v8/src/js_native_api_v8.cc b/v8/src/js_native_api_v8.cc index e8a972b35e..999e55079a 100644 --- a/v8/src/js_native_api_v8.cc +++ b/v8/src/js_native_api_v8.cc @@ -118,7 +118,8 @@ v8::MaybeLocal NapiHostImportModuleDynamically( v8::Local global = context->Global(); v8::Local helper_name = v8::String::NewFromUtf8Literal(isolate, "__napi_dynamic_import"); - v8::Local helper_value; + // Undefined unless `process` is an object that has the helper. + v8::Local helper_value = v8::Undefined(isolate); v8::Local process_name = v8::String::NewFromUtf8Literal(isolate, "process"); v8::Local process_value; From 18f04e3dd2c3c0641822e09389e92241271d4808 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 19:42:03 -0800 Subject: [PATCH 089/150] QuickJS: say what unofficial_napi_create_env_from_context trusts An env takes the getters of buffer, byteOffset and byteLength on %TypedArray%.prototype and DataView.prototype, and the DataView constructor, from its context's global when it is made ("QuickJS: read a view's buffer through the intrinsic getters", "QuickJS: read a view's length and offset from its slots"), and locates views' memory through them. From a context where script had already replaced them, a `buffer` getter that returned a fresh ArrayBuffer made napi_get_typedarray_info report data in that buffer, which it then freed (QuickJS ASan: heap-use-after-free in a review test). unofficial_napi_create_env always reads them from the fresh context it makes. unofficial_napi_create_env_from_context is exported but in no header, and nothing in napi, EdgeJS or WebkitWasm calls it; it now says that its context must be one no script has run in. Reading the getters from a second, fresh context of the same runtime would lift that, at the cost of a context per such env. Co-Authored-By: Claude Opus 5.5 --- quickjs/src/unofficial_napi.cc | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/quickjs/src/unofficial_napi.cc b/quickjs/src/unofficial_napi.cc index 8a7ff0ca5c..ee124118ca 100644 --- a/quickjs/src/unofficial_napi.cc +++ b/quickjs/src/unofficial_napi.cc @@ -236,6 +236,11 @@ extern "C" return napi_create_typedarray(env, type, length, arraybuffer, 0, result); } + // The env takes the getters of buffer, byteOffset and byteLength on + // %TypedArray%.prototype and DataView.prototype, and the DataView + // constructor, from the context's global when it is made, and trusts + // them to locate views' memory: `context` must be one no script has run + // in, as the fresh one unofficial_napi_create_env makes is. napi_status NAPI_CDECL unofficial_napi_create_env_from_context( JSContext *context, int32_t module_api_version, napi_env *result) { From faa05e806cceff2c3e00945824ff0274df89daaf Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 19:49:46 -0800 Subject: [PATCH 090/150] Test a view's layout against its buffer as it is, in test_33 ViewOffsetAndLengthComeFromOneStateOfTheBuffer took any empty layout as right, also one read while the buffer held the view: a provider that reported every view as out of bounds would have passed, and on V8, which runs no script to read a view, only the out-of-bounds layout was ever checked (the buffer stays shrunk). Each read is now checked against the buffer's size after it (no script runs in between): 16 bytes means offset 8, length 4 and the data at the buffer's base plus 8; 4 bytes means length 0. Before the loop the view is read once in bounds and once out of bounds, on both engines. With the change to view_layout from "QuickJS: read a view's offset and length from one state of its buffer" reverted, QuickJS still reports offset 0 and length 4 in 2, 0 and 2 of the 40000 reads of the three runs; with it, none. Codex review of the fix-up range. Co-Authored-By: Claude Opus 5.5 --- tests/runners/test_33_typedarray.cc | 39 +++++++++++++++++++---------- 1 file changed, 26 insertions(+), 13 deletions(-) diff --git a/tests/runners/test_33_typedarray.cc b/tests/runners/test_33_typedarray.cc index 3b2b9f689e..ba533338a6 100644 --- a/tests/runners/test_33_typedarray.cc +++ b/tests/runners/test_33_typedarray.cc @@ -693,6 +693,28 @@ TEST_F(Test33TypedArray, ViewOffsetAndLengthComeFromOneStateOfTheBuffer) { "0"); napi_value rab = NamedGlobal(s.env, "rab"); napi_value typed = NamedGlobal(s.env, "typed"); + // The layout the view has with its buffer as it is now: no script runs + // between the end of the read and this check. + enum class Read { kRight, kMixed, kWrong }; + auto read = [&] { + const ViewLayout layout = TypedArrayLayout(s.env, typed); + void* base = nullptr; + size_t size = 0; + EXPECT_EQ(napi_get_arraybuffer_info(s.env, rab, &base, &size), napi_ok); + const bool in_bounds = size == 16; + if (layout.status == napi_ok && + (in_bounds ? layout.length == 4 && layout.offset == 8 && + layout.data == static_cast(base) + 8 + : layout.length == 0)) + return Read::kRight; + if (layout.status == napi_ok && layout.length == 4 && layout.offset == 0) + return Read::kMixed; + return Read::kWrong; + }; + RunBufferScript(s.env, "rab.resize(16); 0"); + EXPECT_EQ(read(), Read::kRight) << "in bounds"; + RunBufferScript(s.env, "rab.resize(4); 0"); + EXPECT_EQ(read(), Read::kRight) << "out of bounds"; for (int extra = 0; extra < 3; ++extra) { SCOPED_TRACE(extra); napi_value value = nullptr; @@ -705,23 +727,14 @@ TEST_F(Test33TypedArray, ViewOffsetAndLengthComeFromOneStateOfTheBuffer) { for (int i = 0; i < 40000; ++i) { napi_handle_scope scope = nullptr; ASSERT_EQ(napi_open_handle_scope(s.env, &scope), napi_ok); - const ViewLayout layout = TypedArrayLayout(s.env, typed); - uint8_t* base = ArrayBufferData(s.env, rab); - if (layout.status == napi_ok && layout.length == 0) { - // Out of bounds. - } else if (layout.status == napi_ok && layout.length == 4 && layout.offset == 8 && - layout.data == base + 8) { - // In bounds. - } else if (layout.status == napi_ok && layout.length == 4 && layout.offset == 0) { - ++mixed; - } else { - ++wrong; - } + const Read outcome = read(); + mixed += outcome == Read::kMixed; + wrong += outcome == Read::kWrong; ASSERT_EQ(napi_close_handle_scope(s.env, scope), napi_ok); } ASSERT_EQ(unofficial_napi_cancel_terminate_execution(s.env), napi_ok); EXPECT_EQ(mixed, 0) << "an offset from one state of the buffer, a length from another"; - EXPECT_EQ(wrong, 0); + EXPECT_EQ(wrong, 0) << "not the layout of the buffer as it is"; } #if defined(NAPI_TEST_ENGINE_QUICKJS) // V8 runs no script to read a view, so only QuickJS gets here at all. From 37ffb2960e51c94ffb96ae5ee7f4d993d0ce0b06 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 21:34:55 -0800 Subject: [PATCH 091/150] V8: reject an import() the module hooks have nothing to load with unofficial_napi_module_wrap_set_hooks makes ImportModuleDynamicallyWithPhase the isolate's dynamic import callback, and nothing replaces it later. It returned an empty MaybeLocal with nothing thrown when it found no env with module-wrap state, no state or no import callback, and when napi_call_function failed with nothing pending (an import callback that is not a function). V8 takes an empty result for a thrown exception and fails CHECK(has_exception()) in Isolate::UnwindAndFindHandler: the process aborts (SIGTRAP, exit 133). Two ways get there: - set_hooks with no import callback: none at all, only the import.meta one (EdgeJS's ConfigureModuleHooks passes NULL then), or undefined. Every import() after it aborted. - At release, after the loader's cleanup hook (CleanupModuleWrapState) has erased the env's state: an import() from a cleanup hook added before set_hooks, or from a token unassign callback in the sweep after the cleanup hooks. These early returns are the same on origin/main; "Reject an import() that nothing can load, on both engines" fixed only the default callback, NapiHostImportModuleDynamically. The callback now returns a promise of the importing realm, rejected with Error("Not supported"), as NapiHostImportModuleDynamically does and as V8 does with no callback at all. It returns empty only after throwing the import callback's exception, or while execution terminates. The rejected promise of the call-failure branch is escaped through the callback's own handle scope, which it is returned from. Tests, both engines with no guard: - test_65 DynamicImportWithModuleHooksButNoImportCallbackRejects: the three hook settings above, import() in the env's realm, a sandbox realm and a fresh realm; each returns a promise that rejects. - test_65 DynamicImportFromACleanupHookAfterTheLoadersCleanupHookSettles: a cleanup hook added before set_hooks imports from a script, from a module it makes (which makes the loader's state again, with no hooks) and from a script again; each returns a promise that settles. V8 rejects, its loader having let go; QuickJS keeps its hooks until the release's pass is over, so they load it. - test_71 AnImportAnUnassignHookMakesAfterTheLoadersCleanupHookRejects: the unassign callback for the realm a cleanup hook made imports; V8 rejects. QuickJS accepts no token hooks, so nothing imports there. Before this commit, all three aborted on V8 ("Check failed: has_exception()") and passed on QuickJS. Co-Authored-By: Claude Opus 5.5 --- .../runners/test_65_unofficial_contextify.cc | 223 ++++++++++++++++++ tests/runners/test_71_contextify_compat.cc | 92 ++++++++ v8/src/unofficial_napi_contextify.cc | 35 ++- 3 files changed, 346 insertions(+), 4 deletions(-) diff --git a/tests/runners/test_65_unofficial_contextify.cc b/tests/runners/test_65_unofficial_contextify.cc index 0397ba6635..43d8c8537b 100644 --- a/tests/runners/test_65_unofficial_contextify.cc +++ b/tests/runners/test_65_unofficial_contextify.cc @@ -3,6 +3,9 @@ #include "node_api.h" #include "unofficial_napi.h" +#include +#include + class Test65UnofficialContextify : public FixtureTestBase {}; namespace { @@ -1143,3 +1146,223 @@ TEST_F(Test65UnofficialContextify, DynamicImportWithNoLoaderRejects) { ASSERT_EQ(napi_get_value_string_utf8(s.env, result, text, sizeof(text), &length), napi_ok); EXPECT_STREQ(text, "rejected"); } + +namespace { + +// Calls import('missing') and returns a box that records what became of it: +// `sync` is "returned" once import() returned a promise, and `outcome` says +// how that promise settled. +constexpr char kImportBox[] = + "(() => {" + " const box = { sync: 'none', outcome: 'pending' };" + " try {" + " const promise = import('missing');" + " box.sync = Object.prototype.toString.call(promise) === '[object Promise]'" + " ? 'returned' : 'returned no promise';" + " promise.then((ns) => { box.outcome = 'resolved:' + (ns && ns.from); }," + " () => { box.outcome = 'rejected'; });" + " } catch (e) { box.sync = 'threw: ' + e; }" + " return box;" + "})()"; + +std::string BoxText(napi_env env, napi_value box, const char* name) { + napi_value value = nullptr; + napi_value string = nullptr; + char text[128] = {}; + size_t length = 0; + if (box == nullptr || napi_get_named_property(env, box, name, &value) != napi_ok || + napi_coerce_to_string(env, value, &string) != napi_ok || + napi_get_value_string_utf8(env, string, text, sizeof(text), &length) != napi_ok) { + return ""; + } + return std::string(text, length); +} + +// "returned, rejected" for an import() that returned a promise that rejected. +std::string ImportOutcome(napi_env env, napi_value box) { + return BoxText(env, box, "sync") + ", " + BoxText(env, box, "outcome"); +} + +napi_status RunInRealm(napi_env env, + unofficial_napi_realm realm, + const char* code, + napi_value* result_out) { + const unofficial_napi_js_source source = unofficial_napi_js_source_from_text(Str(env, code)); + return unofficial_napi_run_script(env, realm, &source, Str(env, "realm.js"), 0, 0, -1, true, + false, false, Sym(env, "hdo"), result_out); +} + +void RunMicrotasks(napi_env env) { + EXPECT_EQ(unofficial_napi_event_loop_checkpoint( + env, unofficial_napi_event_loop_checkpoint_microtasks, true, nullptr), + napi_ok); +} + +} // namespace + +// Module hooks with no dynamic import callback: none at all, only the +// import.meta one, or one that is not a function. An import() then has +// nothing to load it with, in the env's realm or in another, and rejects. On +// V8 the import callback the hooks install returned no promise and threw +// nothing there, and V8 aborts the process on that (CHECK has_exception()). +TEST_F(Test65UnofficialContextify, DynamicImportWithModuleHooksButNoImportCallbackRejects) { + enum Hooks { kNoCallbacks, kImportMetaOnly, kImportNotAFunction }; + for (Hooks which : {kNoCallbacks, kImportMetaOnly, kImportNotAFunction}) { + SCOPED_TRACE(which == kNoCallbacks ? "no callbacks" + : which == kImportMetaOnly ? "import.meta callback only" + : "import callback undefined"); + EnvScope s(runtime_.get()); + napi_value undefined = nullptr; + ASSERT_EQ(napi_get_undefined(s.env, &undefined), napi_ok); + napi_value meta = nullptr; + ASSERT_EQ(napi_run_script(s.env, Str(s.env, "(() => {})"), &meta), napi_ok); + unofficial_napi_module_hooks hooks{}; + hooks.size = sizeof(hooks); + hooks.version = UNOFFICIAL_NAPI_MODULE_HOOKS_VERSION; + if (which == kImportMetaOnly) hooks.initialize_import_meta_object = meta; + if (which == kImportNotAFunction) hooks.import_module_dynamically = undefined; + ASSERT_EQ(unofficial_napi_module_wrap_set_hooks(s.env, &hooks), napi_ok); + + napi_value sandbox = nullptr; + ASSERT_EQ(napi_create_object(s.env, &sandbox), napi_ok); + unofficial_napi_realm sandbox_realm = nullptr; + ASSERT_EQ(CreateSandboxRealm(s.env, sandbox, false, &sandbox_realm), napi_ok); + unofficial_napi_realm fresh_realm = nullptr; + napi_value fresh_global = nullptr; + ASSERT_EQ(unofficial_napi_create_realm(s.env, nullptr, &fresh_realm, &fresh_global), napi_ok); + + napi_value env_box = nullptr; + ASSERT_EQ(napi_run_script(s.env, Str(s.env, kImportBox), &env_box), napi_ok); + napi_value sandbox_box = nullptr; + ASSERT_EQ(RunInRealm(s.env, sandbox_realm, kImportBox, &sandbox_box), napi_ok); + napi_value fresh_box = nullptr; + ASSERT_EQ(RunInRealm(s.env, fresh_realm, kImportBox, &fresh_box), napi_ok); + RunMicrotasks(s.env); + EXPECT_EQ(ImportOutcome(s.env, env_box), "returned, rejected") << "the env's realm"; + EXPECT_EQ(ImportOutcome(s.env, sandbox_box), "returned, rejected") << "a sandbox realm"; + EXPECT_EQ(ImportOutcome(s.env, fresh_box), "returned, rejected") << "a fresh realm"; + } +} + +namespace { + +struct ImportsAtRelease { + napi_env env = nullptr; + bool ran = false; + std::vector outcomes; +}; + +// A module whose evaluation imports; returns its box. +napi_value ImportFromAModule(napi_env env, std::string* failed) { + napi_value wrapper = nullptr; + napi_value undefined = nullptr; + napi_create_object(env, &wrapper); + napi_get_undefined(env, &undefined); + const std::string code = std::string("export const box = ") + kImportBox + ";"; + const unofficial_napi_js_source source = + unofficial_napi_js_source_from_text(Str(env, code.c_str())); + unofficial_napi_module_create_options options{}; + options.size = sizeof(options); + options.version = UNOFFICIAL_NAPI_MODULE_CREATE_OPTIONS_VERSION; + options.kind = unofficial_napi_module_source_text; + options.wrapper = wrapper; + options.url = Str(env, "imports.mjs"); + options.payload.source_text.source = &source; + options.payload.source_text.host_defined_option_id = undefined; + unofficial_napi_module_create_result created{}; + if (unofficial_napi_module_wrap_create(env, &options, &created) != napi_ok) { + *failed = "create"; + return nullptr; + } + napi_value evaluated = nullptr; + napi_value ns = nullptr; + napi_value box = nullptr; + if (unofficial_napi_module_wrap_link(env, created.module, 0, nullptr) != napi_ok) { + *failed = "link"; + } else if (unofficial_napi_module_wrap_instantiate(env, created.module) != napi_ok) { + *failed = "instantiate"; + } else if (unofficial_napi_module_wrap_evaluate(env, created.module, -1, false, &evaluated) != + napi_ok) { + *failed = "evaluate"; + } else if (unofficial_napi_module_wrap_get_namespace(env, created.module, &ns) != napi_ok || + napi_get_named_property(env, ns, "box", &box) != napi_ok) { + *failed = "namespace"; + } + unofficial_napi_module_wrap_destroy(env, created.module); + return box; +} + +// Added before the module hooks, so the release runs it after the module +// loader's own cleanup hook (most recent first), which on V8 lets go of the +// hooks and of the loader's state. It imports from a script; from a module, +// which makes the loader's state again, with no hooks; and from a script +// again. +void ImportAfterTheLoadersCleanupHook(void* arg) { + auto* imports = static_cast(arg); + napi_env env = imports->env; + imports->ran = true; + napi_handle_scope scope = nullptr; + if (napi_open_handle_scope(env, &scope) != napi_ok) return; + napi_value boxes[3] = {}; + std::string failed; + if (napi_run_script(env, Str(env, kImportBox), &boxes[0]) != napi_ok) failed = "script"; + if (failed.empty()) boxes[1] = ImportFromAModule(env, &failed); + if (failed.empty() && napi_run_script(env, Str(env, kImportBox), &boxes[2]) != napi_ok) { + failed = "second script"; + } + bool pending = false; + if (napi_is_exception_pending(env, &pending) == napi_ok && pending) { + napi_value ignored = nullptr; + napi_get_and_clear_last_exception(env, &ignored); + failed += " (exception pending)"; + } + unofficial_napi_event_loop_checkpoint(env, unofficial_napi_event_loop_checkpoint_microtasks, + true, nullptr); + if (!failed.empty()) imports->outcomes.push_back("failed: " + failed); + for (napi_value box : boxes) { + if (box != nullptr) imports->outcomes.push_back(ImportOutcome(env, box)); + } + napi_close_handle_scope(env, scope); +} + +} // namespace + +// An import() a cleanup hook makes at release, after the module loader's own +// cleanup hook, returns a promise that settles. On V8 the loader's hook has +// let go of the hooks, so it rejects; QuickJS's loader keeps its hooks until +// the release's pass is over, so they load it. On V8 the import callback the +// hooks installed, still the isolate's, found no loader state there and +// returned no promise with nothing thrown, and V8 aborts the process on that. +TEST_F(Test65UnofficialContextify, DynamicImportFromACleanupHookAfterTheLoadersCleanupHookSettles) { + ImportsAtRelease imports; + { + EnvScope s(runtime_.get()); + imports.env = s.env; + ASSERT_EQ(napi_add_env_cleanup_hook(s.env, ImportAfterTheLoadersCleanupHook, &imports), + napi_ok); + napi_value loader = nullptr; + ASSERT_EQ(napi_run_script(s.env, + Str(s.env, "(id, specifier) => Promise.resolve({ from: 'hooks' })"), + &loader), + napi_ok); + unofficial_napi_module_hooks hooks{}; + hooks.size = sizeof(hooks); + hooks.version = UNOFFICIAL_NAPI_MODULE_HOOKS_VERSION; + hooks.import_module_dynamically = loader; + ASSERT_EQ(unofficial_napi_module_wrap_set_hooks(s.env, &hooks), napi_ok); + // Before the release the hooks load it. + napi_value box = nullptr; + ASSERT_EQ(napi_run_script(s.env, Str(s.env, kImportBox), &box), napi_ok); + RunMicrotasks(s.env); + EXPECT_EQ(ImportOutcome(s.env, box), "returned, resolved:hooks"); + ASSERT_EQ(unofficial_napi_release_env(s.scope, nullptr), napi_ok); + s.scope = nullptr; + s.env = nullptr; + } + EXPECT_TRUE(imports.ran); + ASSERT_EQ(imports.outcomes.size(), 3u); + for (const std::string& outcome : imports.outcomes) { + EXPECT_TRUE(outcome == "returned, rejected" || outcome == "returned, resolved:hooks") + << outcome; + } +} diff --git a/tests/runners/test_71_contextify_compat.cc b/tests/runners/test_71_contextify_compat.cc index 3f5e425a15..43cd306311 100644 --- a/tests/runners/test_71_contextify_compat.cc +++ b/tests/runners/test_71_contextify_compat.cc @@ -15,7 +15,9 @@ #include #include +#include #include +#include #include #include @@ -1912,6 +1914,10 @@ struct ReleaseTokens { int unassign_makes = 0; // How many more unassign hooks throw, one per call. int unassign_throws = 0; + // How many more unassign hooks import() from a script, one per call, and + // what became of each import(): "returned, ". + int unassign_imports = 0; + std::vector import_outcomes; }; void CheckHookRealm(napi_env env, ReleaseTokens* log) { @@ -1933,6 +1939,53 @@ void CheckHookRealm(napi_env env, ReleaseTokens* log) { napi_close_handle_scope(env, scope); } +// Imports from a script in the env's realm, then runs the microtasks: says +// what became of the import(). +std::string ImportFromAScript(napi_env env) { + napi_handle_scope scope = nullptr; + if (napi_open_handle_scope(env, &scope) != napi_ok) return "no handle scope"; + napi_value box = nullptr; + std::string outcome; + if (napi_run_script(env, + Str(env, + "(() => {" + " const box = { sync: 'none', outcome: 'pending' };" + " try {" + " const promise = import('missing');" + " box.sync = 'returned';" + " promise.then((ns) => { box.outcome = 'resolved:' + (ns && ns.from); }," + " () => { box.outcome = 'rejected'; });" + " } catch (e) { box.sync = 'threw: ' + e; }" + " return box;" + "})()"), + &box) != napi_ok) { + outcome = "script failed"; + } else { + unofficial_napi_event_loop_checkpoint(env, unofficial_napi_event_loop_checkpoint_microtasks, + true, nullptr); + for (const char* name : {"sync", "outcome"}) { + napi_value value = nullptr; + char text[128] = {}; + size_t length = 0; + if (napi_get_named_property(env, box, name, &value) != napi_ok || + napi_get_value_string_utf8(env, value, text, sizeof(text), &length) != napi_ok) { + std::snprintf(text, sizeof(text), ""); + length = std::strlen(text); + } + if (!outcome.empty()) outcome += ", "; + outcome.append(text, length); + } + } + bool pending = false; + if (napi_is_exception_pending(env, &pending) == napi_ok && pending) { + napi_value ignored = nullptr; + napi_get_and_clear_last_exception(env, &ignored); + outcome += " (exception pending)"; + } + napi_close_handle_scope(env, scope); + return outcome; +} + void MakeReleaseRealm(ReleaseTokens* log) { napi_handle_scope scope = nullptr; if (napi_open_handle_scope(log->env, &scope) != napi_ok) { @@ -1976,6 +2029,10 @@ void UnassignReleaseToken(napi_env env, void* token, void* data) { --log->unassign_throws; napi_throw_error(env, nullptr, "unassign"); } + if (log->unassign_imports > 0) { + --log->unassign_imports; + log->import_outcomes.push_back(ImportFromAScript(env)); + } } void MakeRealmHook(void* data) { @@ -2319,3 +2376,38 @@ TEST_F(Test71ContextifyCompat, TokenHookExceptionsAtReleaseAreDropped) { EXPECT_EQ(state.events_after, state.events_before + 1); #endif } + +// An unassign callback the release runs after the module loader's cleanup +// hook (for the realm a later cleanup hook made, in the sweep after the +// hooks) imports from a script: import() returns a promise, which rejects, +// since on V8 the loader's hook has let go of the module hooks. The import +// callback those hooks installed, still the isolate's, found no loader state +// there and returned no promise with nothing thrown, and V8 aborts the process +// on that. Token hooks are V8's only, so on QuickJS no unassign callback runs. +TEST_F(Test71ContextifyCompat, AnImportAnUnassignHookMakesAfterTheLoadersCleanupHookRejects) { + EnvScope s(runtime_.get()); + ReleaseTokens log; + AttachReleaseTokens(s, &log); + napi_value loader = nullptr; + ASSERT_EQ(napi_run_script(s.env, + Str(s.env, "(id, specifier) => Promise.resolve({ from: 'hooks' })"), + &loader), + napi_ok); + unofficial_napi_module_hooks hooks{}; + hooks.size = sizeof(hooks); + hooks.version = UNOFFICIAL_NAPI_MODULE_HOOKS_VERSION; + hooks.import_module_dynamically = loader; + ASSERT_EQ(unofficial_napi_module_wrap_set_hooks(s.env, &hooks), napi_ok); + EXPECT_EQ(ImportFromAScript(s.env), "returned, resolved:hooks"); + // Added after the loader's cleanup hook, so it runs before it. + ASSERT_EQ(napi_add_env_cleanup_hook(s.env, MakeRealmHook, &log), napi_ok); + log.unassign_imports = 1; + ReleaseTokensEnv(s); + ExpectEveryTokenUnassignedOnce(log, 1); +#if defined(NAPI_TEST_ENGINE_V8) + ASSERT_EQ(log.import_outcomes.size(), 1u); + EXPECT_EQ(log.import_outcomes[0], "returned, rejected"); +#else + EXPECT_TRUE(log.import_outcomes.empty()); +#endif +} diff --git a/v8/src/unofficial_napi_contextify.cc b/v8/src/unofficial_napi_contextify.cc index 2245ed5af4..827eacf9fa 100644 --- a/v8/src/unofficial_napi_contextify.cc +++ b/v8/src/unofficial_napi_contextify.cc @@ -1154,6 +1154,27 @@ v8::Local CreateDynamicImportAttributesObject( return CreateFrozenNullProtoObject(env, names, values); } +// The promise of an import() nothing can load: of the importing realm, +// rejected, as NapiHostImportModuleDynamically and V8 with no import callback +// reject it. V8 takes an empty result for an exception thrown and aborts the +// process when none was, so the import callback returns one only after +// throwing. +v8::MaybeLocal RejectImport(v8::Local context) { + v8::Isolate* isolate = context->GetIsolate(); + v8::EscapableHandleScope handle_scope(isolate); + v8::Context::Scope context_scope(context); + v8::Local resolver; + if (!v8::Promise::Resolver::New(context).ToLocal(&resolver)) { + return v8::MaybeLocal(); + } + v8::Local error = + v8::Exception::Error(v8::String::NewFromUtf8Literal(isolate, "Not supported")); + if (resolver->Reject(context, error).IsNothing()) return v8::MaybeLocal(); + v8::Local promise = resolver->GetPromise(); + NapiV8TrackProviderPromise(isolate, promise); + return handle_scope.Escape(promise); +} + v8::MaybeLocal ImportModuleDynamicallyWithPhase( v8::Local context, v8::Local host_defined_options, @@ -1161,13 +1182,16 @@ v8::MaybeLocal ImportModuleDynamicallyWithPhase( v8::Local specifier, v8::ModuleImportPhase phase, v8::Local import_attributes) { + // The hooks stay the isolate's import callback after the module loader lets + // go of them (its cleanup hook, at the env's release), and they may have + // had no import callback at all: then nothing can load the module. napi_env env = GetModuleWrapEnvForIsolate(context->GetIsolate()); - if (env == nullptr) return v8::MaybeLocal(); + if (env == nullptr) return RejectImport(context); auto* state = GetModuleWrapState(env); - if (state == nullptr) return v8::MaybeLocal(); + if (state == nullptr) return RejectImport(context); napi_value callback = GetRefValue(env, state->import_module_dynamically_ref); - if (callback == nullptr) return v8::MaybeLocal(); + if (callback == nullptr) return RejectImport(context); v8::Isolate* isolate = context->GetIsolate(); v8::EscapableHandleScope handle_scope(isolate); @@ -1220,9 +1244,12 @@ v8::MaybeLocal ImportModuleDynamicallyWithPhase( napi_value error = nullptr; if (napi_get_and_clear_last_exception(env, &error) == napi_ok && error != nullptr) { isolate->ThrowException(napi_v8_unwrap_value(error)); + return v8::MaybeLocal(); } } - return v8::MaybeLocal(); + if (isolate->IsExecutionTerminating()) return v8::MaybeLocal(); + // Nothing thrown: the callback is not a function. + return handle_scope.EscapeMaybe(RejectImport(context)); } } From 3f474a79d0a18d579b70b36f67cdd49c9cd6fedb Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 21:35:40 -0800 Subject: [PATCH 092/150] QuickJS: read a view's offset and length again whenever a read threw view_layout reads a view's byteOffset and byteLength through the intrinsic getters, and a DataView's throw while it is out of bounds of its resizable buffer (or detached). Formatting that error runs Error.prepareStackTrace, which script can define as a getter that changes the buffer. The loop read both values again only when a read threw and both were still obtained. When the offset read threw and the script it ran grew the buffer back, the length read that followed succeeded and the offset stayed -1: the loop stopped and the view was reported out of bounds (length 0, offset 0, data at the buffer's start), while napi_get_dataview_info returned with the buffer holding the view at offset 8 with 4 bytes. Memory was safe (native code got 0 bytes), but the layout was not that of the buffer as it is, which "QuickJS: read a view's offset and length from one state of its buffer" and test_33's ViewOffsetAndLengthComeFromOneStateOfTheBuffer aim for; those use typed arrays, whose getters do not throw out of bounds, so they missed this. Both are now read again whenever a read threw, still at most three times; if every attempt throws, the view is taken as out of bounds as before. A DataView that stays out of bounds or detached makes up to three times as many errors per info call; that path is rare and was already making two. Test: test_33 DataViewLayoutAfterErrorFormattingGrowsItsBuffer, both engines with no guard, three times over: shrink the buffer, read the view, then check the layout against the buffer's size as it is (16 bytes: offset 8, length 4, data at base + 8; 4 bytes: length 0). Before this commit, QuickJS reported length 0, offset 0 and the data at the base with the buffer back at 16 bytes, in each round. V8 runs no script to read a view, so its buffer stays at 4 bytes and length is 0; it passed before and after. Co-Authored-By: Claude Opus 5.5 --- quickjs/src/internal/napi_env.cc | 11 ++++---- tests/runners/test_33_typedarray.cc | 42 +++++++++++++++++++++++++++++ 2 files changed, 48 insertions(+), 5 deletions(-) diff --git a/quickjs/src/internal/napi_env.cc b/quickjs/src/internal/napi_env.cc index d2c7266778..f237d55f98 100644 --- a/quickjs/src/internal/napi_env.cc +++ b/quickjs/src/internal/napi_env.cc @@ -445,10 +445,11 @@ bool napi_env__::view_layout(JSValueConst view, napi_view_layout__ *layout) cons // run script that resizes, transfers or detaches the buffer. So the // buffer's data and size are read last: JS_GetArrayBuffer runs no script // when it succeeds, and when it throws the buffer is detached for good. - // And when a read of the offset or length threw but both were read, the - // two may come from different states of the buffer: they are read again, - // a few times at most, until no read throws; failing that, the view is - // taken as out of bounds. + // And when a read of the offset or length threw, the two may come from + // different states of the buffer, or the one that threw from a state + // the script it ran has changed (it may have brought the view back in + // bounds): both are read again, a few times at most, until no read + // throws; failing that, the view is taken as out of bounds. int64_t offset = -1; int64_t length = -1; for (int reads = 0; reads < 3; ++reads) @@ -462,7 +463,7 @@ bool napi_env__::view_layout(JSValueConst view, napi_view_layout__ *layout) cons length = -1; JS_FreeValue(context_, offset_value); JS_FreeValue(context_, length_value); - if (!threw || offset < 0 || length < 0) + if (!threw) break; offset = -1; length = -1; diff --git a/tests/runners/test_33_typedarray.cc b/tests/runners/test_33_typedarray.cc index ba533338a6..6ad0a54fa2 100644 --- a/tests/runners/test_33_typedarray.cc +++ b/tests/runners/test_33_typedarray.cc @@ -742,6 +742,48 @@ TEST_F(Test33TypedArray, ViewOffsetAndLengthComeFromOneStateOfTheBuffer) { #endif } +// A DataView out of bounds of its resizable buffer: a DataView's byteOffset +// and byteLength getters throw then (QuickJS reads the view through them), and +// formatting the error runs Error.prepareStackTrace, here a getter that grows +// the buffer back. The layout reported is that of the buffer as it is when +// napi_get_dataview_info returns: the view in bounds again, at offset 8 with +// 4 bytes, not out of bounds because one read threw before the buffer grew +// and the other did not. V8 runs no script to read a view: the buffer stays +// short and the view has no bytes. +TEST_F(Test33TypedArray, DataViewLayoutAfterErrorFormattingGrowsItsBuffer) { + EnvScope s(runtime_.get()); + RunBufferScript(s.env, + "globalThis.rab = new ArrayBuffer(16, { maxByteLength: 16 });" + "globalThis.dv = new DataView(rab, 8, 4);" + "globalThis.grows = 0;" + "Object.defineProperty(Error, 'prepareStackTrace', { configurable: true," + " get() { grows++; rab.resize(16); return undefined; } });" + "0"); + napi_value rab = NamedGlobal(s.env, "rab"); + napi_value dv = NamedGlobal(s.env, "dv"); + for (int i = 0; i < 3; ++i) { + SCOPED_TRACE(i); + RunBufferScript(s.env, "rab.resize(4); 0"); + const ViewLayout layout = DataViewLayout(s.env, dv); + void* base = nullptr; + size_t size = 0; + ASSERT_EQ(napi_get_arraybuffer_info(s.env, rab, &base, &size), napi_ok); + ASSERT_EQ(layout.status, napi_ok); + if (size == 16) { + EXPECT_EQ(layout.length, 4u); + EXPECT_EQ(layout.offset, 8u); + EXPECT_EQ(layout.data, static_cast(base) + 8); + } else { + EXPECT_EQ(size, 4u); + EXPECT_EQ(layout.length, 0u); + } + } +#if defined(NAPI_TEST_ENGINE_QUICKJS) + // V8 runs no script to read a view, so only QuickJS gets here at all. + EXPECT_GE(GlobalInt(s.env, "grows"), 3) << "the getter did not run"; +#endif +} + // The serdes binding unofficial_napi_create_serdes_binding returns is still // the binding while the caller makes more values. TEST_F(Test33TypedArray, SerdesBindingOutlivesTheCallThatMadeIt) { From 5d70b1253ad192d48c0265218c6afca7af86b1ce Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 21:37:19 -0800 Subject: [PATCH 093/150] QuickJS: run native callbacks from the release's hooks and finalizers prepare_teardown sets closing_ before it runs the cleanup hooks and finalizers, and invoke_callback refused every native callback of a closing env with ReferenceError "Null NAPI env": every function made by napi_create_function or napi_define_class, from native code or from a script. So a cleanup hook or finalizer at release could not even construct the serdes binding's Serializer (napi_new_instance returned napi_pending_exception), while it could still run scripts, and V8 ran the same code in full. The release contract says hooks and finalizers run with N-API usable. invoke_callback now refuses only once finalizers_done(): after the pass, when no user code runs. The header says what "N-API usable" covers: scripts and the native functions they or native code call. Node runs no JavaScript there at all (FreeEnvironment's DisallowJavascriptExecutionScope); both providers already ran scripts, so they now agree with each other and with their contract rather than with Node. Test: test_41 NativeFunctionsRunAtRelease, both engines with no guard. A cleanup hook, a value's finalizer and the instance-data finalizer each call a function napi_create_function made before the release, from native code and from a script, and make a serdes binding and round-trip a value through it from a script. Before this commit, QuickJS failed each with "napi_call_function 10: Null NAPI env" and no call reached the function; V8 passed. Co-Authored-By: Claude Opus 5.5 --- include/unofficial_napi.h | 6 +- quickjs/src/internal/napi_function.cc | 4 +- tests/runners/test_41_instance_data.cc | 139 +++++++++++++++++++++++++ 3 files changed, 146 insertions(+), 3 deletions(-) diff --git a/include/unofficial_napi.h b/include/unofficial_napi.h index 126147de73..3c0682dd4d 100644 --- a/include/unofficial_napi.h +++ b/include/unofficial_napi.h @@ -274,8 +274,10 @@ NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_attach_env( // only the finalizer's own exception is dropped, and one that JS is throwing, // or that a hook has pending, is kept. Each runs on the env's thread, in the // env's realm (also when another realm was entered when the release began), -// with N-API usable. References made with napi_create_reference keep their -// values until all of them have run. A finalizer the engine would call after +// with N-API usable: scripts run, and so do the native functions they or +// native code call (napi_create_function, napi_define_class, the serdes +// binding). Node runs no JavaScript there. References made with +// napi_create_reference keep their values until all of them have run. A finalizer the engine would call after // this pass, while it frees the engine instance, is dropped, and nothing // touches the env once it is freed. NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_release_env( diff --git a/quickjs/src/internal/napi_function.cc b/quickjs/src/internal/napi_function.cc index 3499399eb8..aab441d5d0 100644 --- a/quickjs/src/internal/napi_function.cc +++ b/quickjs/src/internal/napi_function.cc @@ -103,7 +103,9 @@ JSValue invoke_callback(JSContext *caller_ctx, JSValue *func_data) { auto env = napi_external__::get_env(func_data[0]); - if (!napi_util__::check_env(env) || env->is_closing()) + // The release's hooks and finalizers can use N-API, native functions too + // (unofficial_napi_release_env); once they are done no user code runs. + if (!napi_util__::check_env(env) || env->finalizers_done()) return JS_ThrowReferenceError(caller_ctx, "Null NAPI env"); // Closes the scopes the callback leaves open once everything below is done. napi_realm_frame_scope__ realm_frame{env, realm_ctx, realm_anchor}; diff --git a/tests/runners/test_41_instance_data.cc b/tests/runners/test_41_instance_data.cc index d8d228a85e..a4fdff3db8 100644 --- a/tests/runners/test_41_instance_data.cc +++ b/tests/runners/test_41_instance_data.cc @@ -1376,3 +1376,142 @@ TEST_F(Test41InstanceData, StateMadeAtReleaseGoesWithTheEnv) { Release(s); } } + +namespace { + +// Native code reached from the release: a function napi_create_function made +// before it, called from native code and from a script, and the serdes +// binding, a pair of classes napi_define_class makes, made then and used from +// a script. +struct NativeAtRelease { + napi_env env = nullptr; + napi_ref function = nullptr; + int calls = 0; + std::vector results; +}; + +napi_value CountNativeCall(napi_env env, napi_callback_info info) { + void* data = nullptr; + napi_get_cb_info(env, info, nullptr, nullptr, nullptr, &data); + ++static_cast(data)->calls; + napi_value result = nullptr; + napi_create_int32(env, 7, &result); + return result; +} + +int32_t IntOr(napi_env env, napi_value value, int32_t otherwise) { + int32_t out = 0; + return value != nullptr && napi_get_value_int32(env, value, &out) == napi_ok ? out : otherwise; +} + +std::string UseNativeCode(NativeAtRelease* native) { + napi_env env = native->env; + napi_handle_scope scope = nullptr; + if (napi_open_handle_scope(env, &scope) != napi_ok) return "no handle scope"; + std::string outcome = "ok"; + napi_value global = nullptr; + napi_value function = nullptr; + napi_value result = nullptr; + napi_status status = napi_get_global(env, &global); + if (status == napi_ok) status = napi_get_reference_value(env, native->function, &function); + if (status == napi_ok) status = napi_call_function(env, global, function, 0, nullptr, &result); + if (status != napi_ok || IntOr(env, result, -1) != 7) { + outcome = "napi_call_function " + std::to_string(status); + } + napi_value source = nullptr; + if (outcome == "ok") { + result = nullptr; + status = napi_create_string_utf8(env, "nativeAtRelease() + 1", NAPI_AUTO_LENGTH, &source); + if (status == napi_ok) status = napi_run_script(env, source, &result); + if (status != napi_ok || IntOr(env, result, -1) != 8) { + outcome = "a script's call " + std::to_string(status); + } + } + napi_value serdes = nullptr; + if (outcome == "ok") { + result = nullptr; + status = unofficial_napi_create_serdes_binding(env, &serdes); + if (status == napi_ok) status = napi_set_named_property(env, global, "serdesAtRelease", serdes); + if (status == napi_ok) { + status = napi_create_string_utf8( + env, + "(() => {" + " const serializer = new serdesAtRelease.Serializer();" + " serializer.writeHeader();" + " serializer.writeValue({ a: [1, 2, 3] });" + " const deserializer = new serdesAtRelease.Deserializer(serializer.releaseBuffer());" + " deserializer.readHeader();" + " return deserializer.readValue().a[1];" + "})()", + NAPI_AUTO_LENGTH, &source); + } + if (status == napi_ok) status = napi_run_script(env, source, &result); + if (status != napi_ok || IntOr(env, result, -1) != 2) { + outcome = "serdes " + std::to_string(status); + } + } + bool pending = false; + if (napi_is_exception_pending(env, &pending) == napi_ok && pending) { + napi_value error = nullptr; + napi_value message = nullptr; + char text[128] = {}; + size_t length = 0; + napi_get_and_clear_last_exception(env, &error); + if (napi_get_named_property(env, error, "message", &message) == napi_ok && + napi_get_value_string_utf8(env, message, text, sizeof(text), &length) == napi_ok) { + outcome += std::string(": ") + text; + } + } + napi_close_handle_scope(env, scope); + return outcome; +} + +void HookUsingNativeCode(void* arg) { + auto* native = static_cast(arg); + native->results.push_back("cleanup hook: " + UseNativeCode(native)); +} + +void FinalizeUsingNativeCode(node_api_basic_env, void*, void* hint) { + auto* native = static_cast(hint); + native->results.push_back("finalizer: " + UseNativeCode(native)); +} + +void FinalizeInstanceDataUsingNativeCode(napi_env, void* data, void*) { + auto* native = static_cast(data); + native->results.push_back("instance-data finalizer: " + UseNativeCode(native)); +} + +} // namespace + +// The hooks and finalizers the release runs can use N-API, native functions +// too: one napi_create_function made, called from native code and from a +// script, and the serdes binding's classes. QuickJS refused every native +// callback once the release began ("Null NAPI env"), V8 none. +TEST_F(Test41InstanceData, NativeFunctionsRunAtRelease) { + EnvScope s(runtime_.get()); + NativeAtRelease native; + native.env = s.env; + napi_value function = nullptr; + ASSERT_EQ(napi_create_function(s.env, "nativeAtRelease", NAPI_AUTO_LENGTH, CountNativeCall, + &native, &function), + napi_ok); + ASSERT_EQ(napi_create_reference(s.env, function, 1, &native.function), napi_ok); + Keep(s.env, "nativeAtRelease", function); + EXPECT_EQ(UseNativeCode(&native), "ok") << "before the release"; + ASSERT_EQ(native.calls, 2); + native.calls = 0; + ASSERT_EQ(napi_add_env_cleanup_hook(s.env, HookUsingNativeCode, &native), napi_ok); + napi_value object = nullptr; + ASSERT_EQ(napi_create_object(s.env, &object), napi_ok); + ASSERT_EQ(napi_add_finalizer(s.env, object, nullptr, FinalizeUsingNativeCode, &native, nullptr), + napi_ok); + Keep(s.env, "finalized", object); + ASSERT_EQ(napi_set_instance_data(s.env, &native, FinalizeInstanceDataUsingNativeCode, nullptr), + napi_ok); + + Release(s); + EXPECT_EQ(native.results, + (std::vector{"cleanup hook: ok", "finalizer: ok", + "instance-data finalizer: ok"})); + EXPECT_EQ(native.calls, 6); +} From 6eebd497bfa896663a8e845259731ff2d5303a1b Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 21:38:36 -0800 Subject: [PATCH 094/150] Say an unassign callback's realm made outside a sweep waits for the next The release contract said that a realm an unassign callback makes "is unassigned in the same sweep, before the pass goes on" (from "Say a realm an unassign callback makes is unassigned in the same sweep"). That holds for the unassign callbacks NapiV8UnassignRealmTokens runs. But ReleaseCollectedRealms also runs unassign callbacks, for collected realms, inside unofficial_napi_create_realm and unofficial_napi_collect_garbage, which a hook or finalizer of the release may call. A realm such a callback makes keeps its token while the rest of the pass runs, and loses it at the first sweep after it, as any realm made while releasing (the general rule of "Say which finalizers' realms keep tokens until the next release pass"). Every token is still unassigned exactly once. The header and docs/realms.md now say both. Test: test_71 ARealmAnUnassignCallbackMakesOutsideASweepWaitsForTheNextOne (from the review), both engines with no guard; the token expectations are V8's only, since QuickJS accepts no token hooks. A newer finalizer makes realm A, lets it go and calls collect_garbage; there A's token is unassigned and its unassign callback makes realm B. An older finalizer of the same pass sees B's token still assigned, and every token is unassigned once. It pins the behaviour the text now describes, so it passes before this commit too; with the sentence read literally (B unassigned before the pass goes on) it failed in the review. Co-Authored-By: Claude Opus 5.5 --- docs/realms.md | 13 ++-- include/unofficial_napi.h | 11 +-- tests/runners/test_71_contextify_compat.cc | 80 ++++++++++++++++++++++ 3 files changed, 95 insertions(+), 9 deletions(-) diff --git a/docs/realms.md b/docs/realms.md index 26ce85f63b..80bd20f213 100644 --- a/docs/realms.md +++ b/docs/realms.md @@ -183,11 +183,14 @@ calls take a realm's global or sandbox. finalizer too) makes is pending until the release's next pass unassigns its token, so the finalizers after it in its pass still see the token assigned, unless the realm is collected and its record freed first. One - an unassign callback makes is unassigned in the same sweep, and what else - that callback makes is released as the rest (see - `unofficial_napi_release_env` in the header). Realms made before the - hooks were attached get no token. Both hooks run in the env's realm; at - release what they throw is dropped, as for the other hooks and + an unassign callback makes while a release sweep runs it is unassigned in + the same sweep; one made by an unassign callback that `create_realm` or + `collect_garbage` runs (for a collected realm, from a hook or finalizer of + the release) waits, as any realm made while releasing, for the first + sweep after it. What else an unassign callback makes is released as the + rest (see `unofficial_napi_release_env` in the header). Realms made + before the hooks were attached get no token. Both hooks run in the env's + realm; at release what they throw is dropped, as for the other hooks and finalizers. On `main` a context lived until release, so tokens were only unassigned then. QuickJS does not accept the hooks and never calls them, as on `main`. diff --git a/include/unofficial_napi.h b/include/unofficial_napi.h index 3c0682dd4d..4f85937362 100644 --- a/include/unofficial_napi.h +++ b/include/unofficial_napi.h @@ -260,10 +260,13 @@ NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_attach_env( // finalizers of 2 run, as main did. A realm a finalizer of 2 or the // instance-data finalizer makes is unassigned when the next pass begins: the // finalizers after it in 2 see its token still assigned. One an unassign -// callback makes is unassigned in the same sweep, before the pass goes on. -// So every token is unassigned once before the env is freed. What an -// unassign callback makes besides (values, hooks, instance data) is released -// as the rest. +// callback makes while a sweep runs it is unassigned in the same sweep, +// before the pass goes on. One made by an unassign callback that +// unofficial_napi_create_realm or unofficial_napi_collect_garbage runs (for +// a collected realm, from a hook or finalizer of the release) waits, as any +// realm made while releasing, for the first sweep after it. So every token +// is unassigned once before the env is freed. What an unassign callback +// makes besides (values, hooks, instance data) is released as the rest. // // After each hook, token callback and finalizer, an exception it left // pending is dropped: nothing can catch it then (Node's CallIntoModule drops diff --git a/tests/runners/test_71_contextify_compat.cc b/tests/runners/test_71_contextify_compat.cc index 43cd306311..b5b4195c98 100644 --- a/tests/runners/test_71_contextify_compat.cc +++ b/tests/runners/test_71_contextify_compat.cc @@ -2411,3 +2411,83 @@ TEST_F(Test71ContextifyCompat, AnImportAnUnassignHookMakesAfterTheLoadersCleanup EXPECT_TRUE(log.import_outcomes.empty()); #endif } + +namespace { + +// A finalizer of the release makes a realm and lets the collector free it, so +// that realm's unassign callback runs inside unofficial_napi_collect_garbage, +// outside the release's sweeps, and makes another realm. A finalizer of the +// same pass that runs after it records whether that realm still has its token. +struct UnassignOutsideASweep { + ReleaseTokens* log = nullptr; + // Token events while collect_garbage ran (V8: 'u' for the collected realm, + // 'a' for the one its unassign callback made). + size_t events_inside = 0; + void* made_by_unassign = nullptr; + bool freeing_ran = false; + bool later_ran_after = false; + bool assigned_at_later = false; +}; + +void FinalizerFreeingARealm(node_api_basic_env, void*, void* hint) { + auto* state = static_cast(hint); + ReleaseTokens* log = state->log; + MakeReleaseRealm(log); + const size_t made = log->made.size(); + const size_t events = log->events.size(); + log->unassign_makes = 1; + unofficial_napi_collect_garbage(log->env); + log->unassign_makes = 0; + state->events_inside = log->events.size() - events; + if (log->made.size() > made) state->made_by_unassign = log->made.back(); + state->freeing_ran = true; +} + +void FinalizerCheckingTheToken(node_api_basic_env, void*, void* hint) { + auto* state = static_cast(hint); + state->later_ran_after = state->freeing_ran; + state->assigned_at_later = + state->made_by_unassign != nullptr && + std::find(state->log->live.begin(), state->log->live.end(), state->made_by_unassign) != + state->log->live.end(); +} + +} // namespace + +// A realm an unassign callback makes is unassigned in the same sweep only +// when a sweep of the release runs that callback. One that +// unofficial_napi_collect_garbage runs (here inside a finalizer of the +// release) is in no sweep: the realm it makes keeps its token while the +// pass's later finalizers run, until the next pass begins, as a realm a +// finalizer makes itself. Token hooks are V8's only. +TEST_F(Test71ContextifyCompat, ARealmAnUnassignCallbackMakesOutsideASweepWaitsForTheNextOne) { + EnvScope s(runtime_.get()); + ReleaseTokens log; + AttachReleaseTokens(s, &log); + UnassignOutsideASweep state; + state.log = &log; + // Made first, so finalized after the other (most recent first). + napi_value later = nullptr; + ASSERT_EQ(napi_create_object(s.env, &later), napi_ok); + ASSERT_EQ(napi_add_finalizer(s.env, later, nullptr, FinalizerCheckingTheToken, &state, nullptr), + napi_ok); + KeepOnGlobal(s.env, "later", later); + napi_value first = nullptr; + ASSERT_EQ(napi_create_object(s.env, &first), napi_ok); + ASSERT_EQ(napi_add_finalizer(s.env, first, nullptr, FinalizerFreeingARealm, &state, nullptr), + napi_ok); + KeepOnGlobal(s.env, "first", first); + ReleaseTokensEnv(s); + EXPECT_TRUE(state.freeing_ran); + EXPECT_TRUE(state.later_ran_after) << "the finalizers ran in another order"; +#if defined(NAPI_TEST_ENGINE_V8) + ExpectEveryTokenUnassignedOnce(log, 2); + EXPECT_EQ(state.events_inside, 2u) << "the realm was not freed inside collect_garbage"; + ASSERT_NE(state.made_by_unassign, nullptr); + EXPECT_TRUE(state.assigned_at_later); +#else + ExpectEveryTokenUnassignedOnce(log, 1); + EXPECT_EQ(state.events_inside, 0u); + EXPECT_EQ(state.made_by_unassign, nullptr); +#endif +} From ff533898e26ab160ba64afba5b7e0c3c36b5524c Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 21:54:52 -0800 Subject: [PATCH 095/150] V8: evaluate a synthetic module whose steps are not a function SyntheticModuleEvaluationSteps, the evaluation steps of every synthetic module the provider makes, returned an empty MaybeLocal with nothing thrown when it found no env with module-wrap state, no record for the module, no wrapper or steps, or when napi_call_function failed with nothing pending. CreateSyntheticModule does not check that the steps are callable, so a synthetic module whose steps were `{}` or undefined got there: napi_call_function returned napi_function_expected without throwing, and V8, taking the empty result for a thrown exception, failed CHECK(has_exception()) and aborted the process (SIGTRAP). Found by the Codex review of the commits from "V8: reject an import() the module hooks have nothing to load with" to "Say an unassign callback's realm made outside a sweep waits for the next"; the code predates both lines. Steps that are gone or not a function are now none, as on QuickJS (initialize_synthetic_module skips them): the module evaluates and its exports stay undefined. When calling the steps fails, the callback returns empty only after throwing: their exception, or an Error when none is pending and execution is not terminating. Test: test_65 SyntheticModuleWhoseStepsAreNotAFunctionEvaluates, both engines with no guard, with `{}` and with undefined as the steps: evaluate returns napi_ok, nothing is pending, its promise resolves and the export is undefined. Before this commit, V8 aborted ("Check failed: has_exception()"); QuickJS passed. Co-Authored-By: Claude Opus 5.5 --- .../runners/test_65_unofficial_contextify.cc | 106 ++++++++++++++++++ v8/src/unofficial_napi_contextify.cc | 41 ++++--- 2 files changed, 130 insertions(+), 17 deletions(-) diff --git a/tests/runners/test_65_unofficial_contextify.cc b/tests/runners/test_65_unofficial_contextify.cc index 43d8c8537b..17e8d17fe6 100644 --- a/tests/runners/test_65_unofficial_contextify.cc +++ b/tests/runners/test_65_unofficial_contextify.cc @@ -1366,3 +1366,109 @@ TEST_F(Test65UnofficialContextify, DynamicImportFromACleanupHookAfterTheLoadersC << outcome; } } + +namespace { + +std::string ValueText(napi_env env, napi_value value) { + napi_value string = nullptr; + char text[256] = {}; + size_t length = 0; + if (value == nullptr || napi_coerce_to_string(env, value, &string) != napi_ok || + napi_get_value_string_utf8(env, string, text, sizeof(text), &length) != napi_ok) { + return ""; + } + return std::string(text, length); +} + +// Takes the pending exception: its message, or "" when none was pending. +std::string TakePendingMessage(napi_env env) { + bool pending = false; + if (napi_is_exception_pending(env, &pending) != napi_ok || !pending) return ""; + napi_value error = nullptr; + napi_value message = nullptr; + if (napi_get_and_clear_last_exception(env, &error) != napi_ok) return ""; + if (napi_get_named_property(env, error, "message", &message) != napi_ok) return ""; + return ValueText(env, message); +} + +// How `promise` settles once the microtasks have run: "resolved", or +// "rejected: ". +std::string PromiseOutcome(napi_env env, napi_value promise) { + napi_value global = nullptr; + napi_value outcome = nullptr; + if (promise == nullptr || napi_get_global(env, &global) != napi_ok || + napi_set_named_property(env, global, "settling", promise) != napi_ok || + napi_run_script(env, + Str(env, + "globalThis.outcome = 'pending';" + "Promise.resolve(settling).then(() => { outcome = 'resolved'; }," + " (e) => { outcome = 'rejected: ' + (e && e.message); });" + "0"), + &outcome) != napi_ok) { + return ""; + } + RunMicrotasks(env); + if (napi_get_named_property(env, global, "outcome", &outcome) != napi_ok) return ""; + return ValueText(env, outcome); +} + +struct Evaluated { + napi_status evaluate = napi_generic_failure; + std::string pending; + std::string outcome; + napi_value ns = nullptr; +}; + +// Creates the module, links it to nothing, instantiates and evaluates it. +Evaluated CreateAndEvaluate(napi_env env, const unofficial_napi_module_create_options& options) { + Evaluated out; + unofficial_napi_module_create_result created{}; + EXPECT_EQ(unofficial_napi_module_wrap_create(env, &options, &created), napi_ok); + if (created.module == nullptr) return out; + EXPECT_EQ(unofficial_napi_module_wrap_link(env, created.module, 0, nullptr), napi_ok); + EXPECT_EQ(unofficial_napi_module_wrap_instantiate(env, created.module), napi_ok); + napi_value result = nullptr; + out.evaluate = unofficial_napi_module_wrap_evaluate(env, created.module, -1, false, &result); + out.pending = TakePendingMessage(env); + if (out.evaluate == napi_ok) out.outcome = PromiseOutcome(env, result); + EXPECT_EQ(unofficial_napi_module_wrap_get_namespace(env, created.module, &out.ns), napi_ok); + EXPECT_EQ(unofficial_napi_module_wrap_destroy(env, created.module), napi_ok); + return out; +} + +} // namespace + +// A synthetic module whose evaluation steps are not a function has none to +// run: it evaluates, and its exports stay undefined. V8's evaluation steps +// callback returned no result with nothing thrown there, and V8 aborts the +// process on that (CHECK has_exception()); QuickJS skipped the steps. +TEST_F(Test65UnofficialContextify, SyntheticModuleWhoseStepsAreNotAFunctionEvaluates) { + for (const char* steps_source : {"({})", "undefined"}) { + SCOPED_TRACE(steps_source); + EnvScope s(runtime_.get()); + napi_value wrapper = nullptr; + napi_value names = nullptr; + napi_value steps = nullptr; + ASSERT_EQ(napi_create_object(s.env, &wrapper), napi_ok); + ASSERT_EQ(napi_run_script(s.env, Str(s.env, "['value']"), &names), napi_ok); + ASSERT_EQ(napi_run_script(s.env, Str(s.env, steps_source), &steps), napi_ok); + unofficial_napi_module_create_options options{}; + options.size = sizeof(options); + options.version = UNOFFICIAL_NAPI_MODULE_CREATE_OPTIONS_VERSION; + options.kind = unofficial_napi_module_synthetic; + options.wrapper = wrapper; + options.url = Str(s.env, "synthetic"); + options.payload.synthetic.export_names = names; + options.payload.synthetic.synthetic_evaluation_steps = steps; + const Evaluated evaluated = CreateAndEvaluate(s.env, options); + EXPECT_EQ(evaluated.evaluate, napi_ok); + EXPECT_EQ(evaluated.pending, ""); + EXPECT_EQ(evaluated.outcome, "resolved"); + napi_value value = nullptr; + napi_valuetype type = napi_null; + ASSERT_NE(evaluated.ns, nullptr); + ASSERT_EQ(napi_get_named_property(s.env, evaluated.ns, "value", &value), napi_ok); + ASSERT_EQ(napi_typeof(s.env, value, &type), napi_ok); + EXPECT_EQ(type, napi_undefined); + } +} diff --git a/v8/src/unofficial_napi_contextify.cc b/v8/src/unofficial_napi_contextify.cc index 827eacf9fa..4060a982c9 100644 --- a/v8/src/unofficial_napi_contextify.cc +++ b/v8/src/unofficial_napi_contextify.cc @@ -1104,32 +1104,39 @@ v8::MaybeLocal ModuleResolveSourceCallback(v8::Local co v8::MaybeLocal SyntheticModuleEvaluationSteps(v8::Local context, v8::Local module) { - napi_env env = GetModuleWrapEnvForIsolate(context->GetIsolate()); - if (env == nullptr) return v8::MaybeLocal(); - ModuleWrapRecord* record = FindModuleRecordForModule(env, module); - if (record == nullptr) return v8::MaybeLocal(); - - napi_value wrapper = GetRefValue(env, record->wrapper_ref); - napi_value callback = GetRefValue(env, record->synthetic_eval_steps_ref); - if (wrapper == nullptr || callback == nullptr) return v8::MaybeLocal(); - - napi_value ignored = nullptr; - if (napi_call_function(env, wrapper, callback, 0, nullptr, &ignored) != napi_ok) { - bool pending = false; - if (napi_is_exception_pending(env, &pending) == napi_ok && pending) { + v8::Isolate* isolate = context->GetIsolate(); + napi_env env = GetModuleWrapEnvForIsolate(isolate); + ModuleWrapRecord* record = env != nullptr ? FindModuleRecordForModule(env, module) : nullptr; + napi_value wrapper = record != nullptr ? GetRefValue(env, record->wrapper_ref) : nullptr; + napi_value callback = + record != nullptr ? GetRefValue(env, record->synthetic_eval_steps_ref) : nullptr; + napi_valuetype callback_type = napi_undefined; + // Steps that are gone or not a function are none, as on QuickJS: the module + // evaluates and its exports stay undefined. V8 takes an empty result for an + // exception thrown and aborts the process when none was, so this returns + // one only after throwing. + if (wrapper != nullptr && callback != nullptr && + napi_typeof(env, callback, &callback_type) == napi_ok && callback_type == napi_function) { + napi_value ignored = nullptr; + if (napi_call_function(env, wrapper, callback, 0, nullptr, &ignored) != napi_ok) { + bool pending = false; napi_value error = nullptr; - if (napi_get_and_clear_last_exception(env, &error) == napi_ok && error != nullptr) { - context->GetIsolate()->ThrowException(napi_v8_unwrap_value(error)); + if (napi_is_exception_pending(env, &pending) == napi_ok && pending && + napi_get_and_clear_last_exception(env, &error) == napi_ok && error != nullptr) { + isolate->ThrowException(napi_v8_unwrap_value(error)); + } else if (!isolate->IsExecutionTerminating()) { + isolate->ThrowException(v8::Exception::Error( + v8::String::NewFromUtf8Literal(isolate, "Synthetic module evaluation failed"))); } + return v8::MaybeLocal(); } - return v8::MaybeLocal(); } v8::Local resolver; if (!v8::Promise::Resolver::New(context).ToLocal(&resolver)) { return v8::MaybeLocal(); } - if (resolver->Resolve(context, v8::Undefined(context->GetIsolate())).IsNothing()) { + if (resolver->Resolve(context, v8::Undefined(isolate)).IsNothing()) { return v8::MaybeLocal(); } return resolver->GetPromise(); From c5e1739bd3adb0cfb0f950e51df8f9b5423701ac Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 21:55:02 -0800 Subject: [PATCH 096/150] V8: throw what the import.meta callback throws from import.meta HostInitializeImportMetaObject called the module hooks' import.meta callback through napi_call_function and ignored its failure. What the callback threw stayed in N-API's pending exception: the module ran on past import.meta, its evaluation returned napi_ok with a promise that resolved, and the error surfaced from whatever N-API call next checked for one. Node's callback rethrows it (ModuleWrap's HostInitializeImportMetaObjectCallback), and QuickJS's initialize_import_meta returns -1 so the module throws. Found by the Codex review of the commits from "V8: reject an import() the module hooks have nothing to load with" to "Say an unassign callback's realm made outside a sweep waits for the next"; the code predates both lines. The callback's exception is now taken from N-API and thrown into V8, from the import.meta expression: the module stops there and its evaluation rejects with it. A callback that is not a function still does nothing. Test: test_65 ImportMetaCallbackExceptionThrowsFromTheModule, both engines with no guard: a module runs `continued = 'no'; import.meta; continued = 'yes'` with a callback that throws Error('meta'). Evaluate returns napi_ok with nothing pending, its promise rejects with 'meta', `continued` is 'no' and the callback ran once. Before this commit, V8 left 'meta' pending after evaluate, the promise resolved and `continued` was 'yes'; QuickJS passed. Co-Authored-By: Claude Opus 5.5 --- .../runners/test_65_unofficial_contextify.cc | 46 +++++++++++++++++++ v8/src/unofficial_napi_contextify.cc | 12 ++++- 2 files changed, 57 insertions(+), 1 deletion(-) diff --git a/tests/runners/test_65_unofficial_contextify.cc b/tests/runners/test_65_unofficial_contextify.cc index 17e8d17fe6..e0d943dea3 100644 --- a/tests/runners/test_65_unofficial_contextify.cc +++ b/tests/runners/test_65_unofficial_contextify.cc @@ -1472,3 +1472,49 @@ TEST_F(Test65UnofficialContextify, SyntheticModuleWhoseStepsAreNotAFunctionEvalu EXPECT_EQ(type, napi_undefined); } } + +// What the import.meta callback throws is thrown from the import.meta +// expression, as in Node (ModuleWrap's callback rethrows it): the module stops +// there, and its evaluation rejects with it. V8 left it in N-API's pending +// exception instead: the module ran on, and the error surfaced from the next +// N-API call that checked for one. +TEST_F(Test65UnofficialContextify, ImportMetaCallbackExceptionThrowsFromTheModule) { + EnvScope s(runtime_.get()); + napi_value meta = nullptr; + ASSERT_EQ(napi_run_script(s.env, + Str(s.env, + "globalThis.metaCalls = 0;" + "(id, meta, wrap) => { metaCalls++; throw new Error('meta'); }"), + &meta), + napi_ok); + unofficial_napi_module_hooks hooks{}; + hooks.size = sizeof(hooks); + hooks.version = UNOFFICIAL_NAPI_MODULE_HOOKS_VERSION; + hooks.initialize_import_meta_object = meta; + ASSERT_EQ(unofficial_napi_module_wrap_set_hooks(s.env, &hooks), napi_ok); + napi_value wrapper = nullptr; + napi_value undefined = nullptr; + ASSERT_EQ(napi_create_object(s.env, &wrapper), napi_ok); + ASSERT_EQ(napi_get_undefined(s.env, &undefined), napi_ok); + const unofficial_napi_js_source source = unofficial_napi_js_source_from_text( + Str(s.env, "globalThis.continued = 'no'; import.meta; globalThis.continued = 'yes';")); + unofficial_napi_module_create_options options{}; + options.size = sizeof(options); + options.version = UNOFFICIAL_NAPI_MODULE_CREATE_OPTIONS_VERSION; + options.kind = unofficial_napi_module_source_text; + options.wrapper = wrapper; + options.url = Str(s.env, "meta.mjs"); + options.payload.source_text.source = &source; + options.payload.source_text.host_defined_option_id = undefined; + const Evaluated evaluated = CreateAndEvaluate(s.env, options); + EXPECT_EQ(evaluated.evaluate, napi_ok); + EXPECT_EQ(evaluated.pending, "") << "left pending by the evaluation"; + EXPECT_EQ(evaluated.outcome, "rejected: meta"); + napi_value continued = nullptr; + napi_value calls = nullptr; + ASSERT_EQ(napi_run_script(s.env, Str(s.env, "continued"), &continued), napi_ok); + ASSERT_EQ(napi_run_script(s.env, Str(s.env, "metaCalls"), &calls), napi_ok); + EXPECT_EQ(ValueText(s.env, continued), "no"); + EXPECT_EQ(ValueText(s.env, calls), "1"); + EXPECT_EQ(TakePendingMessage(s.env), ""); +} diff --git a/v8/src/unofficial_napi_contextify.cc b/v8/src/unofficial_napi_contextify.cc index 4060a982c9..4aae857d4e 100644 --- a/v8/src/unofficial_napi_contextify.cc +++ b/v8/src/unofficial_napi_contextify.cc @@ -1311,7 +1311,17 @@ void HostInitializeImportMetaObject(v8::Local context, napi_value ignored = nullptr; napi_value global = nullptr; napi_get_global(env, &global); - (void)napi_call_function(env, global, callback, 3, argv, &ignored); + if (napi_call_function(env, global, callback, 3, argv, &ignored) != napi_ok) { + // What the callback threw is thrown from the import.meta expression, as + // Node's callback rethrows it; left in N-API's pending exception, it + // would surface from whatever N-API call came next. + bool pending = false; + napi_value error = nullptr; + if (napi_is_exception_pending(env, &pending) == napi_ok && pending && + napi_get_and_clear_last_exception(env, &error) == napi_ok && error != nullptr) { + env->isolate->ThrowException(napi_v8_unwrap_value(error)); + } + } } v8::MaybeLocal LinkRequiredFacadeOriginal(v8::Local context, From 9d4c25f953612fd8b3005308a45d0a152fa0abe9 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 21:55:11 -0800 Subject: [PATCH 097/150] Refuse to release an env again while its release runs, on both engines Neither provider guarded unofficial_napi_release_env against being called for an owner whose release was already running. A cleanup hook or finalizer that released its own env, or (on QuickJS since "QuickJS: run native callbacks from the release's hooks and finalizers", which lets native callbacks run during the release) a native function a hook's script called, freed the env and its engine instance (QuickJS context and runtime, V8 isolate) under the release that was running, which then crashed (SIGSEGV on both). Found by the Codex review of the commits from "V8: reject an import() the module hooks have nothing to load with" to "Say an unassign callback's realm made outside a sweep waits for the next"; the direct-hook path predates both lines. Each owner now records that its release is running, and a call for it meanwhile returns napi_invalid_arg and does nothing; the release under way goes on. The header says so. It also reflows the paragraph "QuickJS: run native callbacks from the release's hooks and finalizers" left with an overlong line. Test: test_41 ReleasingAnEnvWhileItsReleaseRunsIsRefused, both engines with no guard: a cleanup hook, a native function a later hook's script calls, and a value's finalizer each call unofficial_napi_release_env on the env's own owner. Each gets napi_invalid_arg, the script returns napi_ok, the finalizer runs once and the outer release returns napi_ok. Before this commit, it crashed with SIGSEGV on V8 and on QuickJS. Co-Authored-By: Claude Opus 5.5 --- include/unofficial_napi.h | 9 ++- quickjs/src/unofficial_napi.cc | 7 +++ tests/runners/test_41_instance_data.cc | 78 ++++++++++++++++++++++++++ v8/src/unofficial_napi.cc | 6 ++ 4 files changed, 97 insertions(+), 3 deletions(-) diff --git a/include/unofficial_napi.h b/include/unofficial_napi.h index 4f85937362..9ccd39ce30 100644 --- a/include/unofficial_napi.h +++ b/include/unofficial_napi.h @@ -280,9 +280,12 @@ NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_attach_env( // with N-API usable: scripts run, and so do the native functions they or // native code call (napi_create_function, napi_define_class, the serdes // binding). Node runs no JavaScript there. References made with -// napi_create_reference keep their values until all of them have run. A finalizer the engine would call after -// this pass, while it frees the engine instance, is dropped, and nothing -// touches the env once it is freed. +// napi_create_reference keep their values until all of them have run. A +// finalizer the engine would call after this pass, while it frees the engine +// instance, is dropped, and nothing touches the env once it is freed. Called +// again for the same owner while its release runs (from a hook, a finalizer +// or a native function they reach), it returns napi_invalid_arg and does +// nothing; the release under way goes on. NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_release_env( unofficial_napi_env_owner owner, struct uv_loop_s* loop_or_null); diff --git a/quickjs/src/unofficial_napi.cc b/quickjs/src/unofficial_napi.cc index ee124118ca..a0c29c7501 100644 --- a/quickjs/src/unofficial_napi.cc +++ b/quickjs/src/unofficial_napi.cc @@ -45,6 +45,8 @@ namespace JSContext *ctx = nullptr; std::unique_ptr agent; napi_env env = nullptr; + // Set while unofficial_napi_release_env runs for this owner. + bool releasing = false; }; napi_status DestroyEnvInstance(napi_env env) @@ -65,6 +67,11 @@ namespace return napi_invalid_arg; auto *scope = reinterpret_cast(owner); + // A hook, a finalizer or a native function the release runs may call + // it again: that call is refused, and the release under way goes on. + if (scope->releasing) + return napi_invalid_arg; + scope->releasing = true; napi_status status = napi_ok; napi_env env_to_delete = nullptr; if (scope->env != nullptr) diff --git a/tests/runners/test_41_instance_data.cc b/tests/runners/test_41_instance_data.cc index a4fdff3db8..fdb9769fb3 100644 --- a/tests/runners/test_41_instance_data.cc +++ b/tests/runners/test_41_instance_data.cc @@ -1515,3 +1515,81 @@ TEST_F(Test41InstanceData, NativeFunctionsRunAtRelease) { "instance-data finalizer: ok"})); EXPECT_EQ(native.calls, 6); } + +namespace { + +// Calls to release an env again while its release runs, and what each +// returned. +struct ReleasingAgain { + unofficial_napi_env_owner owner = nullptr; + std::vector statuses; + int finalized = 0; +}; + +void HookReleasingItsOwnEnv(void* arg) { + auto* again = static_cast(arg); + again->statuses.push_back(unofficial_napi_release_env(again->owner, nullptr)); +} + +napi_value ReleaseFromANativeFunction(napi_env env, napi_callback_info info) { + void* data = nullptr; + napi_get_cb_info(env, info, nullptr, nullptr, nullptr, &data); + auto* again = static_cast(data); + again->statuses.push_back(unofficial_napi_release_env(again->owner, nullptr)); + napi_value undefined = nullptr; + napi_get_undefined(env, &undefined); + return undefined; +} + +struct HookScript { + napi_env env = nullptr; + napi_status status = napi_generic_failure; +}; + +void HookRunningAScriptThatReleases(void* arg) { + auto* hook = static_cast(arg); + napi_value source = nullptr; + napi_value result = nullptr; + napi_create_string_utf8(hook->env, "releaseAgain()", NAPI_AUTO_LENGTH, &source); + hook->status = napi_run_script(hook->env, source, &result); +} + +void FinalizeReleasingAgain(node_api_basic_env, void*, void* hint) { + auto* again = static_cast(hint); + ++again->finalized; + again->statuses.push_back(unofficial_napi_release_env(again->owner, nullptr)); +} + +} // namespace + +// unofficial_napi_release_env called again for an env while its release runs +// (from a cleanup hook, from a native function a hook's script calls, from a +// finalizer) returns napi_invalid_arg and does nothing; the release under way +// goes on and finishes. Both providers freed the env and its engine instance +// under the release that was running, which then crashed. +TEST_F(Test41InstanceData, ReleasingAnEnvWhileItsReleaseRunsIsRefused) { + EnvScope s(runtime_.get()); + ReleasingAgain again; + again.owner = s.scope; + HookScript hook; + hook.env = s.env; + napi_value function = nullptr; + ASSERT_EQ(napi_create_function(s.env, "releaseAgain", NAPI_AUTO_LENGTH, + ReleaseFromANativeFunction, &again, &function), + napi_ok); + Keep(s.env, "releaseAgain", function); + // Most recent first: the hook that releases, then the script. + ASSERT_EQ(napi_add_env_cleanup_hook(s.env, HookRunningAScriptThatReleases, &hook), napi_ok); + ASSERT_EQ(napi_add_env_cleanup_hook(s.env, HookReleasingItsOwnEnv, &again), napi_ok); + napi_value object = nullptr; + ASSERT_EQ(napi_create_object(s.env, &object), napi_ok); + ASSERT_EQ(napi_add_finalizer(s.env, object, nullptr, FinalizeReleasingAgain, &again, nullptr), + napi_ok); + Keep(s.env, "finalized", object); + + Release(s); + EXPECT_EQ(hook.status, napi_ok); + EXPECT_EQ(again.statuses, + (std::vector{napi_invalid_arg, napi_invalid_arg, napi_invalid_arg})); + EXPECT_EQ(again.finalized, 1); +} diff --git a/v8/src/unofficial_napi.cc b/v8/src/unofficial_napi.cc index 648182126e..100b6c851e 100644 --- a/v8/src/unofficial_napi.cc +++ b/v8/src/unofficial_napi.cc @@ -58,6 +58,8 @@ struct UnofficialEnvScope { std::optional> context; std::optional context_scope; napi_env env = nullptr; + // Set while unofficial_napi_release_env runs for this owner. + bool releasing = false; explicit UnofficialEnvScope( v8::Isolate* isolate_in, @@ -1933,6 +1935,10 @@ napi_status ReleaseEnvScope(unofficial_napi_env_owner owner, void* shutdown_pump_handle) { if (owner == nullptr) return napi_invalid_arg; auto* scope = reinterpret_cast(owner); + // A hook, a finalizer or a native function the release runs may call it + // again: that call is refused, and the release under way goes on. + if (scope->releasing) return napi_invalid_arg; + scope->releasing = true; napi_status status = napi_ok; if (scope->env != nullptr) { From 920dbd6fb0bdf96adcf4e7084b3eeb1532cc52e7 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 21:55:22 -0800 Subject: [PATCH 098/150] Pin each engine's outcome of an import() at release, in test_65 DynamicImportFromACleanupHookAfterTheLoadersCleanupHookSettles (from "V8: reject an import() the module hooks have nothing to load with") accepted a rejection or a resolution on either engine, so a regression that let QuickJS's loader drop its hooks early, or kept V8's loader holding them, would still pass. Codex review of the commits from "V8: reject an import() the module hooks have nothing to load with" to "Say an unassign callback's realm made outside a sweep waits for the next". It now expects each engine's own outcome for all three imports: V8's loader lets go of its hooks in its cleanup hook, so the import() rejects; QuickJS's keeps them until the release's pass is over, so they load it. That is provider behaviour, not a contract, hence the engine guard on the expectation only. It passed on both engines before and after. Co-Authored-By: Claude Opus 5.5 --- tests/runners/test_65_unofficial_contextify.cc | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/tests/runners/test_65_unofficial_contextify.cc b/tests/runners/test_65_unofficial_contextify.cc index e0d943dea3..31bf97a5c3 100644 --- a/tests/runners/test_65_unofficial_contextify.cc +++ b/tests/runners/test_65_unofficial_contextify.cc @@ -1328,11 +1328,12 @@ void ImportAfterTheLoadersCleanupHook(void* arg) { } // namespace // An import() a cleanup hook makes at release, after the module loader's own -// cleanup hook, returns a promise that settles. On V8 the loader's hook has -// let go of the hooks, so it rejects; QuickJS's loader keeps its hooks until -// the release's pass is over, so they load it. On V8 the import callback the +// cleanup hook, returns a promise that settles. On V8 the import callback the // hooks installed, still the isolate's, found no loader state there and // returned no promise with nothing thrown, and V8 aborts the process on that. +// How it settles is the providers' own: V8's loader lets go of its hooks in +// its cleanup hook, so the import() rejects; QuickJS's loader keeps them +// until the release's pass is over, so they load it. TEST_F(Test65UnofficialContextify, DynamicImportFromACleanupHookAfterTheLoadersCleanupHookSettles) { ImportsAtRelease imports; { @@ -1360,11 +1361,12 @@ TEST_F(Test65UnofficialContextify, DynamicImportFromACleanupHookAfterTheLoadersC s.env = nullptr; } EXPECT_TRUE(imports.ran); - ASSERT_EQ(imports.outcomes.size(), 3u); - for (const std::string& outcome : imports.outcomes) { - EXPECT_TRUE(outcome == "returned, rejected" || outcome == "returned, resolved:hooks") - << outcome; - } +#if defined(NAPI_TEST_ENGINE_V8) + const std::string expected = "returned, rejected"; +#else + const std::string expected = "returned, resolved:hooks"; +#endif + EXPECT_EQ(imports.outcomes, std::vector(3, expected)); } namespace { From 1f10832c1d1fa8965c6de11d0cd046890667b1fb Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 23:13:00 -0800 Subject: [PATCH 099/150] V8: keep a termination the module hooks run into The import.meta callback, a synthetic module's evaluation steps and the module hooks' import() callback call JS through napi_call_function and, when it fails, take N-API's pending exception and throw it into V8. When the JS they called was terminated (a native call to unofficial_napi_terminate_execution, as EdgeJS's process.exit() and worker.terminate() make), what is pending is the null a TryCatch records for a termination, and ThrowException(null) replaced the termination with a catchable throw of null: the module, or the JS that evaluated it or called import(), caught it and ran on, and the termination was gone. The Codex review of "V8: throw what the import.meta callback throws from import.meta" found it in the import.meta callback and the synthetic steps; the import() callback had it too (it looked for a termination only after rethrowing). The three now go through napi_v8_rethrow_pending_exception, which drops what is pending and throws nothing while V8 terminates, as the callback trampoline (HandleCallbackException) and Node's callbacks do, and otherwise throws it as before. The callbacks still return an empty result only with an exception thrown or a termination unwinding. Test: test_72 (new), both engines with no guard: ImportMetaCallback, SyntheticModuleEvaluationSteps, DynamicImportCallback. Each callback terminates and calls a JS function (as Node's process.exit() does, so that V8 acts at once), terminates and then throws, or calls native code that terminates and then throws; the module's own code, and the script that evaluates it or calls import(), wrap it in try/catch and set flags in the catch and after. The run must come back napi_pending_exception with an exception pending, no flag set, and the env usable once the termination is cancelled. Before this commit, V8 failed all nine cases: the import.meta module caught null and ran on ("innerCaught=yes innerAfter=yes error=null"); for the synthetic steps and import() the script caught null, ran on, and the run returned napi_ok with nothing pending. QuickJS passed: the callbacks' JS_Call keeps its uncatchable error. test_65's ImportMetaCallbackExceptionThrowsFromTheModule and SyntheticModuleWhoseStepsAreNotAFunctionEvaluates still pass. Co-Authored-By: Claude Opus 5.5 --- tests/CMakeLists.txt | 3 + .../runners/test_72_hooks_keep_termination.cc | 255 ++++++++++++++++++ v8/src/internal/napi_v8_env.h | 10 + v8/src/js_native_api_v8.cc | 19 ++ v8/src/unofficial_napi_contextify.cc | 32 +-- 5 files changed, 296 insertions(+), 23 deletions(-) create mode 100644 tests/runners/test_72_hooks_keep_termination.cc diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt index 51cc295e5a..7eab25d4c7 100644 --- a/tests/CMakeLists.txt +++ b/tests/CMakeLists.txt @@ -339,6 +339,9 @@ add_fixture_test(${_napi_test_prefix}_test_70_realm_entry_attack add_fixture_test(${_napi_test_prefix}_test_71_contextify_compat runners/test_71_contextify_compat.cc ) +add_fixture_test(${_napi_test_prefix}_test_72_hooks_keep_termination + runners/test_72_hooks_keep_termination.cc +) if(_napi_test_engine STREQUAL "v8") # Only the V8 provider posts engine tasks through the enqueue hook. add_fixture_test(${_napi_test_prefix}_test_66_foreground_task_handoff diff --git a/tests/runners/test_72_hooks_keep_termination.cc b/tests/runners/test_72_hooks_keep_termination.cc new file mode 100644 index 0000000000..fe1dabb954 --- /dev/null +++ b/tests/runners/test_72_hooks_keep_termination.cc @@ -0,0 +1,255 @@ +// A termination (unofficial_napi_terminate_execution, as EdgeJS's +// process.exit() and worker.terminate() use it) that reaches a callback the +// provider runs JS from for the engine (a module hook, a promise hook, a +// serializer hook, the default import() helper) must come back out of it as a +// termination: what the callback caught is not thrown again as a catchable +// exception, and the JS that led there stops. +// +// The JS here asks for it as Node's process.exit() does: a native call that +// terminates, then a call to a JS function, so that V8, which acts on a +// termination at its next stack check, acts on it at once. JS that runs on +// before V8 acts (and what it throws then) is V8's own behaviour. + +#include "test_env.h" + +#include "unofficial_napi.h" + +#include + +class Test72HooksKeepTermination : public FixtureTestBase {}; + +namespace { + +napi_value Str(napi_env env, const char* value) { + napi_value out = nullptr; + if (napi_create_string_utf8(env, value, NAPI_AUTO_LENGTH, &out) != napi_ok) return nullptr; + return out; +} + +napi_value Global(napi_env env) { + napi_value global = nullptr; + EXPECT_EQ(napi_get_global(env, &global), napi_ok); + return global; +} + +napi_value Terminate(napi_env env, napi_callback_info /*info*/) { + EXPECT_EQ(unofficial_napi_terminate_execution(env), napi_ok); + return nullptr; +} + +// Terminates and calls tick(), so that V8 acts on it. +void TerminateNow(napi_env env) { + EXPECT_EQ(unofficial_napi_terminate_execution(env), napi_ok); + napi_value tick = nullptr; + napi_value ignored = nullptr; + napi_get_named_property(env, Global(env), "tick", &tick); + napi_call_function(env, Global(env), tick, 0, nullptr, &ignored); +} + +// Terminates, then throws, like native code that goes on after it asked for +// the termination. +napi_value TerminateAndThrow(napi_env env, napi_callback_info /*info*/) { + TerminateNow(env); + napi_throw_error(env, nullptr, "after terminate"); + return nullptr; +} + +// Evaluates the module its data names and returns the evaluation's promise; +// what the evaluation left pending is the trampoline's to throw. +napi_value EvaluateModule(napi_env env, napi_callback_info info) { + void* data = nullptr; + if (napi_get_cb_info(env, info, nullptr, nullptr, nullptr, &data) != napi_ok) return nullptr; + napi_value result = nullptr; + if (unofficial_napi_module_wrap_evaluate( + env, static_cast(data), -1, false, &result) != napi_ok) { + return nullptr; + } + return result; +} + +void DefineGlobalFunction(napi_env env, const char* name, napi_callback cb, void* data = nullptr) { + napi_value fn = nullptr; + ASSERT_EQ(napi_create_function(env, name, NAPI_AUTO_LENGTH, cb, data, &fn), napi_ok); + ASSERT_EQ(napi_set_named_property(env, Global(env), name, fn), napi_ok); +} + +napi_status RunScript(napi_env env, const char* source) { + napi_value ignored = nullptr; + return napi_run_script(env, Str(env, source), &ignored); +} + +napi_value Eval(napi_env env, const char* source) { + napi_value result = nullptr; + EXPECT_EQ(napi_run_script(env, Str(env, source), &result), napi_ok) << source; + return result; +} + +std::string GlobalText(napi_env env, const char* name) { + napi_value value = nullptr; + napi_value string = nullptr; + char text[256] = {}; + size_t length = 0; + if (napi_get_named_property(env, Global(env), name, &value) != napi_ok || + napi_coerce_to_string(env, value, &string) != napi_ok || + napi_get_value_string_utf8(env, string, text, sizeof(text), &length) != napi_ok) { + return ""; + } + return std::string(text, length); +} + +// What EdgeJS does once the stack has unwound: take the pending exception, +// then cancel the termination. Returns whether one was pending. +bool FinishTermination(napi_env env) { + bool pending = false; + EXPECT_EQ(napi_is_exception_pending(env, &pending), napi_ok); + if (pending) { + napi_value exception = nullptr; + EXPECT_EQ(napi_get_and_clear_last_exception(env, &exception), napi_ok); + } + EXPECT_EQ(unofficial_napi_cancel_terminate_execution(env), napi_ok); + return pending; +} + +void InstallHelpers(napi_env env) { + DefineGlobalFunction(env, "terminate", Terminate); + DefineGlobalFunction(env, "terminateAndThrow", TerminateAndThrow); + // Each catch block sets its flag first, by a plain store, at which no + // engine looks for a termination. + ASSERT_EQ(RunScript(env, + "globalThis.tick = function tick() {};" + "globalThis.caught = 'no'; globalThis.after = 'no';" + "globalThis.innerCaught = 'no'; globalThis.innerAfter = 'no';" + "globalThis.caughtError = 'none';"), + napi_ok); +} + +// What the JS that led to the callback managed to do. +std::string Flags(napi_env env) { + return "caught=" + GlobalText(env, "caught") + " after=" + GlobalText(env, "after") + + " innerCaught=" + GlobalText(env, "innerCaught") + + " innerAfter=" + GlobalText(env, "innerAfter") + + " error=" + GlobalText(env, "caughtError"); +} + +constexpr char kNothingRan[] = "caught=no after=no innerCaught=no innerAfter=no error=none"; + +// Runs `script` and expects it to come back terminated, as test_67's runs do, +// with nothing it wrapped in try/catch caught, and nothing after that run. +void ExpectRunTerminated(napi_env env, const char* script) { + EXPECT_EQ(RunScript(env, script), napi_pending_exception); + EXPECT_TRUE(FinishTermination(env)) << "nothing pending after the run"; + EXPECT_EQ(Flags(env), kNothingRan); + // Cancelling leaves the env usable. + EXPECT_EQ(RunScript(env, "globalThis.resumed = 'yes';"), napi_ok); + EXPECT_EQ(GlobalText(env, "resumed"), "yes"); +} + +void SetModuleHooks(napi_env env, napi_value import_callback, napi_value meta_callback) { + unofficial_napi_module_hooks hooks{}; + hooks.size = sizeof(hooks); + hooks.version = UNOFFICIAL_NAPI_MODULE_HOOKS_VERSION; + hooks.import_module_dynamically = import_callback; + hooks.initialize_import_meta_object = meta_callback; + ASSERT_EQ(unofficial_napi_module_wrap_set_hooks(env, &hooks), napi_ok); +} + +// A linked and instantiated module: source text, or synthetic with `steps` +// when `source_text` is null. +unofficial_napi_module MakeModule(napi_env env, const char* source_text, napi_value steps) { + napi_value wrapper = nullptr; + napi_value undefined = nullptr; + EXPECT_EQ(napi_create_object(env, &wrapper), napi_ok); + EXPECT_EQ(napi_get_undefined(env, &undefined), napi_ok); + unofficial_napi_module_create_options options{}; + options.size = sizeof(options); + options.version = UNOFFICIAL_NAPI_MODULE_CREATE_OPTIONS_VERSION; + options.wrapper = wrapper; + unofficial_napi_js_source source{}; + if (source_text != nullptr) { + source = unofficial_napi_js_source_from_text(Str(env, source_text)); + options.kind = unofficial_napi_module_source_text; + options.url = Str(env, "hooked.mjs"); + options.payload.source_text.source = &source; + options.payload.source_text.host_defined_option_id = undefined; + } else { + options.kind = unofficial_napi_module_synthetic; + options.url = Str(env, "synthetic"); + options.payload.synthetic.export_names = Eval(env, "['value']"); + options.payload.synthetic.synthetic_evaluation_steps = steps; + } + unofficial_napi_module_create_result created{}; + EXPECT_EQ(unofficial_napi_module_wrap_create(env, &options, &created), napi_ok); + if (created.module == nullptr) return nullptr; + EXPECT_EQ(unofficial_napi_module_wrap_link(env, created.module, 0, nullptr), napi_ok); + EXPECT_EQ(unofficial_napi_module_wrap_instantiate(env, created.module), napi_ok); + return created.module; +} + +// The callback bodies: it terminates; it terminates, then throws; a native +// function it calls terminates, then throws. +constexpr const char* kTerminatingBodies[] = { + "{ terminate(); tick(); }", + "{ terminate(); tick(); throw new Error('after terminate'); }", + "{ terminateAndThrow(); }", +}; + +constexpr char kEvaluateModuleInTryCatch[] = + "try { evaluateModule(); } catch (e) { caught = 'yes'; caughtError = e; }\n" + "after = 'yes';\n"; + +} // namespace + +// The import.meta callback. V8 threw the null its TryCatch records for the +// termination from the import.meta expression: the module caught it and ran +// on, and the termination was gone. +TEST_F(Test72HooksKeepTermination, ImportMetaCallback) { + for (const char* body : kTerminatingBodies) { + SCOPED_TRACE(body); + EnvScope s(runtime_.get()); + InstallHelpers(s.env); + const std::string callback = std::string("(id, meta, wrap) => ") + body; + SetModuleHooks(s.env, nullptr, Eval(s.env, callback.c_str())); + unofficial_napi_module module = MakeModule( + s.env, + "try { import.meta; } catch (e) { globalThis.innerCaught = 'yes'; caughtError = e; }\n" + "globalThis.innerAfter = 'yes';\n", + nullptr); + ASSERT_NE(module, nullptr); + DefineGlobalFunction(s.env, "evaluateModule", EvaluateModule, module); + ExpectRunTerminated(s.env, kEvaluateModuleInTryCatch); + EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, module), napi_ok); + } +} + +// A synthetic module's evaluation steps. V8 threw the null from the module's +// evaluation, which the JS that evaluated it caught. +TEST_F(Test72HooksKeepTermination, SyntheticModuleEvaluationSteps) { + for (const char* body : kTerminatingBodies) { + SCOPED_TRACE(body); + EnvScope s(runtime_.get()); + InstallHelpers(s.env); + const std::string steps = std::string("(function () ") + body + ")"; + unofficial_napi_module module = MakeModule(s.env, nullptr, Eval(s.env, steps.c_str())); + ASSERT_NE(module, nullptr); + DefineGlobalFunction(s.env, "evaluateModule", EvaluateModule, module); + ExpectRunTerminated(s.env, kEvaluateModuleInTryCatch); + EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, module), napi_ok); + } +} + +// The module hooks' import() callback. V8 threw the null from the import() +// expression. +TEST_F(Test72HooksKeepTermination, DynamicImportCallback) { + for (const char* body : kTerminatingBodies) { + SCOPED_TRACE(body); + EnvScope s(runtime_.get()); + InstallHelpers(s.env); + const std::string callback = + std::string("(id, specifier, phase, attributes, name) => ") + body; + SetModuleHooks(s.env, Eval(s.env, callback.c_str()), nullptr); + ExpectRunTerminated( + s.env, + "try { import('x').catch(() => {}); } catch (e) { caught = 'yes'; caughtError = e; }\n" + "after = 'yes';\n"); + } +} diff --git a/v8/src/internal/napi_v8_env.h b/v8/src/internal/napi_v8_env.h index da7ecfa4e7..713a9c53a2 100644 --- a/v8/src/internal/napi_v8_env.h +++ b/v8/src/internal/napi_v8_env.h @@ -255,6 +255,16 @@ void napi_v8_set_last_exception( v8::Local exception, v8::Local message = v8::Local()); +// For a V8 host callback (a module hook, say) that ran JS through N-API and +// failed: moves N-API's pending exception into V8, as Node's callbacks +// rethrow what their TryCatch caught, and returns true. While V8 is +// terminating it throws nothing and drops what is pending: throwing would +// replace the termination with a catchable exception, and the termination +// unwinds by itself. Returns true then too: either way V8 now has something +// to unwind with, so the callback may return an empty result. Returns false +// when nothing was pending and V8 is not terminating. +bool napi_v8_rethrow_pending_exception(napi_env env); + napi_value napi_v8_wrap_value(napi_env env, v8::Local value); v8::Local napi_v8_unwrap_value(napi_value value); void napi_v8_finalize_buffer_records(napi_env env); diff --git a/v8/src/js_native_api_v8.cc b/v8/src/js_native_api_v8.cc index 999e55079a..1e638238b5 100644 --- a/v8/src/js_native_api_v8.cc +++ b/v8/src/js_native_api_v8.cc @@ -864,6 +864,25 @@ void napi_v8_set_last_exception(napi_env env, SetLastException(env, exception, message); } +bool napi_v8_rethrow_pending_exception(napi_env env) { + if (env == nullptr) return false; + // As HandleCallbackException: what is pending while V8 terminates is the + // null a TryCatch records for the termination, and throwing it would make + // the termination a catchable throw and cancel it. + if (TerminatedOrTerminating(env)) { + ClearLastException(env); + return true; + } + bool pending = false; + napi_value error = nullptr; + if (napi_is_exception_pending(env, &pending) != napi_ok || !pending || + napi_get_and_clear_last_exception(env, &error) != napi_ok || error == nullptr) { + return false; + } + env->isolate->ThrowException(napi_v8_unwrap_value(error)); + return true; +} + napi_handle_scope__::napi_handle_scope__(napi_env env) : env(env), wrapper(env->isolate) {} diff --git a/v8/src/unofficial_napi_contextify.cc b/v8/src/unofficial_napi_contextify.cc index 4aae857d4e..ca5dc69844 100644 --- a/v8/src/unofficial_napi_contextify.cc +++ b/v8/src/unofficial_napi_contextify.cc @@ -1119,12 +1119,9 @@ v8::MaybeLocal SyntheticModuleEvaluationSteps(v8::Local napi_typeof(env, callback, &callback_type) == napi_ok && callback_type == napi_function) { napi_value ignored = nullptr; if (napi_call_function(env, wrapper, callback, 0, nullptr, &ignored) != napi_ok) { - bool pending = false; - napi_value error = nullptr; - if (napi_is_exception_pending(env, &pending) == napi_ok && pending && - napi_get_and_clear_last_exception(env, &error) == napi_ok && error != nullptr) { - isolate->ThrowException(napi_v8_unwrap_value(error)); - } else if (!isolate->IsExecutionTerminating()) { + // Their exception, or the termination that stopped them, fails the + // evaluation. + if (!napi_v8_rethrow_pending_exception(env)) { isolate->ThrowException(v8::Exception::Error( v8::String::NewFromUtf8Literal(isolate, "Synthetic module evaluation failed"))); } @@ -1246,15 +1243,9 @@ v8::MaybeLocal ImportModuleDynamicallyWithPhase( napi_value global = nullptr; napi_get_global(env, &global); if (napi_call_function(env, global, callback, 5, argv, &result) != napi_ok) { - bool pending = false; - if (napi_is_exception_pending(env, &pending) == napi_ok && pending) { - napi_value error = nullptr; - if (napi_get_and_clear_last_exception(env, &error) == napi_ok && error != nullptr) { - isolate->ThrowException(napi_v8_unwrap_value(error)); - return v8::MaybeLocal(); - } - } - if (isolate->IsExecutionTerminating()) return v8::MaybeLocal(); + // What the callback threw is thrown from the import() expression; a + // termination keeps unwinding. + if (napi_v8_rethrow_pending_exception(env)) return v8::MaybeLocal(); // Nothing thrown: the callback is not a function. return handle_scope.EscapeMaybe(RejectImport(context)); } @@ -1313,14 +1304,9 @@ void HostInitializeImportMetaObject(v8::Local context, napi_get_global(env, &global); if (napi_call_function(env, global, callback, 3, argv, &ignored) != napi_ok) { // What the callback threw is thrown from the import.meta expression, as - // Node's callback rethrows it; left in N-API's pending exception, it - // would surface from whatever N-API call came next. - bool pending = false; - napi_value error = nullptr; - if (napi_is_exception_pending(env, &pending) == napi_ok && pending && - napi_get_and_clear_last_exception(env, &error) == napi_ok && error != nullptr) { - env->isolate->ThrowException(napi_v8_unwrap_value(error)); - } + // Node's callback rethrows it unless V8 is terminating; left in N-API's + // pending exception, it would surface from whatever N-API call came next. + (void)napi_v8_rethrow_pending_exception(env); } } From 5d4c943122e3883065ea5a194c19659057f536fd Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 23:13:30 -0800 Subject: [PATCH 100/150] V8: fail an import() whose default helper V8 terminated With no module hooks, V8's import() callback calls the `__napi_dynamic_import` helper of `process` or the global. When V8 terminated the helper, or a getter on the way to it, the callback rejected the import()'s promise with the null its TryCatch records for a termination (or with "Not supported") and returned it. V8 took the promise and ran the JS that imported on, and the termination it had left pending was gone once that run returned: the run came back napi_ok, as if the env had never been asked to stop. The callback now returns an empty result while V8 terminates, so the import() expression stops with the termination. Test: test_72 DefaultDynamicImportHelper, V8 only: QuickJS never calls a `__napi_dynamic_import` helper (with no hooks its import() rejects without running JS). The helper, or a getter for it, terminates and calls a JS function; the script calls import() in try/catch and sets flags in the catch and after. The run must come back napi_pending_exception with an exception pending and no flag set. Before this commit, both cases failed: the run returned napi_ok with nothing pending and "after=yes". Co-Authored-By: Claude Opus 5.5 --- .../runners/test_72_hooks_keep_termination.cc | 22 +++++++++++++++++++ v8/src/js_native_api_v8.cc | 5 +++++ 2 files changed, 27 insertions(+) diff --git a/tests/runners/test_72_hooks_keep_termination.cc b/tests/runners/test_72_hooks_keep_termination.cc index fe1dabb954..d749bc8696 100644 --- a/tests/runners/test_72_hooks_keep_termination.cc +++ b/tests/runners/test_72_hooks_keep_termination.cc @@ -253,3 +253,25 @@ TEST_F(Test72HooksKeepTermination, DynamicImportCallback) { "after = 'yes';\n"); } } + +#if defined(NAPI_TEST_ENGINE_V8) +// import() with no module hooks calls the `__napi_dynamic_import` helper; only +// V8 does. V8 rejected the import()'s promise with the null its TryCatch +// records for the termination and returned it: the JS that imported ran on, +// and the termination was gone once the run returned. +TEST_F(Test72HooksKeepTermination, DefaultDynamicImportHelper) { + for (const char* setup : + {"globalThis.__napi_dynamic_import = (specifier, name) => { terminate(); tick(); };", + "Object.defineProperty(globalThis, '__napi_dynamic_import'," + " { get() { terminate(); tick(); }, configurable: true });"}) { + SCOPED_TRACE(setup); + EnvScope s(runtime_.get()); + InstallHelpers(s.env); + ASSERT_EQ(RunScript(s.env, setup), napi_ok); + ExpectRunTerminated( + s.env, + "try { import('x').catch(() => {}); } catch (e) { caught = 'yes'; caughtError = e; }\n" + "after = 'yes';\n"); + } +} +#endif diff --git a/v8/src/js_native_api_v8.cc b/v8/src/js_native_api_v8.cc index 1e638238b5..ebc4da1768 100644 --- a/v8/src/js_native_api_v8.cc +++ b/v8/src/js_native_api_v8.cc @@ -131,6 +131,10 @@ v8::MaybeLocal NapiHostImportModuleDynamically( } if ((!helper_value->IsFunction()) && (!global->Get(context, helper_name).ToLocal(&helper_value) || !helper_value->IsFunction())) { + // A getter V8 terminated: the import() fails with the termination, which + // an empty result reports. A settled promise would let the JS that + // imported run on, and V8 drops the termination once that run returns. + if (isolate->IsExecutionTerminating()) return v8::MaybeLocal(); v8::Local message = v8::String::NewFromUtf8Literal(isolate, "Not supported"); resolver->Reject(context, v8::Exception::Error(message)).FromMaybe(false); NapiV8TrackProviderPromise(isolate, promise); @@ -141,6 +145,7 @@ v8::MaybeLocal NapiHostImportModuleDynamically( v8::Local argv[2] = {specifier, resource_name}; v8::Local result; if (!helper->Call(context, global, 2, argv).ToLocal(&result)) { + if (isolate->IsExecutionTerminating()) return v8::MaybeLocal(); if (try_catch.HasCaught()) { resolver->Reject(context, try_catch.Exception()).FromMaybe(false); try_catch.Reset(); From 65fe7611bbfce07dde00084699ca246461fc460d Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 23:13:54 -0800 Subject: [PATCH 101/150] V8: refuse napi_fatal_exception while V8 terminates napi_fatal_exception threw its error into V8 with no check for a termination, unlike napi_throw and Node's version (NAPI_PREAMBLE). From native code V8 was terminating (it asked for the termination and called JS, or called JS that asked for it) the error replaced the termination: the native code's caller caught it and ran on, and the termination was gone. It now fails with napi_pending_exception while V8 terminates, as napi_throw does. Test: test_72 FatalExceptionWhileTerminating, both engines with no guard: a native function terminates, calls a JS function so that V8 acts, then hands an Error to napi_fatal_exception; the script calls it in try/catch and sets flags in the catch and after. The run must come back napi_pending_exception with an exception pending and no flag set. Before this commit, V8 returned napi_ok with nothing pending, "caught=yes after=yes error=Error: fatal"; QuickJS passed (its napi_fatal_exception only sets the pending exception, which its trampoline drops while terminating). Co-Authored-By: Claude Opus 5.5 --- .../runners/test_72_hooks_keep_termination.cc | 24 +++++++++++++++++++ v8/src/js_native_api_v8.cc | 3 +++ 2 files changed, 27 insertions(+) diff --git a/tests/runners/test_72_hooks_keep_termination.cc b/tests/runners/test_72_hooks_keep_termination.cc index d749bc8696..00e87105e4 100644 --- a/tests/runners/test_72_hooks_keep_termination.cc +++ b/tests/runners/test_72_hooks_keep_termination.cc @@ -12,6 +12,7 @@ #include "test_env.h" +#include "node_api.h" #include "unofficial_napi.h" #include @@ -54,6 +55,16 @@ napi_value TerminateAndThrow(napi_env env, napi_callback_info /*info*/) { return nullptr; } +// Terminates, then hands its argument to napi_fatal_exception. +napi_value TerminateThenFatal(napi_env env, napi_callback_info info) { + size_t argc = 1; + napi_value error = nullptr; + EXPECT_EQ(napi_get_cb_info(env, info, &argc, &error, nullptr, nullptr), napi_ok); + TerminateNow(env); + napi_fatal_exception(env, error); + return nullptr; +} + // Evaluates the module its data names and returns the evaluation's promise; // what the evaluation left pending is the trampoline's to throw. napi_value EvaluateModule(napi_env env, napi_callback_info info) { @@ -113,6 +124,7 @@ bool FinishTermination(napi_env env) { void InstallHelpers(napi_env env) { DefineGlobalFunction(env, "terminate", Terminate); DefineGlobalFunction(env, "terminateAndThrow", TerminateAndThrow); + DefineGlobalFunction(env, "terminateThenFatal", TerminateThenFatal); // Each catch block sets its flag first, by a plain store, at which no // engine looks for a termination. ASSERT_EQ(RunScript(env, @@ -254,6 +266,18 @@ TEST_F(Test72HooksKeepTermination, DynamicImportCallback) { } } +// napi_fatal_exception from native code V8 is terminating. V8 threw the +// error over the termination, and the JS that called the native code caught +// it and ran on. +TEST_F(Test72HooksKeepTermination, FatalExceptionWhileTerminating) { + EnvScope s(runtime_.get()); + InstallHelpers(s.env); + ExpectRunTerminated( + s.env, + "try { terminateThenFatal(new Error('fatal')); } catch (e) { caught = 'yes'; caughtError = e; }\n" + "after = 'yes';\n"); +} + #if defined(NAPI_TEST_ENGINE_V8) // import() with no module hooks calls the `__napi_dynamic_import` helper; only // V8 does. V8 rejected the import()'s promise with the null its TryCatch diff --git a/v8/src/js_native_api_v8.cc b/v8/src/js_native_api_v8.cc index ebc4da1768..2584a96652 100644 --- a/v8/src/js_native_api_v8.cc +++ b/v8/src/js_native_api_v8.cc @@ -3516,6 +3516,9 @@ napi_status NAPI_CDECL napi_run_script(napi_env env, } napi_status NAPI_CDECL napi_fatal_exception(napi_env env, napi_value err) { + // As Node's NAPI_PREAMBLE: throwing while V8 terminates would replace the + // termination with a catchable exception. + NAPI_V8_RETURN_IF_TERMINATING(env); if (!CheckEnv(env) || err == nullptr) return napi_invalid_arg; SetLastException(env, napi_v8_unwrap_value(err)); env->isolate->ThrowException(napi_v8_unwrap_value(err)); From ac8427a278b456f10ba0bf7aea829a3fbe6e7d7f Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 23:14:16 -0800 Subject: [PATCH 102/150] V8: keep a termination the serializer's clone-error hook runs into When V8 cannot clone a value, the serdes binding's ThrowDataCloneError reads the serializer's `_getDataCloneError` and throws what it returns, or a plain Error when reading it failed or it is not a function. When V8 terminated a `_getDataCloneError` getter, the read failed and the plain Error replaced the termination: writeValue's caller caught it and ran on, and the termination was gone. It now throws nothing when V8 terminates; V8's serializer then fails the write with the termination. A read that threw an ordinary exception still throws the plain Error, as before. Test: test_72 SerdesHooks, V8 only: QuickJS's serdes binding writes and reads values itself (JS_WriteObject, JS_ReadObject) and calls none of the serializer's hooks. Each case terminates and calls a JS function from a hook (a `_getDataCloneError` getter, `_getDataCloneError`, `_writeHostObject`, `_getSharedArrayBufferId`, the deserializer's `_readHostObject`); the script wraps the write or read in try/catch and sets flags in the catch and after. The run must come back napi_pending_exception with an exception pending and no flag set. Before this commit, the getter case failed: the run returned napi_ok with nothing pending and "caught=yes after=yes error=Error: () => {} could not be cloned."; the other four passed. Co-Authored-By: Claude Opus 5.5 --- .../runners/test_72_hooks_keep_termination.cc | 46 +++++++++++++++++++ v8/src/unofficial_napi.cc | 6 ++- 2 files changed, 51 insertions(+), 1 deletion(-) diff --git a/tests/runners/test_72_hooks_keep_termination.cc b/tests/runners/test_72_hooks_keep_termination.cc index 00e87105e4..8f14bb2472 100644 --- a/tests/runners/test_72_hooks_keep_termination.cc +++ b/tests/runners/test_72_hooks_keep_termination.cc @@ -298,4 +298,50 @@ TEST_F(Test72HooksKeepTermination, DefaultDynamicImportHelper) { "after = 'yes';\n"); } } + +// The serializer's and deserializer's hooks; only V8's serdes binding calls +// them (QuickJS's writes and reads values itself). A `_getDataCloneError` +// getter V8 terminated made V8 throw the clone error over the termination, +// and the JS that wrote the value caught it. +TEST_F(Test72HooksKeepTermination, SerdesHooks) { + for (const char* script : { + "const s = new serdes.Serializer();\n" + "Object.defineProperty(s, '_getDataCloneError', { get() { terminate(); tick(); } });\n" + "try { s.writeValue(() => {}); } catch (e) { caught = 'yes'; caughtError = e; }\n" + "after = 'yes';\n", + "const s = new serdes.Serializer();\n" + "s._getDataCloneError = (message) => { terminate(); tick(); };\n" + "try { s.writeValue(() => {}); } catch (e) { caught = 'yes'; caughtError = e; }\n" + "after = 'yes';\n", + "const s = new serdes.Serializer();\n" + "s._setTreatArrayBufferViewsAsHostObjects(true);\n" + "s._writeHostObject = (value) => { terminate(); tick(); };\n" + "try { s.writeValue(new Uint8Array(2)); } catch (e) { caught = 'yes'; caughtError = e; }\n" + "after = 'yes';\n", + "const s = new serdes.Serializer();\n" + "s._getSharedArrayBufferId = (buffer) => { terminate(); tick(); };\n" + "try { s.writeValue(new SharedArrayBuffer(2)); }\n" + "catch (e) { caught = 'yes'; caughtError = e; }\n" + "after = 'yes';\n", + "const s = new serdes.Serializer();\n" + "s._setTreatArrayBufferViewsAsHostObjects(true);\n" + "s._writeHostObject = function (value) { this.writeUint32(7); };\n" + "s.writeHeader();\n" + "s.writeValue(new Uint8Array(2));\n" + "const d = new serdes.Deserializer(s.releaseBuffer());\n" + "d._readHostObject = () => { terminate(); tick(); };\n" + "d.readHeader();\n" + "try { d.readValue(); } catch (e) { caught = 'yes'; caughtError = e; }\n" + "after = 'yes';\n", + }) { + SCOPED_TRACE(script); + EnvScope s(runtime_.get()); + InstallHelpers(s.env); + napi_value binding = nullptr; + ASSERT_EQ(unofficial_napi_create_serdes_binding(s.env, &binding), napi_ok); + ASSERT_EQ(napi_set_named_property(s.env, Global(s.env), "serdes", binding), napi_ok); + const std::string wrapped = std::string("(() => {\n") + script + "})();"; + ExpectRunTerminated(s.env, wrapped.c_str()); + } +} #endif diff --git a/v8/src/unofficial_napi.cc b/v8/src/unofficial_napi.cc index 100b6c851e..40282fb32c 100644 --- a/v8/src/unofficial_napi.cc +++ b/v8/src/unofficial_napi.cc @@ -927,7 +927,11 @@ void SerializerContext::ThrowDataCloneError(v8::Local message) { if (!wrap->Get(context, OneByteString(isolate_, "_getDataCloneError")) .ToLocal(&get_data_clone_error) || !get_data_clone_error->IsFunction()) { - isolate_->ThrowException(v8::Exception::Error(message)); + // A getter V8 terminated: the termination is what fails the write, and + // throwing would replace it with a catchable error. + if (!isolate_->IsExecutionTerminating()) { + isolate_->ThrowException(v8::Exception::Error(message)); + } return; } From b1ac5ac27b94da8ae3b3ac1b44b295e3a6e151ca Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 23:14:57 -0800 Subject: [PATCH 103/150] V8: keep a termination the promise reject callback runs into The promise reject callback calls the env's JS callback in a TryCatch and returns nothing. When V8 terminated that JS, it ran on after the callback without looking for the termination, and dropped the termination once the run that rejected returned: the run came back napi_ok, the next one ran too, and the env went on as if it had never been asked to stop. When the TryCatch saw a termination, the callback now asks V8 to terminate again, so V8 acts on it at its next check, as on a termination requested from plain JS. JS that runs before that check, as the rest of the rejecting run here, still runs: the callback cannot stop it, and QuickJS's promise rejection tracker cannot either. Test: test_72 PromiseRejectCallback, both engines with no guard: the reject callback terminates and calls a JS function; a script rejects a promise in try/catch and sets flags in the catch and after; then a second run. Nothing may be caught, and that run or the next must come back napi_pending_exception. Both engines now return napi_ok for the first run ("after=yes") and napi_pending_exception for the next. Before this commit, V8 returned napi_ok for both; QuickJS passed, its termination request outliving the run. Co-Authored-By: Claude Opus 5.5 --- .../runners/test_72_hooks_keep_termination.cc | 24 +++++++++++++++++++ v8/src/unofficial_napi.cc | 8 ++++++- 2 files changed, 31 insertions(+), 1 deletion(-) diff --git a/tests/runners/test_72_hooks_keep_termination.cc b/tests/runners/test_72_hooks_keep_termination.cc index 8f14bb2472..b41e00ee4f 100644 --- a/tests/runners/test_72_hooks_keep_termination.cc +++ b/tests/runners/test_72_hooks_keep_termination.cc @@ -278,6 +278,30 @@ TEST_F(Test72HooksKeepTermination, FatalExceptionWhileTerminating) { "after = 'yes';\n"); } +// The promise reject callback returns nothing, so the JS that rejected goes +// on until the engine next looks for a termination, and the run may come +// back before it does. The termination must still not be catchable, nor +// lost: that run or the next one stops. V8 dropped it once the run returned, +// and the env ran on as if it had never been asked to stop. +TEST_F(Test72HooksKeepTermination, PromiseRejectCallback) { + EnvScope s(runtime_.get()); + InstallHelpers(s.env); + ASSERT_EQ(unofficial_napi_set_promise_reject_callback( + s.env, Eval(s.env, "(type, promise, reason) => { terminate(); tick(); }")), + napi_ok); + const napi_status run = RunScript( + s.env, + "try { Promise.reject(1); } catch (e) { caught = 'yes'; caughtError = e; }\n" + "after = 'yes';\n"); + const napi_status next = RunScript(s.env, "globalThis.next = 'yes';"); + FinishTermination(s.env); + EXPECT_TRUE(run == napi_pending_exception || next == napi_pending_exception) + << "run " << run << ", next run " << next; + EXPECT_EQ(GlobalText(s.env, "caught"), "no"); + EXPECT_EQ(GlobalText(s.env, "caughtError"), "none"); + EXPECT_EQ(RunScript(s.env, "globalThis.resumed = 'yes';"), napi_ok); +} + #if defined(NAPI_TEST_ENGINE_V8) // import() with no module hooks calls the `__napi_dynamic_import` helper; only // V8 does. V8 rejected the import()'s promise with the null its TryCatch diff --git a/v8/src/unofficial_napi.cc b/v8/src/unofficial_napi.cc index 40282fb32c..eacdf69b29 100644 --- a/v8/src/unofficial_napi.cc +++ b/v8/src/unofficial_napi.cc @@ -737,7 +737,13 @@ void PromiseRejectCallback(v8::PromiseRejectMessage message) { promise, value}; (void)callback->Call(context, v8::Undefined(isolate), 3, args); - if (tc.HasCaught() && !tc.HasTerminated()) { + if (tc.HasTerminated()) { + // V8 goes on after this callback without looking for a termination, and + // drops one still left once the call that rejected returns: the env + // would run on as if it had never been asked to stop. Ask again, so V8 + // acts on it at its next check, as on one requested from plain JS. + isolate->TerminateExecution(); + } else if (tc.HasCaught()) { // Match Node behavior: V8 expects this callback to return without a pending // exception. Print a best-effort diagnostic instead of scheduling it. std::fprintf(stderr, "Exception in PromiseRejectCallback:\n"); From 5923973fe77762079ec540c0435276359edeab61 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 23:15:21 -0800 Subject: [PATCH 104/150] Test that the promise and prepare-stack-trace hooks keep a termination The sweep of the places that throw what a callback's JS threw back into the engine found these two keeping a termination already; they get cases in test_72, so they keep doing so. Test: test_72 PromiseHooks, both engines with no guard: each of the init, before, after and resolve hooks terminates and calls a JS function once armed; a script makes a promise with a reaction, in try/catch, then a microtask checkpoint and a second run. Nothing may be caught, in the script or in the reaction, and the run, the checkpoint or the next run must come back napi_pending_exception: the hooks return nothing, and where each engine stops differs (V8 stops the run for init and resolve, and refuses the next run for before and after; QuickJS's hooks drop the uncatchable error and its termination request stops the checkpoint or the next run). PrepareStackTraceCallback, V8 only (QuickJS ignores the callback set through unofficial_napi_set_prepare_stack_trace_callback): the callback terminates and calls a JS function while a script reads an error's stack in try/catch; the run must come back napi_pending_exception with no flag set. Both already passed before this commit. Co-Authored-By: Claude Opus 5.5 --- .../runners/test_72_hooks_keep_termination.cc | 51 +++++++++++++++++++ 1 file changed, 51 insertions(+) diff --git a/tests/runners/test_72_hooks_keep_termination.cc b/tests/runners/test_72_hooks_keep_termination.cc index b41e00ee4f..04e2754f9b 100644 --- a/tests/runners/test_72_hooks_keep_termination.cc +++ b/tests/runners/test_72_hooks_keep_termination.cc @@ -302,7 +302,58 @@ TEST_F(Test72HooksKeepTermination, PromiseRejectCallback) { EXPECT_EQ(RunScript(s.env, "globalThis.resumed = 'yes';"), napi_ok); } +// The promise hooks return nothing too: the same holds for them, in the run +// that made the promise, or in the microtask checkpoint that runs its +// reactions. +TEST_F(Test72HooksKeepTermination, PromiseHooks) { + constexpr const char* kHookNames[] = {"init", "before", "after", "resolve"}; + for (int which = 0; which < 4; ++which) { + SCOPED_TRACE(kHookNames[which]); + EnvScope s(runtime_.get()); + InstallHelpers(s.env); + napi_value hooks[4] = {nullptr, nullptr, nullptr, nullptr}; + hooks[which] = Eval(s.env, + "globalThis.armed = false;" + "(...args) => { if (armed) { terminate(); tick(); } }"); + ASSERT_EQ(unofficial_napi_set_promise_hooks(s.env, hooks[0], hooks[1], hooks[2], hooks[3]), + napi_ok); + const napi_status run = RunScript( + s.env, + "try {\n" + " armed = true;\n" + " Promise.resolve(1).then(() => {\n" + " try { tick(); } catch (e) { innerCaught = 'yes'; caughtError = e; }\n" + " });\n" + "} catch (e) { caught = 'yes'; caughtError = e; }\n" + "after = 'yes';\n"); + const napi_status checkpoint = unofficial_napi_event_loop_checkpoint( + s.env, unofficial_napi_event_loop_checkpoint_microtasks, false, nullptr); + const napi_status next = RunScript(s.env, "globalThis.next = 'yes';"); + FinishTermination(s.env); + EXPECT_TRUE(run == napi_pending_exception || checkpoint == napi_pending_exception || + next == napi_pending_exception) + << "run " << run << ", checkpoint " << checkpoint << ", next run " << next; + EXPECT_EQ(GlobalText(s.env, "caught"), "no"); + EXPECT_EQ(GlobalText(s.env, "innerCaught"), "no"); + EXPECT_EQ(GlobalText(s.env, "caughtError"), "none"); + ASSERT_EQ(RunScript(s.env, "armed = false;"), napi_ok); + } +} + #if defined(NAPI_TEST_ENGINE_V8) +// The prepare-stack-trace callback; QuickJS ignores the one set here. +TEST_F(Test72HooksKeepTermination, PrepareStackTraceCallback) { + EnvScope s(runtime_.get()); + InstallHelpers(s.env); + ASSERT_EQ(unofficial_napi_set_prepare_stack_trace_callback( + s.env, Eval(s.env, "(global, error, trace) => { terminate(); tick(); }")), + napi_ok); + ExpectRunTerminated( + s.env, + "try { new Error('x').stack; } catch (e) { caught = 'yes'; caughtError = e; }\n" + "after = 'yes';\n"); +} + // import() with no module hooks calls the `__napi_dynamic_import` helper; only // V8 does. V8 rejected the import()'s promise with the null its TryCatch // records for the termination and returned it: the JS that imported ran on, From 6159f5ee9e240683e85a04aecc22c0c15a7598fc Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 23:37:21 -0800 Subject: [PATCH 105/150] V8: keep a termination that formatting a module hook's error runs into napi_v8_rethrow_pending_exception took the hook's exception with napi_get_and_clear_last_exception, which formats it: it can call the source-map callback, and then sets the error's arrow and preserved formatting through V8 calls. When V8 acted on a termination in that callback (a hook that asked for one and threw before V8 acted, so the callback was the first JS to run after), those V8 calls dropped the termination, and the helper threw the hook's error: the module caught it and ran on. Found by the Codex review of the commits from "V8: keep a termination the module hooks run into" to "Test that the promise and prepare-stack-trace hooks keep a termination". napi_get_and_clear_last_exception no longer makes those calls once V8 terminates after the source-map callback, and the helper throws through the new napi_v8_throw_unless_terminating, which throws nothing while V8 terminates. Test: test_72 SourceMapCallbackWhileTakingAHookError, V8 only: only V8's provider calls the source-map callback (QuickJS keeps the one unofficial_napi_configure_source_maps sets and never calls it). An import.meta callback from a named script calls terminate() and throws; the source-map callback, the next JS, never gets to run. The run that evaluates the module must come back napi_pending_exception with an exception pending and no flag set. Before this commit, the module caught the hook's error ("innerCaught=yes innerAfter=yes error=Error: meta"). Co-Authored-By: Claude Opus 5.5 --- .../runners/test_72_hooks_keep_termination.cc | 33 +++++++++++++++++++ v8/src/internal/napi_v8_env.h | 6 ++++ v8/src/js_native_api_v8.cc | 29 +++++++++++----- 3 files changed, 60 insertions(+), 8 deletions(-) diff --git a/tests/runners/test_72_hooks_keep_termination.cc b/tests/runners/test_72_hooks_keep_termination.cc index 04e2754f9b..535f9ff5b2 100644 --- a/tests/runners/test_72_hooks_keep_termination.cc +++ b/tests/runners/test_72_hooks_keep_termination.cc @@ -354,6 +354,39 @@ TEST_F(Test72HooksKeepTermination, PrepareStackTraceCallback) { "after = 'yes';\n"); } +// What a module hook threw is formatted as it is taken from N-API, which calls +// the source-map callback; only V8's provider calls that callback. A hook that +// asks for the termination and throws before V8 acts on it has V8 act on it in +// that callback, the first JS to run after. V8 still threw the hook's error +// over the termination, and the module caught it. +TEST_F(Test72HooksKeepTermination, SourceMapCallbackWhileTakingAHookError) { + EnvScope s(runtime_.get()); + InstallHelpers(s.env); + ASSERT_EQ(RunScript(s.env, "globalThis.mapped = 0;"), napi_ok); + ASSERT_EQ(unofficial_napi_configure_source_maps( + s.env, true, Eval(s.env, "(name, line, column) => { mapped++; }")), + napi_ok); + // The hook comes from a named script, so its error's message names one. + const unofficial_napi_js_source hook_source = unofficial_napi_js_source_from_text( + Str(s.env, "(id, meta, wrap) => { terminate(); throw new Error('meta'); }")); + napi_value hook = nullptr; + ASSERT_EQ(unofficial_napi_run_script(s.env, nullptr, &hook_source, Str(s.env, "hook.js"), 0, 0, + -1, true, false, false, nullptr, &hook), + napi_ok); + SetModuleHooks(s.env, nullptr, hook); + unofficial_napi_module module = MakeModule( + s.env, + "try { import.meta; } catch (e) { globalThis.innerCaught = 'yes'; caughtError = e; }\n" + "globalThis.innerAfter = 'yes';\n", + nullptr); + ASSERT_NE(module, nullptr); + DefineGlobalFunction(s.env, "evaluateModule", EvaluateModule, module); + ExpectRunTerminated(s.env, kEvaluateModuleInTryCatch); + // V8 acted on the termination as it entered the callback, which never ran. + EXPECT_EQ(GlobalText(s.env, "mapped"), "0"); + EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, module), napi_ok); +} + // import() with no module hooks calls the `__napi_dynamic_import` helper; only // V8 does. V8 rejected the import()'s promise with the null its TryCatch // records for the termination and returned it: the JS that imported ran on, diff --git a/v8/src/internal/napi_v8_env.h b/v8/src/internal/napi_v8_env.h index 713a9c53a2..0d45222521 100644 --- a/v8/src/internal/napi_v8_env.h +++ b/v8/src/internal/napi_v8_env.h @@ -255,6 +255,12 @@ void napi_v8_set_last_exception( v8::Local exception, v8::Local message = v8::Local()); +// Throws `exception` into V8 unless V8 is terminating, and returns whether it +// threw. Making an exception can run JS that V8 terminates (an inherited +// `code` setter, a getter, the source-map callback), and throwing would then +// replace the termination with a catchable exception. +bool napi_v8_throw_unless_terminating(v8::Isolate* isolate, v8::Local exception); + // For a V8 host callback (a module hook, say) that ran JS through N-API and // failed: moves N-API's pending exception into V8, as Node's callbacks // rethrow what their TryCatch caught, and returns true. While V8 is diff --git a/v8/src/js_native_api_v8.cc b/v8/src/js_native_api_v8.cc index 2584a96652..f86af31c5a 100644 --- a/v8/src/js_native_api_v8.cc +++ b/v8/src/js_native_api_v8.cc @@ -869,6 +869,12 @@ void napi_v8_set_last_exception(napi_env env, SetLastException(env, exception, message); } +bool napi_v8_throw_unless_terminating(v8::Isolate* isolate, v8::Local exception) { + if (isolate == nullptr || isolate->IsExecutionTerminating()) return false; + isolate->ThrowException(exception); + return true; +} + bool napi_v8_rethrow_pending_exception(napi_env env) { if (env == nullptr) return false; // As HandleCallbackException: what is pending while V8 terminates is the @@ -884,7 +890,9 @@ bool napi_v8_rethrow_pending_exception(napi_env env) { napi_get_and_clear_last_exception(env, &error) != napi_ok || error == nullptr) { return false; } - env->isolate->ThrowException(napi_v8_unwrap_value(error)); + // Taking it formats it, which can call the source-map callback: JS that V8 + // may terminate too. + napi_v8_throw_unless_terminating(env->isolate, napi_v8_unwrap_value(error)); return true; } @@ -3444,13 +3452,18 @@ napi_status NAPI_CDECL napi_get_and_clear_last_exception(napi_env env, if (!message.IsEmpty()) { const std::string source_line = unofficial_napi_internal::GetErrorSourceLineForStderrImpl(env, message); - unofficial_napi_internal::SetArrowMessageFromString( - env->isolate, env->context(), ex, source_line); - unofficial_napi_internal::PreserveErrorFormatting( - env, - ex, - source_line, - unofficial_napi_internal::GetThrownAtString(env->isolate, message)); + // That can run the source-map callback, JS that V8 may terminate. The + // V8 calls formatting makes would then drop the termination, as + // NAPI_V8_RETURN_IF_TERMINATING says entering V8 does. + if (!TerminatedOrTerminating(env)) { + unofficial_napi_internal::SetArrowMessageFromString( + env->isolate, env->context(), ex, source_line); + unofficial_napi_internal::PreserveErrorFormatting( + env, + ex, + source_line, + unofficial_napi_internal::GetThrownAtString(env->isolate, message)); + } } else { (void)unofficial_napi_internal::PreserveErrorSourceMessage(env, wrapped); } From d922b7073f658d27ee689bcee1d4df002b8a0920 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 23:38:30 -0800 Subject: [PATCH 106/150] V8: keep a termination an error's code setter runs into napi_throw_error, napi_throw_type_error, napi_throw_range_error and node_api_throw_syntax_error, the serdes binding's TypeErrors (ThrowTypeErrorWithCode) and the module loader's link errors (ThrowV8CodeError) give their error a `code` as Node does, with a plain set, which runs an inherited `code` setter. When V8 terminated that setter, they threw the error anyway, over the termination: the JS that led there caught it and ran on, and the termination was gone. Found by the Codex review of the commits from "V8: keep a termination the module hooks run into" to "Test that the promise and prepare-stack-trace hooks keep a termination". The four napi_throw_* calls now share ThrowErrorWithCode, and all six throw through napi_v8_throw_unless_terminating, which throws nothing while V8 terminates; the napi_throw_* calls then fail with napi_pending_exception, as they do when called while V8 terminates. The serializer's clone-error fallback (from "V8: keep a termination the serializer's clone-error hook runs into") uses it too. Errors thrown while V8 is not terminating are unchanged. Test: test_72 ErrorCodeSetter, both engines: with an Error.prototype `code` setter that terminates and calls a JS function, a native function throws through each of the four napi_throw_* calls, a script calls the serdes binding's Serializer without `new`, and (V8 only) a native function instantiates a module that was never linked; each in try/catch with flags set in the catch and after. The run must come back napi_pending_exception with an exception pending and no flag set. The last case is V8's alone: QuickJS reports such a module through its own loader, a ReferenceError with no code, so no setter runs. Before this commit, every V8 case failed, the run returning napi_ok with the error caught ("error=Error: error", "TypeError: type error", "RangeError: range error", "SyntaxError: syntax error", "TypeError: Class constructor Serializer cannot be invoked without 'new'", "Error: Module is not linked"); QuickJS passed its cases (its trampoline drops what a callback left pending once termination is requested). The test is built against N-API 10 for node_api_throw_syntax_error. Co-Authored-By: Claude Opus 5.5 --- tests/CMakeLists.txt | 1 + .../runners/test_72_hooks_keep_termination.cc | 94 +++++++++++++++ v8/src/js_native_api_v8.cc | 107 +++++++----------- v8/src/unofficial_napi.cc | 10 +- v8/src/unofficial_napi_contextify.cc | 3 +- 5 files changed, 143 insertions(+), 72 deletions(-) diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt index 7eab25d4c7..b32da9e871 100644 --- a/tests/CMakeLists.txt +++ b/tests/CMakeLists.txt @@ -342,6 +342,7 @@ add_fixture_test(${_napi_test_prefix}_test_71_contextify_compat add_fixture_test(${_napi_test_prefix}_test_72_hooks_keep_termination runners/test_72_hooks_keep_termination.cc ) +target_compile_definitions(${_napi_test_prefix}_test_72_hooks_keep_termination PRIVATE NAPI_VERSION=10) if(_napi_test_engine STREQUAL "v8") # Only the V8 provider posts engine tasks through the enqueue hook. add_fixture_test(${_napi_test_prefix}_test_66_foreground_task_handoff diff --git a/tests/runners/test_72_hooks_keep_termination.cc b/tests/runners/test_72_hooks_keep_termination.cc index 535f9ff5b2..c58f031a37 100644 --- a/tests/runners/test_72_hooks_keep_termination.cc +++ b/tests/runners/test_72_hooks_keep_termination.cc @@ -65,6 +65,34 @@ napi_value TerminateThenFatal(napi_env env, napi_callback_info info) { return nullptr; } +// Throws an error with a code through napi_throw_error, napi_throw_type_error, +// napi_throw_range_error or node_api_throw_syntax_error, as its argument says. +napi_value ThrowWithCode(napi_env env, napi_callback_info info) { + size_t argc = 1; + napi_value kind_value = nullptr; + EXPECT_EQ(napi_get_cb_info(env, info, &argc, &kind_value, nullptr, nullptr), napi_ok); + int32_t kind = 0; + EXPECT_EQ(napi_get_value_int32(env, kind_value, &kind), napi_ok); + switch (kind) { + case 0: napi_throw_error(env, "ERR_TEST", "error"); break; + case 1: napi_throw_type_error(env, "ERR_TEST", "type error"); break; + case 2: napi_throw_range_error(env, "ERR_TEST", "range error"); break; + default: node_api_throw_syntax_error(env, "ERR_TEST", "syntax error"); break; + } + return nullptr; +} + +#if defined(NAPI_TEST_ENGINE_V8) +// Instantiates the module its data names; what that left pending is the +// trampoline's to throw. +napi_value InstantiateModule(napi_env env, napi_callback_info info) { + void* data = nullptr; + if (napi_get_cb_info(env, info, nullptr, nullptr, nullptr, &data) != napi_ok) return nullptr; + unofficial_napi_module_wrap_instantiate(env, static_cast(data)); + return nullptr; +} +#endif + // Evaluates the module its data names and returns the evaluation's promise; // what the evaluation left pending is the trampoline's to throw. napi_value EvaluateModule(napi_env env, napi_callback_info info) { @@ -125,6 +153,7 @@ void InstallHelpers(napi_env env) { DefineGlobalFunction(env, "terminate", Terminate); DefineGlobalFunction(env, "terminateAndThrow", TerminateAndThrow); DefineGlobalFunction(env, "terminateThenFatal", TerminateThenFatal); + DefineGlobalFunction(env, "throwWithCode", ThrowWithCode); // Each catch block sets its flag first, by a plain store, at which no // engine looks for a termination. ASSERT_EQ(RunScript(env, @@ -340,6 +369,71 @@ TEST_F(Test72HooksKeepTermination, PromiseHooks) { } } +// Errors the providers make with a code get it set as Node sets it, which runs +// an inherited `code` setter. When V8 terminated the setter, V8's +// napi_throw_error and its siblings, the serdes binding's constructors and +// the module loader's link errors threw their error over the termination. +TEST_F(Test72HooksKeepTermination, ErrorCodeSetter) { + constexpr char kCodeSetter[] = + "Object.defineProperty(Error.prototype, 'code'," + " { set(value) { terminate(); tick(); }, configurable: true });"; + for (int kind = 0; kind < 4; ++kind) { + SCOPED_TRACE(kind); + EnvScope s(runtime_.get()); + InstallHelpers(s.env); + ASSERT_EQ(RunScript(s.env, kCodeSetter), napi_ok); + const std::string script = "try { throwWithCode(" + std::to_string(kind) + + "); } catch (e) { caught = 'yes'; caughtError = e; }\n" + "after = 'yes';\n"; + ExpectRunTerminated(s.env, script.c_str()); + } + { + SCOPED_TRACE("serdes constructor without new"); + EnvScope s(runtime_.get()); + InstallHelpers(s.env); + napi_value binding = nullptr; + ASSERT_EQ(unofficial_napi_create_serdes_binding(s.env, &binding), napi_ok); + ASSERT_EQ(napi_set_named_property(s.env, Global(s.env), "serdes", binding), napi_ok); + ASSERT_EQ(RunScript(s.env, kCodeSetter), napi_ok); + ExpectRunTerminated( + s.env, + "try { serdes.Serializer(); } catch (e) { caught = 'yes'; caughtError = e; }\n" + "after = 'yes';\n"); + } +#if defined(NAPI_TEST_ENGINE_V8) + // QuickJS reports a module that is not linked through its own loader, a + // ReferenceError with no code, so no setter runs there. + { + SCOPED_TRACE("instantiating a module that is not linked"); + EnvScope s(runtime_.get()); + InstallHelpers(s.env); + napi_value wrapper = nullptr; + napi_value undefined = nullptr; + ASSERT_EQ(napi_create_object(s.env, &wrapper), napi_ok); + ASSERT_EQ(napi_get_undefined(s.env, &undefined), napi_ok); + const unofficial_napi_js_source source = + unofficial_napi_js_source_from_text(Str(s.env, "import 'dep';")); + unofficial_napi_module_create_options options{}; + options.size = sizeof(options); + options.version = UNOFFICIAL_NAPI_MODULE_CREATE_OPTIONS_VERSION; + options.kind = unofficial_napi_module_source_text; + options.wrapper = wrapper; + options.url = Str(s.env, "unlinked.mjs"); + options.payload.source_text.source = &source; + options.payload.source_text.host_defined_option_id = undefined; + unofficial_napi_module_create_result created{}; + ASSERT_EQ(unofficial_napi_module_wrap_create(s.env, &options, &created), napi_ok); + DefineGlobalFunction(s.env, "instantiateModule", InstantiateModule, created.module); + ASSERT_EQ(RunScript(s.env, kCodeSetter), napi_ok); + ExpectRunTerminated( + s.env, + "try { instantiateModule(); } catch (e) { caught = 'yes'; caughtError = e; }\n" + "after = 'yes';\n"); + EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, created.module), napi_ok); + } +#endif +} + #if defined(NAPI_TEST_ENGINE_V8) // The prepare-stack-trace callback; QuickJS ignores the one set here. TEST_F(Test72HooksKeepTermination, PrepareStackTraceCallback) { diff --git a/v8/src/js_native_api_v8.cc b/v8/src/js_native_api_v8.cc index f86af31c5a..1a5c97aae2 100644 --- a/v8/src/js_native_api_v8.cc +++ b/v8/src/js_native_api_v8.cc @@ -3247,30 +3247,46 @@ napi_status NAPI_CDECL napi_remove_wrap(napi_env env, napi_value js_object, void return napi_ok; } -napi_status NAPI_CDECL napi_throw_error(napi_env env, - const char* code, - const char* msg) { - NAPI_V8_RETURN_IF_TERMINATING(env); - if (!CheckEnv(env)) return napi_invalid_arg; +// napi_throw_error and its siblings: makes the error, gives it `code` as Node +// does, and throws it. Setting the code runs an inherited `code` setter, JS +// that V8 may terminate: the termination is then what unwinds, and throwing +// would replace it with a catchable error. +static napi_status ThrowErrorWithCode(napi_env env, + v8::Local (*factory)(v8::Local), + const char* code, + const char* msg) { v8::Local message; - if (!v8::String::NewFromUtf8( - env->isolate, (msg == nullptr) ? "N-API error" : msg, v8::NewStringType::kNormal) + if (!v8::String::NewFromUtf8(env->isolate, msg, v8::NewStringType::kNormal) .ToLocal(&message)) { return napi_generic_failure; } - v8::Local err_obj = v8::Exception::Error(message).As(); + v8::Local err = factory(message).As(); if (code != nullptr) { v8::Local code_key = v8::String::NewFromUtf8Literal(env->isolate, "code"); v8::Local code_val; if (v8::String::NewFromUtf8(env->isolate, code, v8::NewStringType::kNormal).ToLocal(&code_val)) { - err_obj->Set(env->context(), code_key, code_val).FromMaybe(false); + err->Set(env->context(), code_key, code_val).FromMaybe(false); } } - env->isolate->ThrowException(err_obj); - SetLastException(env, err_obj); + if (!napi_v8_throw_unless_terminating(env->isolate, err)) { + return napi_v8_set_last_error(env, napi_pending_exception, "Execution is terminating"); + } + SetLastException(env, err); return napi_pending_exception; } +napi_status NAPI_CDECL napi_throw_error(napi_env env, + const char* code, + const char* msg) { + NAPI_V8_RETURN_IF_TERMINATING(env); + if (!CheckEnv(env)) return napi_invalid_arg; + return ThrowErrorWithCode( + env, + [](v8::Local message) { return v8::Exception::Error(message); }, + code, + (msg == nullptr) ? "N-API error" : msg); +} + napi_status NAPI_CDECL napi_throw(napi_env env, napi_value error) { NAPI_V8_RETURN_IF_TERMINATING(env); if (!CheckValue(env, error)) return napi_invalid_arg; @@ -3360,24 +3376,11 @@ napi_status NAPI_CDECL napi_throw_type_error(napi_env env, const char* msg) { NAPI_V8_RETURN_IF_TERMINATING(env); if (!CheckEnv(env)) return napi_invalid_arg; - v8::Local message; - if (!v8::String::NewFromUtf8(env->isolate, - (msg == nullptr) ? "Type error" : msg, - v8::NewStringType::kNormal) - .ToLocal(&message)) { - return napi_generic_failure; - } - v8::Local err = v8::Exception::TypeError(message).As(); - if (code != nullptr) { - v8::Local code_key = v8::String::NewFromUtf8Literal(env->isolate, "code"); - v8::Local code_val; - if (v8::String::NewFromUtf8(env->isolate, code, v8::NewStringType::kNormal).ToLocal(&code_val)) { - err->Set(env->context(), code_key, code_val).FromMaybe(false); - } - } - env->isolate->ThrowException(err); - SetLastException(env, err); - return napi_pending_exception; + return ThrowErrorWithCode( + env, + [](v8::Local message) { return v8::Exception::TypeError(message); }, + code, + (msg == nullptr) ? "Type error" : msg); } napi_status NAPI_CDECL napi_throw_range_error(napi_env env, @@ -3385,24 +3388,11 @@ napi_status NAPI_CDECL napi_throw_range_error(napi_env env, const char* msg) { NAPI_V8_RETURN_IF_TERMINATING(env); if (!CheckEnv(env)) return napi_invalid_arg; - v8::Local message; - if (!v8::String::NewFromUtf8(env->isolate, - (msg == nullptr) ? "Range error" : msg, - v8::NewStringType::kNormal) - .ToLocal(&message)) { - return napi_generic_failure; - } - v8::Local err = v8::Exception::RangeError(message).As(); - if (code != nullptr) { - v8::Local code_key = v8::String::NewFromUtf8Literal(env->isolate, "code"); - v8::Local code_val; - if (v8::String::NewFromUtf8(env->isolate, code, v8::NewStringType::kNormal).ToLocal(&code_val)) { - err->Set(env->context(), code_key, code_val).FromMaybe(false); - } - } - env->isolate->ThrowException(err); - SetLastException(env, err); - return napi_pending_exception; + return ThrowErrorWithCode( + env, + [](v8::Local message) { return v8::Exception::RangeError(message); }, + code, + (msg == nullptr) ? "Range error" : msg); } napi_status NAPI_CDECL node_api_throw_syntax_error(napi_env env, @@ -3410,24 +3400,11 @@ napi_status NAPI_CDECL node_api_throw_syntax_error(napi_env env, const char* msg) { NAPI_V8_RETURN_IF_TERMINATING(env); if (!CheckEnv(env)) return napi_invalid_arg; - v8::Local message; - if (!v8::String::NewFromUtf8(env->isolate, - (msg == nullptr) ? "Syntax error" : msg, - v8::NewStringType::kNormal) - .ToLocal(&message)) { - return napi_generic_failure; - } - v8::Local err = v8::Exception::SyntaxError(message).As(); - if (code != nullptr) { - v8::Local code_key = v8::String::NewFromUtf8Literal(env->isolate, "code"); - v8::Local code_val; - if (v8::String::NewFromUtf8(env->isolate, code, v8::NewStringType::kNormal).ToLocal(&code_val)) { - err->Set(env->context(), code_key, code_val).FromMaybe(false); - } - } - env->isolate->ThrowException(err); - SetLastException(env, err); - return napi_pending_exception; + return ThrowErrorWithCode( + env, + [](v8::Local message) { return v8::Exception::SyntaxError(message); }, + code, + (msg == nullptr) ? "Syntax error" : msg); } napi_status NAPI_CDECL napi_is_exception_pending(napi_env env, bool* result) { diff --git a/v8/src/unofficial_napi.cc b/v8/src/unofficial_napi.cc index eacdf69b29..86070a5aac 100644 --- a/v8/src/unofficial_napi.cc +++ b/v8/src/unofficial_napi.cc @@ -860,7 +860,8 @@ void ThrowTypeErrorWithCode(v8::Local context, (void)exception.As()->Set( context, OneByteString(isolate, "code"), OneByteString(isolate, code)); } - isolate->ThrowException(exception); + // Setting the code runs an inherited `code` setter. + napi_v8_throw_unless_terminating(isolate, exception); } v8::Local CreateBufferObject(v8::Local context, @@ -933,11 +934,8 @@ void SerializerContext::ThrowDataCloneError(v8::Local message) { if (!wrap->Get(context, OneByteString(isolate_, "_getDataCloneError")) .ToLocal(&get_data_clone_error) || !get_data_clone_error->IsFunction()) { - // A getter V8 terminated: the termination is what fails the write, and - // throwing would replace it with a catchable error. - if (!isolate_->IsExecutionTerminating()) { - isolate_->ThrowException(v8::Exception::Error(message)); - } + // A getter V8 terminated: the termination is what fails the write. + napi_v8_throw_unless_terminating(isolate_, v8::Exception::Error(message)); return; } diff --git a/v8/src/unofficial_napi_contextify.cc b/v8/src/unofficial_napi_contextify.cc index ca5dc69844..46a9505639 100644 --- a/v8/src/unofficial_napi_contextify.cc +++ b/v8/src/unofficial_napi_contextify.cc @@ -884,7 +884,8 @@ void ThrowV8CodeError(v8::Local context, const char* code, const st } napi_value error = nullptr; if (!CreateCodeError(env, code, message, &error) || error == nullptr) return; - context->GetIsolate()->ThrowException(napi_v8_unwrap_value(error)); + // Setting the error's code runs an inherited `code` setter. + napi_v8_throw_unless_terminating(context->GetIsolate(), napi_v8_unwrap_value(error)); } ModuleWrapRecord* FindModuleRecordForModule(napi_env env, v8::Local module) { From ee09eb23383ee67b214dfdda2e6f0370e9f7350a Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Thu, 5 Nov 2026 23:38:49 -0800 Subject: [PATCH 107/150] V8: keep a termination the serializer's shared-buffer getter runs into When the serdes binding's serializer meets a SharedArrayBuffer it reads `_getSharedArrayBufferId` and calls it, or, when reading failed or found no function, falls back to V8's default delegate, which throws a clone error. When V8 terminated a `_getSharedArrayBufferId` getter, the fallback threw that error over the termination: writeValue's caller caught it and ran on, and the termination was gone. Found by the Codex review of the commits from "V8: keep a termination the module hooks run into" to "Test that the promise and prepare-stack-trace hooks keep a termination". It now fails the write with the termination instead. A read that threw an ordinary exception still falls back as before. Test: test_72 SerdesHooks, V8 only (QuickJS's serdes binding calls none of the serializer's hooks), gains a `_getSharedArrayBufferId` getter that terminates and calls a JS function while a script writes a SharedArrayBuffer in try/catch. The run must come back napi_pending_exception with an exception pending and no flag set. Before this commit, the run returned napi_ok with "caught=yes after=yes error=Error: # could not be cloned.". Co-Authored-By: Claude Opus 5.5 --- tests/runners/test_72_hooks_keep_termination.cc | 6 ++++++ v8/src/unofficial_napi.cc | 3 +++ 2 files changed, 9 insertions(+) diff --git a/tests/runners/test_72_hooks_keep_termination.cc b/tests/runners/test_72_hooks_keep_termination.cc index c58f031a37..a47068ab6d 100644 --- a/tests/runners/test_72_hooks_keep_termination.cc +++ b/tests/runners/test_72_hooks_keep_termination.cc @@ -521,6 +521,12 @@ TEST_F(Test72HooksKeepTermination, SerdesHooks) { "try { s.writeValue(new Uint8Array(2)); } catch (e) { caught = 'yes'; caughtError = e; }\n" "after = 'yes';\n", "const s = new serdes.Serializer();\n" + "Object.defineProperty(s, '_getSharedArrayBufferId',\n" + " { get() { terminate(); tick(); } });\n" + "try { s.writeValue(new SharedArrayBuffer(2)); }\n" + "catch (e) { caught = 'yes'; caughtError = e; }\n" + "after = 'yes';\n", + "const s = new serdes.Serializer();\n" "s._getSharedArrayBufferId = (buffer) => { terminate(); tick(); };\n" "try { s.writeValue(new SharedArrayBuffer(2)); }\n" "catch (e) { caught = 'yes'; caughtError = e; }\n" diff --git a/v8/src/unofficial_napi.cc b/v8/src/unofficial_napi.cc index 86070a5aac..71b1c6ce77 100644 --- a/v8/src/unofficial_napi.cc +++ b/v8/src/unofficial_napi.cc @@ -955,6 +955,9 @@ v8::Maybe SerializerContext::GetSharedArrayBufferId( v8::Local hook; if (!wrap->Get(context, OneByteString(isolate, "_getSharedArrayBufferId")).ToLocal(&hook) || !hook->IsFunction()) { + // A getter V8 terminated: the termination is what fails the write, and + // the default would throw a clone error over it. + if (isolate->IsExecutionTerminating()) return v8::Nothing(); return v8::ValueSerializer::Delegate::GetSharedArrayBufferId(isolate, shared_array_buffer); } From 72eea7618b8f61c962119da7b41ff6b7a4f19e76 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Fri, 6 Nov 2026 00:53:06 -0800 Subject: [PATCH 108/150] V8: drop the termination's pending null when it is cancelled A call that a termination fails leaves N-API's pending exception set to the null a v8::TryCatch records for a termination. Native code that terminated, made such a call and then cancelled the termination without taking that exception returned with it still pending, and the trampoline threw it into the JS that called: a catchable null that nothing threw. QuickJS drops its uncatchable error at the cancel, so there the JS went on as after any call. Found by the attack on the branch at "V8: keep a termination the serializer's shared-buffer getter runs into" (its finding 7). V8 now marks a pending exception taken from a TryCatch that caught a termination, and unofficial_napi_cancel_terminate_execution drops a marked one. The marker follows the exception: anything that sets or clears the pending exception resets it, and the context-token hook wrapper that stashes the pending exception at the release stashes it too. Ordinary pending exceptions are unchanged, and taking the null before cancelling, as EdgeJS does, works as before. Test: new test_73_termination_until_cancelled, both engines, CancelledInsideANativeFunction and CancelledInsideAModuleHook: a native function terminates, calls a JS function (which fails) and cancels, called in try/catch from a script and from the import.meta hook of a module the script evaluates in try/catch. The JS after the call must run and nothing may be caught or left pending. Before this change V8 gave "caught=yes after=yes ... error=null afterCall=no" for the first and "caught=yes after=yes innerCaught=no innerAfter=yes error=null afterCall=no" for the second; QuickJS passed both. Co-Authored-By: Claude Opus 5.5 --- tests/CMakeLists.txt | 4 + .../test_73_termination_until_cancelled.cc | 204 ++++++++++++++++++ v8/src/internal/napi_v8_env.h | 8 + v8/src/js_native_api_v8.cc | 35 +-- v8/src/unofficial_napi.cc | 4 + v8/src/unofficial_napi_contextify.cc | 3 + 6 files changed, 245 insertions(+), 13 deletions(-) create mode 100644 tests/runners/test_73_termination_until_cancelled.cc diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt index b32da9e871..c1b1b65a16 100644 --- a/tests/CMakeLists.txt +++ b/tests/CMakeLists.txt @@ -343,6 +343,10 @@ add_fixture_test(${_napi_test_prefix}_test_72_hooks_keep_termination runners/test_72_hooks_keep_termination.cc ) target_compile_definitions(${_napi_test_prefix}_test_72_hooks_keep_termination PRIVATE NAPI_VERSION=10) +add_fixture_test(${_napi_test_prefix}_test_73_termination_until_cancelled + runners/test_73_termination_until_cancelled.cc +) +target_compile_definitions(${_napi_test_prefix}_test_73_termination_until_cancelled PRIVATE NAPI_VERSION=10) if(_napi_test_engine STREQUAL "v8") # Only the V8 provider posts engine tasks through the enqueue hook. add_fixture_test(${_napi_test_prefix}_test_66_foreground_task_handoff diff --git a/tests/runners/test_73_termination_until_cancelled.cc b/tests/runners/test_73_termination_until_cancelled.cc new file mode 100644 index 0000000000..8c467c5479 --- /dev/null +++ b/tests/runners/test_73_termination_until_cancelled.cc @@ -0,0 +1,204 @@ +// A termination (unofficial_napi_terminate_execution, as EdgeJS's +// process.exit() and worker.terminate() use it) lasts until it is cancelled: +// calls into JS fail meanwhile, and nothing the JS wrapped in try/catch +// catches it, also when native code goes on after a call it failed, cancels +// it, or runs where the engine does not look for it. +// +// The JS asks for it as test_72's does: a native call that terminates, then +// a call to a JS function, so that V8, which acts on a termination at its +// next stack check, acts on it at once. + +#include "test_env.h" + +#include "node_api.h" +#include "unofficial_napi.h" + +#include + +class Test73TerminationUntilCancelled : public FixtureTestBase {}; + +namespace { + +napi_value Str(napi_env env, const char* value) { + napi_value out = nullptr; + if (napi_create_string_utf8(env, value, NAPI_AUTO_LENGTH, &out) != napi_ok) return nullptr; + return out; +} + +napi_value Global(napi_env env) { + napi_value global = nullptr; + EXPECT_EQ(napi_get_global(env, &global), napi_ok); + return global; +} + +// Terminates and calls tick(), so that V8 acts on it. +void TerminateNow(napi_env env) { + EXPECT_EQ(unofficial_napi_terminate_execution(env), napi_ok); + napi_value tick = nullptr; + napi_value ignored = nullptr; + napi_get_named_property(env, Global(env), "tick", &tick); + napi_call_function(env, Global(env), tick, 0, nullptr, &ignored); +} + +// Terminates, then cancels, without taking what the failed call left +// pending. +napi_value TerminateThenCancel(napi_env env, napi_callback_info /*info*/) { + TerminateNow(env); + EXPECT_EQ(unofficial_napi_cancel_terminate_execution(env), napi_ok); + return nullptr; +} + +void DefineGlobalFunction(napi_env env, const char* name, napi_callback cb, void* data = nullptr) { + napi_value fn = nullptr; + ASSERT_EQ(napi_create_function(env, name, NAPI_AUTO_LENGTH, cb, data, &fn), napi_ok); + ASSERT_EQ(napi_set_named_property(env, Global(env), name, fn), napi_ok); +} + +napi_status RunScript(napi_env env, const char* source) { + napi_value ignored = nullptr; + return napi_run_script(env, Str(env, source), &ignored); +} + +napi_value Eval(napi_env env, const char* source) { + napi_value result = nullptr; + EXPECT_EQ(napi_run_script(env, Str(env, source), &result), napi_ok) << source; + return result; +} + +std::string GlobalText(napi_env env, const char* name) { + napi_value value = nullptr; + napi_value string = nullptr; + char text[256] = {}; + size_t length = 0; + if (napi_get_named_property(env, Global(env), name, &value) != napi_ok || + napi_coerce_to_string(env, value, &string) != napi_ok || + napi_get_value_string_utf8(env, string, text, sizeof(text), &length) != napi_ok) { + return ""; + } + return std::string(text, length); +} + +void InstallHelpers(napi_env env) { + DefineGlobalFunction(env, "terminateThenCancel", TerminateThenCancel); + // Each catch block sets its flag first, by a plain store, at which no + // engine looks for a termination. + ASSERT_EQ(RunScript(env, + "globalThis.tick = function tick() {};" + "globalThis.caught = 'no'; globalThis.after = 'no';" + "globalThis.innerCaught = 'no'; globalThis.innerAfter = 'no';" + "globalThis.caughtError = 'none'; globalThis.afterCall = 'no';"), + napi_ok); +} + +// What the JS that led there managed to do. +std::string Flags(napi_env env) { + return "caught=" + GlobalText(env, "caught") + " after=" + GlobalText(env, "after") + + " innerCaught=" + GlobalText(env, "innerCaught") + + " innerAfter=" + GlobalText(env, "innerAfter") + + " error=" + GlobalText(env, "caughtError") + " afterCall=" + GlobalText(env, "afterCall"); +} + +void SetModuleHooks(napi_env env, napi_value import_callback, napi_value meta_callback) { + unofficial_napi_module_hooks hooks{}; + hooks.size = sizeof(hooks); + hooks.version = UNOFFICIAL_NAPI_MODULE_HOOKS_VERSION; + hooks.import_module_dynamically = import_callback; + hooks.initialize_import_meta_object = meta_callback; + ASSERT_EQ(unofficial_napi_module_wrap_set_hooks(env, &hooks), napi_ok); +} + +// A linked and instantiated module: source text, or synthetic with `steps` +// when `source_text` is null. +unofficial_napi_module MakeModule(napi_env env, const char* source_text, napi_value steps) { + napi_value wrapper = nullptr; + napi_value undefined = nullptr; + EXPECT_EQ(napi_create_object(env, &wrapper), napi_ok); + EXPECT_EQ(napi_get_undefined(env, &undefined), napi_ok); + unofficial_napi_module_create_options options{}; + options.size = sizeof(options); + options.version = UNOFFICIAL_NAPI_MODULE_CREATE_OPTIONS_VERSION; + options.wrapper = wrapper; + unofficial_napi_js_source source{}; + if (source_text != nullptr) { + source = unofficial_napi_js_source_from_text(Str(env, source_text)); + options.kind = unofficial_napi_module_source_text; + options.url = Str(env, "hooked.mjs"); + options.payload.source_text.source = &source; + options.payload.source_text.host_defined_option_id = undefined; + } else { + options.kind = unofficial_napi_module_synthetic; + options.url = Str(env, "synthetic"); + options.payload.synthetic.export_names = Eval(env, "['value']"); + options.payload.synthetic.synthetic_evaluation_steps = steps; + } + unofficial_napi_module_create_result created{}; + EXPECT_EQ(unofficial_napi_module_wrap_create(env, &options, &created), napi_ok); + if (created.module == nullptr) return nullptr; + EXPECT_EQ(unofficial_napi_module_wrap_link(env, created.module, 0, nullptr), napi_ok); + EXPECT_EQ(unofficial_napi_module_wrap_instantiate(env, created.module), napi_ok); + return created.module; +} + +// Evaluates the module its data names; what that left pending is the +// trampoline's to throw. +napi_value EvaluateModule(napi_env env, napi_callback_info info) { + void* data = nullptr; + if (napi_get_cb_info(env, info, nullptr, nullptr, nullptr, &data) != napi_ok) return nullptr; + napi_value result = nullptr; + if (unofficial_napi_module_wrap_evaluate( + env, static_cast(data), -1, false, &result) != napi_ok) { + return nullptr; + } + return result; +} + +constexpr char kEvaluateModuleInTryCatch[] = + "try { evaluateModule(); } catch (e) { caught = 'yes'; caughtError = e; }\n" + "after = 'yes';\n"; + +} // namespace + +// Native code that terminates, makes a call the termination fails, and +// cancels the termination before it returns, without taking what that call +// left pending. Nothing threw that: the JS that called goes on as after any +// call. V8 records a termination as a null pending exception, which it would +// otherwise throw into that JS as a catchable null; QuickJS drops its +// uncatchable error at the cancel. +TEST_F(Test73TerminationUntilCancelled, CancelledInsideANativeFunction) { + EnvScope s(runtime_.get()); + InstallHelpers(s.env); + EXPECT_EQ(RunScript(s.env, + "try { terminateThenCancel(); afterCall = 'yes'; }\n" + "catch (e) { caught = 'yes'; caughtError = e; }\n" + "after = 'yes';\n"), + napi_ok); + EXPECT_EQ(Flags(s.env), + "caught=no after=yes innerCaught=no innerAfter=no error=none afterCall=yes"); + bool pending = true; + EXPECT_EQ(napi_is_exception_pending(s.env, &pending), napi_ok); + EXPECT_FALSE(pending); +} + +// The same inside the import.meta hook, which throws what its callback left +// pending from the import.meta expression. +TEST_F(Test73TerminationUntilCancelled, CancelledInsideAModuleHook) { + EnvScope s(runtime_.get()); + InstallHelpers(s.env); + SetModuleHooks(s.env, nullptr, + Eval(s.env, + "(id, meta, wrap) => {\n" + " try { terminateThenCancel(); afterCall = 'yes'; }\n" + " catch (e) { caught = 'yes'; caughtError = e; }\n" + "}")); + unofficial_napi_module module = MakeModule( + s.env, + "try { import.meta; } catch (e) { globalThis.innerCaught = 'yes'; caughtError = e; }\n" + "globalThis.innerAfter = 'yes';\n", + nullptr); + ASSERT_NE(module, nullptr); + DefineGlobalFunction(s.env, "evaluateModule", EvaluateModule, module); + EXPECT_EQ(RunScript(s.env, kEvaluateModuleInTryCatch), napi_ok); + EXPECT_EQ(Flags(s.env), + "caught=no after=yes innerCaught=no innerAfter=yes error=none afterCall=yes"); + EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, module), napi_ok); +} diff --git a/v8/src/internal/napi_v8_env.h b/v8/src/internal/napi_v8_env.h index 0d45222521..9899304de6 100644 --- a/v8/src/internal/napi_v8_env.h +++ b/v8/src/internal/napi_v8_env.h @@ -172,6 +172,10 @@ struct napi_env__ { v8::Global last_exception_message; std::string last_exception_source_line; std::string last_exception_thrown_at; + // The pending exception is the null a TryCatch records for a termination. + // Nothing threw it, so cancelling the termination drops it, as QuickJS + // drops its uncatchable error then. + bool last_exception_is_termination = false; void* instance_data = nullptr; napi_finalize instance_data_finalize_cb = nullptr; void* instance_data_finalize_hint = nullptr; @@ -255,6 +259,10 @@ void napi_v8_set_last_exception( v8::Local exception, v8::Local message = v8::Local()); +// Drops N-API's pending exception if it stands for a termination: what +// unofficial_napi_cancel_terminate_execution does with it. +void napi_v8_drop_pending_termination(napi_env env); + // Throws `exception` into V8 unless V8 is terminating, and returns whether it // threw. Making an exception can run JS that V8 terminates (an inherited // `code` setter, a getter, the source-map callback), and throwing would then diff --git a/v8/src/js_native_api_v8.cc b/v8/src/js_native_api_v8.cc index 1a5c97aae2..a304e05ae9 100644 --- a/v8/src/js_native_api_v8.cc +++ b/v8/src/js_native_api_v8.cc @@ -552,16 +552,14 @@ void ClearLastException(napi_env env) { env->last_exception_message.Reset(); env->last_exception_source_line.clear(); env->last_exception_thrown_at.clear(); + env->last_exception_is_termination = false; } void SetLastException(napi_env env, v8::Local exception, v8::Local message = v8::Local()) { if (env == nullptr) return; - env->last_exception.Reset(); - env->last_exception_message.Reset(); - env->last_exception_source_line.clear(); - env->last_exception_thrown_at.clear(); + ClearLastException(env); if (exception.IsEmpty()) return; env->last_exception.Reset(env->isolate, exception); @@ -570,9 +568,16 @@ void SetLastException(napi_env env, } } +// What `tc` caught becomes N-API's pending exception. For a termination that +// is the null V8 records for one, marked as such. +void SetLastExceptionFromTryCatch(napi_env env, const v8::TryCatch& tc) { + SetLastException(env, tc.Exception(), tc.Message()); + if (env != nullptr) env->last_exception_is_termination = tc.HasTerminated(); +} + inline napi_status ReturnPendingIfCaught(napi_env env, v8::TryCatch& tc, const char* message) { if (tc.HasCaught()) { - SetLastException(env, tc.Exception(), tc.Message()); + SetLastExceptionFromTryCatch(env, tc); return napi_v8_set_last_error(env, napi_pending_exception, message); } return napi_v8_set_last_error(env, napi_generic_failure, message); @@ -869,6 +874,10 @@ void napi_v8_set_last_exception(napi_env env, SetLastException(env, exception, message); } +void napi_v8_drop_pending_termination(napi_env env) { + if (env != nullptr && env->last_exception_is_termination) ClearLastException(env); +} + bool napi_v8_throw_unless_terminating(v8::Isolate* isolate, v8::Local exception) { if (isolate == nullptr || isolate->IsExecutionTerminating()) return false; isolate->ThrowException(exception); @@ -1317,7 +1326,7 @@ napi_status NAPI_CDECL napi_create_bigint_words(napi_env env, env->context(), sign_bit, static_cast(word_count), words) .ToLocal(&out)) { if (tc.HasCaught()) { - SetLastException(env, tc.Exception(), tc.Message()); + SetLastExceptionFromTryCatch(env, tc); return napi_v8_set_last_error(env, napi_pending_exception, "BigInt creation threw"); } return napi_generic_failure; @@ -2436,7 +2445,7 @@ napi_status NAPI_CDECL napi_new_instance(napi_env env, if (!ctor->NewInstance(env->context(), static_cast(argc), args.data()) .ToLocal(&out)) { if (tryCatch.HasCaught()) { - SetLastException(env, tryCatch.Exception(), tryCatch.Message()); + SetLastExceptionFromTryCatch(env, tryCatch); return napi_v8_set_last_error(env, napi_pending_exception, "Constructor threw"); } return napi_generic_failure; @@ -2468,7 +2477,7 @@ napi_status NAPI_CDECL napi_call_function(napi_env env, v8::MaybeLocal maybe = fn->Call( context, napi_v8_unwrap_value(recv), argc, args.data()); if (tryCatch.HasCaught()) { - SetLastException(env, tryCatch.Exception(), tryCatch.Message()); + SetLastExceptionFromTryCatch(env, tryCatch); return napi_v8_set_last_error(env, napi_pending_exception, "Function call threw"); } if (maybe.IsEmpty()) { @@ -3030,7 +3039,7 @@ napi_status NAPI_CDECL napi_coerce_to_number(napi_env env, v8::Local out; if (!napi_v8_unwrap_value(value)->ToNumber(env->context()).ToLocal(&out)) { if (try_catch.HasCaught()) { - SetLastException(env, try_catch.Exception(), try_catch.Message()); + SetLastExceptionFromTryCatch(env, try_catch); } return napi_v8_set_last_error(env, napi_pending_exception, "Exception during number coercion"); } @@ -3049,7 +3058,7 @@ napi_status NAPI_CDECL napi_coerce_to_object(napi_env env, v8::Local out; if (!napi_v8_unwrap_value(value)->ToObject(env->context()).ToLocal(&out)) { if (try_catch.HasCaught()) { - SetLastException(env, try_catch.Exception(), try_catch.Message()); + SetLastExceptionFromTryCatch(env, try_catch); } return napi_v8_set_last_error(env, napi_pending_exception, "Exception during object coercion"); } @@ -3068,7 +3077,7 @@ napi_status NAPI_CDECL napi_coerce_to_string(napi_env env, v8::Local out; if (!napi_v8_unwrap_value(value)->ToString(env->context()).ToLocal(&out)) { if (try_catch.HasCaught()) { - SetLastException(env, try_catch.Exception(), try_catch.Message()); + SetLastExceptionFromTryCatch(env, try_catch); } return napi_v8_set_last_error(env, napi_pending_exception, "Exception during string coercion"); } @@ -3488,7 +3497,7 @@ napi_status NAPI_CDECL napi_run_script(napi_env env, v8::Local compiled; if (!v8::Script::Compile(env->context(), source.As()).ToLocal(&compiled)) { if (tc.HasCaught()) { - SetLastException(env, tc.Exception(), tc.Message()); + SetLastExceptionFromTryCatch(env, tc); return napi_pending_exception; } return napi_generic_failure; @@ -3496,7 +3505,7 @@ napi_status NAPI_CDECL napi_run_script(napi_env env, v8::Local out; if (!compiled->Run(env->context()).ToLocal(&out)) { if (tc.HasCaught()) { - SetLastException(env, tc.Exception(), tc.Message()); + SetLastExceptionFromTryCatch(env, tc); return napi_pending_exception; } return napi_generic_failure; diff --git a/v8/src/unofficial_napi.cc b/v8/src/unofficial_napi.cc index 71b1c6ce77..3fab409802 100644 --- a/v8/src/unofficial_napi.cc +++ b/v8/src/unofficial_napi.cc @@ -2146,6 +2146,10 @@ napi_status NAPI_CDECL unofficial_napi_terminate_execution(napi_env env) { napi_status NAPI_CDECL unofficial_napi_cancel_terminate_execution(napi_env env) { if (env == nullptr || env->isolate == nullptr) return napi_invalid_arg; env->isolate->CancelTerminateExecution(); + // A call the termination failed left its null pending. Nothing threw it: + // left there, the native function that cancels would throw it into its + // caller as a catchable null. + napi_v8_drop_pending_termination(env); return napi_ok; } diff --git a/v8/src/unofficial_napi_contextify.cc b/v8/src/unofficial_napi_contextify.cc index 46a9505639..dcbbe174b7 100644 --- a/v8/src/unofficial_napi_contextify.cc +++ b/v8/src/unofficial_napi_contextify.cc @@ -1369,6 +1369,8 @@ void CallContextTokenHook(napi_env env, std::string thrown_at; source_line.swap(env->last_exception_source_line); thrown_at.swap(env->last_exception_thrown_at); + const bool is_termination = env->last_exception_is_termination; + env->last_exception_is_termination = false; { v8::TryCatch try_catch(env->isolate); hook(env, realm, env->agent->context_token_data); @@ -1377,6 +1379,7 @@ void CallContextTokenHook(napi_env env, env->last_exception_message = std::move(message); env->last_exception_source_line.swap(source_line); env->last_exception_thrown_at.swap(thrown_at); + env->last_exception_is_termination = is_termination; } // A realm has a token while either hook is attached, as each context did. From 2b83fecf8cc0af085a5a71615e7c92cd816987b2 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Fri, 6 Nov 2026 00:55:31 -0800 Subject: [PATCH 109/150] V8: keep the embedder's termination when a script's timeout expires too unofficial_napi_run_script with a timeout (vm's runInContext) treats a terminated script whose watchdog fired as a timeout: it cancels the termination and throws ERR_SCRIPT_EXECUTION_TIMEOUT (or ERR_SCRIPT_EXECUTION_INTERRUPTED for SIGINT). When the embedder had terminated the env as well (process.exit(), worker.terminate()), that cancelled the embedder's termination and threw a catchable error in its place: the JS that ran the script caught it and went on. Node checks env->is_stopping() before it cancels for the timeout. Found by the attack on the branch at "V8: keep a termination the serializer's shared-buffer getter runs into" (its finding 3). The agent now remembers the embedder's termination: unofficial_napi_terminate_execution sets termination_requested (atomic: any thread may terminate), and unofficial_napi_cancel_terminate_execution and the agent's Shutdown clear it. run_script returns napi_pending_exception without cancelling while it is set, so the termination keeps unwinding. A timeout or SIGINT on its own is unchanged. Test: test_73 ScriptTimeoutKeepsTheEmbeddersTermination, both engines: a native function runs, with a 50 ms timeout, a script that calls a native function which terminates and sleeps 300 ms; the script runs from a script that wraps the call in try/catch. The run must come back napi_pending_exception with an exception pending and no flag set, and run_script must return napi_pending_exception. Before this change V8 gave run 0 and "caught=yes after=yes ... error=Error: Script execution timed out after 50ms"; QuickJS, which has no timeout, passed. Co-Authored-By: Claude Opus 5.5 --- .../test_73_termination_until_cancelled.cc | 68 +++++++++++++++++++ v8/src/internal/napi_v8_agent.h | 14 +++- v8/src/unofficial_napi.cc | 9 +++ v8/src/unofficial_napi_contextify.cc | 8 +++ 4 files changed, 96 insertions(+), 3 deletions(-) diff --git a/tests/runners/test_73_termination_until_cancelled.cc b/tests/runners/test_73_termination_until_cancelled.cc index 8c467c5479..2101f858ba 100644 --- a/tests/runners/test_73_termination_until_cancelled.cc +++ b/tests/runners/test_73_termination_until_cancelled.cc @@ -13,7 +13,9 @@ #include "node_api.h" #include "unofficial_napi.h" +#include #include +#include class Test73TerminationUntilCancelled : public FixtureTestBase {}; @@ -48,6 +50,28 @@ napi_value TerminateThenCancel(napi_env env, napi_callback_info /*info*/) { return nullptr; } +// Terminates, then sleeps long enough for a 50 ms script timeout to expire +// meanwhile. +napi_value TerminateAndSleep(napi_env env, napi_callback_info /*info*/) { + EXPECT_EQ(unofficial_napi_terminate_execution(env), napi_ok); + std::this_thread::sleep_for(std::chrono::milliseconds(300)); + return nullptr; +} + +// The status of the N-API call a native function below made last. +napi_status g_status = napi_ok; + +// Runs a script with a 50 ms timeout that terminates while the timeout +// expires. +napi_value RunScriptWithTimeout(napi_env env, napi_callback_info /*info*/) { + const unofficial_napi_js_source source = unofficial_napi_js_source_from_text( + Str(env, "terminateAndSleep(); tick(); afterCall = 'yes';")); + napi_value out = nullptr; + g_status = unofficial_napi_run_script(env, nullptr, &source, Str(env, "timeout.js"), 0, 0, 50, + true, false, false, nullptr, &out); + return nullptr; +} + void DefineGlobalFunction(napi_env env, const char* name, napi_callback cb, void* data = nullptr) { napi_value fn = nullptr; ASSERT_EQ(napi_create_function(env, name, NAPI_AUTO_LENGTH, cb, data, &fn), napi_ok); @@ -78,8 +102,23 @@ std::string GlobalText(napi_env env, const char* name) { return std::string(text, length); } +// What EdgeJS does once the stack has unwound: take the pending exception, +// then cancel the termination. Returns whether one was pending. +bool FinishTermination(napi_env env) { + bool pending = false; + EXPECT_EQ(napi_is_exception_pending(env, &pending), napi_ok); + if (pending) { + napi_value exception = nullptr; + EXPECT_EQ(napi_get_and_clear_last_exception(env, &exception), napi_ok); + } + EXPECT_EQ(unofficial_napi_cancel_terminate_execution(env), napi_ok); + return pending; +} + void InstallHelpers(napi_env env) { DefineGlobalFunction(env, "terminateThenCancel", TerminateThenCancel); + DefineGlobalFunction(env, "terminateAndSleep", TerminateAndSleep); + DefineGlobalFunction(env, "runScriptWithTimeout", RunScriptWithTimeout); // Each catch block sets its flag first, by a plain store, at which no // engine looks for a termination. ASSERT_EQ(RunScript(env, @@ -98,6 +137,20 @@ std::string Flags(napi_env env) { " error=" + GlobalText(env, "caughtError") + " afterCall=" + GlobalText(env, "afterCall"); } +constexpr char kNothingRan[] = + "caught=no after=no innerCaught=no innerAfter=no error=none afterCall=no"; + +// Runs `script` and expects it to come back terminated, with nothing it +// wrapped in try/catch caught, and nothing after that run. +void ExpectRunTerminated(napi_env env, const char* script) { + EXPECT_EQ(RunScript(env, script), napi_pending_exception); + EXPECT_TRUE(FinishTermination(env)) << "nothing pending after the run"; + EXPECT_EQ(Flags(env), kNothingRan); + // Cancelling leaves the env usable. + EXPECT_EQ(RunScript(env, "globalThis.resumed = 'yes';"), napi_ok); + EXPECT_EQ(GlobalText(env, "resumed"), "yes"); +} + void SetModuleHooks(napi_env env, napi_value import_callback, napi_value meta_callback) { unofficial_napi_module_hooks hooks{}; hooks.size = sizeof(hooks); @@ -202,3 +255,18 @@ TEST_F(Test73TerminationUntilCancelled, CancelledInsideAModuleHook) { "caught=no after=yes innerCaught=no innerAfter=yes error=none afterCall=yes"); EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, module), napi_ok); } + +// A script run with a timeout that the embedder terminates while the +// timeout expires too: the termination is not the timeout's to cancel, and +// must not come back as the timeout's catchable error. QuickJS has no +// timeout, so only the termination stops the script there. +TEST_F(Test73TerminationUntilCancelled, ScriptTimeoutKeepsTheEmbeddersTermination) { + EnvScope s(runtime_.get()); + InstallHelpers(s.env); + g_status = napi_ok; + ExpectRunTerminated( + s.env, + "try { runScriptWithTimeout(); } catch (e) { caught = 'yes'; caughtError = e; }\n" + "after = 'yes';\n"); + EXPECT_EQ(g_status, napi_pending_exception); +} diff --git a/v8/src/internal/napi_v8_agent.h b/v8/src/internal/napi_v8_agent.h index 85bf6a8c3b..8a6c3b1e86 100644 --- a/v8/src/internal/napi_v8_agent.h +++ b/v8/src/internal/napi_v8_agent.h @@ -1,6 +1,7 @@ #ifndef NAPI_V8_AGENT_H_ #define NAPI_V8_AGENT_H_ +#include #include #include #include @@ -19,9 +20,10 @@ class CpuProfiler; // its principal env; envs for other realms of the isolate will share it. // // Only the isolate's own thread reads or writes these fields, except -// `allocator` and `hash_seed`, which are fixed once the agent is set up, and -// the enqueue hook, which backing-store deleters read on any thread under -// NapiV8ExternalHintsMutex(). +// `allocator` and `hash_seed`, which are fixed once the agent is set up, the +// enqueue hook, which backing-store deleters read on any thread under +// NapiV8ExternalHintsMutex(), and `termination_requested`, which any thread +// may set. struct napi_agent__ { explicit napi_agent__(v8::Isolate* isolate); ~napi_agent__(); @@ -69,6 +71,12 @@ struct napi_agent__ { void* near_heap_limit_data = nullptr; bool near_heap_limit_installed = false; + // The embedder's termination: set by unofficial_napi_terminate_execution + // until unofficial_napi_cancel_terminate_execution (or Shutdown) clears + // it. V8 does not tell it apart from one a script timeout's watchdog asks + // for. + std::atomic termination_requested{false}; + // Profiler sessions. V8's CPU and sampling heap profilers are per isolate. v8::CpuProfiler* cpu_profiler = nullptr; std::vector active_profiles; diff --git a/v8/src/unofficial_napi.cc b/v8/src/unofficial_napi.cc index 3fab409802..2677e8280c 100644 --- a/v8/src/unofficial_napi.cc +++ b/v8/src/unofficial_napi.cc @@ -1642,6 +1642,7 @@ void napi_agent__::Shutdown() { near_heap_limit_data = nullptr; fatal_error_callback = nullptr; oom_error_callback = nullptr; + termination_requested.store(false, std::memory_order_release); isolate->CancelTerminateExecution(); isolate->SetPromiseHook(nullptr); isolate->SetPromiseRejectCallback(nullptr); @@ -2139,12 +2140,20 @@ napi_status NAPI_CDECL unofficial_napi_create_uninitialized_arraybuffer( napi_status NAPI_CDECL unofficial_napi_terminate_execution(napi_env env) { if (env == nullptr || env->isolate == nullptr) return napi_invalid_arg; + // Any thread may call this (worker.terminate() does): the agent is fixed + // once the env exists, and its flag is atomic. + if (env->agent != nullptr) { + env->agent->termination_requested.store(true, std::memory_order_release); + } env->isolate->TerminateExecution(); return napi_ok; } napi_status NAPI_CDECL unofficial_napi_cancel_terminate_execution(napi_env env) { if (env == nullptr || env->isolate == nullptr) return napi_invalid_arg; + if (env->agent != nullptr) { + env->agent->termination_requested.store(false, std::memory_order_release); + } env->isolate->CancelTerminateExecution(); // A call the termination failed left its null pending. Nothing threw it: // left there, the native function that cancels would throw it into its diff --git a/v8/src/unofficial_napi_contextify.cc b/v8/src/unofficial_napi_contextify.cc index dcbbe174b7..78deed005e 100644 --- a/v8/src/unofficial_napi_contextify.cc +++ b/v8/src/unofficial_napi_contextify.cc @@ -2237,6 +2237,14 @@ napi_status NAPI_CDECL unofficial_napi_run_script( } if (timed_out || received_signal) { + // The embedder may have terminated the env meanwhile (process.exit(), + // worker.terminate()). That termination is not the timeout's to cancel, + // and turned into the timeout's catchable error it would let the JS that + // ran the script go on: it keeps unwinding instead, as in Node, which + // checks env->is_stopping() first. + if (env->agent->termination_requested.load(std::memory_order_acquire)) { + return napi_pending_exception; + } isolate->CancelTerminateExecution(); napi_value error = nullptr; From b3f0045ee3319ecd8fd0cbaa9a5d936a23f0a9ea Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Fri, 6 Nov 2026 01:02:46 -0800 Subject: [PATCH 110/150] V8: keep a termination until it is cancelled V8 forgets a termination on its own: once the outermost JS frame has unwound, and whenever an API call enters V8 while it unwinds (V8 13.6's PREPARE_FOR_EXECUTION clears it, as napi_create_function, napi_create_date or the compile calls do). The provider only asked V8 whether it was terminating, so: - After a run that a termination stopped, the next run succeeded without a cancel, against the header's "calls into JS fail with napi_pending_exception until the termination is cancelled". A finalizer drained at a checkpoint ran its next call into JS after its first was terminated, the checkpoint returned napi_ok and the next run succeeded; a cleanup hook that terminated during the release left the later hooks and finalizers running JS. QuickJS keeps the termination until the cancel in all of these. - Native code that went on with N-API after its call into JS failed because of a termination made V8 forget it, and the trampoline then threw the null the TryCatch had recorded for the termination: the JS that called caught null and ran on. The same native code called from the hooks test_72 fixed (import.meta, synthetic evaluation steps, import(), the promise reject callback, the prepare-stack-trace callback, the serializer's host-object hook, the context-token assign hook) got past their fixes the same way. Found by the attack on the branch at "V8: keep a termination the serializer's shared-buffer getter runs into" (its findings 5, and 1 for the trampolines; the guards it also asks for follow). The agent's termination_requested flag, which the embedder's termination already sets, now counts as terminating: N-API's TerminatedOrTerminating checks it as well as V8, as Node's can_call_into_js() stays false once the env stops, so calls guarded by NAPI_V8_RETURN_IF_TERMINATING fail until the cancel. A refused call leaves the termination's null pending (marked, so the cancel drops it) unless something else is, as QuickJS leaves its uncatchable error pending; test_67 and test_68 already expected that. When a native callback returns, or a module hook rethrows what its callback left, while the env terminates, what is pending is dropped and V8 is made to unwind with the termination now: if V8 is not unwinding with it, the provider asks for it again and calls a no-op JS function, whose entry is the stack check where V8 acts on it. That also stops the calling JS right after a native function that terminated, as on QuickJS, where V8 used to run on to its next stack check. The event-loop checkpoint fails with napi_pending_exception, and runs no more JS, when the env terminates before it or a finalizer or microtask terminates it. The release still runs its hooks and finalizers with JS usable: Shutdown clears the flag, as it already cancelled V8's termination. Test: test_73, both engines unless noted, each run in try/catch with flags set in the catch and after, which must stay unset: - TopLevelRunKeepsTheTerminationUntilCancelled: after "terminate(); tick();" a run and a napi_call_function must fail until the cancel. Before: the next run returned 0. - NativeCallsAfterTheTermination: a native function terminates, calls a JS function, then makes one of twelve N-API calls (the creators, the compile and realm calls, run_script, napi_get_and_clear_last_exception). Before, on V8, every one but the last gave run 0 and "caught=yes after=yes ... error=null". - NativeCallsAfterTheTerminationInsideModuleHooks: that native function called from the import.meta hook, synthetic steps, the import() hook and the reject callback. Before: run 0 and innerCaught=yes (import.meta) or caught=yes (the others) with error=null; the reject callback gave run 0 and next run 0. - FinalizerDrainedAtACheckpoint: a finalizer calls a JS function that terminates, then another JS function; the second call and the next run must fail. Before: second call 0. - CheckpointAfterTheTermination: a native function terminates and runs a checkpoint with a microtask queued; the checkpoint must fail and run nothing. Before: checkpoint 0, the microtask ran, error=null caught. - TerminationRequestedInsideTheRelease: a cleanup hook terminates during the release; its next run, the later hook's run and a finalizer's run must fail. Before: { 10, 0, 0, 0 }. - V8 only, NativeCallsAfterTheTerminationInsideV8Hooks and ...InsideTheTokenAssignHook: the native function called from the prepare-stack-trace callback (QuickJS never calls it), the serializer's host-object hook (QuickJS's serdes binding calls no serializer hook) and the context-token assign hook (only V8 accepts those hooks). Before: run 0, caught=yes, error=null in each. QuickJS passed all of them before. test_67's QuickJSStopsAsSoonAsTheCallbackReturns ("terminate(); globalThis.reached = true;" must not run the store) now runs on both engines as StopsAsSoonAsTheCallbackReturns. Before this change V8 gave run 0 and reached set, which is why it was QuickJS only. Co-Authored-By: Claude Opus 5.5 --- tests/runners/test_67_terminate_execution.cc | 10 +- .../test_73_termination_until_cancelled.cc | 416 ++++++++++++++++++ v8/src/internal/napi_v8_agent.h | 10 +- v8/src/internal/napi_v8_env.h | 24 +- v8/src/js_native_api_v8.cc | 81 +++- v8/src/unofficial_napi.cc | 34 +- 6 files changed, 534 insertions(+), 41 deletions(-) diff --git a/tests/runners/test_67_terminate_execution.cc b/tests/runners/test_67_terminate_execution.cc index 8016a457c8..4cfe8a9661 100644 --- a/tests/runners/test_67_terminate_execution.cc +++ b/tests/runners/test_67_terminate_execution.cc @@ -220,11 +220,10 @@ TEST_F(Test67TerminateExecution, TerminateBeforeACallStopsThatCall) { EXPECT_EQ(Log(s.env), "called"); } -#if defined(NAPI_TEST_ENGINE_QUICKJS) -// V8 acts on a termination at its next stack check, so a plain store right -// after the terminating callback may still run there. QuickJS stops as soon -// as the callback returns. -TEST_F(Test67TerminateExecution, QuickJSStopsAsSoonAsTheCallbackReturns) { +// The JS stops as soon as the terminating callback returns, also before a +// plain store, at which V8 does not look for a termination: the provider +// makes V8 act on it when the callback returns. +TEST_F(Test67TerminateExecution, StopsAsSoonAsTheCallbackReturns) { EnvScope s(runtime_.get()); InstallHelpers(s.env); @@ -233,6 +232,7 @@ TEST_F(Test67TerminateExecution, QuickJSStopsAsSoonAsTheCallbackReturns) { EXPECT_EQ(RunScriptToString(s.env, "typeof globalThis.reached"), "undefined"); } +#if defined(NAPI_TEST_ENGINE_QUICKJS) TEST_F(Test67TerminateExecution, QuickJSTerminatesInsideAMicrotask) { EnvScope s(runtime_.get()); InstallHelpers(s.env); diff --git a/tests/runners/test_73_termination_until_cancelled.cc b/tests/runners/test_73_termination_until_cancelled.cc index 2101f858ba..16c3145420 100644 --- a/tests/runners/test_73_termination_until_cancelled.cc +++ b/tests/runners/test_73_termination_until_cancelled.cc @@ -14,8 +14,10 @@ #include "unofficial_napi.h" #include +#include #include #include +#include class Test73TerminationUntilCancelled : public FixtureTestBase {}; @@ -33,6 +35,13 @@ napi_value Global(napi_env env) { return global; } +napi_value Terminate(napi_env env, napi_callback_info /*info*/) { + EXPECT_EQ(unofficial_napi_terminate_execution(env), napi_ok); + return nullptr; +} + +napi_value Noop(napi_env /*env*/, napi_callback_info /*info*/) { return nullptr; } + // Terminates and calls tick(), so that V8 acts on it. void TerminateNow(napi_env env) { EXPECT_EQ(unofficial_napi_terminate_execution(env), napi_ok); @@ -72,6 +81,99 @@ napi_value RunScriptWithTimeout(napi_env env, napi_callback_info /*info*/) { return nullptr; } +// N-API calls native code may make after a call into JS failed because of +// a termination, ignoring the failure. Those that enter V8 would have it +// forget the termination; those that run JS set afterCall. +constexpr const char* kAfterCalls[] = { + "napi_create_function", + "napi_create_promise", + "napi_create_date", + "napi_define_class", + "napi_create_buffer", + "unofficial_napi_create_private_symbol", + "unofficial_napi_compile_function", + "unofficial_napi_get_own_non_index_properties", + "unofficial_napi_create_realm (sandbox)", + "unofficial_napi_contextify_contains_module_syntax", + "unofficial_napi_run_script", + "napi_get_and_clear_last_exception", +}; +constexpr int kAfterCallCount = sizeof(kAfterCalls) / sizeof(kAfterCalls[0]); + +napi_status CallAfter(napi_env env, int kind) { + napi_value out = nullptr; + napi_value undefined = nullptr; + napi_get_undefined(env, &undefined); + switch (kind) { + case 0: + return napi_create_function(env, "f", NAPI_AUTO_LENGTH, Noop, nullptr, &out); + case 1: { + napi_deferred deferred = nullptr; + return napi_create_promise(env, &deferred, &out); + } + case 2: + return napi_create_date(env, 0, &out); + case 3: + return napi_define_class(env, "C", NAPI_AUTO_LENGTH, Noop, nullptr, 0, nullptr, &out); + case 4: { + void* data = nullptr; + return napi_create_buffer(env, 4, &data, &out); + } + case 5: + return unofficial_napi_create_private_symbol(env, "p", NAPI_AUTO_LENGTH, &out); + case 6: { + const unofficial_napi_js_source source = + unofficial_napi_js_source_from_text(Str(env, "return 1;")); + return unofficial_napi_compile_function(env, nullptr, &source, Str(env, "f.js"), 0, 0, + undefined, undefined, undefined, &out); + } + case 7: { + napi_value object = nullptr; + napi_create_object(env, &object); + return unofficial_napi_get_own_non_index_properties(env, object, 0, &out); + } + case 8: { + napi_value sandbox = nullptr; + napi_create_object(env, &sandbox); + unofficial_napi_realm_options options; + unofficial_napi_realm_options_init(&options); + options.sandbox_or_null = sandbox; + unofficial_napi_realm realm = nullptr; + return unofficial_napi_create_realm(env, &options, &realm, &out); + } + case 9: { + bool result = false; + return unofficial_napi_contextify_contains_module_syntax( + env, Str(env, "export {}"), Str(env, "m.js"), undefined, false, &result); + } + case 10: { + const unofficial_napi_js_source source = + unofficial_napi_js_source_from_text(Str(env, "globalThis.afterCall = 'yes';")); + return unofficial_napi_run_script(env, nullptr, &source, Str(env, "after.js"), 0, 0, -1, + true, false, false, nullptr, &out); + } + default: { + bool pending = false; + napi_is_exception_pending(env, &pending); + if (!pending) return napi_ok; + return napi_get_and_clear_last_exception(env, &out); + } + } +} + +// Terminates, then makes the N-API call its argument names, as native code +// that ignores the failed call does. +napi_value TerminateThen(napi_env env, napi_callback_info info) { + size_t argc = 1; + napi_value kind_value = nullptr; + EXPECT_EQ(napi_get_cb_info(env, info, &argc, &kind_value, nullptr, nullptr), napi_ok); + int32_t kind = 0; + EXPECT_EQ(napi_get_value_int32(env, kind_value, &kind), napi_ok); + TerminateNow(env); + g_status = CallAfter(env, kind); + return nullptr; +} + void DefineGlobalFunction(napi_env env, const char* name, napi_callback cb, void* data = nullptr) { napi_value fn = nullptr; ASSERT_EQ(napi_create_function(env, name, NAPI_AUTO_LENGTH, cb, data, &fn), napi_ok); @@ -116,6 +218,8 @@ bool FinishTermination(napi_env env) { } void InstallHelpers(napi_env env) { + DefineGlobalFunction(env, "terminate", Terminate); + DefineGlobalFunction(env, "terminateThen", TerminateThen); DefineGlobalFunction(env, "terminateThenCancel", TerminateThenCancel); DefineGlobalFunction(env, "terminateAndSleep", TerminateAndSleep); DefineGlobalFunction(env, "runScriptWithTimeout", RunScriptWithTimeout); @@ -151,6 +255,21 @@ void ExpectRunTerminated(napi_env env, const char* script) { EXPECT_EQ(GlobalText(env, "resumed"), "yes"); } +// Runs `script` and expects it, or the next run, to come back terminated, +// with nothing caught: for callbacks the engine cannot report a failure +// from. +void ExpectRunOrNextTerminated(napi_env env, const char* script) { + const napi_status run = RunScript(env, script); + const napi_status next = RunScript(env, "globalThis.next = 'yes';"); + FinishTermination(env); + EXPECT_TRUE(run == napi_pending_exception || next == napi_pending_exception) + << "run " << run << ", next run " << next; + EXPECT_EQ(GlobalText(env, "caught"), "no"); + EXPECT_EQ(GlobalText(env, "innerCaught"), "no"); + EXPECT_EQ(GlobalText(env, "caughtError"), "none"); + EXPECT_EQ(RunScript(env, "globalThis.resumed = 'yes';"), napi_ok); +} + void SetModuleHooks(napi_env env, napi_value import_callback, napi_value meta_callback) { unofficial_napi_module_hooks hooks{}; hooks.size = sizeof(hooks); @@ -270,3 +389,300 @@ TEST_F(Test73TerminationUntilCancelled, ScriptTimeoutKeepsTheEmbeddersTerminatio "after = 'yes';\n"); EXPECT_EQ(g_status, napi_pending_exception); } + +// The run a termination stopped leaves it in effect: the next run fails too +// until the termination is cancelled. V8 forgets a termination once the +// outermost JS frame has unwound. +TEST_F(Test73TerminationUntilCancelled, TopLevelRunKeepsTheTerminationUntilCancelled) { + EnvScope s(runtime_.get()); + InstallHelpers(s.env); + napi_value mark = Eval(s.env, "() => { afterCall = 'yes'; }"); + EXPECT_EQ(RunScript(s.env, "terminate(); tick();"), napi_pending_exception); + EXPECT_EQ(RunScript(s.env, "afterCall = 'yes';"), napi_pending_exception); + napi_value result = nullptr; + EXPECT_EQ(napi_call_function(s.env, Global(s.env), mark, 0, nullptr, &result), + napi_pending_exception); + EXPECT_TRUE(FinishTermination(s.env)); + EXPECT_EQ(GlobalText(s.env, "afterCall"), "no"); + EXPECT_EQ(RunScript(s.env, "afterCall = 'yes';"), napi_ok); +} + +// Native code that goes on with N-API after its call into JS failed because +// of the termination. On V8 an N-API call that enters V8 clears the +// termination, and the trampoline then threw the null the TryCatch recorded +// for it, which the JS caught. +TEST_F(Test73TerminationUntilCancelled, NativeCallsAfterTheTermination) { + for (int kind = 0; kind < kAfterCallCount; ++kind) { + SCOPED_TRACE(kAfterCalls[kind]); + EnvScope s(runtime_.get()); + InstallHelpers(s.env); + const std::string script = "try { terminateThen(" + std::to_string(kind) + + "); } catch (e) { caught = 'yes'; caughtError = e; }\n" + "after = 'yes';\n"; + ExpectRunTerminated(s.env, script.c_str()); + } +} + +// The same native code, called from the module hooks test_72 covers: those +// see what the native function threw. +TEST_F(Test73TerminationUntilCancelled, NativeCallsAfterTheTerminationInsideModuleHooks) { + { + SCOPED_TRACE("import.meta"); + EnvScope s(runtime_.get()); + InstallHelpers(s.env); + SetModuleHooks(s.env, nullptr, Eval(s.env, "(id, meta, wrap) => { terminateThen(0); }")); + unofficial_napi_module module = MakeModule( + s.env, + "try { import.meta; } catch (e) { globalThis.innerCaught = 'yes'; caughtError = e; }\n" + "globalThis.innerAfter = 'yes';\n", + nullptr); + ASSERT_NE(module, nullptr); + DefineGlobalFunction(s.env, "evaluateModule", EvaluateModule, module); + ExpectRunTerminated(s.env, kEvaluateModuleInTryCatch); + EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, module), napi_ok); + } + { + SCOPED_TRACE("synthetic steps"); + EnvScope s(runtime_.get()); + InstallHelpers(s.env); + unofficial_napi_module module = + MakeModule(s.env, nullptr, Eval(s.env, "(function () { terminateThen(1); })")); + ASSERT_NE(module, nullptr); + DefineGlobalFunction(s.env, "evaluateModule", EvaluateModule, module); + ExpectRunTerminated(s.env, kEvaluateModuleInTryCatch); + EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, module), napi_ok); + } + { + SCOPED_TRACE("import()"); + EnvScope s(runtime_.get()); + InstallHelpers(s.env); + SetModuleHooks( + s.env, + Eval(s.env, "(id, specifier, phase, attributes, name) => { terminateThen(2); }"), + nullptr); + ExpectRunTerminated( + s.env, + "try { import('x').catch(() => {}); } catch (e) { caught = 'yes'; caughtError = e; }\n" + "after = 'yes';\n"); + } + { + SCOPED_TRACE("promise reject callback"); + EnvScope s(runtime_.get()); + InstallHelpers(s.env); + ASSERT_EQ(unofficial_napi_set_promise_reject_callback( + s.env, Eval(s.env, "(type, promise, reason) => { terminateThen(3); }")), + napi_ok); + ExpectRunOrNextTerminated( + s.env, + "try { Promise.reject(1); tick(); } catch (e) { caught = 'yes'; caughtError = e; }\n" + "after = 'yes';\n"); + } +} + +// A finalizer drained at a checkpoint (V8; QuickJS runs it while it +// collects) whose JS is terminated. Nothing reports a failure from a +// finalizer: its next call into JS must fail, and the next run. +namespace { +napi_status g_finalizer_first = napi_ok; +napi_status g_finalizer_second = napi_ok; +bool g_finalizer_ran = false; +void TerminatingFinalizer(napi_env env, void* /*data*/, void* /*hint*/) { + g_finalizer_ran = true; + napi_value terminate_js = nullptr; + napi_value mark = nullptr; + napi_value ignored = nullptr; + napi_get_named_property(env, Global(env), "terminateJs", &terminate_js); + napi_get_named_property(env, Global(env), "markAfterCall", &mark); + g_finalizer_first = napi_call_function(env, Global(env), terminate_js, 0, nullptr, &ignored); + g_finalizer_second = napi_call_function(env, Global(env), mark, 0, nullptr, &ignored); +} +} // namespace + +TEST_F(Test73TerminationUntilCancelled, FinalizerDrainedAtACheckpoint) { + EnvScope s(runtime_.get()); + InstallHelpers(s.env); + ASSERT_EQ(RunScript(s.env, + "globalThis.terminateJs = () => { terminate(); tick(); };" + "globalThis.markAfterCall = () => { afterCall = 'yes'; };"), + napi_ok); + g_finalizer_ran = false; + { + napi_handle_scope scope = nullptr; + ASSERT_EQ(napi_open_handle_scope(s.env, &scope), napi_ok); + napi_value object = nullptr; + ASSERT_EQ(napi_create_object(s.env, &object), napi_ok); + ASSERT_EQ(napi_add_finalizer(s.env, object, nullptr, TerminatingFinalizer, nullptr, nullptr), + napi_ok); + ASSERT_EQ(napi_close_handle_scope(s.env, scope), napi_ok); + } + napi_status checkpoint = napi_ok; + for (int i = 0; i < 5 && !g_finalizer_ran; ++i) { + ASSERT_EQ(unofficial_napi_collect_garbage(s.env), napi_ok); + checkpoint = unofficial_napi_event_loop_checkpoint( + s.env, unofficial_napi_event_loop_checkpoint_microtasks, false, nullptr); + } + ASSERT_TRUE(g_finalizer_ran); + EXPECT_EQ(g_finalizer_first, napi_pending_exception); + EXPECT_EQ(g_finalizer_second, napi_pending_exception); + EXPECT_EQ(RunScript(s.env, "afterCall = 'yes';"), napi_pending_exception) + << "checkpoint " << checkpoint; + FinishTermination(s.env); + EXPECT_EQ(GlobalText(s.env, "afterCall"), "no"); +} + +// A native function that terminates and then runs a checkpoint with a +// microtask queued: the checkpoint runs no JS. +namespace { +napi_value TerminateThenCheckpoint(napi_env env, napi_callback_info /*info*/) { + TerminateNow(env); + g_status = unofficial_napi_event_loop_checkpoint( + env, unofficial_napi_event_loop_checkpoint_microtasks, false, nullptr); + return nullptr; +} +} // namespace + +TEST_F(Test73TerminationUntilCancelled, CheckpointAfterTheTermination) { + EnvScope s(runtime_.get()); + InstallHelpers(s.env); + DefineGlobalFunction(s.env, "terminateThenCheckpoint", TerminateThenCheckpoint); + g_status = napi_ok; + ExpectRunTerminated( + s.env, + "Promise.resolve().then(() => { afterCall = 'yes'; });\n" + "try { terminateThenCheckpoint(); } catch (e) { caught = 'yes'; caughtError = e; }\n" + "after = 'yes';\n"); + EXPECT_EQ(g_status, napi_pending_exception); +} + +// A cleanup hook that terminates while the env is released: the release +// completes, and the hooks and finalizers after it run no JS. +namespace { +std::vector g_release_runs; +void TerminatingCleanupHook(void* arg) { + napi_env env = static_cast(arg); + napi_value fn = nullptr; + napi_value ignored = nullptr; + napi_get_named_property(env, Global(env), "terminateJs", &fn); + g_release_runs.push_back(napi_call_function(env, Global(env), fn, 0, nullptr, &ignored)); + napi_value made = nullptr; + (void)napi_create_function(env, "f", NAPI_AUTO_LENGTH, Noop, nullptr, &made); + g_release_runs.push_back(napi_run_script(env, Str(env, "afterCall = 'yes'; 1"), &made)); +} +void LaterCleanupHook(void* arg) { + napi_env env = static_cast(arg); + napi_value result = nullptr; + g_release_runs.push_back(napi_run_script(env, Str(env, "afterCall = 'yes'; 1"), &result)); +} +void ReleaseFinalizer(napi_env env, void* /*data*/, void* /*hint*/) { + napi_value result = nullptr; + g_release_runs.push_back(napi_run_script(env, Str(env, "afterCall = 'yes'; 1"), &result)); +} +} // namespace + +TEST_F(Test73TerminationUntilCancelled, TerminationRequestedInsideTheRelease) { + g_release_runs.clear(); + { + EnvScope s(runtime_.get()); + InstallHelpers(s.env); + ASSERT_EQ(RunScript(s.env, "globalThis.terminateJs = () => { terminate(); tick(); };"), + napi_ok); + napi_value object = nullptr; + ASSERT_EQ(napi_create_object(s.env, &object), napi_ok); + napi_ref keep = nullptr; + ASSERT_EQ(napi_create_reference(s.env, object, 1, &keep), napi_ok); + ASSERT_EQ(napi_add_finalizer(s.env, object, nullptr, ReleaseFinalizer, nullptr, nullptr), + napi_ok); + ASSERT_EQ(napi_add_env_cleanup_hook(s.env, LaterCleanupHook, s.env), napi_ok); + ASSERT_EQ(napi_add_env_cleanup_hook(s.env, TerminatingCleanupHook, s.env), napi_ok); + } + // The terminating hook's call and run, the later hook's run, the + // finalizer's run. + EXPECT_EQ(g_release_runs, + std::vector(4, napi_pending_exception)); +} + +#if defined(NAPI_TEST_ENGINE_V8) +// The same native code, called from the hooks only V8 runs: the +// prepare-stack-trace callback (QuickJS never calls it), the serializer's +// host-object hook (QuickJS's serdes binding calls none of the serializer's +// hooks) and the deprecated context-token assign hook (only V8 accepts the +// context-token hooks). +TEST_F(Test73TerminationUntilCancelled, NativeCallsAfterTheTerminationInsideV8Hooks) { + { + SCOPED_TRACE("prepare-stack-trace callback"); + EnvScope s(runtime_.get()); + InstallHelpers(s.env); + ASSERT_EQ(unofficial_napi_set_prepare_stack_trace_callback( + s.env, Eval(s.env, "(global, error, trace) => { terminateThen(0); }")), + napi_ok); + ExpectRunTerminated( + s.env, + "try { new Error('x').stack; } catch (e) { caught = 'yes'; caughtError = e; }\n" + "after = 'yes';\n"); + } + { + SCOPED_TRACE("serializer host-object hook"); + EnvScope s(runtime_.get()); + InstallHelpers(s.env); + napi_value binding = nullptr; + ASSERT_EQ(unofficial_napi_create_serdes_binding(s.env, &binding), napi_ok); + ASSERT_EQ(napi_set_named_property(s.env, Global(s.env), "serdes", binding), napi_ok); + ExpectRunTerminated( + s.env, + "(() => {\n" + "const s = new serdes.Serializer();\n" + "s._setTreatArrayBufferViewsAsHostObjects(true);\n" + "s._writeHostObject = (value) => { terminateThen(0); };\n" + "try { s.writeValue(new Uint8Array(2)); } catch (e) { caught = 'yes'; caughtError = e; }\n" + "after = 'yes';\n" + "})();"); + } +} + +namespace { +napi_ref g_token_fn = nullptr; +bool g_token_armed = false; +void TerminatingTokenHook(napi_env env, void* /*token*/, void* /*data*/) { + if (!g_token_armed) return; + g_token_armed = false; + napi_value fn = nullptr; + napi_get_reference_value(env, g_token_fn, &fn); + napi_value ignored = nullptr; + napi_call_function(env, Global(env), fn, 0, nullptr, &ignored); +} +napi_value CreateRealm(napi_env env, napi_callback_info /*info*/) { + unofficial_napi_realm realm = nullptr; + napi_value global = nullptr; + g_status = unofficial_napi_create_realm(env, nullptr, &realm, &global); + return global; +} +void AttachTokenHooks(napi_env env, bool assign) { + unofficial_napi_env_hooks hooks{}; + hooks.size = sizeof(hooks); + hooks.version = UNOFFICIAL_NAPI_ENV_HOOKS_VERSION; + if (assign) { + hooks.context_token_assign_callback = TerminatingTokenHook; + } else { + hooks.context_token_unassign_callback = TerminatingTokenHook; + } + uint64_t accepted = 0; + ASSERT_EQ(unofficial_napi_attach_env(env, &hooks, &accepted), napi_ok); +} +} // namespace + +TEST_F(Test73TerminationUntilCancelled, NativeCallsAfterTheTerminationInsideTheTokenAssignHook) { + EnvScope s(runtime_.get()); + InstallHelpers(s.env); + AttachTokenHooks(s.env, true); + ASSERT_EQ(napi_create_reference(s.env, Eval(s.env, "(() => { terminateThen(0); })"), 1, + &g_token_fn), + napi_ok); + DefineGlobalFunction(s.env, "createRealm", CreateRealm); + g_token_armed = true; + ExpectRunTerminated( + s.env, + "try { createRealm(); } catch (e) { caught = 'yes'; caughtError = e; }\nafter = 'yes';\n"); + g_token_armed = false; + napi_delete_reference(s.env, g_token_fn); +} +#endif diff --git a/v8/src/internal/napi_v8_agent.h b/v8/src/internal/napi_v8_agent.h index 8a6c3b1e86..4e672b8a53 100644 --- a/v8/src/internal/napi_v8_agent.h +++ b/v8/src/internal/napi_v8_agent.h @@ -74,8 +74,16 @@ struct napi_agent__ { // The embedder's termination: set by unofficial_napi_terminate_execution // until unofficial_napi_cancel_terminate_execution (or Shutdown) clears // it. V8 does not tell it apart from one a script timeout's watchdog asks - // for. + // for, and forgets it on its own: once the outermost JS frame has unwound, + // and whenever an API call enters V8 while it unwinds (V8 13.6's + // PREPARE_FOR_EXECUTION clears it). This keeps it, so that calls into JS + // fail until it is cancelled, as on QuickJS and as Node's can_call_into_js() + // stays false once the env stops. std::atomic termination_requested{false}; + // A no-op JS function, made the first time it is needed. Called right + // after a termination request, it makes V8 act on the request at its + // entry, a stack check. + v8::Global termination_probe; // Profiler sessions. V8's CPU and sampling heap profilers are per isolate. v8::CpuProfiler* cpu_profiler = nullptr; diff --git a/v8/src/internal/napi_v8_env.h b/v8/src/internal/napi_v8_env.h index 9899304de6..42a2915cb8 100644 --- a/v8/src/internal/napi_v8_env.h +++ b/v8/src/internal/napi_v8_env.h @@ -269,14 +269,26 @@ void napi_v8_drop_pending_termination(napi_env env); // replace the termination with a catchable exception. bool napi_v8_throw_unless_terminating(v8::Isolate* isolate, v8::Local exception); +// Whether the env terminates: the embedder terminated it +// (unofficial_napi_terminate_execution) and has not cancelled that, or V8 is +// unwinding with a termination. Calls into JS fail meanwhile. +bool napi_v8_terminating(napi_env env); + +// What a call refused while the env terminates returns: +// napi_pending_exception, with the null a TryCatch records for a termination +// pending unless something else is, as QuickJS leaves its uncatchable error +// pending. +napi_status napi_v8_fail_terminating(napi_env env); + // For a V8 host callback (a module hook, say) that ran JS through N-API and // failed: moves N-API's pending exception into V8, as Node's callbacks -// rethrow what their TryCatch caught, and returns true. While V8 is -// terminating it throws nothing and drops what is pending: throwing would -// replace the termination with a catchable exception, and the termination -// unwinds by itself. Returns true then too: either way V8 now has something -// to unwind with, so the callback may return an empty result. Returns false -// when nothing was pending and V8 is not terminating. +// rethrow what their TryCatch caught, and returns true. While the env +// terminates it drops what is pending instead (throwing would replace the +// termination with a catchable exception) and makes V8 unwind with the +// termination, which V8 may have forgotten. Returns true then too: either +// way V8 now has something to unwind with, so the callback may return an +// empty result. Returns false when nothing was pending and the env is not +// terminating. bool napi_v8_rethrow_pending_exception(napi_env env); napi_value napi_v8_wrap_value(napi_env env, v8::Local value); diff --git a/v8/src/js_native_api_v8.cc b/v8/src/js_native_api_v8.cc index a304e05ae9..382f698949 100644 --- a/v8/src/js_native_api_v8.cc +++ b/v8/src/js_native_api_v8.cc @@ -583,10 +583,17 @@ inline napi_status ReturnPendingIfCaught(napi_env env, v8::TryCatch& tc, const c return napi_v8_set_last_error(env, napi_generic_failure, message); } -// Like Node's napi_env__::terminatedOrTerminating(): V8 is terminating the -// env's JS (worker terminate(), process.exit()). +// Like Node's napi_env__::terminatedOrTerminating(), with its +// can_call_into_js() that stays false once the env stops: the embedder +// terminated the env (worker terminate(), process.exit()) and has not +// cancelled that, or V8 is unwinding with a termination (a script timeout's +// too). V8 alone forgets a termination: once the outermost JS frame has +// unwound, and when an API call enters V8 while it unwinds. inline bool TerminatedOrTerminating(napi_env env) { - return env != nullptr && env->isolate != nullptr && env->isolate->IsExecutionTerminating(); + return env != nullptr && env->isolate != nullptr && + ((env->agent != nullptr && + env->agent->termination_requested.load(std::memory_order_acquire)) || + env->isolate->IsExecutionTerminating()); } // Like Node's NAPI_PREAMBLE: while terminating, calls that may run JS fail @@ -594,10 +601,7 @@ inline bool TerminatedOrTerminating(napi_env env) { // would keep running JS after it was told to stop. #define NAPI_V8_RETURN_IF_TERMINATING(env) \ do { \ - if (TerminatedOrTerminating(env)) { \ - return napi_v8_set_last_error( \ - (env), napi_pending_exception, "Execution is terminating"); \ - } \ + if (TerminatedOrTerminating(env)) return napi_v8_fail_terminating(env); \ } while (0) inline napi_status InvalidArg(napi_env env) { @@ -686,16 +690,47 @@ inline bool GetTypedArrayType(v8::Local value, napi_typedarray_type* return true; } +// For a callback V8 runs for JS (a native function, an accessor, a module +// hook) that returns while the env terminates: makes V8 unwind that JS with +// the termination now. V8 may have forgotten it (an N-API call that entered +// V8 since cleared it) or not acted on it yet (it acts on a request at its +// next stack check, which the JS after the call, a catch block say, need not +// reach). So this asks again and calls a no-op function, whose entry is such +// a check. Called only below JS, which the termination then unwinds. +void KeepTerminating(napi_env env) { + v8::Isolate* isolate = env->isolate; + if (isolate->IsExecutionTerminating()) return; + v8::HandleScope handle_scope(isolate); + v8::Local context = env->main_context(); + v8::Local probe; + if (!env->agent->termination_probe.IsEmpty()) { + probe = env->agent->termination_probe.Get(isolate); + } else { + // Compiling runs no JS, so it does not act on a request made already. + v8::ScriptCompiler::Source source(v8::String::Empty(isolate)); + if (v8::ScriptCompiler::CompileFunction(context, &source).ToLocal(&probe)) { + env->agent->termination_probe.Reset(isolate, probe); + } + } + isolate->TerminateExecution(); + if (!probe.IsEmpty()) (void)probe->Call(context, v8::Undefined(isolate), 0, nullptr); +} + // Like Node's napi_env__::CallIntoModule() and HandleThrow(): after a native -// callback returns, rethrow the exception it left pending, unless V8 is -// terminating. TryCatch records a termination as a null exception, and -// rethrowing that would turn the termination into a catchable throw and cancel -// it. Returns whether an exception was pending. +// callback returns, rethrow the exception it left pending, unless the env +// terminates. Then what is pending is dropped (TryCatch records a +// termination as a null exception, and rethrowing that would turn the +// termination into a catchable throw and cancel it), and the termination +// unwinds the JS that called, as QuickJS's trampoline does. Returns whether +// that JS unwinds. bool HandleCallbackException(napi_env env) { - if (env->last_exception.IsEmpty()) return false; - if (!TerminatedOrTerminating(env)) { - env->isolate->ThrowException(env->last_exception.Get(env->isolate)); + if (TerminatedOrTerminating(env)) { + ClearLastException(env); + KeepTerminating(env); + return true; } + if (env->last_exception.IsEmpty()) return false; + env->isolate->ThrowException(env->last_exception.Get(env->isolate)); ClearLastException(env); return true; } @@ -884,13 +919,24 @@ bool napi_v8_throw_unless_terminating(v8::Isolate* isolate, v8::Local return true; } +bool napi_v8_terminating(napi_env env) { return TerminatedOrTerminating(env); } + +napi_status napi_v8_fail_terminating(napi_env env) { + if (env->last_exception.IsEmpty()) { + env->last_exception.Reset(env->isolate, v8::Null(env->isolate)); + env->last_exception_is_termination = true; + } + return napi_v8_set_last_error(env, napi_pending_exception, "Execution is terminating"); +} + bool napi_v8_rethrow_pending_exception(napi_env env) { if (env == nullptr) return false; - // As HandleCallbackException: what is pending while V8 terminates is the - // null a TryCatch records for the termination, and throwing it would make - // the termination a catchable throw and cancel it. + // As HandleCallbackException: what is pending while the env terminates is + // the null a TryCatch records for the termination, and throwing it would + // make the termination a catchable throw and cancel it. if (TerminatedOrTerminating(env)) { ClearLastException(env); + KeepTerminating(env); return true; } bool pending = false; @@ -1012,6 +1058,7 @@ napi_agent__::napi_agent__(v8::Isolate* isolate_in) : isolate(isolate_in) { } napi_agent__::~napi_agent__() { + termination_probe.Reset(); wrap_private_key.Reset(); buffer_private_key.Reset(); type_tag_private_key.Reset(); diff --git a/v8/src/unofficial_napi.cc b/v8/src/unofficial_napi.cc index 2677e8280c..4f38747030 100644 --- a/v8/src/unofficial_napi.cc +++ b/v8/src/unofficial_napi.cc @@ -1642,8 +1642,10 @@ void napi_agent__::Shutdown() { near_heap_limit_data = nullptr; fatal_error_callback = nullptr; oom_error_callback = nullptr; + // The release runs its hooks and finalizers with JS usable. termination_requested.store(false, std::memory_order_release); isolate->CancelTerminateExecution(); + termination_probe.Reset(); isolate->SetPromiseHook(nullptr); isolate->SetPromiseRejectCallback(nullptr); isolate->SetFatalErrorHandler(nullptr); @@ -2077,21 +2079,23 @@ bool PumpPlatformForegroundTasks(napi_env env) { return false; } -bool DrainMicrotasksForEnv(napi_env env) { - if (env == nullptr || env->isolate == nullptr) return false; +// Returns false, having run no more JS, once the env terminates (a +// finalizer or a microtask may terminate it). +bool DrainMicrotasksForEnv(napi_env env, bool* host_task_admitted) { + *host_task_admitted = false; env->DrainFinalizerQueue(); + if (napi_v8_terminating(env)) return false; v8::Local context = env->main_context(); - if (!context.IsEmpty()) { - v8::MicrotaskQueue* queue = context->GetMicrotaskQueue(); - if (queue != nullptr) { - queue->PerformCheckpoint(env->isolate); - env->DrainFinalizerQueue(); - return PumpPlatformForegroundTasks(env); - } + v8::MicrotaskQueue* queue = context.IsEmpty() ? nullptr : context->GetMicrotaskQueue(); + if (queue != nullptr) { + queue->PerformCheckpoint(env->isolate); + } else { + env->isolate->PerformMicrotaskCheckpoint(); } - env->isolate->PerformMicrotaskCheckpoint(); env->DrainFinalizerQueue(); - return PumpPlatformForegroundTasks(env); + if (napi_v8_terminating(env)) return false; + *host_task_admitted = PumpPlatformForegroundTasks(env); + return true; } napi_status NAPI_CDECL unofficial_napi_event_loop_checkpoint( @@ -2105,7 +2109,13 @@ napi_status NAPI_CDECL unofficial_napi_event_loop_checkpoint( mode != unofficial_napi_event_loop_checkpoint_host_tasks) { return napi_invalid_arg; } - const bool host_task_admitted = DrainMicrotasksForEnv(env); + // As the calls into JS: a terminating env runs none, and a termination a + // finalizer or a microtask runs into fails the checkpoint, as on QuickJS, + // so the event loop stops instead of going on as if nothing happened. + bool host_task_admitted = false; + if (napi_v8_terminating(env) || !DrainMicrotasksForEnv(env, &host_task_admitted)) { + return napi_v8_fail_terminating(env); + } if (state_out != nullptr) { *state_out = NapiV8HasPendingProviderWork(env) ? unofficial_napi_event_loop_checkpoint_state_pending_provider_work From d58a614d8135da3f2511f39f75a137342b13c8b0 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Fri, 6 Nov 2026 01:09:18 -0800 Subject: [PATCH 111/150] Refuse N-API calls that run JS while the env terminates, on both engines Several calls that run JS, or on V8 enter V8, had no termination guard. On V8, native code whose call into JS a termination failed (V8 then unwinds with it) and which went on to make one of them had V8 clear the termination on entry, and the JS it ran then ran to completion: unofficial_napi_run_script, module_wrap_evaluate, evaluate_sync, get_own_non_index_properties (proxy traps), create_realm (a proxy sandbox), structured_clone and message_create (getters), compile_function (a getter in the context extensions) and the Buffer calls (they read the env's Buffer, which may be a getter). On QuickJS, which polls its interrupt handler only every 10,000 operations, the proxy trap of get_own_non_index_properties and the Buffer getter ran too, and create_realm, structured_clone, message_create and compile_function returned other statuses than the refused calls do. Found by the attack on the branch at "V8: keep a termination the serializer's shared-buffer getter runs into" (its finding 1, which asks for these guards; the trampoline half came with the sticky termination). V8: NAPI_V8_RETURN_IF_TERMINATING moves to napi_v8_env.h and guards those calls, plus module_wrap_instantiate and create_required_module_facade, which evaluate or link modules, and the creators the attack saw clear the termination: napi_create_function, napi_define_class, napi_create_date, napi_create_promise and unofficial_napi_create_private_symbol. Those run no JS; they are refused because entering V8 clears the termination, as Node's NAPI_PREAMBLE refuses them. QuickJS: the same guard (fail_if_terminating) on get_own_non_index_properties, create_realm, structured_clone, message_create, compile_function, napi_create_buffer, napi_create_external_buffer (before it makes the external array buffer, so a refused call leaves the data with the caller) and node_api_create_buffer_from_arraybuffer. A refused call returns napi_pending_exception with the termination pending, as the other guarded calls do. Test: test_73 CallsRunningJsAfterTheTermination, both engines: for each of nine calls, a native function calls a JS function that terminates, then makes the call with a payload whose JS sets a flag (a module that sets it, a proxy whose ownKeys trap sets it, a getter, a Buffer getter on the global); called from a script in try/catch. The run must come back terminated with no flag set, and the call must return napi_pending_exception. Before this change V8 ran the payload in eight of the nine (afterCall=yes, status 0) and returned napi_ok from run_script; QuickJS ran it for get_own_non_index_properties and napi_create_buffer and returned 0 or 9 (napi_generic_failure) for create_realm, structured_clone, message_create and compile_function. Co-Authored-By: Claude Opus 5.5 --- quickjs/src/js_native_api_quickjs.cc | 5 + quickjs/src/unofficial_napi.cc | 20 +++ .../test_73_termination_until_cancelled.cc | 116 ++++++++++++++++++ v8/src/internal/napi_v8_env.h | 9 ++ v8/src/js_native_api_v8.cc | 15 ++- v8/src/unofficial_napi.cc | 4 + v8/src/unofficial_napi_contextify.cc | 7 ++ 7 files changed, 168 insertions(+), 8 deletions(-) diff --git a/quickjs/src/js_native_api_quickjs.cc b/quickjs/src/js_native_api_quickjs.cc index f52a08fcdc..cd3334a801 100644 --- a/quickjs/src/js_native_api_quickjs.cc +++ b/quickjs/src/js_native_api_quickjs.cc @@ -3253,6 +3253,8 @@ extern "C" { if (!napi_util__::check_env(env) || data == nullptr || result == nullptr) return napi_util__::invalid_arg(env); + // Making a Buffer reads the env's Buffer, which a getter may be. + NAPI_QUICKJS_RETURN_IF_TERMINATING(env); napi_value arraybuffer = nullptr; napi_status status = napi_create_arraybuffer(env, length, data, &arraybuffer); @@ -3293,6 +3295,8 @@ extern "C" { if (!napi_util__::check_env(env) || result == nullptr || (length > 0 && data == nullptr)) return napi_util__::invalid_arg(env); + // Making a Buffer reads the env's Buffer, which a getter may be. + NAPI_QUICKJS_RETURN_IF_TERMINATING(env); napi_value arraybuffer = nullptr; napi_status status = napi_create_external_arraybuffer( @@ -3330,6 +3334,7 @@ extern "C" { if (!napi_util__::check_value(env, arraybuffer) || result == nullptr) return napi_util__::invalid_arg(env); + NAPI_QUICKJS_RETURN_IF_TERMINATING(env); size_t arraybuffer_length = 0; uint8_t *arraybuffer_data = JS_GetArrayBuffer( diff --git a/quickjs/src/unofficial_napi.cc b/quickjs/src/unofficial_napi.cc index a0c29c7501..1bdd229f41 100644 --- a/quickjs/src/unofficial_napi.cc +++ b/quickjs/src/unofficial_napi.cc @@ -783,6 +783,10 @@ extern "C" napi_value transfer_list_or_null, napi_value *result_out) { + // Like NAPI_QUICKJS_RETURN_IF_TERMINATING: this can run JS (a getter, + // a proxy trap). + if (napi_util__::check_env(env) && env->termination_requested()) + return napi_util__::fail_if_terminating(env, napi_util__::context(env)); return QuickJSStructuredClone(env, value, transfer_list_or_null, result_out); } @@ -791,6 +795,10 @@ extern "C" napi_value value, unofficial_napi_message *message_out) { + // Like NAPI_QUICKJS_RETURN_IF_TERMINATING: this can run JS (a getter, + // a proxy trap). + if (napi_util__::check_env(env) && env->termination_requested()) + return napi_util__::fail_if_terminating(env, napi_util__::context(env)); return napi_serdes__::serialize_value( env, value, reinterpret_cast(message_out)); } @@ -821,6 +829,10 @@ extern "C" uint32_t filter_bits, napi_value *result_out) { + // Like NAPI_QUICKJS_RETURN_IF_TERMINATING: this can run JS (a getter, + // a proxy trap). + if (napi_util__::check_env(env) && env->termination_requested()) + return napi_util__::fail_if_terminating(env, napi_util__::context(env)); if (!napi_util__::check_env(env) || value == nullptr || result_out == nullptr) return napi_invalid_arg; JSContext *ctx = napi_util__::context(env); @@ -1171,6 +1183,10 @@ extern "C" return napi_invalid_arg; options = *options_or_null; } + // Like NAPI_QUICKJS_RETURN_IF_TERMINATING: this can run JS (a getter, + // a proxy trap). + if (napi_util__::check_env(env) && env->termination_requested()) + return napi_util__::fail_if_terminating(env, napi_util__::context(env)); return napi_util__::check_env(env) ? env->contextify().create_realm(options, realm_out, global_out) : napi_invalid_arg; } @@ -1331,6 +1347,10 @@ extern "C" napi_value host_defined_option_id, napi_value *result_out) { + // Like NAPI_QUICKJS_RETURN_IF_TERMINATING: this can run JS (a getter, + // a proxy trap). + if (napi_util__::check_env(env) && env->termination_requested()) + return napi_util__::fail_if_terminating(env, napi_util__::context(env)); return napi_util__::check_env(env) ? env->contextify().compile_function(realm_or_null, source, filename, diff --git a/tests/runners/test_73_termination_until_cancelled.cc b/tests/runners/test_73_termination_until_cancelled.cc index 16c3145420..760edf417e 100644 --- a/tests/runners/test_73_termination_until_cancelled.cc +++ b/tests/runners/test_73_termination_until_cancelled.cc @@ -174,6 +174,99 @@ napi_value TerminateThen(napi_env env, napi_callback_info info) { return nullptr; } +// N-API calls that run JS, given what makes them run it: native code may +// make them after a call into JS failed because of a termination. Each +// payload sets afterCall if its JS runs. +constexpr const char* kJsCalls[] = { + "unofficial_napi_run_script", + "unofficial_napi_module_wrap_evaluate", + "unofficial_napi_module_wrap_evaluate_sync", + "unofficial_napi_get_own_non_index_properties (proxy)", + "unofficial_napi_create_realm (proxy sandbox)", + "unofficial_napi_structured_clone (getter)", + "unofficial_napi_message_create (getter)", + "unofficial_napi_compile_function (getter in the extensions)", + "napi_create_buffer (Buffer getter)", +}; +constexpr int kJsCallCount = sizeof(kJsCalls) / sizeof(kJsCalls[0]); + +constexpr const char* kJsCallPayloads[] = { + "undefined", + "undefined", + "undefined", + "new Proxy({}, { ownKeys() { afterCall = 'yes'; return []; } })", + "new Proxy({}, { ownKeys() { afterCall = 'yes'; return []; } })", + "({ get x() { afterCall = 'yes'; return 1; } })", + "({ get x() { afterCall = 'yes'; return 1; } })", + "(() => { const a = [{}]; Object.defineProperty(a, 0, { get() { afterCall = 'yes'; return {}; } }); return a; })()", + "(Object.defineProperty(globalThis, 'Buffer', { get() { afterCall = 'yes'; return undefined; }, configurable: true }), undefined)", +}; + +// The module kJsCalls's evaluations evaluate. +unofficial_napi_module g_module = nullptr; + +napi_status CallRunningJs(napi_env env, int kind, napi_value payload) { + napi_value out = nullptr; + napi_value undefined = nullptr; + napi_get_undefined(env, &undefined); + switch (kind) { + case 0: { + const unofficial_napi_js_source source = + unofficial_napi_js_source_from_text(Str(env, "globalThis.afterCall = 'yes';")); + return unofficial_napi_run_script(env, nullptr, &source, Str(env, "after.js"), 0, 0, -1, + true, false, false, nullptr, &out); + } + case 1: + return unofficial_napi_module_wrap_evaluate(env, g_module, -1, false, &out); + case 2: + return unofficial_napi_module_wrap_evaluate_sync(env, g_module, Str(env, "m.mjs"), + Str(env, "parent.js"), &out); + case 3: + return unofficial_napi_get_own_non_index_properties(env, payload, 0, &out); + case 4: { + unofficial_napi_realm_options options; + unofficial_napi_realm_options_init(&options); + options.sandbox_or_null = payload; + unofficial_napi_realm realm = nullptr; + return unofficial_napi_create_realm(env, &options, &realm, &out); + } + case 5: + return unofficial_napi_structured_clone(env, payload, nullptr, &out); + case 6: { + unofficial_napi_message message = nullptr; + const napi_status status = unofficial_napi_message_create(env, payload, &message); + if (message != nullptr) unofficial_napi_message_drop(message); + return status; + } + case 7: { + const unofficial_napi_js_source source = + unofficial_napi_js_source_from_text(Str(env, "return 1;")); + return unofficial_napi_compile_function(env, nullptr, &source, Str(env, "f.js"), 0, 0, + payload, undefined, undefined, &out); + } + default: { + void* data = nullptr; + return napi_create_buffer(env, 4, &data, &out); + } + } +} + +// Calls its first argument, a JS function that terminates, then makes the +// N-API call its second argument names with its third as the payload, as +// native code that ignores the failed call does. +napi_value CallThen(napi_env env, napi_callback_info info) { + size_t argc = 3; + napi_value argv[3] = {nullptr, nullptr, nullptr}; + EXPECT_EQ(napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr), napi_ok); + int32_t kind = 0; + EXPECT_EQ(napi_get_value_int32(env, argv[1], &kind), napi_ok); + napi_value ignored = nullptr; + EXPECT_EQ(napi_call_function(env, Global(env), argv[0], 0, nullptr, &ignored), + napi_pending_exception); + g_status = CallRunningJs(env, kind, argv[2]); + return nullptr; +} + void DefineGlobalFunction(napi_env env, const char* name, napi_callback cb, void* data = nullptr) { napi_value fn = nullptr; ASSERT_EQ(napi_create_function(env, name, NAPI_AUTO_LENGTH, cb, data, &fn), napi_ok); @@ -220,6 +313,7 @@ bool FinishTermination(napi_env env) { void InstallHelpers(napi_env env) { DefineGlobalFunction(env, "terminate", Terminate); DefineGlobalFunction(env, "terminateThen", TerminateThen); + DefineGlobalFunction(env, "callThen", CallThen); DefineGlobalFunction(env, "terminateThenCancel", TerminateThenCancel); DefineGlobalFunction(env, "terminateAndSleep", TerminateAndSleep); DefineGlobalFunction(env, "runScriptWithTimeout", RunScriptWithTimeout); @@ -423,6 +517,28 @@ TEST_F(Test73TerminationUntilCancelled, NativeCallsAfterTheTermination) { } } +// Native code whose call into JS a termination failed, and which then makes +// an N-API call that runs JS. On V8 the termination is in effect when that +// call enters V8, which clears it and runs the JS. +TEST_F(Test73TerminationUntilCancelled, CallsRunningJsAfterTheTermination) { + for (int kind = 0; kind < kJsCallCount; ++kind) { + SCOPED_TRACE(kJsCalls[kind]); + EnvScope s(runtime_.get()); + InstallHelpers(s.env); + g_module = MakeModule(s.env, "globalThis.afterCall = 'yes';", nullptr); + ASSERT_NE(g_module, nullptr); + g_status = napi_ok; + const std::string script = + std::string("const payload = ") + kJsCallPayloads[kind] + ";\n" + + "try { callThen(() => { terminate(); tick(); }, " + std::to_string(kind) + + ", payload); } catch (e) { caught = 'yes'; caughtError = e; }\n" + "after = 'yes';\n"; + ExpectRunTerminated(s.env, script.c_str()); + EXPECT_EQ(g_status, napi_pending_exception); + EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, g_module), napi_ok); + } +} + // The same native code, called from the module hooks test_72 covers: those // see what the native function threw. TEST_F(Test73TerminationUntilCancelled, NativeCallsAfterTheTerminationInsideModuleHooks) { diff --git a/v8/src/internal/napi_v8_env.h b/v8/src/internal/napi_v8_env.h index 42a2915cb8..c902d2c039 100644 --- a/v8/src/internal/napi_v8_env.h +++ b/v8/src/internal/napi_v8_env.h @@ -280,6 +280,15 @@ bool napi_v8_terminating(napi_env env); // pending. napi_status napi_v8_fail_terminating(napi_env env); +// Like Node's NAPI_PREAMBLE: while the env terminates, calls that enter V8 or +// may run JS fail without entering V8. Entering V8 clears the termination +// (V8 13.6's PREPARE_FOR_EXECUTION does), and JS run then runs on with +// nothing to stop it. +#define NAPI_V8_RETURN_IF_TERMINATING(env) \ + do { \ + if (napi_v8_terminating(env)) return napi_v8_fail_terminating(env); \ + } while (0) + // For a V8 host callback (a module hook, say) that ran JS through N-API and // failed: moves N-API's pending exception into V8, as Node's callbacks // rethrow what their TryCatch caught, and returns true. While the env diff --git a/v8/src/js_native_api_v8.cc b/v8/src/js_native_api_v8.cc index 382f698949..1b5566c60b 100644 --- a/v8/src/js_native_api_v8.cc +++ b/v8/src/js_native_api_v8.cc @@ -596,14 +596,6 @@ inline bool TerminatedOrTerminating(napi_env env) { env->isolate->IsExecutionTerminating()); } -// Like Node's NAPI_PREAMBLE: while terminating, calls that may run JS fail -// without entering V8. Entering V8 then clears the termination, so the thread -// would keep running JS after it was told to stop. -#define NAPI_V8_RETURN_IF_TERMINATING(env) \ - do { \ - if (TerminatedOrTerminating(env)) return napi_v8_fail_terminating(env); \ - } while (0) - inline napi_status InvalidArg(napi_env env) { if (CheckEnv(env)) { return napi_v8_set_last_error(env, napi_invalid_arg, "Invalid argument"); @@ -870,6 +862,7 @@ napi_status CreateExternalBuffer(napi_env env, napi_v8_external_free_callback free_cb, void* finalize_hint, napi_value* result) { + NAPI_V8_RETURN_IF_TERMINATING(env); if (!CheckEnv(env) || data == nullptr || result == nullptr) return napi_invalid_arg; v8::Local context = env->context(); v8::Context::Scope context_scope(context); @@ -1383,6 +1376,7 @@ napi_status NAPI_CDECL napi_create_bigint_words(napi_env env, } napi_status NAPI_CDECL napi_create_date(napi_env env, double time, napi_value* result) { + NAPI_V8_RETURN_IF_TERMINATING(env); if (!CheckEnv(env) || result == nullptr) return napi_invalid_arg; v8::MaybeLocal maybe_date = v8::Date::New(env->context(), time); if (maybe_date.IsEmpty()) { @@ -2311,6 +2305,7 @@ napi_status NAPI_CDECL napi_create_function(napi_env env, napi_callback cb, void* data, napi_value* result) { + NAPI_V8_RETURN_IF_TERMINATING(env); if (!CheckEnv(env)) return napi_invalid_arg; if (cb == nullptr || result == nullptr) { return napi_v8_set_last_error(env, napi_invalid_arg, "Invalid argument"); @@ -2349,6 +2344,7 @@ napi_status NAPI_CDECL napi_define_class(napi_env env, size_t property_count, const napi_property_descriptor* properties, napi_value* result) { + NAPI_V8_RETURN_IF_TERMINATING(env); if (!CheckEnv(env)) { return napi_invalid_arg; } @@ -2630,6 +2626,7 @@ napi_status NAPI_CDECL napi_define_properties( napi_status NAPI_CDECL napi_create_promise(napi_env env, napi_deferred* deferred, napi_value* promise) { + NAPI_V8_RETURN_IF_TERMINATING(env); if (!CheckEnv(env) || deferred == nullptr || promise == nullptr) { return napi_v8_set_last_error(env, napi_invalid_arg, "Invalid argument"); } @@ -3606,6 +3603,7 @@ napi_status NAPI_CDECL napi_create_buffer(napi_env env, size_t length, void** data, napi_value* result) { + NAPI_V8_RETURN_IF_TERMINATING(env); if (!CheckEnv(env) || data == nullptr || result == nullptr) return napi_invalid_arg; v8::Local context = env->context(); v8::Context::Scope context_scope(context); @@ -3679,6 +3677,7 @@ napi_status NAPI_CDECL node_api_create_buffer_from_arraybuffer( size_t byte_offset, size_t byte_length, napi_value* result) { + NAPI_V8_RETURN_IF_TERMINATING(env); if (!CheckEnv(env) || arraybuffer == nullptr || result == nullptr) return napi_invalid_arg; v8::Local raw = napi_v8_unwrap_value(arraybuffer); if (!raw->IsArrayBuffer()) return napi_invalid_arg; diff --git a/v8/src/unofficial_napi.cc b/v8/src/unofficial_napi.cc index 4f38747030..feea80878f 100644 --- a/v8/src/unofficial_napi.cc +++ b/v8/src/unofficial_napi.cc @@ -1583,6 +1583,7 @@ napi_status StructuredCloneImpl( if (env == nullptr || env->isolate == nullptr || value == nullptr || result_out == nullptr) { return napi_invalid_arg; } + NAPI_V8_RETURN_IF_TERMINATING(env); v8::Isolate* isolate = env->isolate; v8::EscapableHandleScope handle_scope(isolate); @@ -2222,6 +2223,7 @@ napi_status NAPI_CDECL unofficial_napi_message_create( if (env == nullptr || env->isolate == nullptr || value == nullptr || message_out == nullptr) { return napi_invalid_arg; } + NAPI_V8_RETURN_IF_TERMINATING(env); *message_out = nullptr; v8::Isolate* isolate = env->isolate; @@ -2575,6 +2577,7 @@ napi_status NAPI_CDECL unofficial_napi_create_private_symbol(napi_env env, size_t length, napi_value* result_out) { if (env == nullptr || env->isolate == nullptr || result_out == nullptr) return napi_invalid_arg; + NAPI_V8_RETURN_IF_TERMINATING(env); if (utf8description == nullptr && length > 0) return napi_invalid_arg; v8::Isolate* isolate = env->isolate; @@ -2615,6 +2618,7 @@ napi_status NAPI_CDECL unofficial_napi_get_own_non_index_properties( if (env == nullptr || value == nullptr || result_out == nullptr) { return napi_invalid_arg; } + NAPI_V8_RETURN_IF_TERMINATING(env); v8::Local raw = napi_v8_unwrap_value(value); if (raw.IsEmpty() || !raw->IsObject()) return napi_object_expected; diff --git a/v8/src/unofficial_napi_contextify.cc b/v8/src/unofficial_napi_contextify.cc index 78deed005e..39f093c120 100644 --- a/v8/src/unofficial_napi_contextify.cc +++ b/v8/src/unofficial_napi_contextify.cc @@ -1752,6 +1752,7 @@ napi_status NAPI_CDECL unofficial_napi_create_realm( unofficial_napi_realm* realm_out, napi_value* global_out) { if (env == nullptr || realm_out == nullptr) return napi_invalid_arg; + NAPI_V8_RETURN_IF_TERMINATING(env); unofficial_napi_realm_options options; unofficial_napi_realm_options_init(&options); if (options_or_null != nullptr) { @@ -2143,6 +2144,7 @@ napi_status NAPI_CDECL unofficial_napi_run_script( result_out == nullptr) { return napi_invalid_arg; } + NAPI_V8_RETURN_IF_TERMINATING(env); (void)break_on_first_line; v8::Isolate* isolate = env->isolate; @@ -2299,6 +2301,7 @@ napi_status NAPI_CDECL unofficial_napi_compile_function( result_out == nullptr) { return napi_invalid_arg; } + NAPI_V8_RETURN_IF_TERMINATING(env); v8::Isolate* isolate = env->isolate; v8::EscapableHandleScope handle_scope(isolate); @@ -2853,6 +2856,7 @@ napi_status NAPI_CDECL unofficial_napi_module_wrap_instantiate( napi_env env, unofficial_napi_module module_handle) { if (env == nullptr || module_handle == nullptr) return napi_invalid_arg; + NAPI_V8_RETURN_IF_TERMINATING(env); ModuleWrapRecord* record = ModuleRecord(module_handle); v8::Isolate* isolate = env->isolate; v8::HandleScope handle_scope(isolate); @@ -2878,6 +2882,7 @@ napi_status NAPI_CDECL unofficial_napi_module_wrap_evaluate( bool /*break_on_sigint*/, napi_value* result_out) { if (env == nullptr || module_handle == nullptr || result_out == nullptr) return napi_invalid_arg; + NAPI_V8_RETURN_IF_TERMINATING(env); ModuleWrapRecord* record = ModuleRecord(module_handle); v8::Isolate* isolate = env->isolate; v8::EscapableHandleScope handle_scope(isolate); @@ -2904,6 +2909,7 @@ napi_status NAPI_CDECL unofficial_napi_module_wrap_evaluate_sync( napi_value parent_filename, napi_value* result_out) { if (env == nullptr || module_handle == nullptr || result_out == nullptr) return napi_invalid_arg; + NAPI_V8_RETURN_IF_TERMINATING(env); *result_out = nullptr; ModuleWrapRecord* record = ModuleRecord(module_handle); @@ -3155,6 +3161,7 @@ napi_status NAPI_CDECL unofficial_napi_module_wrap_create_required_module_facade unofficial_napi_module module, napi_value* result_out) { if (env == nullptr || module == nullptr || result_out == nullptr) return napi_invalid_arg; + NAPI_V8_RETURN_IF_TERMINATING(env); ModuleWrapRecord* record = ModuleRecord(module); v8::Isolate* isolate = env->isolate; v8::EscapableHandleScope handle_scope(isolate); From c1b2886570c02e309d5257e6b1acee6a60ebd6c7 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Fri, 6 Nov 2026 01:11:04 -0800 Subject: [PATCH 112/150] V8: keep a termination an interrupt callback's JS runs into V8 runs an unofficial_napi_request_interrupt callback at a stack check of the JS it interrupts, and goes on with that JS whatever the callback left: StackGuard::HandleInterrupts ignores an exception there. When the callback's JS was terminated, the TryCatch of its napi_call_function rethrew the termination as V8's current exception, V8 ignored it and later dropped it, and no termination request was left: the interrupted JS ran on with nothing to stop it (a loop ran to completion), the run returned napi_ok, and N-API was left with the termination's null pending. Found by the attack on the branch at "V8: keep a termination the serializer's shared-buffer getter runs into" (its finding 2). After the callback, while the env terminates, the provider now drops what the callback left pending, clears the termination V8 would ignore, and asks V8 for the termination again, as "V8: keep a termination the promise reject callback runs into" does for the promise reject callback: V8 acts on it at its next stack check. The JS that calls the stack check where the interrupt ran may still run up to the next one. Test: test_73 InterruptCallbackTerminated, both engines: a script calls a native function that requests an interrupt, then loops 100000 times calling tick() and counting, all in try/catch; the interrupt callback calls a JS function that terminates. The run must come back terminated with no flag set, and the loop may count at most once (V8 runs the callback at the first tick()'s entry and acts on the termination at the next check; QuickJS runs it inside requestInterrupt()). Before this change V8 gave run 0, after=yes and 100000 calls; QuickJS passed. Co-Authored-By: Claude Opus 5.5 --- .../test_73_termination_until_cancelled.cc | 36 +++++++++++++++++++ v8/src/internal/napi_v8_env.h | 9 +++++ v8/src/js_native_api_v8.cc | 10 ++++++ v8/src/unofficial_napi.cc | 1 + 4 files changed, 56 insertions(+) diff --git a/tests/runners/test_73_termination_until_cancelled.cc b/tests/runners/test_73_termination_until_cancelled.cc index 760edf417e..7d88e754ee 100644 --- a/tests/runners/test_73_termination_until_cancelled.cc +++ b/tests/runners/test_73_termination_until_cancelled.cc @@ -802,3 +802,39 @@ TEST_F(Test73TerminationUntilCancelled, NativeCallsAfterTheTerminationInsideTheT napi_delete_reference(s.env, g_token_fn); } #endif + +// An interrupt callback whose JS is terminated, while a run loops: the +// interrupted JS stops. V8 runs the callback at a stack check (the first +// tick()'s entry) and acts on the termination at the next one, so the loop +// body may run once; QuickJS runs the callback inside requestInterrupt(). +namespace { +napi_ref g_interrupt_fn = nullptr; +void InterruptCallback(napi_env env, void* /*data*/) { + napi_value fn = nullptr; + napi_get_reference_value(env, g_interrupt_fn, &fn); + napi_value ignored = nullptr; + napi_call_function(env, Global(env), fn, 0, nullptr, &ignored); +} +napi_value RequestInterrupt(napi_env env, napi_callback_info /*info*/) { + EXPECT_EQ(unofficial_napi_request_interrupt(env, InterruptCallback, nullptr), napi_ok); + return nullptr; +} +} // namespace + +TEST_F(Test73TerminationUntilCancelled, InterruptCallbackTerminated) { + EnvScope s(runtime_.get()); + InstallHelpers(s.env); + ASSERT_EQ(napi_create_reference(s.env, Eval(s.env, "(() => { terminate(); tick(); })"), 1, + &g_interrupt_fn), + napi_ok); + DefineGlobalFunction(s.env, "requestInterrupt", RequestInterrupt); + ASSERT_EQ(RunScript(s.env, "globalThis.calls = 0;"), napi_ok); + ExpectRunTerminated( + s.env, + "try { requestInterrupt(); for (let i = 0; i < 100000; i++) { tick(); calls++; } }\n" + "catch (e) { caught = 'yes'; caughtError = e; }\n" + "after = 'yes';\n"); + const std::string calls = GlobalText(s.env, "calls"); + EXPECT_TRUE(calls == "0" || calls == "1") << "calls " << calls; + napi_delete_reference(s.env, g_interrupt_fn); +} diff --git a/v8/src/internal/napi_v8_env.h b/v8/src/internal/napi_v8_env.h index c902d2c039..2eb893b3e5 100644 --- a/v8/src/internal/napi_v8_env.h +++ b/v8/src/internal/napi_v8_env.h @@ -274,6 +274,15 @@ bool napi_v8_throw_unless_terminating(v8::Isolate* isolate, v8::Local // unwinding with a termination. Calls into JS fail meanwhile. bool napi_v8_terminating(napi_env env); +// For an interrupt callback (unofficial_napi_request_interrupt) that returns +// while the env terminates. V8 runs it at a stack check and then goes on with +// the interrupted JS whatever it left: StackGuard::HandleInterrupts ignores +// an exception there, a termination too, so the JS would run on with nothing +// to stop it. This asks V8 for the termination again, so it acts on it at +// its next stack check, and drops what the callback left pending, as after a +// native callback. +void napi_v8_keep_terminating_after_interrupt(napi_env env); + // What a call refused while the env terminates returns: // napi_pending_exception, with the null a TryCatch records for a termination // pending unless something else is, as QuickJS leaves its uncatchable error diff --git a/v8/src/js_native_api_v8.cc b/v8/src/js_native_api_v8.cc index 1b5566c60b..8cfc8bb1d1 100644 --- a/v8/src/js_native_api_v8.cc +++ b/v8/src/js_native_api_v8.cc @@ -914,6 +914,16 @@ bool napi_v8_throw_unless_terminating(v8::Isolate* isolate, v8::Local bool napi_v8_terminating(napi_env env) { return TerminatedOrTerminating(env); } +void napi_v8_keep_terminating_after_interrupt(napi_env env) { + if (!TerminatedOrTerminating(env)) return; + ClearLastException(env); + v8::Isolate* isolate = env->isolate; + // A termination the callback's JS ran into is V8's current exception, which + // it ignores there and drops later. + if (isolate->IsExecutionTerminating()) isolate->CancelTerminateExecution(); + isolate->TerminateExecution(); +} + napi_status napi_v8_fail_terminating(napi_env env) { if (env->last_exception.IsEmpty()) { env->last_exception.Reset(env->isolate, v8::Null(env->isolate)); diff --git a/v8/src/unofficial_napi.cc b/v8/src/unofficial_napi.cc index feea80878f..79210ec650 100644 --- a/v8/src/unofficial_napi.cc +++ b/v8/src/unofficial_napi.cc @@ -2203,6 +2203,7 @@ napi_status NAPI_CDECL unofficial_napi_request_interrupt( v8::Context::Scope context_scope(context); napi_realm_frame_scope__ realm_frame(request->env, nullptr); request->callback(request->env, request->data); + napi_v8_keep_terminating_after_interrupt(request->env); }, request); return napi_ok; From b74e789ec49028cfa6f9990d8c5b43a29d7392c6 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Fri, 6 Nov 2026 01:12:41 -0800 Subject: [PATCH 113/150] V8: fail create_realm when an unassign hook it runs is terminated unofficial_napi_create_realm first runs the context-token unassign hooks of the realms collected since, then reads the sandbox, makes the context and sets its privates. When a hook's JS was terminated, those V8 calls cleared the termination, and create_realm made the realm and returned napi_ok, as if nothing had stopped. The hook runs embedder code inside JS execution, the same class of site test_72 covers, and needs no misbehaving native code. Found by the attack on the branch at "V8: keep a termination the serializer's shared-buffer getter runs into" (its finding 4). create_realm now fails with napi_pending_exception, without making the realm, when the env terminates after those hooks. Since the previous commits the JS that called create_realm already stopped (the native function's trampoline makes V8 unwind with the termination), so what this changes is the status and the realm that was made. Test: test_73 CreateRealmAfterATerminatedUnassignHook, V8 only (only V8 accepts the context-token hooks): an unassign hook calls a JS function that terminates; a realm is made and dropped, and a script collects it and calls a native function that makes a realm (with a sandbox, then with a fresh global) in try/catch. The run must come back terminated with no flag set, the hook must have run, and create_realm must return napi_pending_exception. Before this change create_realm returned napi_ok in both cases (on the branch at "V8: keep a termination the serializer's shared-buffer getter runs into" the run also caught null, which the sticky termination already fixed). Co-Authored-By: Claude Opus 5.5 --- .../test_73_termination_until_cancelled.cc | 47 +++++++++++++++++++ v8/src/unofficial_napi_contextify.cc | 3 ++ 2 files changed, 50 insertions(+) diff --git a/tests/runners/test_73_termination_until_cancelled.cc b/tests/runners/test_73_termination_until_cancelled.cc index 7d88e754ee..0c121302e2 100644 --- a/tests/runners/test_73_termination_until_cancelled.cc +++ b/tests/runners/test_73_termination_until_cancelled.cc @@ -786,6 +786,18 @@ void AttachTokenHooks(napi_env env, bool assign) { } } // namespace +napi_value CreateSandboxRealm(napi_env env, napi_callback_info /*info*/) { + napi_value sandbox = nullptr; + napi_create_object(env, &sandbox); + unofficial_napi_realm_options options; + unofficial_napi_realm_options_init(&options); + options.sandbox_or_null = sandbox; + unofficial_napi_realm realm = nullptr; + napi_value global = nullptr; + g_status = unofficial_napi_create_realm(env, &options, &realm, &global); + return global; +} + TEST_F(Test73TerminationUntilCancelled, NativeCallsAfterTheTerminationInsideTheTokenAssignHook) { EnvScope s(runtime_.get()); InstallHelpers(s.env); @@ -801,6 +813,41 @@ TEST_F(Test73TerminationUntilCancelled, NativeCallsAfterTheTerminationInsideTheT g_token_armed = false; napi_delete_reference(s.env, g_token_fn); } + +// unofficial_napi_create_realm first runs the unassign hooks of the realms +// collected since, then makes the realm. When a hook's JS is terminated, it +// must fail without making the realm: the V8 calls that make it would clear +// the termination. +TEST_F(Test73TerminationUntilCancelled, CreateRealmAfterATerminatedUnassignHook) { + for (bool with_sandbox : {true, false}) { + SCOPED_TRACE(with_sandbox ? "with a sandbox" : "with a fresh global"); + EnvScope s(runtime_.get()); + InstallHelpers(s.env); + AttachTokenHooks(s.env, false); + ASSERT_EQ(napi_create_reference(s.env, Eval(s.env, "(() => { terminate(); tick(); })"), 1, + &g_token_fn), + napi_ok); + { + napi_handle_scope scope = nullptr; + ASSERT_EQ(napi_open_handle_scope(s.env, &scope), napi_ok); + unofficial_napi_realm realm = nullptr; + napi_value global = nullptr; + ASSERT_EQ(unofficial_napi_create_realm(s.env, nullptr, &realm, &global), napi_ok); + ASSERT_EQ(napi_close_handle_scope(s.env, scope), napi_ok); + } + DefineGlobalFunction(s.env, "createRealm", with_sandbox ? CreateSandboxRealm : CreateRealm); + g_token_armed = true; + g_status = napi_ok; + ExpectRunTerminated( + s.env, + "gc(); gc();\n" + "try { createRealm(); } catch (e) { caught = 'yes'; caughtError = e; }\nafter = 'yes';\n"); + EXPECT_FALSE(g_token_armed) << "the unassign hook did not run"; + EXPECT_EQ(g_status, napi_pending_exception); + g_token_armed = false; + napi_delete_reference(s.env, g_token_fn); + } +} #endif // An interrupt callback whose JS is terminated, while a run loops: the diff --git a/v8/src/unofficial_napi_contextify.cc b/v8/src/unofficial_napi_contextify.cc index 39f093c120..f0a6c76884 100644 --- a/v8/src/unofficial_napi_contextify.cc +++ b/v8/src/unofficial_napi_contextify.cc @@ -1764,6 +1764,9 @@ napi_status NAPI_CDECL unofficial_napi_create_realm( } *realm_out = nullptr; ReleaseCollectedRealms(env); + // An unassign hook's JS may have been terminated: making the realm would + // enter V8 and clear the termination. + NAPI_V8_RETURN_IF_TERMINATING(env); v8::Isolate* isolate = env->isolate; v8::EscapableHandleScope handle_scope(isolate); From a7f7d3e654898e0f08e5f2246746d2130856a54a Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Fri, 6 Nov 2026 01:14:57 -0800 Subject: [PATCH 114/150] Say what termination leaves pending, and QuickJS's prepareStackTrace gap The header now says what the previous commits made both engines do: a call a termination stops or refuses leaves it as the pending exception unless another is pending; a native callback that returns while the env terminates has what it left pending dropped and its caller unwinds; cancelling drops a pending exception that stands for the termination and keeps any other (the attack on the branch at "V8: keep a termination the serializer's shared-buffer getter runs into" asked to pick one behaviour for that and document it, its finding 7; V8 now behaves as QuickJS did). It also says where V8 acts on a termination requested from another thread or run into by an interrupt callback. It documents, instead of fixing, the attack's finding 6 (low): QuickJS-ng reads Error.prepareStackTrace, which may be a getter, whenever it gives an error its stack (build_backtrace, quickjs.c), also while a termination unwinds, and it drops whatever that getter throws. So such a getter runs as JS during a termination, and a termination the getter itself runs into is lost until the next call into JS: the catch block and the code after it run, and the run returns napi_ok. Both happen inside the engine, between bytecode instructions, where the provider has no hook: closing them needs a QuickJS-ng change (build_backtrace propagating an uncatchable exception and not calling user getters for one), which lands through wasmerio/quickjs and a pin bump, and nothing may be pushed from here. A provider-only change (failing the run after the fact) would report the termination one call earlier but would not stop the JS that runs after it, so it is not made. Co-Authored-By: Claude Opus 5.5 --- include/unofficial_napi.h | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/include/unofficial_napi.h b/include/unofficial_napi.h index 9ccd39ce30..645d9617ac 100644 --- a/include/unofficial_napi.h +++ b/include/unofficial_napi.h @@ -533,10 +533,28 @@ NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_create_uninitialized_ar // unwinds without running catch or finally blocks, and calls into JS fail with // napi_pending_exception until the termination is cancelled. Any thread may // call this. +// +// A call the termination stops or refuses leaves it as the pending exception +// (null on V8, QuickJS's uncatchable error) unless another one is pending. +// When a native callback returns while the env terminates, what it left +// pending is dropped and the JS that called it unwinds. V8 acts on a +// termination requested from another thread at its next stack check, and on +// one an interrupt callback's JS runs into at the stack check after the one +// that ran the callback. +// +// Known QuickJS gap: QuickJS-ng reads Error.prepareStackTrace, which may be a +// getter, whenever it gives an error its stack, also while a termination +// unwinds, so such a getter runs as JS then. It also drops whatever that +// getter throws: a termination the getter runs into does not stop the code +// after it (a catch block included) until the next call into JS, which +// fails. Closing that needs a QuickJS-ng change. NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_terminate_execution(napi_env env); // Clears a previously requested engine termination on the current env. This is // used when embedder code intentionally stops a worker but still needs the -// current JS stack to unwind normally. Call it on the env's engine thread. +// current JS stack to unwind normally. Call it on the env's engine thread. A +// pending exception that stands for the termination is dropped: nothing threw +// it, so a native callback that cancels returns to its caller as after any +// call. Any other pending exception stays. NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_cancel_terminate_execution(napi_env env); typedef void (*unofficial_napi_interrupt_callback)(napi_env env, void* data); From c741083ea6296c266eb2cab835de3aa35fd50ebf Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Fri, 6 Nov 2026 01:44:03 -0800 Subject: [PATCH 115/150] Test that cancelling drops the null a TryCatch records for a termination Since the termination became sticky ("V8: keep a termination until it is cancelled"), the native function in test_73's cancellation tests had its call refused before it entered JS: the null it cancelled came from the refusal (napi_v8_fail_terminating), not from the TryCatch marker that "V8: drop the termination's pending null when it is cancelled" added, so the tests no longer covered that marker. Found by the Codex review of the commits from "V8: drop the termination's pending null when it is cancelled" to "Say what termination leaves pending, and QuickJS's prepareStackTrace gap". The native function now calls terminateJs(), JS that terminates, so the termination stops the call inside JS and its TryCatch records the null. The finalizer and release tests use the same terminateJs, now defined once with the helpers. Check: with SetLastExceptionFromTryCatch's marker line removed, the old tests still passed on V8 (14 of 14); the new CancelledInsideANativeFunction and CancelledInsideAModuleHook fail ("caught=yes ... error=null"). Both engines pass with the marker. Co-Authored-By: Claude Opus 5.5 --- .../test_73_termination_until_cancelled.cc | 30 +++++++++++-------- 1 file changed, 17 insertions(+), 13 deletions(-) diff --git a/tests/runners/test_73_termination_until_cancelled.cc b/tests/runners/test_73_termination_until_cancelled.cc index 0c121302e2..e79f337ed2 100644 --- a/tests/runners/test_73_termination_until_cancelled.cc +++ b/tests/runners/test_73_termination_until_cancelled.cc @@ -42,7 +42,9 @@ napi_value Terminate(napi_env env, napi_callback_info /*info*/) { napi_value Noop(napi_env /*env*/, napi_callback_info /*info*/) { return nullptr; } -// Terminates and calls tick(), so that V8 acts on it. +// Terminates and calls tick(), as native code that terminates and goes on +// does. The termination fails the call; V8 acts on it when the native +// function returns. void TerminateNow(napi_env env) { EXPECT_EQ(unofficial_napi_terminate_execution(env), napi_ok); napi_value tick = nullptr; @@ -51,10 +53,15 @@ void TerminateNow(napi_env env) { napi_call_function(env, Global(env), tick, 0, nullptr, &ignored); } -// Terminates, then cancels, without taking what the failed call left -// pending. +// Calls terminateJs(), JS that terminates, then cancels, without taking +// what the call, which the termination stopped inside JS, left pending: on +// V8 the null its TryCatch recorded. napi_value TerminateThenCancel(napi_env env, napi_callback_info /*info*/) { - TerminateNow(env); + napi_value terminate_js = nullptr; + napi_value ignored = nullptr; + EXPECT_EQ(napi_get_named_property(env, Global(env), "terminateJs", &terminate_js), napi_ok); + EXPECT_EQ(napi_call_function(env, Global(env), terminate_js, 0, nullptr, &ignored), + napi_pending_exception); EXPECT_EQ(unofficial_napi_cancel_terminate_execution(env), napi_ok); return nullptr; } @@ -321,6 +328,7 @@ void InstallHelpers(napi_env env) { // engine looks for a termination. ASSERT_EQ(RunScript(env, "globalThis.tick = function tick() {};" + "globalThis.terminateJs = () => { terminate(); tick(); };" "globalThis.caught = 'no'; globalThis.after = 'no';" "globalThis.innerCaught = 'no'; globalThis.innerAfter = 'no';" "globalThis.caughtError = 'none'; globalThis.afterCall = 'no';"), @@ -424,10 +432,10 @@ constexpr char kEvaluateModuleInTryCatch[] = } // namespace -// Native code that terminates, makes a call the termination fails, and -// cancels the termination before it returns, without taking what that call -// left pending. Nothing threw that: the JS that called goes on as after any -// call. V8 records a termination as a null pending exception, which it would +// Native code whose call into JS a termination stopped, and which cancels the +// termination before it returns, without taking what that call left pending. +// Nothing threw that: the JS that called goes on as after any call. V8's +// TryCatch records a termination as a null exception, which V8 would // otherwise throw into that JS as a catchable null; QuickJS drops its // uncatchable error at the cancel. TEST_F(Test73TerminationUntilCancelled, CancelledInsideANativeFunction) { @@ -617,9 +625,7 @@ void TerminatingFinalizer(napi_env env, void* /*data*/, void* /*hint*/) { TEST_F(Test73TerminationUntilCancelled, FinalizerDrainedAtACheckpoint) { EnvScope s(runtime_.get()); InstallHelpers(s.env); - ASSERT_EQ(RunScript(s.env, - "globalThis.terminateJs = () => { terminate(); tick(); };" - "globalThis.markAfterCall = () => { afterCall = 'yes'; };"), + ASSERT_EQ(RunScript(s.env, "globalThis.markAfterCall = () => { afterCall = 'yes'; };"), napi_ok); g_finalizer_ran = false; { @@ -700,8 +706,6 @@ TEST_F(Test73TerminationUntilCancelled, TerminationRequestedInsideTheRelease) { { EnvScope s(runtime_.get()); InstallHelpers(s.env); - ASSERT_EQ(RunScript(s.env, "globalThis.terminateJs = () => { terminate(); tick(); };"), - napi_ok); napi_value object = nullptr; ASSERT_EQ(napi_create_object(s.env, &object), napi_ok); napi_ref keep = nullptr; From 21003ef530677938e106dacc51698449700d8fb7 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Fri, 6 Nov 2026 01:47:50 -0800 Subject: [PATCH 116/150] V8: leave the termination pending when it stops an unofficial call A call that a termination stops is meant to fail with napi_pending_exception and leave the termination pending, as napi_run_script does. The unofficial calls did not: run_script returned napi_pending_exception with nothing pending (its TryCatch's termination is gone once the call returns at call depth 0), as did the branch that keeps the embedder's termination over a timeout ("V8: keep the embedder's termination when a script's timeout expires too") and create_realm when reading a sandbox was terminated; module_wrap_evaluate, evaluate_sync and instantiate returned napi_generic_failure, also with nothing pending; and get_own_non_index_properties left the TryCatch's null pending unmarked, so a cancel did not drop it. An embedder that checks napi_is_exception_pending, as EdgeJS does after a failed call, found none. Found by the Codex review of the commits from "V8: drop the termination's pending null when it is cancelled" to "Say what termination leaves pending, and QuickJS's prepareStackTrace gap". ThrowTryCatchException now fails a terminated call with napi_v8_fail_terminating (napi_pending_exception, the termination's null pending and marked unless something else is pending), and those call sites use it when their TryCatch caught a termination. Test: test_73 CallsTheTerminationStopsLeaveItPending, both engines: the embedder, outside any JS, calls run_script, module_wrap_evaluate and evaluate_sync on JS that terminates, get_own_non_index_properties on a proxy whose ownKeys trap terminates, and (V8 only: QuickJS's create_realm does not read a sandbox's keys) create_realm with that proxy as the sandbox. Each must return napi_pending_exception with an exception pending, which a cancel then drops, and the JS after the termination must not run. Before this change V8 had nothing pending after run_script and create_realm, returned 9 (napi_generic_failure) with nothing pending from both evaluations, and kept the null pending after the cancel for get_own_non_index_properties. QuickJS passed. Co-Authored-By: Claude Opus 5.5 --- .../test_73_termination_until_cancelled.cc | 67 +++++++++++++++++++ v8/src/unofficial_napi.cc | 1 + v8/src/unofficial_napi_contextify.cc | 30 ++++----- 3 files changed, 82 insertions(+), 16 deletions(-) diff --git a/tests/runners/test_73_termination_until_cancelled.cc b/tests/runners/test_73_termination_until_cancelled.cc index e79f337ed2..f638dd4093 100644 --- a/tests/runners/test_73_termination_until_cancelled.cc +++ b/tests/runners/test_73_termination_until_cancelled.cc @@ -547,6 +547,73 @@ TEST_F(Test73TerminationUntilCancelled, CallsRunningJsAfterTheTermination) { } } +// N-API calls that run JS a termination stops, made by the embedder outside +// any JS: they must fail with napi_pending_exception and leave the +// termination pending, as napi_run_script does. Each payload's JS calls +// terminateJs(). Only V8's create_realm reads a sandbox's own keys (to keep +// them), so only there does a proxy sandbox run JS. +constexpr const char* kStoppedCalls[] = { + "unofficial_napi_run_script", + "unofficial_napi_module_wrap_evaluate", + "unofficial_napi_module_wrap_evaluate_sync", + "unofficial_napi_get_own_non_index_properties (proxy)", +#if defined(NAPI_TEST_ENGINE_V8) + "unofficial_napi_create_realm (proxy sandbox)", +#endif +}; +constexpr int kStoppedCallCount = sizeof(kStoppedCalls) / sizeof(kStoppedCalls[0]); + +TEST_F(Test73TerminationUntilCancelled, CallsTheTerminationStopsLeaveItPending) { + for (int kind = 0; kind < kStoppedCallCount; ++kind) { + SCOPED_TRACE(kStoppedCalls[kind]); + EnvScope s(runtime_.get()); + InstallHelpers(s.env); + unofficial_napi_module module = MakeModule(s.env, "terminateJs();", nullptr); + ASSERT_NE(module, nullptr); + napi_value proxy = + Eval(s.env, "new Proxy({}, { ownKeys() { terminateJs(); afterCall = 'yes'; return []; } })"); + napi_value out = nullptr; + napi_status status = napi_ok; + switch (kind) { + case 0: { + const unofficial_napi_js_source source = + unofficial_napi_js_source_from_text(Str(s.env, "terminateJs(); afterCall = 'yes';")); + status = unofficial_napi_run_script(s.env, nullptr, &source, Str(s.env, "stopped.js"), 0, + 0, -1, true, false, false, nullptr, &out); + break; + } + case 1: + status = unofficial_napi_module_wrap_evaluate(s.env, module, -1, false, &out); + break; + case 2: + status = unofficial_napi_module_wrap_evaluate_sync(s.env, module, Str(s.env, "m.mjs"), + Str(s.env, "parent.js"), &out); + break; + case 3: + status = unofficial_napi_get_own_non_index_properties(s.env, proxy, 0, &out); + break; + default: { + unofficial_napi_realm_options options; + unofficial_napi_realm_options_init(&options); + options.sandbox_or_null = proxy; + unofficial_napi_realm realm = nullptr; + status = unofficial_napi_create_realm(s.env, &options, &realm, &out); + break; + } + } + EXPECT_EQ(status, napi_pending_exception); + bool pending = false; + EXPECT_EQ(napi_is_exception_pending(s.env, &pending), napi_ok); + EXPECT_TRUE(pending) << "nothing pending after the call"; + // Cancelling without taking it drops it: it stands for the termination. + EXPECT_EQ(unofficial_napi_cancel_terminate_execution(s.env), napi_ok); + EXPECT_EQ(napi_is_exception_pending(s.env, &pending), napi_ok); + EXPECT_FALSE(pending) << "the termination is still pending after the cancel"; + EXPECT_EQ(Flags(s.env), kNothingRan); + EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, module), napi_ok); + } +} + // The same native code, called from the module hooks test_72 covers: those // see what the native function threw. TEST_F(Test73TerminationUntilCancelled, NativeCallsAfterTheTerminationInsideModuleHooks) { diff --git a/v8/src/unofficial_napi.cc b/v8/src/unofficial_napi.cc index 79210ec650..92197e1411 100644 --- a/v8/src/unofficial_napi.cc +++ b/v8/src/unofficial_napi.cc @@ -2631,6 +2631,7 @@ napi_status NAPI_CDECL unofficial_napi_get_own_non_index_properties( static_cast(filter_bits), v8::IndexFilter::kSkipIndices) .ToLocal(&properties)) { + if (try_catch.HasTerminated()) return napi_v8_fail_terminating(env); if (try_catch.HasCaught()) { napi_v8_set_last_exception( env, try_catch.Exception(), try_catch.Message()); diff --git a/v8/src/unofficial_napi_contextify.cc b/v8/src/unofficial_napi_contextify.cc index f0a6c76884..1702dc3d78 100644 --- a/v8/src/unofficial_napi_contextify.cc +++ b/v8/src/unofficial_napi_contextify.cc @@ -130,7 +130,9 @@ bool IsNullish(napi_env env, napi_value value) { } napi_status ThrowTryCatchException(napi_env env, v8::TryCatch& try_catch) { - if (env == nullptr || !try_catch.HasCaught() || try_catch.HasTerminated()) { + // A termination stays: it is what the call fails with. + if (env != nullptr && try_catch.HasTerminated()) return napi_v8_fail_terminating(env); + if (env == nullptr || !try_catch.HasCaught()) { return napi_pending_exception; } v8::Local exception = try_catch.Exception(); @@ -1809,7 +1811,8 @@ napi_status NAPI_CDECL unofficial_napi_create_realm( // creation must retain V8's normal, uncaught lifecycle. v8::TryCatch try_catch(isolate); if (!SnapshotOwnProperties(isolate, current, sandbox, &saved_properties)) { - if (try_catch.HasCaught() && !try_catch.HasTerminated()) { + if (try_catch.HasTerminated()) return napi_v8_fail_terminating(env); + if (try_catch.HasCaught()) { napi_v8_set_last_exception(env, try_catch.Exception(), try_catch.Message()); } return napi_pending_exception; @@ -2217,6 +2220,7 @@ napi_status NAPI_CDECL unofficial_napi_run_script( } return ThrowTryCatchException(env, try_catch); } + if (try_catch.HasTerminated()) return napi_v8_fail_terminating(env); return napi_generic_failure; } @@ -2248,7 +2252,7 @@ napi_status NAPI_CDECL unofficial_napi_run_script( // ran the script go on: it keeps unwinding instead, as in Node, which // checks env->is_stopping() first. if (env->agent->termination_requested.load(std::memory_order_acquire)) { - return napi_pending_exception; + return napi_v8_fail_terminating(env); } isolate->CancelTerminateExecution(); @@ -2274,10 +2278,7 @@ napi_status NAPI_CDECL unofficial_napi_run_script( unofficial_napi_internal::AttachSyntaxArrowMessage( isolate, target_context, try_catch.Exception(), try_catch.Message()); } - if (!try_catch.HasTerminated()) { - return ThrowTryCatchException(env, try_catch); - } - return napi_pending_exception; + return ThrowTryCatchException(env, try_catch); } v8::Local result; @@ -2870,9 +2871,8 @@ napi_status NAPI_CDECL unofficial_napi_module_wrap_instantiate( v8::TryCatch try_catch(isolate); auto maybe = module->InstantiateModule(context, ModuleResolveCallback, ModuleResolveSourceCallback); if (maybe.IsNothing()) { - if (try_catch.HasCaught() && !try_catch.HasTerminated()) { - return ThrowTryCatchException(env, try_catch); - } + // A termination too: it stays, and is what the call fails with. + if (try_catch.HasCaught()) return ThrowTryCatchException(env, try_catch); return napi_generic_failure; } return napi_ok; @@ -2896,9 +2896,8 @@ napi_status NAPI_CDECL unofficial_napi_module_wrap_evaluate( v8::TryCatch try_catch(isolate); v8::Local result; if (!module->Evaluate(context).ToLocal(&result)) { - if (try_catch.HasCaught() && !try_catch.HasTerminated()) { - return ThrowTryCatchException(env, try_catch); - } + // A termination too: it stays, and is what the call fails with. + if (try_catch.HasCaught()) return ThrowTryCatchException(env, try_catch); return napi_generic_failure; } *result_out = napi_v8_wrap_value(env, handle_scope.Escape(result)); @@ -2925,9 +2924,8 @@ napi_status NAPI_CDECL unofficial_napi_module_wrap_evaluate_sync( v8::TryCatch try_catch(isolate); v8::Local result; if (!module->Evaluate(context).ToLocal(&result)) { - if (try_catch.HasCaught() && !try_catch.HasTerminated()) { - return ThrowTryCatchException(env, try_catch); - } + // A termination too: it stays, and is what the call fails with. + if (try_catch.HasCaught()) return ThrowTryCatchException(env, try_catch); return napi_generic_failure; } if (!result->IsPromise()) return napi_generic_failure; From 455192bb6eb91e56e738d0f220387047f905fbae Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Fri, 6 Nov 2026 01:49:05 -0800 Subject: [PATCH 117/150] V8: drop the termination's pending null when the release cancels it The release of an env whose termination was never cancelled (as after worker.terminate()) cancels it in napi_agent__::Shutdown, so that its cleanup hooks and finalizers can run JS, but kept what the termination had left pending: the null of the run it stopped, or of a call it refused. When a hook's JS then called a native function, the trampoline found that null pending, with the env no longer terminating, and threw it into the hook's JS as a catchable null. Found by the Codex review of the commits from "V8: drop the termination's pending null when it is cancelled" to "Say what termination leaves pending, and QuickJS's prepareStackTrace gap". Shutdown now drops a pending exception that stands for the termination of its principal env, as unofficial_napi_cancel_terminate_execution does. Test: test_73 ReleaseAfterAnUncancelledTermination, both engines: a run ends terminated, and without a cancel the env is released; its cleanup hook runs a script that calls a native no-op in try/catch. The hook must see "ok" (V8, which runs the hooks' JS) or have its run refused (QuickJS, which keeps the termination through the release). Before this change V8 gave "caught null". Co-Authored-By: Claude Opus 5.5 --- .../test_73_termination_until_cancelled.cc | 46 +++++++++++++++++-- v8/src/unofficial_napi.cc | 5 +- 2 files changed, 46 insertions(+), 5 deletions(-) diff --git a/tests/runners/test_73_termination_until_cancelled.cc b/tests/runners/test_73_termination_until_cancelled.cc index f638dd4093..9527db7860 100644 --- a/tests/runners/test_73_termination_until_cancelled.cc +++ b/tests/runners/test_73_termination_until_cancelled.cc @@ -291,19 +291,23 @@ napi_value Eval(napi_env env, const char* source) { return result; } -std::string GlobalText(napi_env env, const char* name) { - napi_value value = nullptr; +std::string Text(napi_env env, napi_value value) { napi_value string = nullptr; char text[256] = {}; size_t length = 0; - if (napi_get_named_property(env, Global(env), name, &value) != napi_ok || - napi_coerce_to_string(env, value, &string) != napi_ok || + if (value == nullptr || napi_coerce_to_string(env, value, &string) != napi_ok || napi_get_value_string_utf8(env, string, text, sizeof(text), &length) != napi_ok) { return ""; } return std::string(text, length); } +std::string GlobalText(napi_env env, const char* name) { + napi_value value = nullptr; + if (napi_get_named_property(env, Global(env), name, &value) != napi_ok) return ""; + return Text(env, value); +} + // What EdgeJS does once the stack has unwound: take the pending exception, // then cancel the termination. Returns whether one was pending. bool FinishTermination(napi_env env) { @@ -319,6 +323,7 @@ bool FinishTermination(napi_env env) { void InstallHelpers(napi_env env) { DefineGlobalFunction(env, "terminate", Terminate); + DefineGlobalFunction(env, "noop", Noop); DefineGlobalFunction(env, "terminateThen", TerminateThen); DefineGlobalFunction(env, "callThen", CallThen); DefineGlobalFunction(env, "terminateThenCancel", TerminateThenCancel); @@ -788,6 +793,39 @@ TEST_F(Test73TerminationUntilCancelled, TerminationRequestedInsideTheRelease) { std::vector(4, napi_pending_exception)); } +// The release of an env whose termination was never cancelled, as after +// worker.terminate(). V8's release cancels it and runs the hooks with JS +// usable; QuickJS keeps it and refuses their JS. Either way, the null the +// termination left pending must not be thrown into a hook's JS when it calls +// a native function. +namespace { +std::string g_release_result; +void ReleaseRunsJs(void* arg) { + napi_env env = static_cast(arg); + napi_value result = nullptr; + if (napi_run_script(env, + Str(env, + "(() => { try { noop(); return 'ok'; }\n" + "catch (e) { return 'caught ' + String(e); } })()"), + &result) != napi_ok) { + g_release_result = "refused"; + return; + } + g_release_result = Text(env, result); +} +} // namespace + +TEST_F(Test73TerminationUntilCancelled, ReleaseAfterAnUncancelledTermination) { + g_release_result.clear(); + { + EnvScope s(runtime_.get()); + InstallHelpers(s.env); + ASSERT_EQ(napi_add_env_cleanup_hook(s.env, ReleaseRunsJs, s.env), napi_ok); + EXPECT_EQ(RunScript(s.env, "terminate(); tick();"), napi_pending_exception); + } + EXPECT_TRUE(g_release_result == "ok" || g_release_result == "refused") << g_release_result; +} + #if defined(NAPI_TEST_ENGINE_V8) // The same native code, called from the hooks only V8 runs: the // prepare-stack-trace callback (QuickJS never calls it), the serializer's diff --git a/v8/src/unofficial_napi.cc b/v8/src/unofficial_napi.cc index 92197e1411..b27aa7f625 100644 --- a/v8/src/unofficial_napi.cc +++ b/v8/src/unofficial_napi.cc @@ -1643,9 +1643,12 @@ void napi_agent__::Shutdown() { near_heap_limit_data = nullptr; fatal_error_callback = nullptr; oom_error_callback = nullptr; - // The release runs its hooks and finalizers with JS usable. + // The release runs its hooks and finalizers with JS usable. As a cancel, + // this drops what the termination left pending: a native function that + // a hook's JS calls would otherwise throw it into that JS. termination_requested.store(false, std::memory_order_release); isolate->CancelTerminateExecution(); + if (principal_env != nullptr) napi_v8_drop_pending_termination(principal_env); termination_probe.Reset(); isolate->SetPromiseHook(nullptr); isolate->SetPromiseRejectCallback(nullptr); From d3286c41cc39a1f905cb5fb5cfe08c2024f155f8 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Fri, 6 Nov 2026 01:50:35 -0800 Subject: [PATCH 118/150] V8: let a context-token hook's cancel drop the termination's null During the release the context-token hooks run with N-API's pending exception put aside, and put back after (CallContextTokenHook), so that a hook's own exception is dropped and the one the release had is kept. When the put-aside exception was the termination's null and the hook cancelled the termination, the cancel found nothing to drop, and the null came back afterwards: the cleanup hook that had collected the realm then ran JS, and a native function it called threw the null into it as a catchable exception. Found by the Codex review of the commits from "V8: drop the termination's pending null when it is cancelled" to "Say what termination leaves pending, and QuickJS's prepareStackTrace gap". After the hook, a termination's null that was put aside is dropped when the env no longer terminates. Test: test_73 UnassignHookCancelsDuringTheRelease, V8 only (only V8 accepts the context-token hooks): during the release a cleanup hook makes and drops a realm, terminates, has a run refused (which leaves the termination's null pending), and collects the realm, whose unassign hook cancels the termination; it then runs a script that calls a native no-op in try/catch, which must give "ok". Before this change: "caught null". Co-Authored-By: Claude Opus 5.5 --- .../test_73_termination_until_cancelled.cc | 48 +++++++++++++++++++ v8/src/unofficial_napi_contextify.cc | 3 ++ 2 files changed, 51 insertions(+) diff --git a/tests/runners/test_73_termination_until_cancelled.cc b/tests/runners/test_73_termination_until_cancelled.cc index 9527db7860..7eaa55dd11 100644 --- a/tests/runners/test_73_termination_until_cancelled.cc +++ b/tests/runners/test_73_termination_until_cancelled.cc @@ -927,6 +927,54 @@ TEST_F(Test73TerminationUntilCancelled, NativeCallsAfterTheTerminationInsideTheT // collected since, then makes the realm. When a hook's JS is terminated, it // must fail without making the realm: the V8 calls that make it would clear // the termination. +// During the release, the context-token hooks run with what is pending put +// aside, and it is put back after. An unassign hook that cancels the +// termination drops what the termination left pending: put back, the null +// would be thrown into the JS the cleanup hook runs next. +namespace { +bool g_cancel_armed = false; +void CancellingTokenHook(napi_env env, void* /*token*/, void* /*data*/) { + if (!g_cancel_armed) return; + g_cancel_armed = false; + EXPECT_EQ(unofficial_napi_cancel_terminate_execution(env), napi_ok); +} +void CleanupHookCancelledByAnUnassignHook(void* arg) { + napi_env env = static_cast(arg); + { + napi_handle_scope scope = nullptr; + ASSERT_EQ(napi_open_handle_scope(env, &scope), napi_ok); + unofficial_napi_realm realm = nullptr; + napi_value global = nullptr; + ASSERT_EQ(unofficial_napi_create_realm(env, nullptr, &realm, &global), napi_ok); + ASSERT_EQ(napi_close_handle_scope(env, scope), napi_ok); + } + ASSERT_EQ(unofficial_napi_terminate_execution(env), napi_ok); + napi_value result = nullptr; + EXPECT_EQ(napi_run_script(env, Str(env, "1"), &result), napi_pending_exception); + g_cancel_armed = true; + ASSERT_EQ(unofficial_napi_collect_garbage(env), napi_ok); + EXPECT_FALSE(g_cancel_armed) << "the unassign hook did not run"; + ReleaseRunsJs(env); +} +} // namespace + +TEST_F(Test73TerminationUntilCancelled, UnassignHookCancelsDuringTheRelease) { + g_release_result.clear(); + { + EnvScope s(runtime_.get()); + InstallHelpers(s.env); + unofficial_napi_env_hooks hooks{}; + hooks.size = sizeof(hooks); + hooks.version = UNOFFICIAL_NAPI_ENV_HOOKS_VERSION; + hooks.context_token_unassign_callback = CancellingTokenHook; + uint64_t accepted = 0; + ASSERT_EQ(unofficial_napi_attach_env(s.env, &hooks, &accepted), napi_ok); + ASSERT_EQ(napi_add_env_cleanup_hook(s.env, CleanupHookCancelledByAnUnassignHook, s.env), + napi_ok); + } + EXPECT_EQ(g_release_result, "ok"); +} + TEST_F(Test73TerminationUntilCancelled, CreateRealmAfterATerminatedUnassignHook) { for (bool with_sandbox : {true, false}) { SCOPED_TRACE(with_sandbox ? "with a sandbox" : "with a fresh global"); diff --git a/v8/src/unofficial_napi_contextify.cc b/v8/src/unofficial_napi_contextify.cc index 1702dc3d78..683f988d7c 100644 --- a/v8/src/unofficial_napi_contextify.cc +++ b/v8/src/unofficial_napi_contextify.cc @@ -1382,6 +1382,9 @@ void CallContextTokenHook(napi_env env, env->last_exception_source_line.swap(source_line); env->last_exception_thrown_at.swap(thrown_at); env->last_exception_is_termination = is_termination; + // The hook may have cancelled the termination, which drops what it left + // pending: that was put aside, so drop it now. + if (is_termination && !napi_v8_terminating(env)) napi_v8_drop_pending_termination(env); } // A realm has a token while either hook is attached, as each context did. From 8dff763d5560d5c84edc74630dc47180b773a1e0 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Fri, 6 Nov 2026 01:53:30 -0800 Subject: [PATCH 119/150] V8: fail the checkpoint when a task it runs is terminated The event-loop checkpoint looks for a termination after the finalizers and microtasks it runs ("V8: keep a termination until it is cancelled"), but then pumps one platform foreground task, such as a FinalizationRegistry's cleanup, which runs JS too. When that JS was terminated, the checkpoint still returned napi_ok with nothing pending: the embedder's loop went on as if nothing had happened, and only its next call into JS failed. Found by the Codex review of the commits from "V8: drop the termination's pending null when it is cancelled" to "Say what termination leaves pending, and QuickJS's prepareStackTrace gap". The checkpoint now also fails, with napi_pending_exception and the termination pending, when the env terminates during the task. Test: test_73, both engines. FinalizationRegistryCleanupAtACheckpoint: a registry's cleanup callback marks that it ran, terminates and calls a JS function; the test collects and runs host-task checkpoints until it ran. The checkpoint that ran it must fail and the next run too. Before this change V8's checkpoint returned 0; QuickJS, which runs the callback as a job, passed. FinalizerDrainedAtACheckpoint now also asserts the checkpoint's status, which it skipped because QuickJS runs the finalizer when it frees the object, before the loop's first checkpoint: the loop now always runs one, and the checkpoint must fail on both engines. Co-Authored-By: Claude Opus 5.5 --- .../test_73_termination_until_cancelled.cc | 50 ++++++++++++++++--- v8/src/unofficial_napi.cc | 10 ++-- 2 files changed, 50 insertions(+), 10 deletions(-) diff --git a/tests/runners/test_73_termination_until_cancelled.cc b/tests/runners/test_73_termination_until_cancelled.cc index 7eaa55dd11..c2e919d044 100644 --- a/tests/runners/test_73_termination_until_cancelled.cc +++ b/tests/runners/test_73_termination_until_cancelled.cc @@ -675,9 +675,9 @@ TEST_F(Test73TerminationUntilCancelled, NativeCallsAfterTheTerminationInsideModu } } -// A finalizer drained at a checkpoint (V8; QuickJS runs it while it -// collects) whose JS is terminated. Nothing reports a failure from a -// finalizer: its next call into JS must fail, and the next run. +// A finalizer whose JS is terminated. Nothing reports a failure from a +// finalizer: its next call into JS must fail, and the checkpoint and the +// next run. namespace { napi_status g_finalizer_first = napi_ok; napi_status g_finalizer_second = napi_ok; @@ -709,17 +709,55 @@ TEST_F(Test73TerminationUntilCancelled, FinalizerDrainedAtACheckpoint) { napi_ok); ASSERT_EQ(napi_close_handle_scope(s.env, scope), napi_ok); } + // V8 runs the finalizer at the checkpoint; QuickJS when it frees the + // object, before. Either way the checkpoint after it fails. napi_status checkpoint = napi_ok; - for (int i = 0; i < 5 && !g_finalizer_ran; ++i) { + for (int i = 0; i < 5; ++i) { ASSERT_EQ(unofficial_napi_collect_garbage(s.env), napi_ok); checkpoint = unofficial_napi_event_loop_checkpoint( s.env, unofficial_napi_event_loop_checkpoint_microtasks, false, nullptr); + if (g_finalizer_ran) break; } ASSERT_TRUE(g_finalizer_ran); EXPECT_EQ(g_finalizer_first, napi_pending_exception); EXPECT_EQ(g_finalizer_second, napi_pending_exception); - EXPECT_EQ(RunScript(s.env, "afterCall = 'yes';"), napi_pending_exception) - << "checkpoint " << checkpoint; + EXPECT_EQ(checkpoint, napi_pending_exception); + EXPECT_EQ(RunScript(s.env, "afterCall = 'yes';"), napi_pending_exception); + FinishTermination(s.env); + EXPECT_EQ(GlobalText(s.env, "afterCall"), "no"); +} + +// A FinalizationRegistry cleanup callback, which the checkpoint runs (V8: +// as a foreground task it pumps; QuickJS: as a job), and whose JS is +// terminated: the checkpoint must fail. +namespace { +bool g_cleanup_ran = false; +napi_value MarkCleanup(napi_env /*env*/, napi_callback_info /*info*/) { + g_cleanup_ran = true; + return nullptr; +} +} // namespace + +TEST_F(Test73TerminationUntilCancelled, FinalizationRegistryCleanupAtACheckpoint) { + EnvScope s(runtime_.get()); + InstallHelpers(s.env); + DefineGlobalFunction(s.env, "markCleanup", MarkCleanup); + ASSERT_EQ(RunScript(s.env, + "globalThis.registry = new FinalizationRegistry(() => {\n" + " markCleanup(); terminate(); tick(); afterCall = 'yes';\n" + "});\n" + "(() => { registry.register({}, 1); })();\n"), + napi_ok); + g_cleanup_ran = false; + napi_status checkpoint = napi_ok; + for (int i = 0; i < 20 && !g_cleanup_ran; ++i) { + ASSERT_EQ(unofficial_napi_collect_garbage(s.env), napi_ok); + checkpoint = unofficial_napi_event_loop_checkpoint( + s.env, unofficial_napi_event_loop_checkpoint_host_tasks, true, nullptr); + } + ASSERT_TRUE(g_cleanup_ran); + EXPECT_EQ(checkpoint, napi_pending_exception); + EXPECT_EQ(RunScript(s.env, "afterCall = 'yes';"), napi_pending_exception); FinishTermination(s.env); EXPECT_EQ(GlobalText(s.env, "afterCall"), "no"); } diff --git a/v8/src/unofficial_napi.cc b/v8/src/unofficial_napi.cc index b27aa7f625..026e9cccc4 100644 --- a/v8/src/unofficial_napi.cc +++ b/v8/src/unofficial_napi.cc @@ -2084,7 +2084,7 @@ bool PumpPlatformForegroundTasks(napi_env env) { } // Returns false, having run no more JS, once the env terminates (a -// finalizer or a microtask may terminate it). +// finalizer, a microtask or a task may terminate it). bool DrainMicrotasksForEnv(napi_env env, bool* host_task_admitted) { *host_task_admitted = false; env->DrainFinalizerQueue(); @@ -2098,8 +2098,9 @@ bool DrainMicrotasksForEnv(napi_env env, bool* host_task_admitted) { } env->DrainFinalizerQueue(); if (napi_v8_terminating(env)) return false; + // The task may run JS too (a FinalizationRegistry's cleanup). *host_task_admitted = PumpPlatformForegroundTasks(env); - return true; + return !napi_v8_terminating(env); } napi_status NAPI_CDECL unofficial_napi_event_loop_checkpoint( @@ -2114,8 +2115,9 @@ napi_status NAPI_CDECL unofficial_napi_event_loop_checkpoint( return napi_invalid_arg; } // As the calls into JS: a terminating env runs none, and a termination a - // finalizer or a microtask runs into fails the checkpoint, as on QuickJS, - // so the event loop stops instead of going on as if nothing happened. + // finalizer, a microtask or a task runs into fails the checkpoint, as on + // QuickJS, so the event loop stops instead of going on as if nothing + // happened. bool host_task_admitted = false; if (napi_v8_terminating(env) || !DrainMicrotasksForEnv(env, &host_task_admitted)) { return napi_v8_fail_terminating(env); From c0390defdd3abf37d7ab7c9867d36b108ade0b41 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Fri, 6 Nov 2026 01:55:41 -0800 Subject: [PATCH 120/150] Refuse error creators and V8's mark_promise_as_handled while terminating napi_create_error, napi_create_type_error, napi_create_range_error and node_api_create_syntax_error give their error a `code` with a plain set, which runs an inherited `code` setter, and on QuickJS making the error reads Error.prepareStackTrace, which may be a getter. They had no termination guard on either engine, so native code whose call into JS a termination stopped and which then made an error with a code ran that setter to completion: V8 cleared the termination on entering the set, and QuickJS polls its interrupt handler too rarely to stop a short setter. V8's unofficial_napi_mark_promise_as_handled calls the reject callback for a rejected promise, and ran it the same way. Found by the Codex review of the commits from "V8: drop the termination's pending null when it is cancelled" to "Say what termination leaves pending, and QuickJS's prepareStackTrace gap" (the error creators); the reject callback by the same check. Both engines now refuse the error creators while the env terminates, as the napi_throw_* calls already were, and V8 refuses mark_promise_as_handled. QuickJS's mark_promise_as_handled runs no JS (it marks the promise without calling the reject callback) and is left as it is. Test: test_73 CallsRunningJsAfterTheTermination gains two calls: a napi_create_error with a code, with an Error.prototype `code` setter that sets the flag, and mark_promise_as_handled on a rejected promise, with a reject callback that sets the flag when a handler is added. The run must come back terminated with the flag unset, and the call must return napi_pending_exception (QuickJS's mark_promise_as_handled: napi_ok). Before this change the setter ran and the call returned 0 on both engines, and V8 ran the reject callback and returned 0. Co-Authored-By: Claude Opus 5.5 --- quickjs/src/internal/napi_util.cc | 4 ++++ .../test_73_termination_until_cancelled.cc | 21 ++++++++++++++++++- v8/src/js_native_api_v8.cc | 2 ++ v8/src/unofficial_napi.cc | 2 ++ 4 files changed, 28 insertions(+), 1 deletion(-) diff --git a/quickjs/src/internal/napi_util.cc b/quickjs/src/internal/napi_util.cc index da781fd1d9..a03cd716f9 100644 --- a/quickjs/src/internal/napi_util.cc +++ b/quickjs/src/internal/napi_util.cc @@ -794,6 +794,10 @@ napi_status napi_util__::create_error_common(napi_env env, { if (!check_env(env) || msg == nullptr || result == nullptr) return napi_invalid_arg; + // Making the error reads Error.prepareStackTrace and setting its code runs + // an inherited `code` setter: JS, which a terminating env must not run. + if (env->termination_requested()) + return fail_if_terminating(env, context(env)); JSValue msg_val = napi_quickjs_value_inner(env, msg); if (!JS_IsString(msg_val)) diff --git a/tests/runners/test_73_termination_until_cancelled.cc b/tests/runners/test_73_termination_until_cancelled.cc index c2e919d044..eb11315102 100644 --- a/tests/runners/test_73_termination_until_cancelled.cc +++ b/tests/runners/test_73_termination_until_cancelled.cc @@ -194,6 +194,8 @@ constexpr const char* kJsCalls[] = { "unofficial_napi_message_create (getter)", "unofficial_napi_compile_function (getter in the extensions)", "napi_create_buffer (Buffer getter)", + "napi_create_error (code setter)", + "unofficial_napi_mark_promise_as_handled (reject callback)", }; constexpr int kJsCallCount = sizeof(kJsCalls) / sizeof(kJsCalls[0]); @@ -207,6 +209,8 @@ constexpr const char* kJsCallPayloads[] = { "({ get x() { afterCall = 'yes'; return 1; } })", "(() => { const a = [{}]; Object.defineProperty(a, 0, { get() { afterCall = 'yes'; return {}; } }); return a; })()", "(Object.defineProperty(globalThis, 'Buffer', { get() { afterCall = 'yes'; return undefined; }, configurable: true }), undefined)", + "(Object.defineProperty(Error.prototype, 'code', { set(v) { afterCall = 'yes'; }, configurable: true }), undefined)", + "(() => { const p = Promise.reject(1); return p; })()", }; // The module kJsCalls's evaluations evaluate. @@ -251,10 +255,14 @@ napi_status CallRunningJs(napi_env env, int kind, napi_value payload) { return unofficial_napi_compile_function(env, nullptr, &source, Str(env, "f.js"), 0, 0, payload, undefined, undefined, &out); } - default: { + case 8: { void* data = nullptr; return napi_create_buffer(env, 4, &data, &out); } + case 9: + return napi_create_error(env, Str(env, "E_CODE"), Str(env, "message"), &out); + default: + return unofficial_napi_mark_promise_as_handled(env, payload); } } @@ -540,6 +548,10 @@ TEST_F(Test73TerminationUntilCancelled, CallsRunningJsAfterTheTermination) { InstallHelpers(s.env); g_module = MakeModule(s.env, "globalThis.afterCall = 'yes';", nullptr); ASSERT_NE(g_module, nullptr); + // Called again, for a rejected promise a handler is added to. + ASSERT_EQ(unofficial_napi_set_promise_reject_callback( + s.env, Eval(s.env, "(type, promise, reason) => { if (type === 1) afterCall = 'yes'; }")), + napi_ok); g_status = napi_ok; const std::string script = std::string("const payload = ") + kJsCallPayloads[kind] + ";\n" + @@ -547,6 +559,13 @@ TEST_F(Test73TerminationUntilCancelled, CallsRunningJsAfterTheTermination) { ", payload); } catch (e) { caught = 'yes'; caughtError = e; }\n" "after = 'yes';\n"; ExpectRunTerminated(s.env, script.c_str()); +#if defined(NAPI_TEST_ENGINE_QUICKJS) + // QuickJS marks the promise without calling the reject callback: no JS + // runs, and the call succeeds. + if (kind == kJsCallCount - 1) { + EXPECT_EQ(g_status, napi_ok); + } else +#endif EXPECT_EQ(g_status, napi_pending_exception); EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, g_module), napi_ok); } diff --git a/v8/src/js_native_api_v8.cc b/v8/src/js_native_api_v8.cc index 8cfc8bb1d1..c5a19fe377 100644 --- a/v8/src/js_native_api_v8.cc +++ b/v8/src/js_native_api_v8.cc @@ -3371,6 +3371,8 @@ static napi_status CreateErrorCommon(napi_env env, napi_value code, napi_value msg, napi_value* result) { + // Setting the code runs an inherited `code` setter. + NAPI_V8_RETURN_IF_TERMINATING(env); if (!CheckEnv(env) || msg == nullptr || result == nullptr) return napi_invalid_arg; v8::Local msg_val = napi_v8_unwrap_value(msg); if (!msg_val->IsString()) return napi_string_expected; diff --git a/v8/src/unofficial_napi.cc b/v8/src/unofficial_napi.cc index 026e9cccc4..4e61641c8f 100644 --- a/v8/src/unofficial_napi.cc +++ b/v8/src/unofficial_napi.cc @@ -2401,6 +2401,8 @@ napi_status NAPI_CDECL unofficial_napi_mark_promise_as_handled( napi_env env, napi_value promise) { if (env == nullptr || promise == nullptr) return napi_invalid_arg; + // A rejected promise calls the reject callback, JS. + NAPI_V8_RETURN_IF_TERMINATING(env); v8::Local raw = napi_v8_unwrap_value(promise); if (raw.IsEmpty() || !raw->IsPromise()) return napi_invalid_arg; From f23ef7077c2b05062caadbf224e0b6146e21642b Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Fri, 6 Nov 2026 01:57:14 -0800 Subject: [PATCH 121/150] QuickJS: keep native code's pending exception when a call is refused A call refused while the env terminates (fail_if_terminating) made the termination's uncatchable error the pending exception, replacing one native code had left pending. A cancel then dropped the uncatchable error, and the native code's exception was gone: native code that threw, terminated, made a refused call and cancelled returned to its caller as if nothing had been thrown. V8 keeps the pending exception there (napi_v8_fail_terminating records the termination only when nothing is pending), as the header now says. Found by the Codex review of the commits from "V8: drop the termination's pending null when it is cancelled" to "Say what termination leaves pending, and QuickJS's prepareStackTrace gap". fail_if_terminating now leaves an ordinary pending exception in place, dropping the termination error the runtime may hold. When nothing is pending, or the termination's error is, it works as before. Test: test_73 CancelKeepsAnExceptionThrownBefore, both engines: a native function throws "kept", terminates, makes two calls the termination refuses (napi_create_buffer, napi_get_named_property) and cancels; the script that calls it in try/catch must catch "kept" and not run the statement after the call. Before this change QuickJS gave "caught=no after=yes ... afterCall=yes"; V8 passed. Co-Authored-By: Claude Opus 5.5 --- quickjs/src/internal/napi_util.cc | 10 ++++++ .../test_73_termination_until_cancelled.cc | 32 +++++++++++++++++++ 2 files changed, 42 insertions(+) diff --git a/quickjs/src/internal/napi_util.cc b/quickjs/src/internal/napi_util.cc index a03cd716f9..3259b3bfc8 100644 --- a/quickjs/src/internal/napi_util.cc +++ b/quickjs/src/internal/napi_util.cc @@ -177,6 +177,16 @@ napi_status napi_util__::fail_if_terminating(napi_env env, JSContext *ctx) { if (!env->termination_requested()) return napi_ok; + // An exception native code left pending stays pending, as on V8: a cancel + // drops only the termination's, and the native function's caller then gets + // that exception. A termination error the runtime holds goes. + if (env->has_last_exception() && !env->last_exception_is_uncatchable()) + { + if (JS_HasException(ctx)) + JS_FreeValue(ctx, JS_GetException(ctx)); + return napi_quickjs_set_last_error(env, napi_pending_exception, + "JavaScript execution is terminating"); + } throw_termination(ctx); return return_pending_if_caught(env, ctx, "JavaScript execution is terminating"); } diff --git a/tests/runners/test_73_termination_until_cancelled.cc b/tests/runners/test_73_termination_until_cancelled.cc index eb11315102..92b0474adc 100644 --- a/tests/runners/test_73_termination_until_cancelled.cc +++ b/tests/runners/test_73_termination_until_cancelled.cc @@ -466,6 +466,38 @@ TEST_F(Test73TerminationUntilCancelled, CancelledInsideANativeFunction) { EXPECT_FALSE(pending); } +// Native code that left an exception pending, then terminates, makes a call +// the termination refuses, and cancels: the exception it left stays, and is +// thrown into the JS that called it, as if no termination had happened. +namespace { +napi_value ThrowTerminateCancel(napi_env env, napi_callback_info /*info*/) { + napi_throw_error(env, nullptr, "kept"); + bool pending = false; + EXPECT_EQ(napi_is_exception_pending(env, &pending), napi_ok); + EXPECT_TRUE(pending); + EXPECT_EQ(unofficial_napi_terminate_execution(env), napi_ok); + napi_value out = nullptr; + void* data = nullptr; + EXPECT_EQ(napi_create_buffer(env, 4, &data, &out), napi_pending_exception); + EXPECT_EQ(napi_get_named_property(env, Global(env), "tick", &out), napi_pending_exception); + EXPECT_EQ(unofficial_napi_cancel_terminate_execution(env), napi_ok); + return nullptr; +} +} // namespace + +TEST_F(Test73TerminationUntilCancelled, CancelKeepsAnExceptionThrownBefore) { + EnvScope s(runtime_.get()); + InstallHelpers(s.env); + DefineGlobalFunction(s.env, "throwTerminateCancel", ThrowTerminateCancel); + EXPECT_EQ(RunScript(s.env, + "try { throwTerminateCancel(); afterCall = 'yes'; }\n" + "catch (e) { caught = 'yes'; caughtError = e.message; }\n" + "after = 'yes';\n"), + napi_ok); + EXPECT_EQ(Flags(s.env), + "caught=yes after=yes innerCaught=no innerAfter=no error=kept afterCall=no"); +} + // The same inside the import.meta hook, which throws what its callback left // pending from the import.meta expression. TEST_F(Test73TerminationUntilCancelled, CancelledInsideAModuleHook) { From 1fe1ee71a556ae65c830d49dcb85f8669add3b85 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Fri, 6 Nov 2026 01:58:39 -0800 Subject: [PATCH 122/150] V8: run no JS to stop a native function that no JS called When a native function returns while the env terminates, the trampoline makes V8 unwind its caller by asking for the termination again and calling a no-op JS function ("V8: keep a termination until it is cancelled"). A native function the embedder calls from C++ has no JS caller to stop, and the embedder may have disallowed JS there (v8::Isolate::DisallowJavascriptExecutionScope): V8 calls API functions without checking that, but aborts on the no-op function ("Invoke in DisallowJavascriptExecutionScope"). Such a native function that terminated took the process down. Found by the Codex review of the commits from "V8: drop the termination's pending null when it is cancelled" to "Say what termination leaves pending, and QuickJS's prepareStackTrace gap". The trampolines now only ask for the termination again when no JS frame is on the stack (v8::StackTrace::CurrentStackTrace finds none); the termination stays in effect through the sticky flag, and V8 acts on the request when JS next runs. Module hooks still always call the no-op function: V8 expects them to leave an exception when they fail, and they only run while JS runs. A native function the embedder calls from C++, under a disallow scope, from inside a native function that JS called still gets the no-op call; V8 has no API to tell that a scope is open. Test: test_73 NativeFunctionCalledFromCppWithJsDisallowed, V8 only (QuickJS has no such scope): the test calls the terminate() native function through v8::Function::Call inside a CRASH_ON_FAILURE DisallowJavascriptExecutionScope; then a run must fail until the cancel. Before this change the test binary aborted with V8's fatal "Invoke in DisallowJavascriptExecutionScope". Co-Authored-By: Claude Opus 5.5 --- .../test_73_termination_until_cancelled.cc | 34 +++++++++++++++++++ v8/src/js_native_api_v8.cc | 19 +++++++---- 2 files changed, 47 insertions(+), 6 deletions(-) diff --git a/tests/runners/test_73_termination_until_cancelled.cc b/tests/runners/test_73_termination_until_cancelled.cc index 92b0474adc..1958cba54d 100644 --- a/tests/runners/test_73_termination_until_cancelled.cc +++ b/tests/runners/test_73_termination_until_cancelled.cc @@ -15,10 +15,15 @@ #include #include +#include #include #include #include +#if defined(NAPI_TEST_ENGINE_V8) +#include +#endif + class Test73TerminationUntilCancelled : public FixtureTestBase {}; namespace { @@ -1012,6 +1017,35 @@ TEST_F(Test73TerminationUntilCancelled, NativeCallsAfterTheTerminationInsideTheT napi_delete_reference(s.env, g_token_fn); } +// A native function that terminates, called by the embedder from C++ with JS +// execution disallowed (v8::Isolate::DisallowJavascriptExecutionScope, which +// QuickJS has no counterpart of). No JS called it, so there is none to stop, +// and V8 aborts on any JS run there: the provider must run none. The +// termination stays in effect. +TEST_F(Test73TerminationUntilCancelled, NativeFunctionCalledFromCppWithJsDisallowed) { + EnvScope s(runtime_.get()); + InstallHelpers(s.env); + napi_value terminate = nullptr; + ASSERT_EQ(napi_get_named_property(s.env, Global(s.env), "terminate", &terminate), napi_ok); + v8::Isolate* isolate = v8::Isolate::GetCurrent(); + ASSERT_NE(isolate, nullptr); + { + v8::HandleScope handle_scope(isolate); + // This provider's napi_value is a v8::Local. + v8::Local value; + std::memcpy(static_cast(&value), &terminate, sizeof(terminate)); + v8::Local fn = value.As(); + v8::Local context = fn->GetCreationContextChecked(); + v8::Isolate::DisallowJavascriptExecutionScope no_js( + isolate, v8::Isolate::DisallowJavascriptExecutionScope::CRASH_ON_FAILURE); + v8::TryCatch try_catch(isolate); + (void)fn->Call(context, v8::Undefined(isolate), 0, nullptr); + } + EXPECT_EQ(RunScript(s.env, "afterCall = 'yes';"), napi_pending_exception); + FinishTermination(s.env); + EXPECT_EQ(GlobalText(s.env, "afterCall"), "no"); +} + // unofficial_napi_create_realm first runs the unassign hooks of the realms // collected since, then makes the realm. When a hook's JS is terminated, it // must fail without making the realm: the V8 calls that make it would clear diff --git a/v8/src/js_native_api_v8.cc b/v8/src/js_native_api_v8.cc index c5a19fe377..cf2d6331e3 100644 --- a/v8/src/js_native_api_v8.cc +++ b/v8/src/js_native_api_v8.cc @@ -682,17 +682,24 @@ inline bool GetTypedArrayType(v8::Local value, napi_typedarray_type* return true; } -// For a callback V8 runs for JS (a native function, an accessor, a module -// hook) that returns while the env terminates: makes V8 unwind that JS with +// For a callback V8 runs (a native function, an accessor, a module hook) +// that returns while the env terminates: makes V8 unwind the JS below it with // the termination now. V8 may have forgotten it (an N-API call that entered // V8 since cleared it) or not acted on it yet (it acts on a request at its // next stack check, which the JS after the call, a catch block say, need not // reach). So this asks again and calls a no-op function, whose entry is such -// a check. Called only below JS, which the termination then unwinds. -void KeepTerminating(napi_env env) { +// a check. A native function the embedder called from C++ has no JS below it +// to stop, and its caller may have disallowed JS (V8 aborts on JS run then): +// with `only_below_js`, asking again is all this does then. A module hook +// must leave V8 with an exception, so it always calls the function. +void KeepTerminating(napi_env env, bool only_below_js) { v8::Isolate* isolate = env->isolate; if (isolate->IsExecutionTerminating()) return; v8::HandleScope handle_scope(isolate); + if (only_below_js && v8::StackTrace::CurrentStackTrace(isolate, 1)->GetFrameCount() == 0) { + isolate->TerminateExecution(); + return; + } v8::Local context = env->main_context(); v8::Local probe; if (!env->agent->termination_probe.IsEmpty()) { @@ -718,7 +725,7 @@ void KeepTerminating(napi_env env) { bool HandleCallbackException(napi_env env) { if (TerminatedOrTerminating(env)) { ClearLastException(env); - KeepTerminating(env); + KeepTerminating(env, /*only_below_js=*/true); return true; } if (env->last_exception.IsEmpty()) return false; @@ -939,7 +946,7 @@ bool napi_v8_rethrow_pending_exception(napi_env env) { // make the termination a catchable throw and cancel it. if (TerminatedOrTerminating(env)) { ClearLastException(env); - KeepTerminating(env); + KeepTerminating(env, /*only_below_js=*/false); return true; } bool pending = false; From f9cea907d95ff7f7d3d2b26ad4ab34a8714a8c35 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Fri, 6 Nov 2026 01:59:33 -0800 Subject: [PATCH 123/150] V8: ask V8 nothing when a native callback returns with nothing to do Since the termination became sticky ("V8: keep a termination until it is cancelled"), HandleCallbackException, which every native function, getter and setter returns through, asked V8 whether it was terminating on every return, an out-of-line call, where it used to look only at N-API's pending exception. It now reads the termination flag and the pending exception first, and asks V8 only when one of them is set. When neither is, V8 unwinding with a termination of its own (a script timeout's) needs nothing from the trampoline, as before "V8: keep a termination until it is cancelled". No behaviour changes; test_73 and the rest of both suites cover these paths. Co-Authored-By: Claude Opus 5.5 --- v8/src/js_native_api_v8.cc | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/v8/src/js_native_api_v8.cc b/v8/src/js_native_api_v8.cc index cf2d6331e3..8c838fc7e7 100644 --- a/v8/src/js_native_api_v8.cc +++ b/v8/src/js_native_api_v8.cc @@ -723,12 +723,16 @@ void KeepTerminating(napi_env env, bool only_below_js) { // unwinds the JS that called, as QuickJS's trampoline does. Returns whether // that JS unwinds. bool HandleCallbackException(napi_env env) { - if (TerminatedOrTerminating(env)) { + // Every native callback returns through here: the common case, nothing + // pending and no termination requested, asks V8 nothing. V8 unwinding + // with a termination of its own then needs nothing either. + const bool requested = env->agent->termination_requested.load(std::memory_order_acquire); + if (!requested && env->last_exception.IsEmpty()) return false; + if (requested || env->isolate->IsExecutionTerminating()) { ClearLastException(env); KeepTerminating(env, /*only_below_js=*/true); return true; } - if (env->last_exception.IsEmpty()) return false; env->isolate->ThrowException(env->last_exception.Get(env->isolate)); ClearLastException(env); return true; From 483e7b070c821060b3ef1f1c62762fc970dc8bbc Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Fri, 6 Nov 2026 02:36:12 -0800 Subject: [PATCH 124/150] Renumber the termination runners to test_75 and test_76 main has its own test_72_unofficial_memory_pressure, test_73 and test_74 runners, so the termination runners would share their numbers once main is merged into next. They move to the next free numbers: - tests/runners/test_72_hooks_keep_termination.cc becomes test_75_hooks_keep_termination.cc, suite Test75HooksKeepTermination; - tests/runners/test_73_termination_until_cancelled.cc becomes test_76_termination_until_cancelled.cc, suite Test76TerminationUntilCancelled. tests/CMakeLists.txt registers them under the new names, and the two comments in test_76 that point at test_72 now point at test_75. The tests are unchanged otherwise. Test: both engines build; V8 300/300 and QuickJS 271/271 pass. The runners keep their cases: 11 in test_75 and 20 in test_76 on V8, 7 and 15 on QuickJS, which compiles out the V8-only ones. Co-Authored-By: Claude Opus 5.5 --- tests/CMakeLists.txt | 12 ++--- ...n.cc => test_75_hooks_keep_termination.cc} | 24 +++++----- ...=> test_76_termination_until_cancelled.cc} | 46 +++++++++---------- 3 files changed, 41 insertions(+), 41 deletions(-) rename tests/runners/{test_72_hooks_keep_termination.cc => test_75_hooks_keep_termination.cc} (97%) rename tests/runners/{test_73_termination_until_cancelled.cc => test_76_termination_until_cancelled.cc} (97%) diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt index c1b1b65a16..040107b851 100644 --- a/tests/CMakeLists.txt +++ b/tests/CMakeLists.txt @@ -339,14 +339,14 @@ add_fixture_test(${_napi_test_prefix}_test_70_realm_entry_attack add_fixture_test(${_napi_test_prefix}_test_71_contextify_compat runners/test_71_contextify_compat.cc ) -add_fixture_test(${_napi_test_prefix}_test_72_hooks_keep_termination - runners/test_72_hooks_keep_termination.cc +add_fixture_test(${_napi_test_prefix}_test_75_hooks_keep_termination + runners/test_75_hooks_keep_termination.cc ) -target_compile_definitions(${_napi_test_prefix}_test_72_hooks_keep_termination PRIVATE NAPI_VERSION=10) -add_fixture_test(${_napi_test_prefix}_test_73_termination_until_cancelled - runners/test_73_termination_until_cancelled.cc +target_compile_definitions(${_napi_test_prefix}_test_75_hooks_keep_termination PRIVATE NAPI_VERSION=10) +add_fixture_test(${_napi_test_prefix}_test_76_termination_until_cancelled + runners/test_76_termination_until_cancelled.cc ) -target_compile_definitions(${_napi_test_prefix}_test_73_termination_until_cancelled PRIVATE NAPI_VERSION=10) +target_compile_definitions(${_napi_test_prefix}_test_76_termination_until_cancelled PRIVATE NAPI_VERSION=10) if(_napi_test_engine STREQUAL "v8") # Only the V8 provider posts engine tasks through the enqueue hook. add_fixture_test(${_napi_test_prefix}_test_66_foreground_task_handoff diff --git a/tests/runners/test_72_hooks_keep_termination.cc b/tests/runners/test_75_hooks_keep_termination.cc similarity index 97% rename from tests/runners/test_72_hooks_keep_termination.cc rename to tests/runners/test_75_hooks_keep_termination.cc index a47068ab6d..68fce0e2fd 100644 --- a/tests/runners/test_72_hooks_keep_termination.cc +++ b/tests/runners/test_75_hooks_keep_termination.cc @@ -17,7 +17,7 @@ #include -class Test72HooksKeepTermination : public FixtureTestBase {}; +class Test75HooksKeepTermination : public FixtureTestBase {}; namespace { @@ -243,7 +243,7 @@ constexpr char kEvaluateModuleInTryCatch[] = // The import.meta callback. V8 threw the null its TryCatch records for the // termination from the import.meta expression: the module caught it and ran // on, and the termination was gone. -TEST_F(Test72HooksKeepTermination, ImportMetaCallback) { +TEST_F(Test75HooksKeepTermination, ImportMetaCallback) { for (const char* body : kTerminatingBodies) { SCOPED_TRACE(body); EnvScope s(runtime_.get()); @@ -264,7 +264,7 @@ TEST_F(Test72HooksKeepTermination, ImportMetaCallback) { // A synthetic module's evaluation steps. V8 threw the null from the module's // evaluation, which the JS that evaluated it caught. -TEST_F(Test72HooksKeepTermination, SyntheticModuleEvaluationSteps) { +TEST_F(Test75HooksKeepTermination, SyntheticModuleEvaluationSteps) { for (const char* body : kTerminatingBodies) { SCOPED_TRACE(body); EnvScope s(runtime_.get()); @@ -280,7 +280,7 @@ TEST_F(Test72HooksKeepTermination, SyntheticModuleEvaluationSteps) { // The module hooks' import() callback. V8 threw the null from the import() // expression. -TEST_F(Test72HooksKeepTermination, DynamicImportCallback) { +TEST_F(Test75HooksKeepTermination, DynamicImportCallback) { for (const char* body : kTerminatingBodies) { SCOPED_TRACE(body); EnvScope s(runtime_.get()); @@ -298,7 +298,7 @@ TEST_F(Test72HooksKeepTermination, DynamicImportCallback) { // napi_fatal_exception from native code V8 is terminating. V8 threw the // error over the termination, and the JS that called the native code caught // it and ran on. -TEST_F(Test72HooksKeepTermination, FatalExceptionWhileTerminating) { +TEST_F(Test75HooksKeepTermination, FatalExceptionWhileTerminating) { EnvScope s(runtime_.get()); InstallHelpers(s.env); ExpectRunTerminated( @@ -312,7 +312,7 @@ TEST_F(Test72HooksKeepTermination, FatalExceptionWhileTerminating) { // back before it does. The termination must still not be catchable, nor // lost: that run or the next one stops. V8 dropped it once the run returned, // and the env ran on as if it had never been asked to stop. -TEST_F(Test72HooksKeepTermination, PromiseRejectCallback) { +TEST_F(Test75HooksKeepTermination, PromiseRejectCallback) { EnvScope s(runtime_.get()); InstallHelpers(s.env); ASSERT_EQ(unofficial_napi_set_promise_reject_callback( @@ -334,7 +334,7 @@ TEST_F(Test72HooksKeepTermination, PromiseRejectCallback) { // The promise hooks return nothing too: the same holds for them, in the run // that made the promise, or in the microtask checkpoint that runs its // reactions. -TEST_F(Test72HooksKeepTermination, PromiseHooks) { +TEST_F(Test75HooksKeepTermination, PromiseHooks) { constexpr const char* kHookNames[] = {"init", "before", "after", "resolve"}; for (int which = 0; which < 4; ++which) { SCOPED_TRACE(kHookNames[which]); @@ -373,7 +373,7 @@ TEST_F(Test72HooksKeepTermination, PromiseHooks) { // an inherited `code` setter. When V8 terminated the setter, V8's // napi_throw_error and its siblings, the serdes binding's constructors and // the module loader's link errors threw their error over the termination. -TEST_F(Test72HooksKeepTermination, ErrorCodeSetter) { +TEST_F(Test75HooksKeepTermination, ErrorCodeSetter) { constexpr char kCodeSetter[] = "Object.defineProperty(Error.prototype, 'code'," " { set(value) { terminate(); tick(); }, configurable: true });"; @@ -436,7 +436,7 @@ TEST_F(Test72HooksKeepTermination, ErrorCodeSetter) { #if defined(NAPI_TEST_ENGINE_V8) // The prepare-stack-trace callback; QuickJS ignores the one set here. -TEST_F(Test72HooksKeepTermination, PrepareStackTraceCallback) { +TEST_F(Test75HooksKeepTermination, PrepareStackTraceCallback) { EnvScope s(runtime_.get()); InstallHelpers(s.env); ASSERT_EQ(unofficial_napi_set_prepare_stack_trace_callback( @@ -453,7 +453,7 @@ TEST_F(Test72HooksKeepTermination, PrepareStackTraceCallback) { // asks for the termination and throws before V8 acts on it has V8 act on it in // that callback, the first JS to run after. V8 still threw the hook's error // over the termination, and the module caught it. -TEST_F(Test72HooksKeepTermination, SourceMapCallbackWhileTakingAHookError) { +TEST_F(Test75HooksKeepTermination, SourceMapCallbackWhileTakingAHookError) { EnvScope s(runtime_.get()); InstallHelpers(s.env); ASSERT_EQ(RunScript(s.env, "globalThis.mapped = 0;"), napi_ok); @@ -485,7 +485,7 @@ TEST_F(Test72HooksKeepTermination, SourceMapCallbackWhileTakingAHookError) { // V8 does. V8 rejected the import()'s promise with the null its TryCatch // records for the termination and returned it: the JS that imported ran on, // and the termination was gone once the run returned. -TEST_F(Test72HooksKeepTermination, DefaultDynamicImportHelper) { +TEST_F(Test75HooksKeepTermination, DefaultDynamicImportHelper) { for (const char* setup : {"globalThis.__napi_dynamic_import = (specifier, name) => { terminate(); tick(); };", "Object.defineProperty(globalThis, '__napi_dynamic_import'," @@ -505,7 +505,7 @@ TEST_F(Test72HooksKeepTermination, DefaultDynamicImportHelper) { // them (QuickJS's writes and reads values itself). A `_getDataCloneError` // getter V8 terminated made V8 throw the clone error over the termination, // and the JS that wrote the value caught it. -TEST_F(Test72HooksKeepTermination, SerdesHooks) { +TEST_F(Test75HooksKeepTermination, SerdesHooks) { for (const char* script : { "const s = new serdes.Serializer();\n" "Object.defineProperty(s, '_getDataCloneError', { get() { terminate(); tick(); } });\n" diff --git a/tests/runners/test_73_termination_until_cancelled.cc b/tests/runners/test_76_termination_until_cancelled.cc similarity index 97% rename from tests/runners/test_73_termination_until_cancelled.cc rename to tests/runners/test_76_termination_until_cancelled.cc index 1958cba54d..d5a448f5a3 100644 --- a/tests/runners/test_73_termination_until_cancelled.cc +++ b/tests/runners/test_76_termination_until_cancelled.cc @@ -4,7 +4,7 @@ // catches it, also when native code goes on after a call it failed, cancels // it, or runs where the engine does not look for it. // -// The JS asks for it as test_72's does: a native call that terminates, then +// The JS asks for it as test_75's does: a native call that terminates, then // a call to a JS function, so that V8, which acts on a termination at its // next stack check, acts on it at once. @@ -24,7 +24,7 @@ #include #endif -class Test73TerminationUntilCancelled : public FixtureTestBase {}; +class Test76TerminationUntilCancelled : public FixtureTestBase {}; namespace { @@ -456,7 +456,7 @@ constexpr char kEvaluateModuleInTryCatch[] = // TryCatch records a termination as a null exception, which V8 would // otherwise throw into that JS as a catchable null; QuickJS drops its // uncatchable error at the cancel. -TEST_F(Test73TerminationUntilCancelled, CancelledInsideANativeFunction) { +TEST_F(Test76TerminationUntilCancelled, CancelledInsideANativeFunction) { EnvScope s(runtime_.get()); InstallHelpers(s.env); EXPECT_EQ(RunScript(s.env, @@ -490,7 +490,7 @@ napi_value ThrowTerminateCancel(napi_env env, napi_callback_info /*info*/) { } } // namespace -TEST_F(Test73TerminationUntilCancelled, CancelKeepsAnExceptionThrownBefore) { +TEST_F(Test76TerminationUntilCancelled, CancelKeepsAnExceptionThrownBefore) { EnvScope s(runtime_.get()); InstallHelpers(s.env); DefineGlobalFunction(s.env, "throwTerminateCancel", ThrowTerminateCancel); @@ -505,7 +505,7 @@ TEST_F(Test73TerminationUntilCancelled, CancelKeepsAnExceptionThrownBefore) { // The same inside the import.meta hook, which throws what its callback left // pending from the import.meta expression. -TEST_F(Test73TerminationUntilCancelled, CancelledInsideAModuleHook) { +TEST_F(Test76TerminationUntilCancelled, CancelledInsideAModuleHook) { EnvScope s(runtime_.get()); InstallHelpers(s.env); SetModuleHooks(s.env, nullptr, @@ -531,7 +531,7 @@ TEST_F(Test73TerminationUntilCancelled, CancelledInsideAModuleHook) { // timeout expires too: the termination is not the timeout's to cancel, and // must not come back as the timeout's catchable error. QuickJS has no // timeout, so only the termination stops the script there. -TEST_F(Test73TerminationUntilCancelled, ScriptTimeoutKeepsTheEmbeddersTermination) { +TEST_F(Test76TerminationUntilCancelled, ScriptTimeoutKeepsTheEmbeddersTermination) { EnvScope s(runtime_.get()); InstallHelpers(s.env); g_status = napi_ok; @@ -545,7 +545,7 @@ TEST_F(Test73TerminationUntilCancelled, ScriptTimeoutKeepsTheEmbeddersTerminatio // The run a termination stopped leaves it in effect: the next run fails too // until the termination is cancelled. V8 forgets a termination once the // outermost JS frame has unwound. -TEST_F(Test73TerminationUntilCancelled, TopLevelRunKeepsTheTerminationUntilCancelled) { +TEST_F(Test76TerminationUntilCancelled, TopLevelRunKeepsTheTerminationUntilCancelled) { EnvScope s(runtime_.get()); InstallHelpers(s.env); napi_value mark = Eval(s.env, "() => { afterCall = 'yes'; }"); @@ -563,7 +563,7 @@ TEST_F(Test73TerminationUntilCancelled, TopLevelRunKeepsTheTerminationUntilCance // of the termination. On V8 an N-API call that enters V8 clears the // termination, and the trampoline then threw the null the TryCatch recorded // for it, which the JS caught. -TEST_F(Test73TerminationUntilCancelled, NativeCallsAfterTheTermination) { +TEST_F(Test76TerminationUntilCancelled, NativeCallsAfterTheTermination) { for (int kind = 0; kind < kAfterCallCount; ++kind) { SCOPED_TRACE(kAfterCalls[kind]); EnvScope s(runtime_.get()); @@ -578,7 +578,7 @@ TEST_F(Test73TerminationUntilCancelled, NativeCallsAfterTheTermination) { // Native code whose call into JS a termination failed, and which then makes // an N-API call that runs JS. On V8 the termination is in effect when that // call enters V8, which clears it and runs the JS. -TEST_F(Test73TerminationUntilCancelled, CallsRunningJsAfterTheTermination) { +TEST_F(Test76TerminationUntilCancelled, CallsRunningJsAfterTheTermination) { for (int kind = 0; kind < kJsCallCount; ++kind) { SCOPED_TRACE(kJsCalls[kind]); EnvScope s(runtime_.get()); @@ -624,7 +624,7 @@ constexpr const char* kStoppedCalls[] = { }; constexpr int kStoppedCallCount = sizeof(kStoppedCalls) / sizeof(kStoppedCalls[0]); -TEST_F(Test73TerminationUntilCancelled, CallsTheTerminationStopsLeaveItPending) { +TEST_F(Test76TerminationUntilCancelled, CallsTheTerminationStopsLeaveItPending) { for (int kind = 0; kind < kStoppedCallCount; ++kind) { SCOPED_TRACE(kStoppedCalls[kind]); EnvScope s(runtime_.get()); @@ -675,9 +675,9 @@ TEST_F(Test73TerminationUntilCancelled, CallsTheTerminationStopsLeaveItPending) } } -// The same native code, called from the module hooks test_72 covers: those +// The same native code, called from the module hooks test_75 covers: those // see what the native function threw. -TEST_F(Test73TerminationUntilCancelled, NativeCallsAfterTheTerminationInsideModuleHooks) { +TEST_F(Test76TerminationUntilCancelled, NativeCallsAfterTheTerminationInsideModuleHooks) { { SCOPED_TRACE("import.meta"); EnvScope s(runtime_.get()); @@ -750,7 +750,7 @@ void TerminatingFinalizer(napi_env env, void* /*data*/, void* /*hint*/) { } } // namespace -TEST_F(Test73TerminationUntilCancelled, FinalizerDrainedAtACheckpoint) { +TEST_F(Test76TerminationUntilCancelled, FinalizerDrainedAtACheckpoint) { EnvScope s(runtime_.get()); InstallHelpers(s.env); ASSERT_EQ(RunScript(s.env, "globalThis.markAfterCall = () => { afterCall = 'yes'; };"), @@ -794,7 +794,7 @@ napi_value MarkCleanup(napi_env /*env*/, napi_callback_info /*info*/) { } } // namespace -TEST_F(Test73TerminationUntilCancelled, FinalizationRegistryCleanupAtACheckpoint) { +TEST_F(Test76TerminationUntilCancelled, FinalizationRegistryCleanupAtACheckpoint) { EnvScope s(runtime_.get()); InstallHelpers(s.env); DefineGlobalFunction(s.env, "markCleanup", MarkCleanup); @@ -829,7 +829,7 @@ napi_value TerminateThenCheckpoint(napi_env env, napi_callback_info /*info*/) { } } // namespace -TEST_F(Test73TerminationUntilCancelled, CheckpointAfterTheTermination) { +TEST_F(Test76TerminationUntilCancelled, CheckpointAfterTheTermination) { EnvScope s(runtime_.get()); InstallHelpers(s.env); DefineGlobalFunction(s.env, "terminateThenCheckpoint", TerminateThenCheckpoint); @@ -867,7 +867,7 @@ void ReleaseFinalizer(napi_env env, void* /*data*/, void* /*hint*/) { } } // namespace -TEST_F(Test73TerminationUntilCancelled, TerminationRequestedInsideTheRelease) { +TEST_F(Test76TerminationUntilCancelled, TerminationRequestedInsideTheRelease) { g_release_runs.clear(); { EnvScope s(runtime_.get()); @@ -909,7 +909,7 @@ void ReleaseRunsJs(void* arg) { } } // namespace -TEST_F(Test73TerminationUntilCancelled, ReleaseAfterAnUncancelledTermination) { +TEST_F(Test76TerminationUntilCancelled, ReleaseAfterAnUncancelledTermination) { g_release_result.clear(); { EnvScope s(runtime_.get()); @@ -926,7 +926,7 @@ TEST_F(Test73TerminationUntilCancelled, ReleaseAfterAnUncancelledTermination) { // host-object hook (QuickJS's serdes binding calls none of the serializer's // hooks) and the deprecated context-token assign hook (only V8 accepts the // context-token hooks). -TEST_F(Test73TerminationUntilCancelled, NativeCallsAfterTheTerminationInsideV8Hooks) { +TEST_F(Test76TerminationUntilCancelled, NativeCallsAfterTheTerminationInsideV8Hooks) { { SCOPED_TRACE("prepare-stack-trace callback"); EnvScope s(runtime_.get()); @@ -1001,7 +1001,7 @@ napi_value CreateSandboxRealm(napi_env env, napi_callback_info /*info*/) { return global; } -TEST_F(Test73TerminationUntilCancelled, NativeCallsAfterTheTerminationInsideTheTokenAssignHook) { +TEST_F(Test76TerminationUntilCancelled, NativeCallsAfterTheTerminationInsideTheTokenAssignHook) { EnvScope s(runtime_.get()); InstallHelpers(s.env); AttachTokenHooks(s.env, true); @@ -1022,7 +1022,7 @@ TEST_F(Test73TerminationUntilCancelled, NativeCallsAfterTheTerminationInsideTheT // QuickJS has no counterpart of). No JS called it, so there is none to stop, // and V8 aborts on any JS run there: the provider must run none. The // termination stays in effect. -TEST_F(Test73TerminationUntilCancelled, NativeFunctionCalledFromCppWithJsDisallowed) { +TEST_F(Test76TerminationUntilCancelled, NativeFunctionCalledFromCppWithJsDisallowed) { EnvScope s(runtime_.get()); InstallHelpers(s.env); napi_value terminate = nullptr; @@ -1081,7 +1081,7 @@ void CleanupHookCancelledByAnUnassignHook(void* arg) { } } // namespace -TEST_F(Test73TerminationUntilCancelled, UnassignHookCancelsDuringTheRelease) { +TEST_F(Test76TerminationUntilCancelled, UnassignHookCancelsDuringTheRelease) { g_release_result.clear(); { EnvScope s(runtime_.get()); @@ -1098,7 +1098,7 @@ TEST_F(Test73TerminationUntilCancelled, UnassignHookCancelsDuringTheRelease) { EXPECT_EQ(g_release_result, "ok"); } -TEST_F(Test73TerminationUntilCancelled, CreateRealmAfterATerminatedUnassignHook) { +TEST_F(Test76TerminationUntilCancelled, CreateRealmAfterATerminatedUnassignHook) { for (bool with_sandbox : {true, false}) { SCOPED_TRACE(with_sandbox ? "with a sandbox" : "with a fresh global"); EnvScope s(runtime_.get()); @@ -1148,7 +1148,7 @@ napi_value RequestInterrupt(napi_env env, napi_callback_info /*info*/) { } } // namespace -TEST_F(Test73TerminationUntilCancelled, InterruptCallbackTerminated) { +TEST_F(Test76TerminationUntilCancelled, InterruptCallbackTerminated) { EnvScope s(runtime_.get()); InstallHelpers(s.env); ASSERT_EQ(napi_create_reference(s.env, Eval(s.env, "(() => { terminate(); tick(); })"), 1, From c3a6e57be1ed48fae3d9537f9d456e431521ae60 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Fri, 6 Nov 2026 00:09:10 -0800 Subject: [PATCH 125/150] V8: report a module that is not instantiated as settled in the TLA check unofficial_napi_module_wrap_check_unsettled_top_level_await called v8::Module::IsGraphAsync on any source text module. V8 accepts only an instantiated module there and otherwise stops the process with "Fatal error in v8::Module::IsGraphAsync ... must be used on an instantiated module". So asking about a module that was never instantiated, or only linked, aborted. The bug is older than f928811. A module that is not instantiated has no top-level await under way. The check now reports it settled, with napi_ok and nothing pending. QuickJS already answers that for every module. Node makes this check only at exit, on the entry module, which is instantiated by then. Instantiated modules are unchanged. Test: test_77_module_wrap_state, a new runner for module calls made in the wrong state, on both engines. CheckUnsettledTopLevelAwaitOfAModuleNotInstantiatedIsSettled asks about a module with and without top-level await, first never linked, then linked, then instantiated, and also about a synthetic module. Each answer must be napi_ok, settled, with nothing pending. Before this commit, V8 aborted on the first call (exit 133, "v8::Module::IsGraphAsync must be used on an instantiated module"). QuickJS passed. Co-Authored-By: Claude Opus 5.5 --- tests/CMakeLists.txt | 3 + tests/runners/test_77_module_wrap_state.cc | 130 +++++++++++++++++++++ v8/src/unofficial_napi_contextify.cc | 3 + 3 files changed, 136 insertions(+) create mode 100644 tests/runners/test_77_module_wrap_state.cc diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt index 040107b851..c7ae18e1ce 100644 --- a/tests/CMakeLists.txt +++ b/tests/CMakeLists.txt @@ -347,6 +347,9 @@ add_fixture_test(${_napi_test_prefix}_test_76_termination_until_cancelled runners/test_76_termination_until_cancelled.cc ) target_compile_definitions(${_napi_test_prefix}_test_76_termination_until_cancelled PRIVATE NAPI_VERSION=10) +add_fixture_test(${_napi_test_prefix}_test_77_module_wrap_state + runners/test_77_module_wrap_state.cc +) if(_napi_test_engine STREQUAL "v8") # Only the V8 provider posts engine tasks through the enqueue hook. add_fixture_test(${_napi_test_prefix}_test_66_foreground_task_handoff diff --git a/tests/runners/test_77_module_wrap_state.cc b/tests/runners/test_77_module_wrap_state.cc new file mode 100644 index 0000000000..e6dfda1527 --- /dev/null +++ b/tests/runners/test_77_module_wrap_state.cc @@ -0,0 +1,130 @@ +// The module calls made when the module is not in the state they expect: not +// instantiated yet, or in the middle of its evaluation. Each returns an +// answer or an error. The V8 provider aborted the process on several of them +// (the V8 API checks the state with a fatal ApiCheck or CHECK). +#ifdef NAPI_MODULE +#undef NAPI_MODULE +#endif +#include "node_api.h" + +#include "test_env.h" + +#include "unofficial_napi.h" + +#include + +class Test77ModuleWrapState : public FixtureTestBase {}; + +namespace { + +// Module states, as unofficial_napi_module_wrap_get_state reports them. +constexpr int32_t kUninstantiated = 0; +constexpr int32_t kInstantiated = 2; + +napi_value Str(napi_env env, const char* value) { + napi_value out = nullptr; + if (napi_create_string_utf8(env, value, NAPI_AUTO_LENGTH, &out) != napi_ok) return nullptr; + return out; +} + +unofficial_napi_module CreateSourceTextModule(napi_env env, const char* text) { + napi_value wrapper = nullptr; + napi_value undefined = nullptr; + EXPECT_EQ(napi_create_object(env, &wrapper), napi_ok); + EXPECT_EQ(napi_get_undefined(env, &undefined), napi_ok); + const unofficial_napi_js_source source = unofficial_napi_js_source_from_text(Str(env, text)); + unofficial_napi_module_create_options options{}; + options.size = sizeof(options); + options.version = UNOFFICIAL_NAPI_MODULE_CREATE_OPTIONS_VERSION; + options.kind = unofficial_napi_module_source_text; + options.wrapper = wrapper; + options.url = Str(env, "state.mjs"); + options.payload.source_text.source = &source; + options.payload.source_text.host_defined_option_id = undefined; + unofficial_napi_module_create_result created{}; + EXPECT_EQ(unofficial_napi_module_wrap_create(env, &options, &created), napi_ok); + return created.module; +} + +// `steps` is the source of the evaluation steps function. +unofficial_napi_module CreateSyntheticModule(napi_env env, const char* steps) { + napi_value wrapper = nullptr; + napi_value names = nullptr; + napi_value steps_value = nullptr; + EXPECT_EQ(napi_create_object(env, &wrapper), napi_ok); + EXPECT_EQ(napi_run_script(env, Str(env, "['value']"), &names), napi_ok); + EXPECT_EQ(napi_run_script(env, Str(env, steps), &steps_value), napi_ok); + unofficial_napi_module_create_options options{}; + options.size = sizeof(options); + options.version = UNOFFICIAL_NAPI_MODULE_CREATE_OPTIONS_VERSION; + options.kind = unofficial_napi_module_synthetic; + options.wrapper = wrapper; + options.url = Str(env, "synthetic"); + options.payload.synthetic.export_names = names; + options.payload.synthetic.synthetic_evaluation_steps = steps_value; + unofficial_napi_module_create_result created{}; + EXPECT_EQ(unofficial_napi_module_wrap_create(env, &options, &created), napi_ok); + return created.module; +} + +int32_t Status(napi_env env, unofficial_napi_module module) { + int32_t status = -1; + EXPECT_EQ(unofficial_napi_module_wrap_get_state(env, module, &status, nullptr, nullptr), + napi_ok); + return status; +} + +bool ExceptionPending(napi_env env) { + bool pending = false; + EXPECT_EQ(napi_is_exception_pending(env, &pending), napi_ok); + return pending; +} + +} // namespace + +// A module that is not instantiated has no top-level await under way: the +// check reports it settled, as QuickJS does and as Node's check (made at exit +// on the entry module) would. V8's IsGraphAsync takes an instantiated module +// only, and the V8 provider aborted the process here. +TEST_F(Test77ModuleWrapState, CheckUnsettledTopLevelAwaitOfAModuleNotInstantiatedIsSettled) { + EnvScope s(runtime_.get()); + for (const char* text : {"export const value = 1;", "await 0; export const value = 1;"}) { + SCOPED_TRACE(text); + unofficial_napi_module module = CreateSourceTextModule(s.env, text); + ASSERT_NE(module, nullptr); + for (bool warnings : {false, true}) { + bool settled = false; + EXPECT_EQ(unofficial_napi_module_wrap_check_unsettled_top_level_await( + s.env, module, warnings, &settled), + napi_ok); + EXPECT_TRUE(settled); + EXPECT_FALSE(ExceptionPending(s.env)); + } + // Linked, not instantiated yet. + ASSERT_EQ(unofficial_napi_module_wrap_link(s.env, module, 0, nullptr), napi_ok); + bool settled = false; + EXPECT_EQ(unofficial_napi_module_wrap_check_unsettled_top_level_await( + s.env, module, true, &settled), + napi_ok); + EXPECT_TRUE(settled); + EXPECT_EQ(Status(s.env, module), kUninstantiated); + // Instantiated, not evaluated: nothing is under way either. + ASSERT_EQ(unofficial_napi_module_wrap_instantiate(s.env, module), napi_ok); + settled = false; + EXPECT_EQ(unofficial_napi_module_wrap_check_unsettled_top_level_await( + s.env, module, true, &settled), + napi_ok); + EXPECT_TRUE(settled); + EXPECT_EQ(Status(s.env, module), kInstantiated); + EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, module), napi_ok); + } + + unofficial_napi_module synthetic = CreateSyntheticModule(s.env, "(function() {})"); + ASSERT_NE(synthetic, nullptr); + bool settled = false; + EXPECT_EQ(unofficial_napi_module_wrap_check_unsettled_top_level_await( + s.env, synthetic, true, &settled), + napi_ok); + EXPECT_TRUE(settled); + EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, synthetic), napi_ok); +} diff --git a/v8/src/unofficial_napi_contextify.cc b/v8/src/unofficial_napi_contextify.cc index 683f988d7c..d3897bf9cf 100644 --- a/v8/src/unofficial_napi_contextify.cc +++ b/v8/src/unofficial_napi_contextify.cc @@ -3043,6 +3043,9 @@ napi_status NAPI_CDECL unofficial_napi_module_wrap_check_unsettled_top_level_awa v8::Local module = record->module.Get(isolate); if (!module->IsSourceTextModule()) return napi_ok; + // A module that is not instantiated has no top-level await under way, as + // on QuickJS. IsGraphAsync aborts the process for one. + if (module->GetStatus() < v8::Module::kInstantiated) return napi_ok; if (!module->IsGraphAsync()) return napi_ok; auto stalled_messages = std::get<1>(module->GetStalledTopLevelAwaitMessages(isolate)); From 0aa4c4029057b0c5121da3b2ff5e1ab4122b77db Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Fri, 6 Nov 2026 00:11:07 -0800 Subject: [PATCH 126/150] V8: instantiate a module that is not instantiated before evaluating it unofficial_napi_module_wrap_evaluate and _evaluate_sync called v8::Module::Evaluate whatever the module's state. V8 evaluates only an instantiated module and otherwise stops the process with "Fatal error in Module::Evaluate ... Expected instantiated module". So evaluating a module before instantiating it aborted. The bug is older than f928811. QuickJS's JS_EvaluateModule links an unlinked module first, so on QuickJS such a call already worked. V8 now does the same: both calls instantiate the module first, as unofficial_napi_module_wrap_instantiate would. When that fails, for example on a request the module was not linked for, they return what instantiating returned (the error pending) and the module stays uninstantiated. Instantiated, evaluated and errored modules are unchanged. unofficial_napi_module_wrap_instantiate keeps its termination check first, ahead of the instantiation it now shares. evaluate and evaluate_sync check the termination before instantiating, so a terminating env instantiates nothing. Test: test_77 EvaluatingAModuleNotInstantiatedInstantiatesItFirst, both engines. Through each of evaluate and evaluate_sync, a module with no requests that was never linked must evaluate, run once and reach status 4. A module with a request it was not linked for must give napi_pending_exception with an error pending, stay at status 0 and not run. Before this commit, V8 aborted on the first evaluate (exit 133, "Expected instantiated module"). QuickJS passed. Co-Authored-By: Claude Opus 5.5 --- tests/runners/test_77_module_wrap_state.cc | 91 ++++++++++++++++++++++ v8/src/unofficial_napi_contextify.cc | 30 +++++-- 2 files changed, 115 insertions(+), 6 deletions(-) diff --git a/tests/runners/test_77_module_wrap_state.cc b/tests/runners/test_77_module_wrap_state.cc index e6dfda1527..34abeb974e 100644 --- a/tests/runners/test_77_module_wrap_state.cc +++ b/tests/runners/test_77_module_wrap_state.cc @@ -20,6 +20,7 @@ namespace { // Module states, as unofficial_napi_module_wrap_get_state reports them. constexpr int32_t kUninstantiated = 0; constexpr int32_t kInstantiated = 2; +constexpr int32_t kEvaluated = 4; napi_value Str(napi_env env, const char* value) { napi_value out = nullptr; @@ -80,6 +81,52 @@ bool ExceptionPending(napi_env env) { return pending; } +std::string ValueText(napi_env env, napi_value value) { + napi_value string = nullptr; + char text[256] = {}; + size_t length = 0; + if (value == nullptr || napi_coerce_to_string(env, value, &string) != napi_ok || + napi_get_value_string_utf8(env, string, text, sizeof(text), &length) != napi_ok) { + return ""; + } + return std::string(text, length); +} + +std::string RunText(napi_env env, const char* source) { + napi_value result = nullptr; + if (napi_run_script(env, Str(env, source), &result) != napi_ok) return ""; + return ValueText(env, result); +} + +// Takes the pending exception: its message, or "" when none was pending. +std::string TakePendingMessage(napi_env env) { + if (!ExceptionPending(env)) return ""; + napi_value error = nullptr; + napi_value message = nullptr; + if (napi_get_and_clear_last_exception(env, &error) != napi_ok) return ""; + if (napi_get_named_property(env, error, "message", &message) != napi_ok) return ""; + return ValueText(env, message); +} + +// How `promise` settles once the microtasks have run: "resolved", or +// "rejected: ". +std::string PromiseOutcome(napi_env env, napi_value promise) { + napi_value global = nullptr; + if (promise == nullptr || napi_get_global(env, &global) != napi_ok || + napi_set_named_property(env, global, "settling", promise) != napi_ok) { + return ""; + } + RunText(env, + "globalThis.outcome = 'pending';" + "Promise.resolve(settling).then(() => { outcome = 'resolved'; }," + " (e) => { outcome = 'rejected: ' + (e && e.message); });" + "0"); + EXPECT_EQ(unofficial_napi_event_loop_checkpoint( + env, unofficial_napi_event_loop_checkpoint_microtasks, true, nullptr), + napi_ok); + return RunText(env, "outcome"); +} + } // namespace // A module that is not instantiated has no top-level await under way: the @@ -128,3 +175,47 @@ TEST_F(Test77ModuleWrapState, CheckUnsettledTopLevelAwaitOfAModuleNotInstantiate EXPECT_TRUE(settled); EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, synthetic), napi_ok); } + +// Evaluating a module that is not instantiated instantiates it first, as +// QuickJS's JS_EvaluateModule does: with nothing to link it to, the module +// runs; with a request it was not linked for, the evaluation fails as +// instantiating it does and the module stays uninstantiated. V8's Evaluate +// takes an instantiated module only, and the V8 provider aborted the process +// here. +TEST_F(Test77ModuleWrapState, EvaluatingAModuleNotInstantiatedInstantiatesItFirst) { + EnvScope s(runtime_.get()); + for (bool sync : {false, true}) { + SCOPED_TRACE(sync ? "evaluate_sync" : "evaluate"); + ASSERT_EQ(RunText(s.env, "globalThis.runs = 0"), "0"); + unofficial_napi_module module = CreateSourceTextModule( + s.env, "globalThis.runs++; export const value = 42;"); + ASSERT_NE(module, nullptr); + napi_value result = nullptr; + if (sync) { + ASSERT_EQ(unofficial_napi_module_wrap_evaluate_sync(s.env, module, nullptr, nullptr, &result), + napi_ok); + napi_value value = nullptr; + ASSERT_EQ(napi_get_named_property(s.env, result, "value", &value), napi_ok); + EXPECT_EQ(ValueText(s.env, value), "42"); + } else { + ASSERT_EQ(unofficial_napi_module_wrap_evaluate(s.env, module, -1, false, &result), napi_ok); + EXPECT_EQ(PromiseOutcome(s.env, result), "resolved"); + } + EXPECT_EQ(Status(s.env, module), kEvaluated); + EXPECT_EQ(RunText(s.env, "runs"), "1"); + EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, module), napi_ok); + + unofficial_napi_module unlinked = CreateSourceTextModule( + s.env, "import 'missing'; globalThis.runs++;"); + ASSERT_NE(unlinked, nullptr); + result = nullptr; + const napi_status status = + sync ? unofficial_napi_module_wrap_evaluate_sync(s.env, unlinked, nullptr, nullptr, &result) + : unofficial_napi_module_wrap_evaluate(s.env, unlinked, -1, false, &result); + EXPECT_EQ(status, napi_pending_exception); + EXPECT_NE(TakePendingMessage(s.env), ""); + EXPECT_EQ(Status(s.env, unlinked), kUninstantiated); + EXPECT_EQ(RunText(s.env, "runs"), "1"); + EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, unlinked), napi_ok); + } +} diff --git a/v8/src/unofficial_napi_contextify.cc b/v8/src/unofficial_napi_contextify.cc index d3897bf9cf..cf8a58aa4e 100644 --- a/v8/src/unofficial_napi_contextify.cc +++ b/v8/src/unofficial_napi_contextify.cc @@ -2859,12 +2859,8 @@ napi_status NAPI_CDECL unofficial_napi_module_wrap_link( return napi_ok; } -napi_status NAPI_CDECL unofficial_napi_module_wrap_instantiate( - napi_env env, - unofficial_napi_module module_handle) { - if (env == nullptr || module_handle == nullptr) return napi_invalid_arg; - NAPI_V8_RETURN_IF_TERMINATING(env); - ModuleWrapRecord* record = ModuleRecord(module_handle); +// Instantiates the module and the modules it was linked to. +static napi_status InstantiateModuleRecord(napi_env env, ModuleWrapRecord* record) { v8::Isolate* isolate = env->isolate; v8::HandleScope handle_scope(isolate); v8::Local context = record->context.Get(isolate); @@ -2881,6 +2877,24 @@ napi_status NAPI_CDECL unofficial_napi_module_wrap_instantiate( return napi_ok; } +napi_status NAPI_CDECL unofficial_napi_module_wrap_instantiate( + napi_env env, + unofficial_napi_module module_handle) { + if (env == nullptr || module_handle == nullptr) return napi_invalid_arg; + NAPI_V8_RETURN_IF_TERMINATING(env); + return InstantiateModuleRecord(env, ModuleRecord(module_handle)); +} + +// V8 evaluates only an instantiated module and aborts the process for one +// that is not. Instantiate it first, as QuickJS's JS_EvaluateModule does. +static napi_status InstantiateForEvaluation(napi_env env, ModuleWrapRecord* record) { + v8::HandleScope handle_scope(env->isolate); + if (record->module.Get(env->isolate)->GetStatus() >= v8::Module::kInstantiated) { + return napi_ok; + } + return InstantiateModuleRecord(env, record); +} + napi_status NAPI_CDECL unofficial_napi_module_wrap_evaluate( napi_env env, unofficial_napi_module module_handle, @@ -2890,6 +2904,8 @@ napi_status NAPI_CDECL unofficial_napi_module_wrap_evaluate( if (env == nullptr || module_handle == nullptr || result_out == nullptr) return napi_invalid_arg; NAPI_V8_RETURN_IF_TERMINATING(env); ModuleWrapRecord* record = ModuleRecord(module_handle); + const napi_status instantiated = InstantiateForEvaluation(env, record); + if (instantiated != napi_ok) return instantiated; v8::Isolate* isolate = env->isolate; v8::EscapableHandleScope handle_scope(isolate); v8::Local context = record->context.Get(isolate); @@ -2918,6 +2934,8 @@ napi_status NAPI_CDECL unofficial_napi_module_wrap_evaluate_sync( *result_out = nullptr; ModuleWrapRecord* record = ModuleRecord(module_handle); + const napi_status instantiated = InstantiateForEvaluation(env, record); + if (instantiated != napi_ok) return instantiated; v8::Isolate* isolate = env->isolate; v8::EscapableHandleScope handle_scope(isolate); v8::Local context = record->context.Get(isolate); From f6238674b6d97677540c3da26a7d62618c945ff1 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Fri, 6 Nov 2026 00:14:23 -0800 Subject: [PATCH 127/150] Refuse to evaluate a module while its evaluation runs, on both engines A module's own body, or a synthetic module's evaluation steps, can call native code that evaluates the same module again: through unofficial_napi_module_wrap_evaluate, _evaluate_sync, or _create_required_module_facade, which evaluates the module it wraps. - V8 stopped the process with "Check failed: module_status == kLinked || module_status == kEvaluatingAsync || module_status == kEvaluated" (a CHECK in Module::Evaluate). For a source text module, only the facade got through. - QuickJS gave evaluate the module's unsettled promise. evaluate_sync failed with ERR_REQUIRE_ASYNC_MODULE. The facade over a source text module crashed with SIGSEGV in js_inner_module_evaluation. js_evaluate_module asserts that the module is not evaluating; that assert is compiled out of release builds. All three calls now refuse such a module on both engines. They throw an Error with code ERR_VM_MODULE_STATUS ("Module status must not be evaluating") and return napi_pending_exception. Node's vm refuses a module whose status is "evaluating" with the same code. The evaluation already under way goes on. The bugs are older than f928811. Test: test_77 EvaluatingAModuleWhileItEvaluatesIsRefused, both engines. A source text module's body, and then a synthetic module's steps, call a native function. That function makes one of the three calls on the same module and takes what it left pending. Each call must see status 3, return napi_pending_exception with that code and message, and the outer evaluation must resolve with the module run to its end (status 4). Before this commit, V8 aborted on the first case (exit 133, the CHECK above). QuickJS failed the source text cases: evaluate returned napi_ok, evaluate_sync returned ERR_REQUIRE_ASYNC_MODULE, and the facade crashed (exit 139). Co-Authored-By: Claude Opus 5.5 --- quickjs/src/internal/napi_module_wrap.cc | 18 ++++ quickjs/src/internal/napi_module_wrap.h | 1 + tests/runners/test_77_module_wrap_state.cc | 109 +++++++++++++++++++++ v8/src/unofficial_napi_contextify.cc | 17 ++++ 4 files changed, 145 insertions(+) diff --git a/quickjs/src/internal/napi_module_wrap.cc b/quickjs/src/internal/napi_module_wrap.cc index e368b4d163..667becc39c 100644 --- a/quickjs/src/internal/napi_module_wrap.cc +++ b/quickjs/src/internal/napi_module_wrap.cc @@ -692,9 +692,23 @@ napi_status napi_module_wrap__::instantiate(unofficial_napi_module module) return napi_ok; } +// Evaluating a module whose evaluation is under way (from its own body or a +// synthetic module's steps) is refused, as on V8 and in Node's vm for a +// module whose status is "evaluating". js_evaluate_module asserts against it, +// and the facade's evaluation crashed on it. +napi_status napi_module_wrap__::throw_if_evaluating(record *entry) +{ + if (JS_GetModuleStatus(ctx_, entry->module) != JS_MODULE_STATUS_EVALUATING) + return napi_ok; + return throw_error("ERR_VM_MODULE_STATUS", "Module status must not be evaluating"); +} + napi_status napi_module_wrap__::evaluate_unless_terminated(record *entry, JSValue *promise_out) { napi_status status = napi_util__::fail_if_terminating(env_, ctx_); + if (status != napi_ok) + return status; + status = throw_if_evaluating(entry); if (status != napi_ok) return status; // The module evaluates in its realm. @@ -1029,6 +1043,10 @@ 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_); + // The facade evaluates the module it wraps. + napi_status status = throw_if_evaluating(entry); + if (status != napi_ok) + return status; JSContext *ctx = entry->ctx; std::string filename = ": ", or "" when none was +// pending. +std::string TakePendingCodeAndMessage(napi_env env) { + if (!ExceptionPending(env)) return ""; + napi_value error = nullptr; + napi_value code = nullptr; + napi_value message = nullptr; + if (napi_get_and_clear_last_exception(env, &error) != napi_ok) return ""; + if (napi_get_named_property(env, error, "code", &code) != napi_ok || + napi_get_named_property(env, error, "message", &message) != napi_ok) { + return ""; + } + return ValueText(env, code) + ": " + ValueText(env, message); +} + +enum class Reentry { kEvaluate, kEvaluateSync, kFacade }; + +struct ReentryProbe { + Reentry call = Reentry::kEvaluate; + unofficial_napi_module module = nullptr; + int calls = 0; + int32_t status_inside = -1; + napi_status status = napi_ok; + std::string pending; +}; + +// Evaluates the probe's module from inside its own evaluation, and takes +// what that left pending so that the evaluation goes on. +napi_value EvaluateAgain(napi_env env, napi_callback_info info) { + void* data = nullptr; + EXPECT_EQ(napi_get_cb_info(env, info, nullptr, nullptr, nullptr, &data), napi_ok); + auto* probe = static_cast(data); + probe->calls++; + probe->status_inside = Status(env, probe->module); + napi_value result = nullptr; + switch (probe->call) { + case Reentry::kEvaluate: + probe->status = unofficial_napi_module_wrap_evaluate(env, probe->module, -1, false, &result); + break; + case Reentry::kEvaluateSync: + probe->status = unofficial_napi_module_wrap_evaluate_sync( + env, probe->module, nullptr, nullptr, &result); + break; + case Reentry::kFacade: + probe->status = unofficial_napi_module_wrap_create_required_module_facade( + env, probe->module, &result); + break; + } + probe->pending = TakePendingCodeAndMessage(env); + return nullptr; +} + +} // namespace + +// Evaluating a module from inside its own evaluation (its body, or a +// synthetic module's steps) is refused with ERR_VM_MODULE_STATUS, as Node's +// vm refuses a module whose status is "evaluating", and the evaluation under +// way goes on. The same holds for the require() facade, which evaluates the +// module it wraps. V8 aborted the process (a CHECK in Module::Evaluate). +// QuickJS gave the evaluation's promise, unsettled, to evaluate, failed +// evaluate_sync with ERR_REQUIRE_ASYNC_MODULE, and made the facade over +// bindings the body had not reached yet. +TEST_F(Test77ModuleWrapState, EvaluatingAModuleWhileItEvaluatesIsRefused) { + for (bool synthetic : {false, true}) { + for (Reentry call : {Reentry::kEvaluate, Reentry::kEvaluateSync, Reentry::kFacade}) { + SCOPED_TRACE(std::string(synthetic ? "synthetic, " : "source text, ") + + (call == Reentry::kEvaluate ? "evaluate" + : call == Reentry::kEvaluateSync ? "evaluate_sync" + : "facade")); + EnvScope s(runtime_.get()); + ReentryProbe probe; + probe.call = call; + napi_value fn = nullptr; + napi_value global = nullptr; + ASSERT_EQ(napi_create_function(s.env, "evaluateAgain", NAPI_AUTO_LENGTH, EvaluateAgain, + &probe, &fn), + napi_ok); + ASSERT_EQ(napi_get_global(s.env, &global), napi_ok); + ASSERT_EQ(napi_set_named_property(s.env, global, "evaluateAgain", fn), napi_ok); + ASSERT_EQ(RunText(s.env, "globalThis.after = 'no'"), "no"); + probe.module = + synthetic ? CreateSyntheticModule( + s.env, "(function() { evaluateAgain(); globalThis.after = 'yes'; })") + : CreateSourceTextModule(s.env, + "evaluateAgain(); globalThis.after = 'yes';\n" + "export default 1;"); + ASSERT_NE(probe.module, nullptr); + ASSERT_EQ(unofficial_napi_module_wrap_link(s.env, probe.module, 0, nullptr), napi_ok); + ASSERT_EQ(unofficial_napi_module_wrap_instantiate(s.env, probe.module), napi_ok); + + napi_value promise = nullptr; + ASSERT_EQ(unofficial_napi_module_wrap_evaluate(s.env, probe.module, -1, false, &promise), + napi_ok); + EXPECT_EQ(probe.calls, 1); + EXPECT_EQ(probe.status_inside, kEvaluating); + EXPECT_EQ(probe.status, napi_pending_exception); + EXPECT_EQ(probe.pending, "ERR_VM_MODULE_STATUS: Module status must not be evaluating"); + EXPECT_EQ(PromiseOutcome(s.env, promise), "resolved"); + EXPECT_EQ(RunText(s.env, "after"), "yes"); + EXPECT_EQ(Status(s.env, probe.module), kEvaluated); + EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, probe.module), napi_ok); + } + } +} diff --git a/v8/src/unofficial_napi_contextify.cc b/v8/src/unofficial_napi_contextify.cc index cf8a58aa4e..d035048333 100644 --- a/v8/src/unofficial_napi_contextify.cc +++ b/v8/src/unofficial_napi_contextify.cc @@ -2885,6 +2885,19 @@ napi_status NAPI_CDECL unofficial_napi_module_wrap_instantiate( return InstantiateModuleRecord(env, ModuleRecord(module_handle)); } +// Evaluating a module whose evaluation is under way (from its own body or a +// synthetic module's steps) is refused, as Node's vm refuses a module whose +// status is "evaluating". V8 aborts the process for it (a CHECK in +// Module::Evaluate). +static bool ThrowIfEvaluating(napi_env env, ModuleWrapRecord* record) { + v8::HandleScope handle_scope(env->isolate); + if (record->module.Get(env->isolate)->GetStatus() != v8::Module::kEvaluating) { + return false; + } + ThrowCodeError(env, "ERR_VM_MODULE_STATUS", "Module status must not be evaluating"); + return true; +} + // V8 evaluates only an instantiated module and aborts the process for one // that is not. Instantiate it first, as QuickJS's JS_EvaluateModule does. static napi_status InstantiateForEvaluation(napi_env env, ModuleWrapRecord* record) { @@ -2904,6 +2917,7 @@ napi_status NAPI_CDECL unofficial_napi_module_wrap_evaluate( if (env == nullptr || module_handle == nullptr || result_out == nullptr) return napi_invalid_arg; NAPI_V8_RETURN_IF_TERMINATING(env); ModuleWrapRecord* record = ModuleRecord(module_handle); + if (ThrowIfEvaluating(env, record)) return napi_pending_exception; const napi_status instantiated = InstantiateForEvaluation(env, record); if (instantiated != napi_ok) return instantiated; v8::Isolate* isolate = env->isolate; @@ -2934,6 +2948,7 @@ napi_status NAPI_CDECL unofficial_napi_module_wrap_evaluate_sync( *result_out = nullptr; ModuleWrapRecord* record = ModuleRecord(module_handle); + if (ThrowIfEvaluating(env, record)) return napi_pending_exception; const napi_status instantiated = InstantiateForEvaluation(env, record); if (instantiated != napi_ok) return instantiated; v8::Isolate* isolate = env->isolate; @@ -3188,6 +3203,8 @@ napi_status NAPI_CDECL unofficial_napi_module_wrap_create_required_module_facade if (env == nullptr || module == nullptr || result_out == nullptr) return napi_invalid_arg; NAPI_V8_RETURN_IF_TERMINATING(env); ModuleWrapRecord* record = ModuleRecord(module); + // The facade evaluates the module it wraps. + if (ThrowIfEvaluating(env, record)) return napi_pending_exception; v8::Isolate* isolate = env->isolate; v8::EscapableHandleScope handle_scope(isolate); v8::Local context = env->context(); From 128bd38ade6c02aae84e09cbda286ba67ba320a1 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Fri, 6 Nov 2026 00:16:31 -0800 Subject: [PATCH 128/150] V8: start no module instantiation while one runs V8 runs no script while it instantiates a module graph, with one exception: when a request does not resolve. Then ModuleResolveCallback throws ERR_VM_MODULE_LINK_FAILURE, and the error gets its `code` with a plain set, as Node does, which runs an inherited `code` setter. From that setter, script could reach the module calls again while V8 still held the graph half prepared: - unofficial_napi_module_wrap_instantiate on that module or any other, and _create_required_module_facade, crashed with SIGBUS. A second instantiation walked modules the first had not finished. - _evaluate and _evaluate_sync on that module (whose status is still uninstantiated) aborted before "V8: instantiate a module that is not instantiated before evaluating it" ("Expected instantiated module"). Since that commit they instantiate first, so they would crash the same way. These calls now throw ERR_VM_MODULE_LINK_FAILURE ("A module instantiation is under way") and return napi_pending_exception while an instantiation runs for the env. evaluate and evaluate_sync do this only for a module they would have to instantiate. The provider counts instantiations per env in its module state, around InstantiateModule in both instantiate and the facade. The calls that only ask questions already answered: check_unsettled_top_level_await says settled (since "V8: report a module that is not instantiated as settled in the TLA check") and get_namespace throws ERR_MODULE_NOT_INSTANTIATED. QuickJS runs no script while it links: it reports an unresolved request through its own loader, with an error that has no code. The bug is older than f928811. Test: test_77 NoInstantiationStartsWhileOneRuns, both engines. Error.prototype gets a `code` setter that calls a native function once. That function makes each call on the module being instantiated (instantiate, evaluate, evaluate_sync, facade, check, namespace) and instantiate on another module, and records what each returned and threw. Instantiating a module whose request was never linked must then fail with an error pending. On V8 the setter must have run, and the records must be the refusal above for the five instantiating calls, "settled" for the check and ERR_MODULE_NOT_INSTANTIATED for the namespace. That check is guarded to V8, because only V8 runs the setter there. Both modules must stay at status 0. Once linked properly they must instantiate. Before this commit, V8 crashed on the first call (exit 138, SIGBUS). QuickJS passed. Co-Authored-By: Claude Opus 5.5 --- tests/runners/test_77_module_wrap_state.cc | 117 +++++++++++++++++++++ v8/src/unofficial_napi_contextify.cc | 41 +++++++- 2 files changed, 157 insertions(+), 1 deletion(-) diff --git a/tests/runners/test_77_module_wrap_state.cc b/tests/runners/test_77_module_wrap_state.cc index 89acbdfefb..a6f354048b 100644 --- a/tests/runners/test_77_module_wrap_state.cc +++ b/tests/runners/test_77_module_wrap_state.cc @@ -12,6 +12,7 @@ #include "unofficial_napi.h" #include +#include class Test77ModuleWrapState : public FixtureTestBase {}; @@ -328,3 +329,119 @@ TEST_F(Test77ModuleWrapState, EvaluatingAModuleWhileItEvaluatesIsRefused) { } } } + +namespace { + +struct InstantiationProbe { + unofficial_napi_module module = nullptr; + unofficial_napi_module other = nullptr; + bool entered = false; + std::vector outcomes; +}; + +std::string Outcome(napi_env env, napi_status status) { + const std::string pending = TakePendingCodeAndMessage(env); + return std::to_string(status) + (pending.empty() ? "" : " " + pending); +} + +// Makes the calls that would start an instantiation, and two that would not, +// on the module being instantiated and on another one; records what each +// returned and threw. +napi_value CallsDuringInstantiation(napi_env env, napi_callback_info info) { + void* data = nullptr; + EXPECT_EQ(napi_get_cb_info(env, info, nullptr, nullptr, nullptr, &data), napi_ok); + auto* probe = static_cast(data); + // The errors thrown below run the setter too. + if (probe->entered) return nullptr; + probe->entered = true; + napi_value result = nullptr; + bool settled = false; + auto& out = probe->outcomes; + out.push_back("instantiate " + + Outcome(env, unofficial_napi_module_wrap_instantiate(env, probe->module))); + out.push_back("instantiate other " + + Outcome(env, unofficial_napi_module_wrap_instantiate(env, probe->other))); + out.push_back("evaluate " + Outcome(env, unofficial_napi_module_wrap_evaluate( + env, probe->module, -1, false, &result))); + out.push_back("evaluate_sync " + Outcome(env, unofficial_napi_module_wrap_evaluate_sync( + env, probe->module, nullptr, nullptr, &result))); + out.push_back("facade " + Outcome(env, unofficial_napi_module_wrap_create_required_module_facade( + env, probe->module, &result))); + out.push_back("check " + Outcome(env, unofficial_napi_module_wrap_check_unsettled_top_level_await( + env, probe->module, true, &settled)) + + (settled ? " settled" : " unsettled")); + out.push_back("namespace " + + Outcome(env, unofficial_napi_module_wrap_get_namespace(env, probe->module, &result))); + return nullptr; +} + +} // namespace + +// No instantiation starts while one runs: instantiate, and evaluate or the +// facade on a module that is not instantiated, are refused with +// ERR_VM_MODULE_LINK_FAILURE. V8 runs script in the middle of an +// instantiation when a request does not resolve: the error it throws gets its +// `code` with a plain set, which runs an inherited setter. A second +// instantiation from there walked modules the first had only half prepared: +// instantiate and the facade crashed (SIGBUS), and evaluate aborted +// ("Expected instantiated module"). The asking calls answer as usual, and the +// failed instantiation leaves the module ready to link and instantiate. +TEST_F(Test77ModuleWrapState, NoInstantiationStartsWhileOneRuns) { + EnvScope s(runtime_.get()); + InstantiationProbe probe; + napi_value fn = nullptr; + napi_value global = nullptr; + ASSERT_EQ(napi_create_function(s.env, "callsDuringInstantiation", NAPI_AUTO_LENGTH, + CallsDuringInstantiation, &probe, &fn), + napi_ok); + ASSERT_EQ(napi_get_global(s.env, &global), napi_ok); + ASSERT_EQ(napi_set_named_property(s.env, global, "callsDuringInstantiation", fn), napi_ok); + ASSERT_EQ(RunText(s.env, + "Object.defineProperty(Error.prototype, 'code', {" + " configurable: true," + " set(value) {" + " callsDuringInstantiation();" + " Object.defineProperty(this, 'code', {" + " value, writable: true, configurable: true });" + " }," + "}); 'set'"), + "set"); + probe.module = CreateSourceTextModule(s.env, "import 'dependency'; export default 1;"); + probe.other = CreateSourceTextModule(s.env, "export const value = 1;"); + ASSERT_NE(probe.module, nullptr); + ASSERT_NE(probe.other, nullptr); + + // Not linked: the request does not resolve. + EXPECT_EQ(unofficial_napi_module_wrap_instantiate(s.env, probe.module), napi_pending_exception); + EXPECT_NE(TakePendingMessage(s.env), ""); +#if defined(NAPI_TEST_ENGINE_V8) + // QuickJS reports the request through its own loader, an error with no + // code, so no setter runs while it instantiates. + EXPECT_TRUE(probe.entered); +#endif + if (probe.entered) { + const std::string refused = + "10 ERR_VM_MODULE_LINK_FAILURE: A module instantiation is under way"; + EXPECT_EQ(probe.outcomes, (std::vector{ + "instantiate " + refused, + "instantiate other " + refused, + "evaluate " + refused, + "evaluate_sync " + refused, + "facade " + refused, + "check 0 settled", + "namespace 10 ERR_MODULE_NOT_INSTANTIATED: " + "Module is not instantiated", + })); + } + EXPECT_EQ(Status(s.env, probe.module), kUninstantiated); + EXPECT_EQ(Status(s.env, probe.other), kUninstantiated); + + ASSERT_EQ(RunText(s.env, "delete Error.prototype.code; 'gone'"), "gone"); + ASSERT_EQ(unofficial_napi_module_wrap_link(s.env, probe.other, 0, nullptr), napi_ok); + ASSERT_EQ(unofficial_napi_module_wrap_link(s.env, probe.module, 1, &probe.other), napi_ok); + ASSERT_EQ(unofficial_napi_module_wrap_instantiate(s.env, probe.module), napi_ok); + EXPECT_EQ(Status(s.env, probe.module), kInstantiated); + EXPECT_EQ(Status(s.env, probe.other), kInstantiated); + EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, probe.module), napi_ok); + EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, probe.other), napi_ok); +} diff --git a/v8/src/unofficial_napi_contextify.cc b/v8/src/unofficial_napi_contextify.cc index d035048333..dfdcab9f55 100644 --- a/v8/src/unofficial_napi_contextify.cc +++ b/v8/src/unofficial_napi_contextify.cc @@ -83,6 +83,8 @@ struct ModuleWrapBindingState { std::vector modules; std::vector pending_dynamic_imports; ModuleWrapRecord* temporary_required_module_facade_original = nullptr; + // Instantiations running (see InstantiationScope). + int instantiations = 0; }; napi_value GetSymbolsBindingProperty(napi_env env, const char* property_name); @@ -2859,8 +2861,38 @@ napi_status NAPI_CDECL unofficial_napi_module_wrap_link( return napi_ok; } +// Counts an instantiation as running for its env while it lives. V8 runs no +// script while it instantiates, except when a request does not resolve: the +// error ModuleResolveCallback throws then gets its `code` with a plain set, +// which runs an inherited setter, and from there script can reach these calls +// again. A second instantiation would walk modules the first has only half +// prepared (a crash), so none starts while one runs. +class InstantiationScope { + public: + explicit InstantiationScope(napi_env env) : state_(GetModuleWrapState(env)) { + if (state_ != nullptr) state_->instantiations++; + } + ~InstantiationScope() { + if (state_ != nullptr) state_->instantiations--; + } + InstantiationScope(const InstantiationScope&) = delete; + InstantiationScope& operator=(const InstantiationScope&) = delete; + + // Throws and returns true when an instantiation runs for `env`. + static bool ThrowIfRunning(napi_env env) { + auto* state = GetModuleWrapState(env); + if (state == nullptr || state->instantiations == 0) return false; + ThrowCodeError(env, "ERR_VM_MODULE_LINK_FAILURE", "A module instantiation is under way"); + return true; + } + + private: + ModuleWrapBindingState* state_; +}; + // Instantiates the module and the modules it was linked to. static napi_status InstantiateModuleRecord(napi_env env, ModuleWrapRecord* record) { + if (InstantiationScope::ThrowIfRunning(env)) return napi_pending_exception; v8::Isolate* isolate = env->isolate; v8::HandleScope handle_scope(isolate); v8::Local context = record->context.Get(isolate); @@ -2868,6 +2900,7 @@ static napi_status InstantiateModuleRecord(napi_env env, ModuleWrapRecord* recor v8::Local module = record->module.Get(isolate); v8::TryCatch try_catch(isolate); + InstantiationScope instantiating(env); auto maybe = module->InstantiateModule(context, ModuleResolveCallback, ModuleResolveSourceCallback); if (maybe.IsNothing()) { // A termination too: it stays, and is what the call fails with. @@ -3205,6 +3238,8 @@ napi_status NAPI_CDECL unofficial_napi_module_wrap_create_required_module_facade ModuleWrapRecord* record = ModuleRecord(module); // The facade evaluates the module it wraps. if (ThrowIfEvaluating(env, record)) return napi_pending_exception; + // Instantiating the facade instantiates that module too. + if (InstantiationScope::ThrowIfRunning(env)) return napi_pending_exception; v8::Isolate* isolate = env->isolate; v8::EscapableHandleScope handle_scope(isolate); v8::Local context = env->context(); @@ -3231,7 +3266,11 @@ napi_status NAPI_CDECL unofficial_napi_module_wrap_create_required_module_facade std::lock_guard lock(g_module_wrap_mu); GetModuleWrapStateLocked(env)->temporary_required_module_facade_original = record; } - const bool instantiated = facade->InstantiateModule(context, LinkRequiredFacadeOriginal).FromMaybe(false); + bool instantiated = false; + { + InstantiationScope instantiating(env); + instantiated = facade->InstantiateModule(context, LinkRequiredFacadeOriginal).FromMaybe(false); + } { std::lock_guard lock(g_module_wrap_mu); GetModuleWrapStateLocked(env)->temporary_required_module_facade_original = nullptr; From bc10bce1d2c6ea85131848ffbb34e7a0d622d99a Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Fri, 6 Nov 2026 00:18:09 -0800 Subject: [PATCH 129/150] Take only synthetic modules in set_export, on both engines unofficial_napi_module_wrap_set_export sets an export of a synthetic module from its evaluation steps. Given a source text module: - V8 stopped the process with "Fatal error in v8::Module::SyntheticModuleSetExport ... must only be called on a SyntheticModule". - QuickJS crashed with SIGSEGV before the module was instantiated: the export's variable reference does not exist yet. After that, JS_SetModuleExport overwrote the module's own binding. A probe set `export let value = 1` to "two" from outside the module. Both engines now return napi_invalid_arg with nothing pending for any module that is not synthetic, as the host-JS provider does. Synthetic modules are unchanged. The bug is older than f928811. Test: test_77 SetExportTakesOnlySyntheticModules, both engines. set_export on a source text module, with an export's name and with an unknown name, must return napi_invalid_arg with nothing pending. This holds before the module is linked and again after it is evaluated, and then the namespace's `value` must still be "one". Before this commit, V8 aborted on the first call (exit 133, the message above), and QuickJS crashed on it (exit 139). Co-Authored-By: Claude Opus 5.5 --- quickjs/src/internal/napi_module_wrap.cc | 4 ++- tests/runners/test_77_module_wrap_state.cc | 36 ++++++++++++++++++++++ v8/src/unofficial_napi_contextify.cc | 4 +++ 3 files changed, 43 insertions(+), 1 deletion(-) diff --git a/quickjs/src/internal/napi_module_wrap.cc b/quickjs/src/internal/napi_module_wrap.cc index 667becc39c..1f6175884f 100644 --- a/quickjs/src/internal/napi_module_wrap.cc +++ b/quickjs/src/internal/napi_module_wrap.cc @@ -865,7 +865,9 @@ napi_status napi_module_wrap__::set_export(unofficial_napi_module module, napi_value export_value) { record *entry = find(module); - if (entry == nullptr || + // Only a synthetic module has exports to set. JS_SetModuleExport would set + // a source text module's own binding. + if (entry == nullptr || !entry->synthetic || !napi_util__::check_value(env_, export_name) || !napi_util__::check_value(env_, export_value)) return napi_util__::invalid_arg(env_); diff --git a/tests/runners/test_77_module_wrap_state.cc b/tests/runners/test_77_module_wrap_state.cc index a6f354048b..161b4a29ec 100644 --- a/tests/runners/test_77_module_wrap_state.cc +++ b/tests/runners/test_77_module_wrap_state.cc @@ -445,3 +445,39 @@ TEST_F(Test77ModuleWrapState, NoInstantiationStartsWhileOneRuns) { EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, probe.module), napi_ok); EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, probe.other), napi_ok); } + +// set_export sets a synthetic module's export and takes no other module: for +// a source text module it returns napi_invalid_arg, as the host-JS provider +// does, and the module's exports stay its own. V8 aborted the process (an +// ApiCheck in SetSyntheticModuleExport). QuickJS crashed before the module +// was instantiated, and after that overwrote the module's binding. +TEST_F(Test77ModuleWrapState, SetExportTakesOnlySyntheticModules) { + EnvScope s(runtime_.get()); + unofficial_napi_module module = CreateSourceTextModule(s.env, "export let value = 'one';"); + ASSERT_NE(module, nullptr); + for (const char* name : {"value", "missing"}) { + SCOPED_TRACE(name); + EXPECT_EQ(unofficial_napi_module_wrap_set_export(s.env, module, Str(s.env, name), + Str(s.env, "two")), + napi_invalid_arg); + EXPECT_FALSE(ExceptionPending(s.env)); + } + ASSERT_EQ(unofficial_napi_module_wrap_link(s.env, module, 0, nullptr), napi_ok); + ASSERT_EQ(unofficial_napi_module_wrap_instantiate(s.env, module), napi_ok); + napi_value promise = nullptr; + ASSERT_EQ(unofficial_napi_module_wrap_evaluate(s.env, module, -1, false, &promise), napi_ok); + EXPECT_EQ(PromiseOutcome(s.env, promise), "resolved"); + for (const char* name : {"value", "missing"}) { + SCOPED_TRACE(name); + EXPECT_EQ(unofficial_napi_module_wrap_set_export(s.env, module, Str(s.env, name), + Str(s.env, "two")), + napi_invalid_arg); + EXPECT_FALSE(ExceptionPending(s.env)); + } + napi_value ns = nullptr; + napi_value value = nullptr; + ASSERT_EQ(unofficial_napi_module_wrap_get_namespace(s.env, module, &ns), napi_ok); + ASSERT_EQ(napi_get_named_property(s.env, ns, "value", &value), napi_ok); + EXPECT_EQ(ValueText(s.env, value), "one"); + EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, module), napi_ok); +} diff --git a/v8/src/unofficial_napi_contextify.cc b/v8/src/unofficial_napi_contextify.cc index dfdcab9f55..543b7d3ab5 100644 --- a/v8/src/unofficial_napi_contextify.cc +++ b/v8/src/unofficial_napi_contextify.cc @@ -3134,6 +3134,10 @@ napi_status NAPI_CDECL unofficial_napi_module_wrap_set_export( napi_value export_value) { if (env == nullptr || module == nullptr || export_name == nullptr) return napi_invalid_arg; ModuleWrapRecord* record = ModuleRecord(module); + v8::HandleScope handle_scope(env->isolate); + // Only a synthetic module has exports to set. V8 aborts the process for + // any other. + if (!record->module.Get(env->isolate)->IsSyntheticModule()) return napi_invalid_arg; v8::Local name = napi_v8_unwrap_value(export_name); v8::Local value = export_value != nullptr ? napi_v8_unwrap_value(export_value) : v8::Undefined(env->isolate).As(); From 5433d1a4916188ead278a9507fca6c62eb7e35cb Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Fri, 6 Nov 2026 00:19:49 -0800 Subject: [PATCH 130/150] Throw a ReferenceError from set_export for a binding that does not exist A synthetic module has bindings only once it is instantiated. unofficial_napi_module_wrap_set_export before that, or with a name the module never exported, failed differently on each engine: - V8's SetSyntheticModuleExport throws a ReferenceError for both cases. The provider returned napi_generic_failure with nothing pending in N-API. The ReferenceError went to whatever JS was on the stack, or was lost when there was none. - QuickJS threw a ReferenceError for an unknown name. Before the module was instantiated, JS_SetModuleExport wrote through a null variable reference, which crashed with SIGSEGV. Both now return napi_pending_exception with the ReferenceError pending in N-API. V8 takes its exception through a TryCatch. QuickJS throws its existing ReferenceError ("Synthetic module export is not defined") for a module that is not linked yet, without calling JS_SetModuleExport. Setting an existing export of an instantiated module is unchanged. The bugs are older than f928811. Test: test_77 SetExportOfABindingThatDoesNotExistThrows, both engines. Before the synthetic module is linked, setting its export "value" and an unknown name must each return napi_pending_exception with a pending error named ReferenceError. After instantiation, the unknown name must do the same. "value" must then set with napi_ok and nothing pending, and read back from the namespace after evaluation. Before this commit, V8 returned napi_generic_failure (9) with nothing pending for all three. QuickJS crashed on the first call (exit 139). Co-Authored-By: Claude Opus 5.5 --- quickjs/src/internal/napi_module_wrap.cc | 6 ++- tests/runners/test_77_module_wrap_state.cc | 53 ++++++++++++++++++++++ v8/src/unofficial_napi_contextify.cc | 6 +++ 3 files changed, 64 insertions(+), 1 deletion(-) diff --git a/quickjs/src/internal/napi_module_wrap.cc b/quickjs/src/internal/napi_module_wrap.cc index 1f6175884f..621af5d81b 100644 --- a/quickjs/src/internal/napi_module_wrap.cc +++ b/quickjs/src/internal/napi_module_wrap.cc @@ -877,7 +877,11 @@ napi_status napi_module_wrap__::set_export(unofficial_napi_module module, return napi_pending_exception; } std::string name = napi_util__::to_utf8(env_, export_name); - if (JS_SetModuleExport(ctx_, entry->module, name.c_str(), + // Instantiating the module makes its bindings; JS_SetModuleExport would + // write through a null reference before that. Throw what an unknown name + // throws, as V8 does. + if (JS_GetModuleStatus(ctx_, entry->module) < JS_MODULE_STATUS_LINKED || + JS_SetModuleExport(ctx_, entry->module, name.c_str(), JS_DupValue(ctx_, napi_quickjs_value_inner(env_, export_value))) < 0) { env_->set_last_exception(JS_NewReferenceError(ctx_, "Synthetic module export is not defined")); diff --git a/tests/runners/test_77_module_wrap_state.cc b/tests/runners/test_77_module_wrap_state.cc index 161b4a29ec..b4a6482eba 100644 --- a/tests/runners/test_77_module_wrap_state.cc +++ b/tests/runners/test_77_module_wrap_state.cc @@ -481,3 +481,56 @@ TEST_F(Test77ModuleWrapState, SetExportTakesOnlySyntheticModules) { EXPECT_EQ(ValueText(s.env, value), "one"); EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, module), napi_ok); } + +namespace { + +// Takes the pending exception: its constructor's name, or "" when none was +// pending. +std::string TakePendingErrorName(napi_env env) { + if (!ExceptionPending(env)) return ""; + napi_value error = nullptr; + napi_value name = nullptr; + if (napi_get_and_clear_last_exception(env, &error) != napi_ok) return ""; + if (napi_get_named_property(env, error, "name", &name) != napi_ok) return ""; + return ValueText(env, name); +} + +} // namespace + +// Setting an export the synthetic module does not have (yet) throws a +// ReferenceError: one of its export names before the module is +// instantiated, which makes its bindings, or a name it never had. Before, +// V8 returned napi_generic_failure and left the ReferenceError it threw to +// whatever JS was on the stack, if any, instead of N-API. QuickJS crashed +// before the module was instantiated. +TEST_F(Test77ModuleWrapState, SetExportOfABindingThatDoesNotExistThrows) { + EnvScope s(runtime_.get()); + unofficial_napi_module module = CreateSyntheticModule(s.env, "(function() {})"); + ASSERT_NE(module, nullptr); + for (const char* name : {"value", "missing"}) { + SCOPED_TRACE(name); + EXPECT_EQ(unofficial_napi_module_wrap_set_export(s.env, module, Str(s.env, name), + Str(s.env, "early")), + napi_pending_exception); + EXPECT_EQ(TakePendingErrorName(s.env), "ReferenceError"); + } + ASSERT_EQ(unofficial_napi_module_wrap_link(s.env, module, 0, nullptr), napi_ok); + ASSERT_EQ(unofficial_napi_module_wrap_instantiate(s.env, module), napi_ok); + EXPECT_EQ(unofficial_napi_module_wrap_set_export(s.env, module, Str(s.env, "missing"), + Str(s.env, "late")), + napi_pending_exception); + EXPECT_EQ(TakePendingErrorName(s.env), "ReferenceError"); + EXPECT_EQ(unofficial_napi_module_wrap_set_export(s.env, module, Str(s.env, "value"), + Str(s.env, "set")), + napi_ok); + EXPECT_FALSE(ExceptionPending(s.env)); + napi_value promise = nullptr; + ASSERT_EQ(unofficial_napi_module_wrap_evaluate(s.env, module, -1, false, &promise), napi_ok); + EXPECT_EQ(PromiseOutcome(s.env, promise), "resolved"); + napi_value ns = nullptr; + napi_value value = nullptr; + ASSERT_EQ(unofficial_napi_module_wrap_get_namespace(s.env, module, &ns), napi_ok); + ASSERT_EQ(napi_get_named_property(s.env, ns, "value", &value), napi_ok); + EXPECT_EQ(ValueText(s.env, value), "set"); + EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, module), napi_ok); +} diff --git a/v8/src/unofficial_napi_contextify.cc b/v8/src/unofficial_napi_contextify.cc index 543b7d3ab5..42e1c3f405 100644 --- a/v8/src/unofficial_napi_contextify.cc +++ b/v8/src/unofficial_napi_contextify.cc @@ -3142,7 +3142,13 @@ napi_status NAPI_CDECL unofficial_napi_module_wrap_set_export( v8::Local value = export_value != nullptr ? napi_v8_unwrap_value(export_value) : v8::Undefined(env->isolate).As(); if (name.IsEmpty() || !name->IsString()) return napi_invalid_arg; + // V8 throws a ReferenceError for a name the module has no binding for (yet: + // instantiating the module makes its bindings). It is N-API's to report. + v8::TryCatch try_catch(env->isolate); if (record->module.Get(env->isolate)->SetSyntheticModuleExport(env->isolate, name.As(), value).IsNothing()) { + if (try_catch.HasCaught() && !try_catch.HasTerminated()) { + return ThrowTryCatchException(env, try_catch); + } return napi_generic_failure; } return napi_ok; From 602295689b27238b8e5062526c9a97e8e4a592c8 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Fri, 6 Nov 2026 00:20:38 -0800 Subject: [PATCH 131/150] QuickJS: refuse the namespace of a module that is not instantiated unofficial_napi_module_wrap_get_namespace on a QuickJS module that was not instantiated (never linked, or linked but not instantiated) called JS_GetModuleNamespace. That builds the namespace over bindings that do not exist until the module is linked, and it crashed with SIGSEGV. This held for source text and synthetic modules. It now throws an Error with code ERR_MODULE_NOT_INSTANTIATED ("Module is not instantiated") and returns napi_pending_exception. That is what the V8 provider already did, because V8's GetModuleNamespace takes an instantiated module only. The bug is older than f928811. Test: test_77 NamespaceOfAModuleNotInstantiatedIsRefused, both engines. For a source text and a synthetic module, the namespace must be refused that way before linking and after linking. After instantiation it must be given. Before this commit, QuickJS crashed on the first call (exit 139). V8 passed. Co-Authored-By: Claude Opus 5.5 --- quickjs/src/internal/napi_module_wrap.cc | 4 +++ tests/runners/test_77_module_wrap_state.cc | 31 ++++++++++++++++++++++ 2 files changed, 35 insertions(+) diff --git a/quickjs/src/internal/napi_module_wrap.cc b/quickjs/src/internal/napi_module_wrap.cc index 621af5d81b..fc364ff48b 100644 --- a/quickjs/src/internal/napi_module_wrap.cc +++ b/quickjs/src/internal/napi_module_wrap.cc @@ -786,6 +786,10 @@ napi_status napi_module_wrap__::get_namespace(unofficial_napi_module module, record *entry = find(module); if (entry == nullptr || result_out == nullptr) return napi_util__::invalid_arg(env_); + // Instantiating the module makes the bindings its namespace reads; building + // it before that crashed. Refused as on V8. + if (JS_GetModuleStatus(ctx_, entry->module) < JS_MODULE_STATUS_LINKED) + return throw_error("ERR_MODULE_NOT_INSTANTIATED", "Module is not instantiated"); JSValue ns = JS_GetModuleNamespace(ctx_, entry->module); if (JS_IsException(ns)) return return_pending_exception("Failed to get module namespace"); diff --git a/tests/runners/test_77_module_wrap_state.cc b/tests/runners/test_77_module_wrap_state.cc index b4a6482eba..84e9ec7ea9 100644 --- a/tests/runners/test_77_module_wrap_state.cc +++ b/tests/runners/test_77_module_wrap_state.cc @@ -534,3 +534,34 @@ TEST_F(Test77ModuleWrapState, SetExportOfABindingThatDoesNotExistThrows) { EXPECT_EQ(ValueText(s.env, value), "set"); EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, module), napi_ok); } + +// The namespace of a module that is not instantiated is refused with +// ERR_MODULE_NOT_INSTANTIATED on both engines, as the V8 provider already +// did (V8's GetModuleNamespace takes an instantiated module only). QuickJS +// built the namespace over bindings that do not exist yet and crashed. +TEST_F(Test77ModuleWrapState, NamespaceOfAModuleNotInstantiatedIsRefused) { + EnvScope s(runtime_.get()); + for (bool synthetic : {false, true}) { + SCOPED_TRACE(synthetic ? "synthetic" : "source text"); + unofficial_napi_module module = + synthetic ? CreateSyntheticModule(s.env, "(function() {})") + : CreateSourceTextModule(s.env, "export const value = 1;"); + ASSERT_NE(module, nullptr); + for (bool linked : {false, true}) { + SCOPED_TRACE(linked ? "linked" : "not linked"); + if (linked) { + ASSERT_EQ(unofficial_napi_module_wrap_link(s.env, module, 0, nullptr), napi_ok); + } + napi_value ns = nullptr; + EXPECT_EQ(unofficial_napi_module_wrap_get_namespace(s.env, module, &ns), + napi_pending_exception); + EXPECT_EQ(TakePendingCodeAndMessage(s.env), + "ERR_MODULE_NOT_INSTANTIATED: Module is not instantiated"); + } + ASSERT_EQ(unofficial_napi_module_wrap_instantiate(s.env, module), napi_ok); + napi_value ns = nullptr; + EXPECT_EQ(unofficial_napi_module_wrap_get_namespace(s.env, module, &ns), napi_ok); + EXPECT_NE(ns, nullptr); + EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, module), napi_ok); + } +} From f410ebe5f031dbc71813d1e16ab71832d575d496 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Fri, 6 Nov 2026 00:23:39 -0800 Subject: [PATCH 132/150] V8: instantiate the facade's module with its links, report its errors unofficial_napi_module_wrap_create_required_module_facade instantiates a facade module that re-exports the module it wraps (`import ... from 'original'`). When the wrapped module was not instantiated yet, V8 instantiated it as part of the facade's graph. It resolved the module's own requests with the facade's resolver, which knows only 'original': - A module that was linked but not instantiated did not instantiate, and the facade failed. - An import of 'original' would have resolved to the module itself. The facade's failures, from compiling, instantiating or evaluating, also returned napi_pending_exception with nothing pending in N-API. What V8 threw went to whatever JS was on the stack, or was lost. The resolver's refusals threw nothing at all. QuickJS reports these errors as pending. The facade's resolver now hands a request made by a known module record to ModuleResolveCallback, as instantiate does. So the module resolves to what it was linked to, and an unlinked request throws ERR_VM_MODULE_LINK_FAILURE. The facade's compile, instantiation and evaluation run in a TryCatch, and what they throw is given to N-API. A termination stays and is what the call fails with, as elsewhere in the module calls: ThrowTryCatchException leaves the termination's null pending (napi_v8_fail_terminating). QuickJS's facade already linked the module with its own links. The bugs are older than f928811. Test: test_77 RequiredModuleFacadeInstantiatesOrLeavesItsError, both engines. - A module linked to a dependency but not instantiated must get its facade with napi_ok: default 2, both modules at status 4. - A module whose request was never linked must fail with an error pending and stay at status 0. - An evaluated module with no default export must fail with a SyntaxError pending. Before this commit, V8 failed the first case with napi_pending_exception (10). An earlier run of the last two cases alone found nothing pending in either. QuickJS passed. Co-Authored-By: Claude Opus 5.5 --- tests/runners/test_77_module_wrap_state.cc | 54 ++++++++++++++++++++++ v8/src/unofficial_napi_contextify.cc | 18 ++++++-- 2 files changed, 67 insertions(+), 5 deletions(-) diff --git a/tests/runners/test_77_module_wrap_state.cc b/tests/runners/test_77_module_wrap_state.cc index 84e9ec7ea9..7b2d6335ff 100644 --- a/tests/runners/test_77_module_wrap_state.cc +++ b/tests/runners/test_77_module_wrap_state.cc @@ -565,3 +565,57 @@ TEST_F(Test77ModuleWrapState, NamespaceOfAModuleNotInstantiatedIsRefused) { EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, module), napi_ok); } } + +// The require() facade instantiates the module it wraps, if needed, with +// the modules that module was linked to, as instantiate does and as on +// QuickJS. When the facade cannot be made, because the module does not +// instantiate or has no default export to re-export, the call fails with +// that error pending in N-API. V8 resolved the module's own requests with +// the facade's resolver, which knows only 'original': a module that was not +// instantiated yet did not instantiate. And V8 returned +// napi_pending_exception with nothing pending: the error went to whatever +// JS was on the stack, or was lost, or (from the facade's resolver) was +// never thrown. +TEST_F(Test77ModuleWrapState, RequiredModuleFacadeInstantiatesOrLeavesItsError) { + EnvScope s(runtime_.get()); + unofficial_napi_module dependency = CreateSourceTextModule(s.env, "export const value = 2;"); + unofficial_napi_module linked = + CreateSourceTextModule(s.env, "import { value } from 'dependency'; export default value;"); + ASSERT_NE(dependency, nullptr); + ASSERT_NE(linked, nullptr); + ASSERT_EQ(unofficial_napi_module_wrap_link(s.env, dependency, 0, nullptr), napi_ok); + ASSERT_EQ(unofficial_napi_module_wrap_link(s.env, linked, 1, &dependency), napi_ok); + napi_value facade = nullptr; + ASSERT_EQ(unofficial_napi_module_wrap_create_required_module_facade(s.env, linked, &facade), + napi_ok); + napi_value default_value = nullptr; + ASSERT_EQ(napi_get_named_property(s.env, facade, "default", &default_value), napi_ok); + EXPECT_EQ(ValueText(s.env, default_value), "2"); + EXPECT_EQ(Status(s.env, linked), kEvaluated); + EXPECT_EQ(Status(s.env, dependency), kEvaluated); + EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, linked), napi_ok); + EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, dependency), napi_ok); + + unofficial_napi_module unlinked = + CreateSourceTextModule(s.env, "import 'missing'; export default 1;"); + ASSERT_NE(unlinked, nullptr); + napi_value ns = nullptr; + EXPECT_EQ(unofficial_napi_module_wrap_create_required_module_facade(s.env, unlinked, &ns), + napi_pending_exception); + EXPECT_NE(TakePendingMessage(s.env), ""); + EXPECT_EQ(Status(s.env, unlinked), kUninstantiated); + EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, unlinked), napi_ok); + + unofficial_napi_module no_default = CreateSourceTextModule(s.env, "export const value = 1;"); + ASSERT_NE(no_default, nullptr); + ASSERT_EQ(unofficial_napi_module_wrap_link(s.env, no_default, 0, nullptr), napi_ok); + ASSERT_EQ(unofficial_napi_module_wrap_instantiate(s.env, no_default), napi_ok); + napi_value promise = nullptr; + ASSERT_EQ(unofficial_napi_module_wrap_evaluate(s.env, no_default, -1, false, &promise), napi_ok); + EXPECT_EQ(PromiseOutcome(s.env, promise), "resolved"); + ns = nullptr; + EXPECT_EQ(unofficial_napi_module_wrap_create_required_module_facade(s.env, no_default, &ns), + napi_pending_exception); + EXPECT_EQ(TakePendingErrorName(s.env), "SyntaxError"); + EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, no_default), napi_ok); +} diff --git a/v8/src/unofficial_napi_contextify.cc b/v8/src/unofficial_napi_contextify.cc index 42e1c3f405..77f7bc5a9f 100644 --- a/v8/src/unofficial_napi_contextify.cc +++ b/v8/src/unofficial_napi_contextify.cc @@ -1317,10 +1317,16 @@ void HostInitializeImportMetaObject(v8::Local context, v8::MaybeLocal LinkRequiredFacadeOriginal(v8::Local context, v8::Local specifier, - v8::Local /*import_attributes*/, - v8::Local /*referrer*/) { + v8::Local import_attributes, + v8::Local referrer) { napi_env env = GetModuleWrapEnvForIsolate(context->GetIsolate()); if (env == nullptr) return v8::MaybeLocal(); + // Instantiating the facade instantiates the module it wraps, if that is not + // done yet, and the modules it requests: those resolve to what they were + // linked to, as instantiate resolves them. Only the facade is unknown here. + if (FindModuleRecordForModule(env, referrer) != nullptr) { + return ModuleResolveCallback(context, specifier, import_attributes, referrer); + } auto* state = GetModuleWrapState(env); if (state == nullptr || state->temporary_required_module_facade_original == nullptr || state->temporary_required_module_facade_original->module.IsEmpty()) { @@ -3267,9 +3273,11 @@ napi_status NAPI_CDECL unofficial_napi_module_wrap_create_required_module_facade false, true); v8::ScriptCompiler::Source source(OneByteString(isolate, kFacadeSource), origin); + // What instantiating or evaluating the facade throws is N-API's to report. + v8::TryCatch try_catch(isolate); v8::Local facade; if (!v8::ScriptCompiler::CompileModule(isolate, &source).ToLocal(&facade)) { - return napi_pending_exception; + return ThrowTryCatchException(env, try_catch); } { @@ -3285,10 +3293,10 @@ napi_status NAPI_CDECL unofficial_napi_module_wrap_create_required_module_facade std::lock_guard lock(g_module_wrap_mu); GetModuleWrapStateLocked(env)->temporary_required_module_facade_original = nullptr; } - if (!instantiated) return napi_pending_exception; + if (!instantiated) return ThrowTryCatchException(env, try_catch); v8::Local evaluated; - if (!facade->Evaluate(context).ToLocal(&evaluated)) return napi_pending_exception; + if (!facade->Evaluate(context).ToLocal(&evaluated)) return ThrowTryCatchException(env, try_catch); *result_out = napi_v8_wrap_value(env, handle_scope.Escape(facade->GetModuleNamespace())); return napi_ok; } From 0a6dac33f97ff5b2883a01d31f02f7add0cdf34d Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Fri, 6 Nov 2026 00:24:26 -0800 Subject: [PATCH 133/150] Undefine NAPI_MODULE before test_65 includes node_api.h "V8: forget the module loader's state at the end of an env's release" added `#include "node_api.h"` to test_65_unofficial_contextify.cc. The test build defines NAPI_MODULE(modname,regfunc) empty on the command line, and node_api.h defines it again. So every build of test_65 warned on both engines: include/node_api.h:78:9: warning: 'NAPI_MODULE' macro redefined [-Wmacro-redefined] test_65 now undefines it first, as test_71 and the other runners that include node_api.h do. No behaviour changes. The V8 and QuickJS builds show no such warning for test_65, and test_65 passes on both. Co-Authored-By: Claude Opus 5.5 --- tests/runners/test_65_unofficial_contextify.cc | 3 +++ 1 file changed, 3 insertions(+) diff --git a/tests/runners/test_65_unofficial_contextify.cc b/tests/runners/test_65_unofficial_contextify.cc index 31bf97a5c3..1741648609 100644 --- a/tests/runners/test_65_unofficial_contextify.cc +++ b/tests/runners/test_65_unofficial_contextify.cc @@ -1,5 +1,8 @@ #include "test_env.h" +#ifdef NAPI_MODULE +#undef NAPI_MODULE +#endif #include "node_api.h" #include "unofficial_napi.h" From 8c0b960bf8791c68f779d5f3aa6341dd4887b13b Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Fri, 6 Nov 2026 00:24:26 -0800 Subject: [PATCH 134/150] Undefine NAPI_MODULE before test_75 and test_76 include node_api.h test_75_hooks_keep_termination.cc includes node_api.h (since "V8: refuse napi_fatal_exception while V8 terminates"), and so does test_76_termination_until_cancelled.cc (since "V8: drop the termination's pending null when it is cancelled"). Both warned the same way as test_65 did, on both engines: include/node_api.h:78:9: warning: 'NAPI_MODULE' macro redefined [-Wmacro-redefined] The command line defines the macro empty. test_75 and test_76 now undefine it first, as the other runners do. No behaviour changes. The V8 and QuickJS builds show no such warning for either, and both pass on both engines. This fix was first written for test_75 alone, on a history without test_76; test_76 gets the same three lines here. Co-Authored-By: Claude Opus 5.5 --- tests/runners/test_75_hooks_keep_termination.cc | 3 +++ tests/runners/test_76_termination_until_cancelled.cc | 3 +++ 2 files changed, 6 insertions(+) diff --git a/tests/runners/test_75_hooks_keep_termination.cc b/tests/runners/test_75_hooks_keep_termination.cc index 68fce0e2fd..dcb3b7d62f 100644 --- a/tests/runners/test_75_hooks_keep_termination.cc +++ b/tests/runners/test_75_hooks_keep_termination.cc @@ -12,6 +12,9 @@ #include "test_env.h" +#ifdef NAPI_MODULE +#undef NAPI_MODULE +#endif #include "node_api.h" #include "unofficial_napi.h" diff --git a/tests/runners/test_76_termination_until_cancelled.cc b/tests/runners/test_76_termination_until_cancelled.cc index d5a448f5a3..ac256db508 100644 --- a/tests/runners/test_76_termination_until_cancelled.cc +++ b/tests/runners/test_76_termination_until_cancelled.cc @@ -10,6 +10,9 @@ #include "test_env.h" +#ifdef NAPI_MODULE +#undef NAPI_MODULE +#endif #include "node_api.h" #include "unofficial_napi.h" From 9c122a7215b0a6b54a357cff6b78567b0708a20b Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Fri, 6 Nov 2026 00:33:57 -0800 Subject: [PATCH 135/150] Document known limitations: views, token hooks, upgrading from next Behaviour the branch has that nothing public described. Each was checked at the head before writing it down. docs/realms.md, new section "Views of an ArrayBuffer": - A view out of bounds of its shrunk resizable buffer has length 0 on both engines. V8 reports the view's own offset and the buffer's data plus that offset. QuickJS reports offset 0 and the buffer's data. A view over a detached buffer has length 0, offset 0 and NULL data on both. Measured with a probe on both engines: a Uint8Array(rab, 8, 4), a DataView(rab, 6, 4) and a Buffer at 10 over a 16-byte resizable buffer, shrunk to 4 and then detached. Before this, only a comment in quickjs/src/internal/napi_env.h and the test_33 comments said it. - Near the engine's stack limit, QuickJS fails napi_get_typedarray_info and napi_get_dataview_info (napi_generic_failure) and napi_get_buffer_info (napi_invalid_arg), with nothing pending and the outputs left as they were, except the `type` that typedarray_info sets first. It reads a view through the intrinsic getters, which are calls. V8 does not fail there. The release audit's stack-limit probe (ReviewViewLayoutNearTheStackLimit), run again on this branch, gives the same as at "Pin each engine's outcome of an import() at release, in test_65": 48 of 49 reads failed on QuickJS, typed and DataView with status 9 and Buffer with 1, outputs at their sentinels. V8 passed. Context tokens, in the header comment on unofficial_napi_env_hooks and in docs/realms.md: - Outside the release, V8's CallContextTokenHook calls the hooks as they are, with no TryCatch and no pending exception set aside (only the release path saves and restores it). A probe confirmed both effects at this head: - an assign callback's napi_throw_error left create_realm returning napi_ok with "from assign" pending; - with "callers" pending, collect_garbage ran three unassign callbacks that each saw an exception pending, and returned napi_ok with the last callback's "from unassign" pending in place of the caller's. - In the release contract on unofficial_napi_release_env and in docs/realms.md: an unassign callback that makes a realm on every call never lets the release finish, as a finalizer that makes a new value every time does. docs/realms.md, new section "Upgrading from the earlier `next`", for code built against f928811's header. Offsets and sizes were measured with offsetof and sizeof on f928811's include/unofficial_napi.h and on the current one, natively and for wasm32-unknown-unknown: - Bytecode-open options v2: 88 bytes native and 52 wasm32 in both. The realm was at offset 8 in both and is now at 80 and 48. So it is accepted and read wrongly with no error. - Module-create options v2: was 64 and 40 bytes with the realm at 32 and 20; now 72 and 44 with it at 64 and 40. Refused with napi_invalid_arg. - Env hooks: f928811 had version 2, 40 and 24 bytes. Providers now accept only version 1 (56 and 32 bytes), so it gets napi_invalid_arg. - main's layouts (version 1) are unaffected. Both guest backends read the wasm32 structs through src/guest/abi.rs, with the same checks. Documentation only. Co-Authored-By: Claude Opus 5.5 --- docs/realms.md | 68 ++++++++++++++++++++++++++++++++++++--- include/unofficial_napi.h | 14 +++++++- 2 files changed, 77 insertions(+), 5 deletions(-) diff --git a/docs/realms.md b/docs/realms.md index 80bd20f213..82d9ca5111 100644 --- a/docs/realms.md +++ b/docs/realms.md @@ -188,12 +188,19 @@ calls take a realm's global or sandbox. `collect_garbage` runs (for a collected realm, from a hook or finalizer of the release) waits, as any realm made while releasing, for the first sweep after it. What else an unassign callback makes is released as the - rest (see `unofficial_napi_release_env` in the header). Realms made + rest (see `unofficial_napi_release_env` in the header). An unassign + callback that makes a realm on every call never lets the release finish, + as a finalizer that makes a new value every time does. Realms made before the hooks were attached get no token. Both hooks run in the env's realm; at release what they throw is dropped, as for the other hooks and - finalizers. On `main` a context lived until release, so tokens were only - unassigned then. QuickJS does not accept the hooks and never calls them, - as on `main`. + finalizers. Outside the release V8 calls them as they are, with no + TryCatch and no pending exception set aside. An exception the assign + callback leaves pending is still pending when `create_realm` returns + `napi_ok`. The unassign callback of a collected realm, run inside + `create_realm` or `collect_garbage`, sees the caller's pending exception, + and one it leaves pending replaces the caller's. On `main` a context lived + until release, so tokens were only unassigned then. QuickJS does not + accept the hooks and never calls them, as on `main`. - **Statuses are `main`'s V8 ones.** `main`'s QuickJS differed: it took a NULL `name`, refused a symbol sandbox, returned an already contextified sandbox again, compiled in the env's context for a parsing context that @@ -239,6 +246,36 @@ calls take a realm's global or sandbox. sends version 1 module options, and a host-JS test drives the three imports from a guest. +## Upgrading from the earlier `next` + +Code built against `next` as it was before the deprecated API came back +(f928811) must be rebuilt. Three structs changed in place there. They have +`main`'s layouts again now, and the two option structs grow at the end +instead. Code built against `main` uses version 1 of each, which is +unaffected. + +| Struct, as built against f928811 | Native | wasm32 | Now | +|---|---|---|---| +| Bytecode-open options, version 2 | 88 bytes, `realm_or_null` at 8 | 52 bytes, realm at 8 | Accepted and read wrongly, with no error | +| Module-create options, version 2 | 64 bytes, `realm_or_null` at 32 | 40 bytes, realm at 20 | `napi_invalid_arg` | +| Env hooks, version 2 | 40 bytes | 24 bytes | `napi_invalid_arg` | + +- **Bytecode-open options** keep version 2 and the same size, but + `realm_or_null` now comes last (offset 80 native, 48 wasm32), after + `cache_policy`. So a struct built against f928811 passes the version and + size checks, and every field after `version` is read from the wrong place: + its realm as `source_text`, and the realm from its cache flags and + padding. +- **Module-create options** version 2 now appends `realm_or_null` (offset 64 + native, 40 wasm32) after `main`'s layout, which keeps + `context_or_undefined` where f928811 had the realm. A struct built against + f928811 is shorter than version 2 now is, and is refused. +- **Env hooks** are version 1 again, `main`'s layout with the token + callbacks (56 bytes native, 32 wasm32). Providers accept only version 1, + so f928811's version 2 is refused. +- WASIX and host-JS guests follow the same rules: both guest backends read + the wasm32 layouts above. + ## How the current realm works Each env keeps a stack of realm frames, innermost last: the scopes @@ -279,6 +316,29 @@ and interrupt callbacks push the env's realm. that realm. - Everything else, hooks included, goes through the env. +## Views of an ArrayBuffer + +`napi_get_typedarray_info`, `napi_get_dataview_info` and +`napi_get_buffer_info` read a view's layout from its internal slots, never +from its properties, which its realm's scripts control. Two cases differ +between the engines: + +- **A view that is out of bounds of its resizable buffer**, which shrank + under it, has length 0 on both engines. V8 reports the view's own offset + and the buffer's data plus that offset, which may lie past the buffer's + end. QuickJS + reports offset 0 and the buffer's data: its accessors report 0 for such a + view, or throw. A view over a detached buffer has length 0, offset 0 and + NULL data on both. +- **Near the engine's stack limit, QuickJS fails these calls.** It reads the + slots through the intrinsic getters (`%TypedArray%.prototype.buffer` and + the rest, as the env was made), and a getter is a call, which needs stack. + When none is left, `napi_get_typedarray_info` and `napi_get_dataview_info` + return `napi_generic_failure` and `napi_get_buffer_info` returns + `napi_invalid_arg`, with nothing pending. They leave their outputs as they + were, except the `type` that `napi_get_typedarray_info` sets first. V8 + reads the slots directly and does not fail there. + ## Not done - **QuickJS needs engine commit 870aa7b** (wasmerio/quickjs#10), which makes diff --git a/include/unofficial_napi.h b/include/unofficial_napi.h index 645d9617ac..10c6ae2668 100644 --- a/include/unofficial_napi.h +++ b/include/unofficial_napi.h @@ -172,6 +172,16 @@ enum { UNOFFICIAL_NAPI_ENV_HOOKS_VERSION = 1 }; // realms made while it runs too. Both run in the env's realm. Realms made // before the hooks were attached get no token. QuickJS does not accept them // and never calls them. +// +// Outside the release, V8 calls them as they are: in no TryCatch, with no +// pending exception set aside. An exception the assign callback leaves +// pending is still pending when unofficial_napi_create_realm returns napi_ok. +// The unassign callback of a collected realm, which +// unofficial_napi_create_realm or unofficial_napi_collect_garbage runs, sees +// its caller's state: an exception the caller has pending is pending in the +// callback too, and one the callback leaves pending replaces it and is the +// caller's when the call returns its own status. At the release, what they +// throw is dropped (see unofficial_napi_release_env). UNOFFICIAL_NAPI_SUPPRESS_DEPRECATED_BEGIN typedef struct { uint32_t size; @@ -266,7 +276,9 @@ NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_attach_env( // a collected realm, from a hook or finalizer of the release) waits, as any // realm made while releasing, for the first sweep after it. So every token // is unassigned once before the env is freed. What an unassign callback -// makes besides (values, hooks, instance data) is released as the rest. +// makes besides (values, hooks, instance data) is released as the rest. An +// unassign callback that makes a realm every time it is called never lets +// the release finish, as a finalizer that makes a new value every time does. // // After each hook, token callback and finalizer, an exception it left // pending is dropped: nothing can catch it then (Node's CallIntoModule drops From 307800cbee160e3d6e0c616efb647c082c26053e Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Fri, 6 Nov 2026 00:50:35 -0800 Subject: [PATCH 136/150] Refuse to evaluate a module that imports an evaluating synthetic module Found by the Codex review of the commits from "V8: report a module that is not instantiated as settled in the TLA check" to "Document known limitations: views, token hooks, upgrading from next". A synthetic module's evaluation steps can reach native code that evaluates a source text module importing that same synthetic module. In Node this is a CommonJS module that requires an ES module importing it, a cycle Node refuses with ERR_REQUIRE_CYCLE_MODULE. The synthetic module is not itself the one asked for, so the check from "Refuse to evaluate a module while its evaluation runs, on both engines" did not see it. - V8 evaluates the synthetic dependency through Module::Evaluate, whose CHECK rejects a module that is evaluating. So evaluate, evaluate_sync and the require() facade aborted the process ("Check failed: module_status == kLinked || ..."). - QuickJS ran the module against the synthetic module's exports as they were. Both providers now count the synthetic modules whose steps are running. While any are, before evaluating they walk what the evaluation would reach: the not yet evaluated source text modules (after evaluate instantiates one), through the records they were linked to. Records that were destroyed since are skipped. If one of those requests a synthetic module that is evaluating, the call throws an Error with code ERR_VM_MODULE_STATUS ("A synthetic module it imports is evaluating") and returns napi_pending_exception. Nothing is walked when no steps are running. Test: test_77 EvaluatingAModuleThatImportsAnEvaluatingSyntheticModuleIsRefused, both engines. A source text module imports a synthetic module. It is instantiated, or only linked. The synthetic module's steps evaluate the source text module through evaluate, evaluate_sync and the facade, in turn. Each must be refused with that code and message. The steps must finish, and the source text module must not run until it is evaluated afterwards. Before this commit, V8 aborted on the first case (exit 133, the CHECK above). QuickJS returned napi_ok and ran the module in every case. Co-Authored-By: Claude Opus 5.5 --- quickjs/src/internal/napi_module_wrap.cc | 44 +++++++++++++++ quickjs/src/internal/napi_module_wrap.h | 3 ++ tests/runners/test_77_module_wrap_state.cc | 63 ++++++++++++++++++++++ v8/src/unofficial_napi_contextify.cc | 49 ++++++++++++++++- 4 files changed, 158 insertions(+), 1 deletion(-) diff --git a/quickjs/src/internal/napi_module_wrap.cc b/quickjs/src/internal/napi_module_wrap.cc index fc364ff48b..00801f248c 100644 --- a/quickjs/src/internal/napi_module_wrap.cc +++ b/quickjs/src/internal/napi_module_wrap.cc @@ -11,6 +11,7 @@ #include #include #include +#include #include #include @@ -703,12 +704,50 @@ napi_status napi_module_wrap__::throw_if_evaluating(record *entry) return throw_error("ERR_VM_MODULE_STATUS", "Module status must not be evaluating"); } +// Evaluating a module that imports a synthetic module whose evaluation steps +// are running (from those steps: a CommonJS module that requires an ES module +// importing it, a cycle Node refuses too) is refused, as on V8, which aborts +// the process for it. QuickJS would run the module against the synthetic +// module's exports as they are. What it would link and evaluate is the +// modules it reaches through the ones not evaluated yet. +napi_status napi_module_wrap__::throw_if_importing_an_evaluating_synthetic_module(record *entry) +{ + if (synthetic_steps_running_ == 0) + return napi_ok; + // A record another was linked to may be destroyed since. + const std::unordered_set live(records_.begin(), records_.end()); + std::vector pending{entry}; + std::unordered_set seen{entry}; + while (!pending.empty()) + { + record *current = pending.back(); + pending.pop_back(); + const JSModuleStatusEnum status = JS_GetModuleStatus(ctx_, current->module); + if (current->synthetic || + (status != JS_MODULE_STATUS_UNLINKED && status != JS_MODULE_STATUS_LINKED)) + continue; + for (record *linked : current->linked_records) + { + if (live.count(linked) == 0 || !seen.insert(linked).second) + continue; + if (linked->synthetic && + JS_GetModuleStatus(ctx_, linked->module) == JS_MODULE_STATUS_EVALUATING) + return throw_error("ERR_VM_MODULE_STATUS", "A synthetic module it imports is evaluating"); + pending.push_back(linked); + } + } + return napi_ok; +} + napi_status napi_module_wrap__::evaluate_unless_terminated(record *entry, JSValue *promise_out) { napi_status status = napi_util__::fail_if_terminating(env_, ctx_); if (status != napi_ok) return status; status = throw_if_evaluating(entry); + if (status != napi_ok) + return status; + status = throw_if_importing_an_evaluating_synthetic_module(entry); if (status != napi_ok) return status; // The module evaluates in its realm. @@ -1055,6 +1094,9 @@ napi_status napi_module_wrap__::create_required_module_facade(unofficial_napi_mo return napi_util__::invalid_arg(env_); // The facade evaluates the module it wraps. napi_status status = throw_if_evaluating(entry); + if (status != napi_ok) + return status; + status = throw_if_importing_an_evaluating_synthetic_module(entry); if (status != napi_ok) return status; @@ -1175,8 +1217,10 @@ int napi_module_wrap__::initialize_synthetic_module(JSModuleDef *module) record *entry = find_by_module(module); if (entry == nullptr || !JS_IsFunction(ctx_, entry->synthetic_eval_steps)) return 0; + synthetic_steps_running_++; JSValue result = JS_Call(ctx_, entry->synthetic_eval_steps, entry->wrapper, 0, nullptr); + synthetic_steps_running_--; if (JS_IsException(result)) return -1; JS_FreeValue(ctx_, result); diff --git a/quickjs/src/internal/napi_module_wrap.h b/quickjs/src/internal/napi_module_wrap.h index 9871692632..3ed5e42db7 100644 --- a/quickjs/src/internal/napi_module_wrap.h +++ b/quickjs/src/internal/napi_module_wrap.h @@ -117,6 +117,7 @@ class napi_module_wrap__ napi_status throw_error(const char *code, const char *message); napi_status return_pending_exception(const char *message); napi_status throw_if_evaluating(record *entry); + napi_status throw_if_importing_an_evaluating_synthetic_module(record *entry); napi_status evaluate_unless_terminated(record *entry, JSValue *promise_out); napi_status wrap_owned(JSValue value, napi_value *result_out) const; JSValue call_callback(JSValueConst callback, @@ -139,6 +140,8 @@ class napi_module_wrap__ std::vector script_referrers_; std::vector pending_dynamic_imports_; uint64_t facade_counter_ = 0; + // Synthetic modules whose evaluation steps are running. + int synthetic_steps_running_ = 0; // Subsystem lifecycle. bool torn_down_ = false; diff --git a/tests/runners/test_77_module_wrap_state.cc b/tests/runners/test_77_module_wrap_state.cc index 7b2d6335ff..e8f49c78ad 100644 --- a/tests/runners/test_77_module_wrap_state.cc +++ b/tests/runners/test_77_module_wrap_state.cc @@ -619,3 +619,66 @@ TEST_F(Test77ModuleWrapState, RequiredModuleFacadeInstantiatesOrLeavesItsError) EXPECT_EQ(TakePendingErrorName(s.env), "SyntaxError"); EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, no_default), napi_ok); } + +// Evaluating a module that imports a synthetic module whose evaluation steps +// are running (from those steps: a CommonJS module that requires an ES module +// importing it) is refused with ERR_VM_MODULE_STATUS on both engines, as +// Node refuses such a cycle (ERR_REQUIRE_CYCLE_MODULE), whether the module is +// instantiated already or not. The same holds for the require() facade over +// it. V8 aborted the process: it evaluates the synthetic module through +// Module::Evaluate, whose CHECK rejects one that is evaluating. QuickJS ran +// the module against the synthetic module's exports as they were. Once the +// steps are done, the module evaluates. +TEST_F(Test77ModuleWrapState, EvaluatingAModuleThatImportsAnEvaluatingSyntheticModuleIsRefused) { + for (bool instantiated : {true, false}) { + for (Reentry call : {Reentry::kEvaluate, Reentry::kEvaluateSync, Reentry::kFacade}) { + SCOPED_TRACE(std::string(instantiated ? "instantiated, " : "linked, ") + + (call == Reentry::kEvaluate ? "evaluate" + : call == Reentry::kEvaluateSync ? "evaluate_sync" + : "facade")); + EnvScope s(runtime_.get()); + ReentryProbe probe; + probe.call = call; + napi_value fn = nullptr; + napi_value global = nullptr; + ASSERT_EQ(napi_create_function(s.env, "evaluateAgain", NAPI_AUTO_LENGTH, EvaluateAgain, + &probe, &fn), + napi_ok); + ASSERT_EQ(napi_get_global(s.env, &global), napi_ok); + ASSERT_EQ(napi_set_named_property(s.env, global, "evaluateAgain", fn), napi_ok); + ASSERT_EQ(RunText(s.env, "globalThis.after = 'no'; globalThis.ran = 'no'"), "no"); + unofficial_napi_module synthetic = CreateSyntheticModule( + s.env, "(function() { evaluateAgain(); globalThis.after = 'yes'; })"); + probe.module = CreateSourceTextModule( + s.env, "import { value } from 'synthetic'; globalThis.ran = 'yes'; export default 1;"); + ASSERT_NE(synthetic, nullptr); + ASSERT_NE(probe.module, nullptr); + ASSERT_EQ(unofficial_napi_module_wrap_link(s.env, synthetic, 0, nullptr), napi_ok); + ASSERT_EQ(unofficial_napi_module_wrap_link(s.env, probe.module, 1, &synthetic), napi_ok); + if (instantiated) { + ASSERT_EQ(unofficial_napi_module_wrap_instantiate(s.env, probe.module), napi_ok); + } else { + ASSERT_EQ(unofficial_napi_module_wrap_instantiate(s.env, synthetic), napi_ok); + } + + napi_value promise = nullptr; + ASSERT_EQ(unofficial_napi_module_wrap_evaluate(s.env, synthetic, -1, false, &promise), + napi_ok); + EXPECT_EQ(probe.calls, 1); + EXPECT_EQ(probe.status, napi_pending_exception); + EXPECT_EQ(probe.pending, + "ERR_VM_MODULE_STATUS: A synthetic module it imports is evaluating"); + EXPECT_EQ(PromiseOutcome(s.env, promise), "resolved"); + EXPECT_EQ(RunText(s.env, "after"), "yes"); + EXPECT_EQ(RunText(s.env, "ran"), "no"); + EXPECT_EQ(Status(s.env, synthetic), kEvaluated); + + ASSERT_EQ(unofficial_napi_module_wrap_evaluate(s.env, probe.module, -1, false, &promise), + napi_ok); + EXPECT_EQ(PromiseOutcome(s.env, promise), "resolved"); + EXPECT_EQ(RunText(s.env, "ran"), "yes"); + EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, probe.module), napi_ok); + EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, synthetic), napi_ok); + } + } +} diff --git a/v8/src/unofficial_napi_contextify.cc b/v8/src/unofficial_napi_contextify.cc index 77f7bc5a9f..7bc61be478 100644 --- a/v8/src/unofficial_napi_contextify.cc +++ b/v8/src/unofficial_napi_contextify.cc @@ -85,6 +85,8 @@ struct ModuleWrapBindingState { ModuleWrapRecord* temporary_required_module_facade_original = nullptr; // Instantiations running (see InstantiationScope). int instantiations = 0; + // Synthetic modules whose evaluation steps are running. + int synthetic_steps_running = 0; }; napi_value GetSymbolsBindingProperty(napi_env env, const char* property_name); @@ -1123,7 +1125,10 @@ v8::MaybeLocal SyntheticModuleEvaluationSteps(v8::Local if (wrapper != nullptr && callback != nullptr && napi_typeof(env, callback, &callback_type) == napi_ok && callback_type == napi_function) { napi_value ignored = nullptr; - if (napi_call_function(env, wrapper, callback, 0, nullptr, &ignored) != napi_ok) { + GetModuleWrapState(env)->synthetic_steps_running++; + const napi_status called = napi_call_function(env, wrapper, callback, 0, nullptr, &ignored); + GetModuleWrapState(env)->synthetic_steps_running--; + if (called != napi_ok) { // Their exception, or the termination that stopped them, fails the // evaluation. if (!napi_v8_rethrow_pending_exception(env)) { @@ -2937,6 +2942,45 @@ static bool ThrowIfEvaluating(napi_env env, ModuleWrapRecord* record) { return true; } +// V8 evaluates a synthetic module that an instantiated source text module +// requests through Module::Evaluate, which aborts the process for one whose +// evaluation steps are running (a CHECK). Script reaches that from those +// steps, for example a CommonJS module that requires an ES module importing +// it, a cycle Node refuses too. So evaluating `record` is refused when what it +// would evaluate (the instantiated source text modules it reaches through the +// modules they were linked to) imports such a module. +static bool ThrowIfImportingAnEvaluatingSyntheticModule(napi_env env, ModuleWrapRecord* record) { + auto* state = GetModuleWrapState(env); + if (state == nullptr || state->synthetic_steps_running == 0) return false; + // A record another was linked to may be destroyed since. + const std::unordered_set live(state->modules.begin(), state->modules.end()); + v8::Isolate* isolate = env->isolate; + v8::HandleScope handle_scope(isolate); + std::vector pending{record}; + std::unordered_set seen{record}; + while (!pending.empty()) { + ModuleWrapRecord* current = pending.back(); + pending.pop_back(); + v8::Local module = current->module.Get(isolate); + if (module.IsEmpty() || !module->IsSourceTextModule() || + module->GetStatus() != v8::Module::kInstantiated) { + continue; + } + for (ModuleWrapRecord* linked : current->linked_requests) { + if (live.count(linked) == 0 || !seen.insert(linked).second) continue; + v8::Local requested = linked->module.Get(isolate); + if (requested.IsEmpty()) continue; + if (requested->IsSyntheticModule() && + requested->GetStatus() == v8::Module::kEvaluating) { + ThrowCodeError(env, "ERR_VM_MODULE_STATUS", "A synthetic module it imports is evaluating"); + return true; + } + pending.push_back(linked); + } + } + return false; +} + // V8 evaluates only an instantiated module and aborts the process for one // that is not. Instantiate it first, as QuickJS's JS_EvaluateModule does. static napi_status InstantiateForEvaluation(napi_env env, ModuleWrapRecord* record) { @@ -2959,6 +3003,7 @@ napi_status NAPI_CDECL unofficial_napi_module_wrap_evaluate( if (ThrowIfEvaluating(env, record)) return napi_pending_exception; const napi_status instantiated = InstantiateForEvaluation(env, record); if (instantiated != napi_ok) return instantiated; + if (ThrowIfImportingAnEvaluatingSyntheticModule(env, record)) return napi_pending_exception; v8::Isolate* isolate = env->isolate; v8::EscapableHandleScope handle_scope(isolate); v8::Local context = record->context.Get(isolate); @@ -2990,6 +3035,7 @@ napi_status NAPI_CDECL unofficial_napi_module_wrap_evaluate_sync( if (ThrowIfEvaluating(env, record)) return napi_pending_exception; const napi_status instantiated = InstantiateForEvaluation(env, record); if (instantiated != napi_ok) return instantiated; + if (ThrowIfImportingAnEvaluatingSyntheticModule(env, record)) return napi_pending_exception; v8::Isolate* isolate = env->isolate; v8::EscapableHandleScope handle_scope(isolate); v8::Local context = record->context.Get(isolate); @@ -3294,6 +3340,7 @@ napi_status NAPI_CDECL unofficial_napi_module_wrap_create_required_module_facade GetModuleWrapStateLocked(env)->temporary_required_module_facade_original = nullptr; } if (!instantiated) return ThrowTryCatchException(env, try_catch); + if (ThrowIfImportingAnEvaluatingSyntheticModule(env, record)) return napi_pending_exception; v8::Local evaluated; if (!facade->Evaluate(context).ToLocal(&evaluated)) return ThrowTryCatchException(env, try_catch); From 3fc90b625e8a998580160474b89218a2ce5d9d2d Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Fri, 6 Nov 2026 00:52:41 -0800 Subject: [PATCH 137/150] QuickJS: start no module link while one runs Found by the Codex review of the commits from "V8: report a module that is not instantiated as settled in the TLA check" to "Document known limitations: views, token hooks, upgrading from next". QuickJS runs script in the middle of a link when it throws there: a request that does not resolve, or an import the requested module does not export. The error gets its stack through an Error.prepareStackTrace getter. From that getter, script could reach the module calls while the first link held its modules half linked: - evaluate on the module being linked (status "linking") crashed with SIGSEGV; - instantiate linked it again, taking it to "linked" under the first link; - the facade and evaluate_sync went the same ways. "V8: start no module instantiation while one runs" gave V8 the same guard for its own path (an error's `code` setter), and V8 runs no getter there. The QuickJS provider now counts the links it runs (instantiate, the link evaluate does for a module not linked yet, the facade's). While one runs, these calls throw ERR_VM_MODULE_LINK_FAILURE ("A module instantiation is under way") and return napi_pending_exception, as V8 does: - instantiate; - evaluate and evaluate_sync on a module that is not linked; - the facade. evaluate now links such a module through the same counted call before JS_EvaluateModule, instead of letting JS_EvaluateModule link it. The failure message stays "Failed to evaluate module". Test: test_77 NoLinkStartsWhileOneRunsFromPrepareStackTrace, both engines. An Error.prepareStackTrace getter calls a native function once. That function makes the module calls on the module being instantiated, and instantiate on another one, as in NoInstantiationStartsWhileOneRuns. Instantiation must fail with an error pending, both for an unresolved request and for a missing export. On QuickJS the getter must have run, and the records must be the refusal for the five instantiating calls, "settled" for the check and ERR_MODULE_NOT_INSTANTIATED for the namespace. Afterwards the modules must link and instantiate. The must-run check is guarded to QuickJS, because V8 reads Error.prepareStackTrace only when a stack is read, so no script runs during its instantiation here. Before this commit, QuickJS crashed (exit 139). V8 passed. Co-Authored-By: Claude Opus 5.5 --- quickjs/src/internal/napi_module_wrap.cc | 51 ++++++++++++-- quickjs/src/internal/napi_module_wrap.h | 4 ++ tests/runners/test_77_module_wrap_state.cc | 80 ++++++++++++++++++++++ 3 files changed, 130 insertions(+), 5 deletions(-) diff --git a/quickjs/src/internal/napi_module_wrap.cc b/quickjs/src/internal/napi_module_wrap.cc index 00801f248c..75ece65155 100644 --- a/quickjs/src/internal/napi_module_wrap.cc +++ b/quickjs/src/internal/napi_module_wrap.cc @@ -683,14 +683,38 @@ napi_status napi_module_wrap__::link(unofficial_napi_module module, return napi_ok; } +// QuickJS runs script in the middle of a link when it throws there (an +// unresolved request, an import the requested module does not export): the +// error gets its stack through Error.prepareStackTrace. From there script can +// reach these calls again, with the modules of the first link half done: a +// second link takes one from "linking" to "linked" under the first, and +// evaluating one crashes. So no link starts while one runs, as on V8. +napi_status napi_module_wrap__::throw_if_linking() +{ + if (links_running_ == 0) + return napi_ok; + return throw_error("ERR_VM_MODULE_LINK_FAILURE", "A module instantiation is under way"); +} + +napi_status napi_module_wrap__::link_module(JSContext *ctx, JSModuleDef *module, const char *failure) +{ + napi_status status = throw_if_linking(); + if (status != napi_ok) + return status; + links_running_++; + const int linked = JS_LinkModule(ctx, module); + links_running_--; + if (linked < 0) + return return_pending_exception(failure); + 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_); - if (JS_LinkModule(entry->ctx, entry->module) < 0) - return return_pending_exception("Module linking failed"); - return napi_ok; + return link_module(entry->ctx, entry->module, "Module linking failed"); } // Evaluating a module whose evaluation is under way (from its own body or a @@ -750,6 +774,14 @@ napi_status napi_module_wrap__::evaluate_unless_terminated(record *entry, JSValu status = throw_if_importing_an_evaluating_synthetic_module(entry); if (status != napi_ok) return status; + // JS_EvaluateModule links a module that is not linked yet; that link is + // one as any other. + if (JS_GetModuleStatus(ctx_, entry->module) < JS_MODULE_STATUS_LINKED) + { + status = link_module(entry->ctx, entry->module, "Failed to evaluate module"); + if (status != napi_ok) + return status; + } // The module evaluates in its realm. JSValue promise = JS_EvaluateModule(entry->ctx, entry->module); if (JS_IsException(promise)) @@ -1097,6 +1129,10 @@ napi_status napi_module_wrap__::create_required_module_facade(unofficial_napi_mo if (status != napi_ok) return status; status = throw_if_importing_an_evaluating_synthetic_module(entry); + if (status != napi_ok) + return status; + // Linking the facade links that module too. + status = throw_if_linking(); if (status != napi_ok) return status; @@ -1125,12 +1161,17 @@ napi_status napi_module_wrap__::create_required_module_facade(unofficial_napi_mo } if (JS_GetModuleRequestCount(ctx, facade) < 1 || - JS_SetModuleRequestModule(ctx, facade, 0, entry->module) < 0 || - JS_LinkModule(ctx, facade) < 0) + JS_SetModuleRequestModule(ctx, facade, 0, entry->module) < 0) { JS_FreeValue(ctx, facade_value); return return_pending_exception("Failed to link required module facade"); } + status = link_module(ctx, facade, "Failed to link required module facade"); + if (status != napi_ok) + { + JS_FreeValue(ctx, facade_value); + return status; + } JSValue promise = JS_EvaluateModule(ctx, facade); if (JS_IsException(promise)) diff --git a/quickjs/src/internal/napi_module_wrap.h b/quickjs/src/internal/napi_module_wrap.h index 3ed5e42db7..069a7f8504 100644 --- a/quickjs/src/internal/napi_module_wrap.h +++ b/quickjs/src/internal/napi_module_wrap.h @@ -116,6 +116,8 @@ class napi_module_wrap__ JSValue clone_attributes(JSValueConst value) const; napi_status throw_error(const char *code, const char *message); napi_status return_pending_exception(const char *message); + napi_status throw_if_linking(); + napi_status link_module(JSContext *ctx, JSModuleDef *module, const char *failure); napi_status throw_if_evaluating(record *entry); napi_status throw_if_importing_an_evaluating_synthetic_module(record *entry); napi_status evaluate_unless_terminated(record *entry, JSValue *promise_out); @@ -142,6 +144,8 @@ class napi_module_wrap__ uint64_t facade_counter_ = 0; // Synthetic modules whose evaluation steps are running. int synthetic_steps_running_ = 0; + // Links running (see link_module). + int links_running_ = 0; // Subsystem lifecycle. bool torn_down_ = false; diff --git a/tests/runners/test_77_module_wrap_state.cc b/tests/runners/test_77_module_wrap_state.cc index e8f49c78ad..6079d25d0c 100644 --- a/tests/runners/test_77_module_wrap_state.cc +++ b/tests/runners/test_77_module_wrap_state.cc @@ -682,3 +682,83 @@ TEST_F(Test77ModuleWrapState, EvaluatingAModuleThatImportsAnEvaluatingSyntheticM } } } + +// No link starts while one runs, on QuickJS too: instantiate, and evaluate or +// the facade on a module that is not linked, are refused with +// ERR_VM_MODULE_LINK_FAILURE. QuickJS runs script in the middle of a link +// when it throws there (a request that does not resolve, an import the +// requested module does not export): the error gets its stack through an +// Error.prepareStackTrace getter. Evaluating the module being linked crashed +// (SIGSEGV), and a second link took the module from "linking" to "linked" +// under the first. The asking calls answer as usual, and the failed link +// leaves the modules ready to link and instantiate. +TEST_F(Test77ModuleWrapState, NoLinkStartsWhileOneRunsFromPrepareStackTrace) { + for (bool resolves : {false, true}) { + SCOPED_TRACE(resolves ? "missing export" : "unresolved request"); + EnvScope s(runtime_.get()); + InstantiationProbe probe; + napi_value fn = nullptr; + napi_value global = nullptr; + ASSERT_EQ(napi_create_function(s.env, "callsDuringInstantiation", NAPI_AUTO_LENGTH, + CallsDuringInstantiation, &probe, &fn), + napi_ok); + ASSERT_EQ(napi_get_global(s.env, &global), napi_ok); + ASSERT_EQ(napi_set_named_property(s.env, global, "callsDuringInstantiation", fn), napi_ok); + ASSERT_EQ(RunText(s.env, + "Object.defineProperty(Error, 'prepareStackTrace', {" + " configurable: true," + " get() { callsDuringInstantiation(); return undefined; }," + "}); 'set'"), + "set"); + unofficial_napi_module dependency = CreateSourceTextModule(s.env, "export const value = 1;"); + probe.module = CreateSourceTextModule( + s.env, "import { missing } from 'dependency'; export default missing;"); + probe.other = CreateSourceTextModule(s.env, "export const value = 1;"); + ASSERT_NE(dependency, nullptr); + ASSERT_NE(probe.module, nullptr); + ASSERT_NE(probe.other, nullptr); + ASSERT_EQ(unofficial_napi_module_wrap_link(s.env, dependency, 0, nullptr), napi_ok); + if (resolves) { + ASSERT_EQ(unofficial_napi_module_wrap_link(s.env, probe.module, 1, &dependency), napi_ok); + } + + EXPECT_EQ(unofficial_napi_module_wrap_instantiate(s.env, probe.module), + napi_pending_exception); + EXPECT_NE(TakePendingMessage(s.env), ""); +#if defined(NAPI_TEST_ENGINE_QUICKJS) + // V8 reads Error.prepareStackTrace only when a stack is read, so no + // script runs while it instantiates here. + EXPECT_TRUE(probe.entered); +#endif + if (probe.entered) { + const std::string refused = + "10 ERR_VM_MODULE_LINK_FAILURE: A module instantiation is under way"; + EXPECT_EQ(probe.outcomes, (std::vector{ + "instantiate " + refused, + "instantiate other " + refused, + "evaluate " + refused, + "evaluate_sync " + refused, + "facade " + refused, + "check 0 settled", + "namespace 10 ERR_MODULE_NOT_INSTANTIATED: " + "Module is not instantiated", + })); + } + EXPECT_EQ(Status(s.env, probe.module), kUninstantiated); + EXPECT_EQ(Status(s.env, probe.other), kUninstantiated); + + ASSERT_EQ(RunText(s.env, "delete Error.prepareStackTrace; 'gone'"), "gone"); + ASSERT_EQ(unofficial_napi_module_wrap_link(s.env, probe.other, 0, nullptr), napi_ok); + unofficial_napi_module linked = CreateSourceTextModule( + s.env, "import { value } from 'other'; export default value;"); + ASSERT_NE(linked, nullptr); + ASSERT_EQ(unofficial_napi_module_wrap_link(s.env, linked, 1, &probe.other), napi_ok); + ASSERT_EQ(unofficial_napi_module_wrap_instantiate(s.env, linked), napi_ok); + EXPECT_EQ(Status(s.env, linked), kInstantiated); + EXPECT_EQ(Status(s.env, probe.other), kInstantiated); + EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, linked), napi_ok); + EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, probe.module), napi_ok); + EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, probe.other), napi_ok); + EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, dependency), napi_ok); + } +} From ee92f4ab3318ad80d597ff4a0b6903535e09e9d3 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Fri, 6 Nov 2026 00:54:23 -0800 Subject: [PATCH 138/150] V8: give the facade's instantiation the source-phase resolver Found by the Codex review of the commits from "V8: report a module that is not instantiated as settled in the TLA check" to "Document known limitations: views, token hooks, upgrading from next". unofficial_napi_module_wrap_create_required_module_facade instantiated the facade's graph with LinkRequiredFacadeOriginal and no source resolver. "V8: instantiate the facade's module with its links, report its errors" made that instantiation instantiate the wrapped module with its links when it is not instantiated yet. A source-phase import in that module (`import source x from '...'`, which V8 parses behind --js-source-phase-imports) then made V8 call the missing resolver without checking it (SourceTextModule::PrepareInstantiate). That crashed with SIGSEGV. The facade now passes ModuleResolveSourceCallback, as instantiate does. A source-phase request resolves to the source object set on the module it was linked to, or throws ERR_SOURCE_PHASE_NOT_DEFINED. Test: test_77 RequiredModuleFacadeResolvesSourcePhaseImports, both engines. The test_77 fixture now configures the runtime with --js-source-phase-imports added to the default flags. Two modules `import source dependency from 'dependency'; export default dependency.marker;` are linked to a module whose source object has marker "its source". One is instantiated and evaluated, the other only given a facade. Both paths must give the same outcome. On V8 that must be "ok: its source". That check is guarded to V8, because QuickJS fails to instantiate such a module at all, the same way on both paths. Before this commit, V8 crashed in the facade (exit 139). QuickJS passed. Co-Authored-By: Claude Opus 5.5 --- tests/runners/test_77_module_wrap_state.cc | 77 +++++++++++++++++++++- v8/src/unofficial_napi_contextify.cc | 6 +- 2 files changed, 81 insertions(+), 2 deletions(-) diff --git a/tests/runners/test_77_module_wrap_state.cc b/tests/runners/test_77_module_wrap_state.cc index 6079d25d0c..440ef9de40 100644 --- a/tests/runners/test_77_module_wrap_state.cc +++ b/tests/runners/test_77_module_wrap_state.cc @@ -14,7 +14,21 @@ #include #include -class Test77ModuleWrapState : public FixtureTestBase {}; +// The default flags, and source-phase imports (`import source`), which V8 +// parses only behind a flag. +class Test77ModuleWrapState : public FixtureTestBase { + protected: + static void SetUpTestSuite() { + static constexpr char kFlags[] = "--expose-gc --js-float16array --js-source-phase-imports"; + unofficial_napi_runtime_options options{}; + options.size = sizeof(options); + options.version = UNOFFICIAL_NAPI_RUNTIME_OPTIONS_VERSION; + options.engine_flags = kFlags; + options.engine_flags_length = sizeof(kFlags) - 1; + ASSERT_EQ(unofficial_napi_configure_runtime(&options), napi_ok); + } + static void TearDownTestSuite() {} +}; namespace { @@ -762,3 +776,64 @@ TEST_F(Test77ModuleWrapState, NoLinkStartsWhileOneRunsFromPrepareStackTrace) { EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, dependency), napi_ok); } } + +namespace { + +// "ok: " when the module evaluates, through instantiate and +// evaluate or through the require() facade, else the error's message. +std::string DefaultExportOf(napi_env env, unofficial_napi_module module, bool facade) { + napi_value ns = nullptr; + if (facade) { + if (unofficial_napi_module_wrap_create_required_module_facade(env, module, &ns) != napi_ok) { + return TakePendingMessage(env); + } + } else { + napi_value promise = nullptr; + if (unofficial_napi_module_wrap_instantiate(env, module) != napi_ok || + unofficial_napi_module_wrap_evaluate(env, module, -1, false, &promise) != napi_ok) { + return TakePendingMessage(env); + } + const std::string outcome = PromiseOutcome(env, promise); + if (outcome != "resolved") return outcome; + if (unofficial_napi_module_wrap_get_namespace(env, module, &ns) != napi_ok) { + return TakePendingMessage(env); + } + } + napi_value value = nullptr; + if (napi_get_named_property(env, ns, "default", &value) != napi_ok) return ""; + return "ok: " + ValueText(env, value); +} + +} // namespace + +// The require() facade instantiates a module that has a source-phase import +// (`import source`) as instantiate does: its source object is the one set on +// the module it was linked to. V8 instantiated the facade's graph with no +// source resolver and crashed (SIGSEGV) calling it. QuickJS fails to +// instantiate such a module at all, through either path, the same way. +TEST_F(Test77ModuleWrapState, RequiredModuleFacadeResolvesSourcePhaseImports) { + EnvScope s(runtime_.get()); + unofficial_napi_module dependency = CreateSourceTextModule(s.env, "export const value = 1;"); + ASSERT_NE(dependency, nullptr); + napi_value source_object = nullptr; + ASSERT_EQ(napi_run_script(s.env, Str(s.env, "({ marker: 'its source' })"), &source_object), + napi_ok); + ASSERT_EQ(unofficial_napi_module_wrap_set_module_source_object(s.env, dependency, source_object), + napi_ok); + ASSERT_EQ(unofficial_napi_module_wrap_link(s.env, dependency, 0, nullptr), napi_ok); + std::string outcomes[2]; + for (bool facade : {false, true}) { + unofficial_napi_module module = CreateSourceTextModule( + s.env, "import source dependency from 'dependency'; export default dependency.marker;"); + ASSERT_NE(module, nullptr); + ASSERT_EQ(unofficial_napi_module_wrap_link(s.env, module, 1, &dependency), napi_ok); + outcomes[facade] = DefaultExportOf(s.env, module, facade); + EXPECT_FALSE(ExceptionPending(s.env)); + EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, module), napi_ok); + } + EXPECT_EQ(outcomes[1], outcomes[0]); +#if defined(NAPI_TEST_ENGINE_V8) + EXPECT_EQ(outcomes[0], "ok: its source"); +#endif + EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, dependency), napi_ok); +} diff --git a/v8/src/unofficial_napi_contextify.cc b/v8/src/unofficial_napi_contextify.cc index 7bc61be478..2bd04cfb24 100644 --- a/v8/src/unofficial_napi_contextify.cc +++ b/v8/src/unofficial_napi_contextify.cc @@ -3333,7 +3333,11 @@ napi_status NAPI_CDECL unofficial_napi_module_wrap_create_required_module_facade bool instantiated = false; { InstantiationScope instantiating(env); - instantiated = facade->InstantiateModule(context, LinkRequiredFacadeOriginal).FromMaybe(false); + // The module's source-phase requests resolve as instantiate resolves + // them. V8 calls the source resolver without checking that it is set. + instantiated = facade->InstantiateModule(context, LinkRequiredFacadeOriginal, + ModuleResolveSourceCallback) + .FromMaybe(false); } { std::lock_guard lock(g_module_wrap_mu); From eedc8784c5fde69c3ee47f804d455adb828cbc62 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Fri, 6 Nov 2026 00:55:56 -0800 Subject: [PATCH 139/150] V8: fail the require() facade of a module that throws or awaits Found by the Codex review of the commits from "V8: report a module that is not instantiated as settled in the TLA check" to "Document known limitations: views, token hooks, upgrading from next". unofficial_napi_module_wrap_create_required_module_facade evaluated the facade and returned its namespace whatever the evaluation's promise was. A module that threw (`export default 1; throw new Error('boom')`) rejects that promise; Evaluate itself succeeds, so the TryCatch from "V8: instantiate the facade's module with its links, report its errors" did not see it. A module that awaits forever leaves the promise pending. In both cases V8 returned napi_ok with a namespace, and nothing pending. QuickJS's facade fails both. Node's checks that the evaluation is fulfilled. The facade now does what evaluate_sync does with the promise: - rejected: it marks the promise handled (so the reject callback hears of the handler) and throws its reason; - pending: it throws ERR_REQUIRE_ASYNC_MODULE. It returns napi_pending_exception in both cases. A fulfilled evaluation is unchanged. The bug is older than f928811. Test: test_77 RequiredModuleFacadeOfAModuleThatThrowsOrAwaitsFails, both engines. - The facade of a linked module that throws "boom" must return napi_pending_exception, no namespace, "boom" pending, and the module at status 5. - The facade of one that awaits forever must fail the same way, with ERR_REQUIRE_ASYNC_MODULE and a message starting "require() cannot be used on an ESM graph with top-level await". Before this commit, V8 returned napi_ok and a namespace for both. QuickJS passed. Co-Authored-By: Claude Opus 5.5 --- tests/runners/test_77_module_wrap_state.cc | 38 ++++++++++++++++++++++ v8/src/unofficial_napi_contextify.cc | 17 ++++++++++ 2 files changed, 55 insertions(+) diff --git a/tests/runners/test_77_module_wrap_state.cc b/tests/runners/test_77_module_wrap_state.cc index 440ef9de40..28d6b59508 100644 --- a/tests/runners/test_77_module_wrap_state.cc +++ b/tests/runners/test_77_module_wrap_state.cc @@ -837,3 +837,41 @@ TEST_F(Test77ModuleWrapState, RequiredModuleFacadeResolvesSourcePhaseImports) { #endif EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, dependency), napi_ok); } + +// The require() facade gives no namespace for a module whose evaluation +// throws (the error is pending, as from evaluate_sync) or awaits (it fails +// with ERR_REQUIRE_ASYNC_MODULE), on both engines, as QuickJS did. Node +// checks that the evaluation is fulfilled before it returns the namespace. +// V8 returned napi_ok and the facade's namespace in both cases. +TEST_F(Test77ModuleWrapState, RequiredModuleFacadeOfAModuleThatThrowsOrAwaitsFails) { + EnvScope s(runtime_.get()); + unofficial_napi_module throws = + CreateSourceTextModule(s.env, "export default 1; throw new Error('boom');"); + unofficial_napi_module awaits = + CreateSourceTextModule(s.env, "export default 1; await new Promise(() => {});"); + ASSERT_NE(throws, nullptr); + ASSERT_NE(awaits, nullptr); + ASSERT_EQ(unofficial_napi_module_wrap_link(s.env, throws, 0, nullptr), napi_ok); + ASSERT_EQ(unofficial_napi_module_wrap_link(s.env, awaits, 0, nullptr), napi_ok); + + napi_value ns = nullptr; + EXPECT_EQ(unofficial_napi_module_wrap_create_required_module_facade(s.env, throws, &ns), + napi_pending_exception); + EXPECT_EQ(ns, nullptr); + EXPECT_EQ(TakePendingMessage(s.env), "boom"); + EXPECT_EQ(Status(s.env, throws), 5); + + ns = nullptr; + EXPECT_EQ(unofficial_napi_module_wrap_create_required_module_facade(s.env, awaits, &ns), + napi_pending_exception); + EXPECT_EQ(ns, nullptr); + const std::string pending = TakePendingCodeAndMessage(s.env); + EXPECT_EQ(pending.rfind("ERR_REQUIRE_ASYNC_MODULE: require() cannot be used on an ESM graph " + "with top-level await", + 0), + 0u) + << pending; + EXPECT_FALSE(ExceptionPending(s.env)); + EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, throws), napi_ok); + EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, awaits), napi_ok); +} diff --git a/v8/src/unofficial_napi_contextify.cc b/v8/src/unofficial_napi_contextify.cc index 2bd04cfb24..0134dc88d2 100644 --- a/v8/src/unofficial_napi_contextify.cc +++ b/v8/src/unofficial_napi_contextify.cc @@ -3348,6 +3348,23 @@ napi_status NAPI_CDECL unofficial_napi_module_wrap_create_required_module_facade v8::Local evaluated; if (!facade->Evaluate(context).ToLocal(&evaluated)) return ThrowTryCatchException(env, try_catch); + // The facade is for require(): a module whose evaluation threw or awaits + // gives no namespace, as evaluate_sync and QuickJS's facade do (Node checks + // that the evaluation is fulfilled). + if (evaluated->IsPromise()) { + v8::Local promise = evaluated.As(); + if (promise->State() == v8::Promise::kRejected) { + napi_value promise_value = napi_v8_wrap_value(env, promise); + const napi_status handled = unofficial_napi_mark_promise_as_handled(env, promise_value); + if (handled != napi_ok && handled != napi_pending_exception) return handled; + napi_throw(env, napi_v8_wrap_value(env, promise->Result())); + return napi_pending_exception; + } + if (promise->State() == v8::Promise::kPending) { + ThrowCodeError(env, "ERR_REQUIRE_ASYNC_MODULE", RequireAsyncModuleMessage("", "")); + return napi_pending_exception; + } + } *result_out = napi_v8_wrap_value(env, handle_scope.Escape(facade->GetModuleNamespace())); return napi_ok; } From 3ecd094f8bf3f08d5e3277f20c4653133b7ce0aa Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Fri, 6 Nov 2026 00:57:23 -0800 Subject: [PATCH 140/150] QuickJS: leave an evaluating module linked, and link none through one Found by the Codex review of the commits from "V8: report a module that is not instantiated as settled in the TLA check" to "Document known limitations: views, token hooks, upgrading from next". A module's body, or a synthetic module's evaluation steps, can reach native code that instantiates that same module. QuickJS's JS_LinkModule then linked the module again. js_link_module asserts against a module that is evaluating; that assert is compiled out of release builds, and without it the module went from "evaluating" back to "linked" while its evaluation ran. Instantiating a module that imports one being evaluated did the same to the imported module through js_inner_module_linking. V8 leaves such a module as it is (PrepareInstantiate and FinishInstantiate return early for it). The QuickJS provider now does this: - instantiate returns napi_ok and does nothing for a module that is linked already (linked, evaluating, or evaluated), as on V8; - every link it makes (instantiate, the link evaluate makes, the facade's) first walks what the link would reach: the module and, through the records they were linked to, the modules not linked yet. If one of them is evaluating, it throws ERR_VM_MODULE_STATUS ("A module it imports is evaluating") and returns napi_pending_exception. V8 instantiates such an importer, taking the evaluating module as linked. That difference stays, and the test pins it. Test: test_77 InstantiatingAModuleWhileItEvaluates, both engines. A synthetic module's steps, and then a source text module's body, instantiate the module itself and then a module that imports it. The first must give napi_ok with the module still at status 3. The second must give napi_ok and status 2 on V8, and the refusal above with status 0 on QuickJS. That one check is engine-specific, for the reason above. After the evaluation, the importer must instantiate and evaluate on both engines. Before this commit, QuickJS returned napi_ok for both calls with each module at status 2. V8 passed. Co-Authored-By: Claude Opus 5.5 --- quickjs/src/internal/napi_module_wrap.cc | 36 ++++++++-- quickjs/src/internal/napi_module_wrap.h | 2 +- tests/runners/test_77_module_wrap_state.cc | 80 ++++++++++++++++++++++ 3 files changed, 113 insertions(+), 5 deletions(-) diff --git a/quickjs/src/internal/napi_module_wrap.cc b/quickjs/src/internal/napi_module_wrap.cc index 75ece65155..150b4b1c59 100644 --- a/quickjs/src/internal/napi_module_wrap.cc +++ b/quickjs/src/internal/napi_module_wrap.cc @@ -696,11 +696,35 @@ napi_status napi_module_wrap__::throw_if_linking() return throw_error("ERR_VM_MODULE_LINK_FAILURE", "A module instantiation is under way"); } -napi_status napi_module_wrap__::link_module(JSContext *ctx, JSModuleDef *module, const char *failure) +// Links `module`, which links what `entry` was linked to. QuickJS's linker +// asserts that no module it reaches is evaluating, and without the assert +// takes one back to "linked" under its evaluation. V8 takes such a module as +// linked. Here a link that would reach one, through the modules not linked +// yet, is refused. +napi_status napi_module_wrap__::link_module(record *entry, JSContext *ctx, JSModuleDef *module, + const char *failure) { napi_status status = throw_if_linking(); if (status != napi_ok) return status; + const std::unordered_set live(records_.begin(), records_.end()); + std::vector pending{entry}; + std::unordered_set seen{entry}; + while (!pending.empty()) + { + record *current = pending.back(); + pending.pop_back(); + if (JS_GetModuleStatus(ctx_, current->module) != JS_MODULE_STATUS_UNLINKED) + continue; + for (record *linked : current->linked_records) + { + if (live.count(linked) == 0 || !seen.insert(linked).second) + continue; + if (JS_GetModuleStatus(ctx_, linked->module) == JS_MODULE_STATUS_EVALUATING) + return throw_error("ERR_VM_MODULE_STATUS", "A module it imports is evaluating"); + pending.push_back(linked); + } + } links_running_++; const int linked = JS_LinkModule(ctx, module); links_running_--; @@ -714,7 +738,11 @@ napi_status napi_module_wrap__::instantiate(unofficial_napi_module module) record *entry = find(module); if (entry == nullptr) return napi_util__::invalid_arg(env_); - return link_module(entry->ctx, entry->module, "Module linking failed"); + // A module linked already, also one whose evaluation is under way, stays as + // it is, as on V8. + if (JS_GetModuleStatus(ctx_, entry->module) >= JS_MODULE_STATUS_LINKED) + return napi_ok; + return link_module(entry, entry->ctx, entry->module, "Module linking failed"); } // Evaluating a module whose evaluation is under way (from its own body or a @@ -778,7 +806,7 @@ napi_status napi_module_wrap__::evaluate_unless_terminated(record *entry, JSValu // one as any other. if (JS_GetModuleStatus(ctx_, entry->module) < JS_MODULE_STATUS_LINKED) { - status = link_module(entry->ctx, entry->module, "Failed to evaluate module"); + status = link_module(entry, entry->ctx, entry->module, "Failed to evaluate module"); if (status != napi_ok) return status; } @@ -1166,7 +1194,7 @@ napi_status napi_module_wrap__::create_required_module_facade(unofficial_napi_mo JS_FreeValue(ctx, facade_value); return return_pending_exception("Failed to link required module facade"); } - status = link_module(ctx, facade, "Failed to link required module facade"); + status = link_module(entry, ctx, facade, "Failed to link required module facade"); if (status != napi_ok) { JS_FreeValue(ctx, facade_value); diff --git a/quickjs/src/internal/napi_module_wrap.h b/quickjs/src/internal/napi_module_wrap.h index 069a7f8504..264b2e18aa 100644 --- a/quickjs/src/internal/napi_module_wrap.h +++ b/quickjs/src/internal/napi_module_wrap.h @@ -117,7 +117,7 @@ class napi_module_wrap__ napi_status throw_error(const char *code, const char *message); napi_status return_pending_exception(const char *message); napi_status throw_if_linking(); - napi_status link_module(JSContext *ctx, JSModuleDef *module, const char *failure); + napi_status link_module(record *entry, JSContext *ctx, JSModuleDef *module, const char *failure); napi_status throw_if_evaluating(record *entry); napi_status throw_if_importing_an_evaluating_synthetic_module(record *entry); napi_status evaluate_unless_terminated(record *entry, JSValue *promise_out); diff --git a/tests/runners/test_77_module_wrap_state.cc b/tests/runners/test_77_module_wrap_state.cc index 28d6b59508..23746ef2b1 100644 --- a/tests/runners/test_77_module_wrap_state.cc +++ b/tests/runners/test_77_module_wrap_state.cc @@ -875,3 +875,83 @@ TEST_F(Test77ModuleWrapState, RequiredModuleFacadeOfAModuleThatThrowsOrAwaitsFai EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, throws), napi_ok); EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, awaits), napi_ok); } + +namespace { + +// Instantiates, from inside a module's evaluation, that module and then one +// that imports it; records what each call returned and threw, and the status +// each module had after it. +napi_value InstantiateDuringEvaluation(napi_env env, napi_callback_info info) { + void* data = nullptr; + EXPECT_EQ(napi_get_cb_info(env, info, nullptr, nullptr, nullptr, &data), napi_ok); + auto* probe = static_cast(data); + if (probe->entered) return nullptr; + probe->entered = true; + probe->outcomes.push_back( + "self " + Outcome(env, unofficial_napi_module_wrap_instantiate(env, probe->module)) + + ", status " + std::to_string(Status(env, probe->module))); + probe->outcomes.push_back( + "importer " + Outcome(env, unofficial_napi_module_wrap_instantiate(env, probe->other)) + + ", status " + std::to_string(Status(env, probe->other))); + return nullptr; +} + +} // namespace + +// Instantiating a module from inside its own evaluation (its body, or a +// synthetic module's steps) does nothing, as on V8: the module is linked +// already and goes on evaluating. QuickJS linked it again and took it from +// "evaluating" back to "linked" (its linker asserts against such a module). +// Instantiating a module that imports one being evaluated is engine-specific: +// V8 takes the evaluating module as linked and instantiates it; QuickJS's +// linker cannot link through one (it took it to "linked" too), so the +// QuickJS provider refuses it with ERR_VM_MODULE_STATUS. Either way it +// instantiates once the evaluation is done. +TEST_F(Test77ModuleWrapState, InstantiatingAModuleWhileItEvaluates) { + for (bool synthetic : {true, false}) { + SCOPED_TRACE(synthetic ? "synthetic" : "source text"); + EnvScope s(runtime_.get()); + InstantiationProbe probe; + napi_value fn = nullptr; + napi_value global = nullptr; + ASSERT_EQ(napi_create_function(s.env, "instantiateDuringEvaluation", NAPI_AUTO_LENGTH, + InstantiateDuringEvaluation, &probe, &fn), + napi_ok); + ASSERT_EQ(napi_get_global(s.env, &global), napi_ok); + ASSERT_EQ(napi_set_named_property(s.env, global, "instantiateDuringEvaluation", fn), napi_ok); + probe.module = + synthetic ? CreateSyntheticModule(s.env, "(function() { instantiateDuringEvaluation(); })") + : CreateSourceTextModule(s.env, + "instantiateDuringEvaluation(); export const value = 1;"); + probe.other = CreateSourceTextModule( + s.env, "import { value } from 'evaluating'; export default value;"); + ASSERT_NE(probe.module, nullptr); + ASSERT_NE(probe.other, nullptr); + ASSERT_EQ(unofficial_napi_module_wrap_link(s.env, probe.module, 0, nullptr), napi_ok); + ASSERT_EQ(unofficial_napi_module_wrap_link(s.env, probe.other, 1, &probe.module), napi_ok); + ASSERT_EQ(unofficial_napi_module_wrap_instantiate(s.env, probe.module), napi_ok); + + napi_value promise = nullptr; + ASSERT_EQ(unofficial_napi_module_wrap_evaluate(s.env, probe.module, -1, false, &promise), + napi_ok); + EXPECT_EQ(PromiseOutcome(s.env, promise), "resolved"); + ASSERT_TRUE(probe.entered); + ASSERT_EQ(probe.outcomes.size(), 2u); + EXPECT_EQ(probe.outcomes[0], "self 0, status 3"); +#if defined(NAPI_TEST_ENGINE_V8) + EXPECT_EQ(probe.outcomes[1], "importer 0, status 2"); +#else + EXPECT_EQ(probe.outcomes[1], + "importer 10 ERR_VM_MODULE_STATUS: A module it imports is evaluating, status 0"); +#endif + EXPECT_EQ(Status(s.env, probe.module), kEvaluated); + + ASSERT_EQ(unofficial_napi_module_wrap_instantiate(s.env, probe.other), napi_ok); + ASSERT_EQ(unofficial_napi_module_wrap_evaluate(s.env, probe.other, -1, false, &promise), + napi_ok); + EXPECT_EQ(PromiseOutcome(s.env, promise), "resolved"); + EXPECT_EQ(Status(s.env, probe.other), kEvaluated); + EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, probe.other), napi_ok); + EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, probe.module), napi_ok); + } +} From ea0d15b53a519a2e74d51fdfbfafc37be1762d3a Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Fri, 6 Nov 2026 00:57:54 -0800 Subject: [PATCH 141/150] Say what an f928811 bytecode-open struct does now, not "with no error" Found by the Codex review of the commits from "V8: report a module that is not instantiated as settled in the TLA check" to "Document known limitations: views, token hooks, upgrading from next". The upgrade section that "Document known limitations: views, token hooks, upgrading from next" added to docs/realms.md said a version-2 bytecode-open struct built against f928811 is "accepted and read wrongly, with no error". That overstates it. The struct passes the version and size checks, but both providers then refuse a NULL `source_text` (v8/src/unofficial_napi_contextify.cc and quickjs/src/unofficial_napi.cc, in unofficial_napi_bytecode_open). The old struct's realm sits where `source_text` is now read: - a NULL realm reads as a NULL source text, and the call returns napi_invalid_arg; - a realm handle is used as the source text's napi_value, which is undefined behavior. The table cell now says it passes the checks and is read wrongly, and the paragraph below the table gives both cases. Documentation only. Co-Authored-By: Claude Opus 5.5 --- docs/realms.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/realms.md b/docs/realms.md index 82d9ca5111..38dcdaece0 100644 --- a/docs/realms.md +++ b/docs/realms.md @@ -256,7 +256,7 @@ unaffected. | Struct, as built against f928811 | Native | wasm32 | Now | |---|---|---|---| -| Bytecode-open options, version 2 | 88 bytes, `realm_or_null` at 8 | 52 bytes, realm at 8 | Accepted and read wrongly, with no error | +| Bytecode-open options, version 2 | 88 bytes, `realm_or_null` at 8 | 52 bytes, realm at 8 | Passes the checks and is read wrongly | | Module-create options, version 2 | 64 bytes, `realm_or_null` at 32 | 40 bytes, realm at 20 | `napi_invalid_arg` | | Env hooks, version 2 | 40 bytes | 24 bytes | `napi_invalid_arg` | @@ -265,7 +265,9 @@ unaffected. `cache_policy`. So a struct built against f928811 passes the version and size checks, and every field after `version` is read from the wrong place: its realm as `source_text`, and the realm from its cache flags and - padding. + padding. With a NULL realm, `source_text` reads as NULL and the call + fails with `napi_invalid_arg`. With a realm, the realm handle is used as + the source text's `napi_value`, which is undefined behavior. - **Module-create options** version 2 now appends `realm_or_null` (offset 64 native, 40 wasm32) after `main`'s layout, which keeps `context_or_undefined` where f928811 had the realm. A struct built against From 946cf55fc66832fa99df71a32557e84af1255c26 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Fri, 6 Nov 2026 00:10:36 -0800 Subject: [PATCH 142/150] Say what memory_pressure finalizes, and that it frees no realm record main's memory pressure signal (#131) said what each engine collects, but not what runs when it does, which next's release contract and its realms make a question: does the call run finalizers or token callbacks? What a collection there frees is finalized as after any other. V8 queues the finalizers for the env's thread and runs none in the call, nor any JavaScript; a drain task goes to the enqueue hook, or else the next checkpoint runs them. QuickJS runs them in the call, in the env's realm, as collect_garbage does. Unlike collect_garbage, the call does not free the records of collected realms, so it runs no context-token callback: a realm it collects keeps its token until the next create_realm or collect_garbage, or the release. The release contract, which lists where V8 runs a collected realm's unassign callback, stays as it is. Tests pin both, on both engines. test_72's CriticalPressureFinalizesAsAnyCollection frees an object with a finalizer by critical pressure: V8 has not run it when the call returns and runs it at the next checkpoint, QuickJS has run it. test_71's MemoryPressureLeavesACollectedRealmsTokenToCollectGarbage collects a realm by critical pressure and checks that no token callback ran until collect_garbage unassigns its token (V8; QuickJS takes no token hooks). Neither is a fix: with memory_pressure changed to drain the finalizer queue and free collected realms, they fail ("V8 ran a finalizer inside the call", "memory pressure ran a token callback"). Each passed 50 runs in a row on both engines. Co-Authored-By: Claude Opus 5.5 --- include/unofficial_napi.h | 11 ++++ tests/runners/test_71_contextify_compat.cc | 56 +++++++++++++++++++ .../test_72_unofficial_memory_pressure.cc | 36 ++++++++++++ 3 files changed, 103 insertions(+) diff --git a/include/unofficial_napi.h b/include/unofficial_napi.h index 1787780c9d..0e8b9f42bb 100644 --- a/include/unofficial_napi.h +++ b/include/unofficial_napi.h @@ -476,6 +476,17 @@ typedef enum unofficial_napi_memory_pressure_level { // // QuickJS: moderate and critical run a full cycle collection. // +// What a collection here frees is finalized as after any other collection. +// V8 runs no JavaScript and no finalizer in the call: it queues the +// finalizers for the env's thread, where a task it posts through the enqueue +// hook (in the call), or else the next unofficial_napi_event_loop_checkpoint, +// runs them. QuickJS runs the finalizers of the values it frees in the call, +// in the env's realm, as unofficial_napi_collect_garbage does. Unlike +// unofficial_napi_collect_garbage, the call frees no record of a collected +// realm, so it runs no context-token callback (deprecated, V8 only): a realm +// it collects keeps its token until the next unofficial_napi_create_realm or +// unofficial_napi_collect_garbage, or the env's release. +// // Host-JavaScript providers: napi_generic_failure for every valid level. NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_memory_pressure( napi_env env, diff --git a/tests/runners/test_71_contextify_compat.cc b/tests/runners/test_71_contextify_compat.cc index b5b4195c98..d0ca668c84 100644 --- a/tests/runners/test_71_contextify_compat.cc +++ b/tests/runners/test_71_contextify_compat.cc @@ -1887,6 +1887,62 @@ TEST_F(Test71ContextifyCompat, ContextTokensFollowRealms) { EXPECT_FALSE(log.wrong_env); } +// unofficial_napi_memory_pressure frees no realm record, so it runs no token +// callback: a realm its collection takes keeps its token until +// unofficial_napi_collect_garbage frees the record. Token hooks are V8's +// only. +TEST_F(Test71ContextifyCompat, MemoryPressureLeavesACollectedRealmsTokenToCollectGarbage) { + EnvScope s(runtime_.get()); + TokenLog log; + log.env = s.env; + unofficial_napi_env_hooks hooks{}; + hooks.size = sizeof(hooks); + hooks.version = UNOFFICIAL_NAPI_ENV_HOOKS_VERSION; + hooks.data = &log; + hooks.context_token_assign_callback = AssignToken; + hooks.context_token_unassign_callback = UnassignToken; + uint64_t accepted = 0; + ASSERT_EQ(unofficial_napi_attach_env(s.env, &hooks, &accepted), napi_ok); + + // A realm that nothing keeps, and a weak reference that tells when its + // global is collected. + napi_ref weak = nullptr; + { + napi_handle_scope scope = nullptr; + ASSERT_EQ(napi_open_handle_scope(s.env, &scope), napi_ok); + napi_value global = nullptr; + ASSERT_NE(FreshRealm(s.env, &global), nullptr); + ASSERT_EQ(napi_create_reference(s.env, global, 0, &weak), napi_ok); + ASSERT_EQ(napi_close_handle_scope(s.env, scope), napi_ok); + } + const size_t assigned = log.events.size(); + + ASSERT_EQ(unofficial_napi_memory_pressure(s.env, unofficial_napi_memory_pressure_critical), + napi_ok); + bool collected = false; + { + napi_handle_scope scope = nullptr; + ASSERT_EQ(napi_open_handle_scope(s.env, &scope), napi_ok); + napi_value global = nullptr; + ASSERT_EQ(napi_get_reference_value(s.env, weak, &global), napi_ok); + collected = global == nullptr; + ASSERT_EQ(napi_close_handle_scope(s.env, scope), napi_ok); + } + EXPECT_TRUE(collected) << "critical pressure did not collect the realm's global"; + EXPECT_EQ(log.events.size(), assigned) << "memory pressure ran a token callback"; + + ASSERT_EQ(unofficial_napi_collect_garbage(s.env), napi_ok); +#if defined(NAPI_TEST_ENGINE_V8) + ASSERT_EQ(assigned, 1u); + ASSERT_EQ(log.events.size(), 2u); + EXPECT_EQ(log.events[1], std::make_pair('u', log.events[0].second)); +#else + EXPECT_TRUE(log.events.empty()); +#endif + ASSERT_EQ(napi_delete_reference(s.env, weak), napi_ok); + EXPECT_FALSE(log.wrong_env); +} + namespace { // The context-token hooks at release, for realms made while the env is diff --git a/tests/runners/test_72_unofficial_memory_pressure.cc b/tests/runners/test_72_unofficial_memory_pressure.cc index 71c0a13f3f..dd5a3e7d54 100644 --- a/tests/runners/test_72_unofficial_memory_pressure.cc +++ b/tests/runners/test_72_unofficial_memory_pressure.cc @@ -91,6 +91,20 @@ void DeleteGarbageReference(napi_env env) { g_garbage = nullptr; } +// makeFinalizedGarbage(): an object that points to itself, with a finalizer +// that counts its runs. +int g_finalized = 0; +void CountFinalize(node_api_basic_env /*env*/, void* /*data*/, void* /*hint*/) { + ++g_finalized; +} +napi_value MakeFinalizedGarbage(napi_env env, napi_callback_info /*info*/) { + napi_value object = nullptr; + EXPECT_EQ(napi_create_object(env, &object), napi_ok); + EXPECT_EQ(napi_set_named_property(env, object, "self", object), napi_ok); + EXPECT_EQ(napi_add_finalizer(env, object, nullptr, CountFinalize, nullptr, nullptr), napi_ok); + return nullptr; +} + #if defined(NAPI_TEST_ENGINE_V8) // runBigScript(): compiles and runs g_big_script. Its top-level function is // gone once the call returns, so only V8's compilation cache keeps the @@ -167,6 +181,28 @@ TEST_F(Test72UnofficialMemoryPressure, CriticalPressureCollectsGarbageNow) { DeleteGarbageReference(s.env); } +// Critical pressure finalizes what it frees as any collection does, which is +// engine-specific: V8 runs no finalizer in the call but queues it for the +// env's thread, where the next checkpoint runs it (the fixture attaches no +// enqueue hook to post it to); QuickJS runs it in the call. +TEST_F(Test72UnofficialMemoryPressure, CriticalPressureFinalizesAsAnyCollection) { + EnvScope s(runtime_.get()); + DefineGlobalFunction(s.env, "makeFinalizedGarbage", MakeFinalizedGarbage); + g_finalized = 0; + ASSERT_EQ(RunScript(s.env, "makeFinalizedGarbage();"), napi_ok); + ASSERT_EQ(g_finalized, 0); + + ASSERT_EQ(unofficial_napi_memory_pressure(s.env, kCritical), napi_ok); +#if defined(NAPI_TEST_ENGINE_V8) + EXPECT_EQ(g_finalized, 0) << "V8 ran a finalizer inside the call"; + uint32_t state = 0; + ASSERT_EQ(unofficial_napi_event_loop_checkpoint( + s.env, unofficial_napi_event_loop_checkpoint_microtasks, false, &state), + napi_ok); +#endif + EXPECT_EQ(g_finalized, 1) << "the value critical pressure freed was not finalized"; +} + #if defined(NAPI_TEST_ENGINE_V8) // The point of the call on V8: critical pressure keeps a script that ran // earlier compiled, and running it again uses that bytecode, where From d454d0d518a3b95d6f54195516a142d13f379372 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Fri, 6 Nov 2026 00:16:10 -0800 Subject: [PATCH 143/150] Say memory pressure in a release leaves buffer finalizers to its pass The memory pressure doc said V8 runs what a collection frees at the next checkpoint and QuickJS in the call. Called by a hook or finalizer while the env is released, neither holds for external ArrayBuffers and Buffers: V8's checkpoint drain leaves them to the release pass while the env is releasing (DrainFinalizerQueue takes no external finalizer then), and QuickJS's release_array_buffer returns without running the finalizer of a pending buffer while the env closes. Both then run in the release's order, as for any collection during the release. Say so. Codex found this reviewing the trial merge. Documentation only: the behaviour is next's, and its release tests cover it. Co-Authored-By: Claude Opus 5.5 --- include/unofficial_napi.h | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/include/unofficial_napi.h b/include/unofficial_napi.h index 0e8b9f42bb..8dca6ce0dc 100644 --- a/include/unofficial_napi.h +++ b/include/unofficial_napi.h @@ -481,11 +481,15 @@ typedef enum unofficial_napi_memory_pressure_level { // finalizers for the env's thread, where a task it posts through the enqueue // hook (in the call), or else the next unofficial_napi_event_loop_checkpoint, // runs them. QuickJS runs the finalizers of the values it frees in the call, -// in the env's realm, as unofficial_napi_collect_garbage does. Unlike -// unofficial_napi_collect_garbage, the call frees no record of a collected -// realm, so it runs no context-token callback (deprecated, V8 only): a realm -// it collects keeps its token until the next unofficial_napi_create_realm or -// unofficial_napi_collect_garbage, or the env's release. +// in the env's realm, as unofficial_napi_collect_garbage does. Called while +// the env is released (by a hook or finalizer that +// unofficial_napi_release_env runs), both engines leave the finalizers of +// external ArrayBuffers and Buffers to the release's pass, in its order, as +// for any collection then. Unlike unofficial_napi_collect_garbage, the call +// frees no record of a collected realm, so it runs no context-token callback +// (deprecated, V8 only): a realm it collects keeps its token until the next +// unofficial_napi_create_realm or unofficial_napi_collect_garbage, or the +// env's release. // // Host-JavaScript providers: napi_generic_failure for every valid level. NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_memory_pressure( From 1ea4aa1f36b0415e7b0e57fbdd8e89a1feae44ee Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Fri, 6 Nov 2026 03:51:43 -0800 Subject: [PATCH 144/150] Say a terminating env's checkpoint leaves pressure's finalizers queued The memory pressure doc, from "Say what memory_pressure finalizes, and that it frees no realm record", says that V8 runs what a collection frees in a task it posts through the enqueue hook, or else at the next unofficial_napi_event_loop_checkpoint. With next's sticky termination that does not hold while the env terminates: V8's checkpoint then fails with napi_pending_exception and runs no finalizer, so with no enqueue hook the finalizers wait for the first checkpoint after the cancel. The posted task, and QuickJS in the call, do run them while the env terminates, and a call a finalizer makes into JS is refused then, as any call into JS is. Say so, and pin it in test_72: - PressureWhileTerminatingFinalizesAsTheEngineDoes, both engines: critical pressure while the env terminates, with no enqueue hook. V8 runs no finalizer in the call, its checkpoint fails and runs none, and the first checkpoint after the cancel runs it, and its call into JS succeeds. QuickJS finalizes in the call; the finalizer's napi_get_named_property is refused with napi_pending_exception and no JS runs. - V8PressureWhileTerminatingPostsTheFinalizers: with an enqueue hook, the posted drain runs the finalizer while the env terminates, its call into JS is refused, and it does not run again after the cancel. Documentation and tests only: the behaviour is next's, so the tests pass as they are. They fail against three mutations of the providers: a V8 checkpoint that drains the finalizers before it refuses ("the checkpoint of a terminating env ran a finalizer"), a V8 drain task that does nothing while the env terminates ("the posted task did not finalize while terminating"), and a QuickJS memory_pressure that skips the collection while the env terminates ("QuickJS did not finalize in the call"). Each new test passed 50 runs in a row on each engine it runs on. Co-Authored-By: Claude Opus 5.5 --- include/unofficial_napi.h | 9 +- .../test_72_unofficial_memory_pressure.cc | 172 ++++++++++++++++++ 2 files changed, 179 insertions(+), 2 deletions(-) diff --git a/include/unofficial_napi.h b/include/unofficial_napi.h index 8dca6ce0dc..7871ee660d 100644 --- a/include/unofficial_napi.h +++ b/include/unofficial_napi.h @@ -481,8 +481,13 @@ typedef enum unofficial_napi_memory_pressure_level { // finalizers for the env's thread, where a task it posts through the enqueue // hook (in the call), or else the next unofficial_napi_event_loop_checkpoint, // runs them. QuickJS runs the finalizers of the values it frees in the call, -// in the env's realm, as unofficial_napi_collect_garbage does. Called while -// the env is released (by a hook or finalizer that +// in the env's realm, as unofficial_napi_collect_garbage does. While the env +// terminates, they still run there (V8's in the posted task, QuickJS's in +// the call), and a call one makes into JavaScript is refused, as any is +// then. V8's checkpoint fails then and runs none of them, so with no +// enqueue hook V8 runs them at the first checkpoint after +// unofficial_napi_cancel_terminate_execution. Called while the env is +// released (by a hook or finalizer that // unofficial_napi_release_env runs), both engines leave the finalizers of // external ArrayBuffers and Buffers to the release's pass, in its order, as // for any collection then. Unlike unofficial_napi_collect_garbage, the call diff --git a/tests/runners/test_72_unofficial_memory_pressure.cc b/tests/runners/test_72_unofficial_memory_pressure.cc index dd5a3e7d54..4bc1322787 100644 --- a/tests/runners/test_72_unofficial_memory_pressure.cc +++ b/tests/runners/test_72_unofficial_memory_pressure.cc @@ -18,6 +18,7 @@ #include #include +#include #if defined(NAPI_TEST_ENGINE_V8) #include @@ -105,6 +106,41 @@ napi_value MakeFinalizedGarbage(napi_env env, napi_callback_info /*info*/) { return nullptr; } +// makeFinalizedGarbageCallingJs(): as makeFinalizedGarbage(), with a +// finalizer that calls setFlag(), JS that sets globalThis.finalizerRanJs. +int g_js_finalized = 0; +napi_status g_finalizer_get_status = napi_ok; +napi_status g_finalizer_call_status = napi_ok; +void CallJsFinalize(napi_env env, void* /*data*/, void* /*hint*/) { + ++g_js_finalized; + napi_value global = nullptr; + napi_value set_flag = nullptr; + napi_value ignored = nullptr; + if (napi_get_global(env, &global) != napi_ok) return; + g_finalizer_get_status = napi_get_named_property(env, global, "setFlag", &set_flag); + if (g_finalizer_get_status != napi_ok) return; + g_finalizer_call_status = napi_call_function(env, global, set_flag, 0, nullptr, &ignored); +} +napi_value MakeFinalizedGarbageCallingJs(napi_env env, napi_callback_info /*info*/) { + napi_value object = nullptr; + EXPECT_EQ(napi_create_object(env, &object), napi_ok); + EXPECT_EQ(napi_set_named_property(env, object, "self", object), napi_ok); + EXPECT_EQ(napi_add_finalizer(env, object, nullptr, CallJsFinalize, nullptr, nullptr), napi_ok); + return nullptr; +} + +void MakeGarbageCallingJs(napi_env env) { + DefineGlobalFunction(env, "makeFinalizedGarbageCallingJs", MakeFinalizedGarbageCallingJs); + g_js_finalized = 0; + g_finalizer_get_status = napi_ok; + g_finalizer_call_status = napi_ok; + ASSERT_EQ(RunScript(env, + "globalThis.setFlag = () => { globalThis.finalizerRanJs = true; };" + "makeFinalizedGarbageCallingJs();"), + napi_ok); + ASSERT_EQ(g_js_finalized, 0); +} + #if defined(NAPI_TEST_ENGINE_V8) // runBigScript(): compiles and runs g_big_script. Its top-level function is // gone once the call returns, so only V8's compilation cache keeps the @@ -203,6 +239,142 @@ TEST_F(Test72UnofficialMemoryPressure, CriticalPressureFinalizesAsAnyCollection) EXPECT_EQ(g_finalized, 1) << "the value critical pressure freed was not finalized"; } +// While the env terminates, what critical pressure frees is finalized where +// it otherwise is, and a call the finalizer makes into JS is refused. V8's +// checkpoint fails then and runs no finalizer, so with no enqueue hook (the +// fixture attaches none) V8 runs it at the first checkpoint after the cancel, +// where its call into JS succeeds. QuickJS runs it in the call, terminating. +TEST_F(Test72UnofficialMemoryPressure, PressureWhileTerminatingFinalizesAsTheEngineDoes) { + EnvScope s(runtime_.get()); + MakeGarbageCallingJs(s.env); + + ASSERT_EQ(unofficial_napi_terminate_execution(s.env), napi_ok); + ASSERT_EQ(unofficial_napi_memory_pressure(s.env, kCritical), napi_ok); +#if defined(NAPI_TEST_ENGINE_V8) + EXPECT_EQ(g_js_finalized, 0) << "V8 ran a finalizer inside the call"; + uint32_t state = 0; + EXPECT_EQ(unofficial_napi_event_loop_checkpoint( + s.env, unofficial_napi_event_loop_checkpoint_microtasks, false, &state), + napi_pending_exception); + EXPECT_EQ(g_js_finalized, 0) << "the checkpoint of a terminating env ran a finalizer"; + + ASSERT_EQ(unofficial_napi_cancel_terminate_execution(s.env), napi_ok); + ASSERT_EQ(unofficial_napi_event_loop_checkpoint( + s.env, unofficial_napi_event_loop_checkpoint_microtasks, false, &state), + napi_ok); + EXPECT_EQ(g_js_finalized, 1) << "the first checkpoint after the cancel did not finalize"; + EXPECT_EQ(g_finalizer_call_status, napi_ok); + EXPECT_EQ(RunScriptToString(s.env, "String(globalThis.finalizerRanJs)"), "true"); +#else + EXPECT_EQ(g_js_finalized, 1) << "QuickJS did not finalize in the call"; + EXPECT_EQ(g_finalizer_get_status, napi_pending_exception) + << "the finalizer's call into JS was not refused"; + ASSERT_EQ(unofficial_napi_cancel_terminate_execution(s.env), napi_ok); + EXPECT_EQ(RunScriptToString(s.env, "String(globalThis.finalizerRanJs)"), "undefined"); +#endif +} + +#if defined(NAPI_TEST_ENGINE_V8) +namespace { + +struct PostedTask { + unofficial_napi_foreground_task_callback callback; + void* data; + unofficial_napi_foreground_task_cleanup cleanup; +}; +std::vector* g_posted = nullptr; +napi_env g_posting_env = nullptr; +bool g_queue_closed = false; + +// Keeps every task for the test to run on the env's thread, until the queue +// closes; then releases each task it is given. +napi_status QueueTask(void* /*target*/, + unofficial_napi_foreground_task_callback callback, + void* data, + unofficial_napi_foreground_task_cleanup cleanup, + uint64_t /*delay_millis*/) { + if (g_queue_closed) { + if (cleanup != nullptr) cleanup(g_posting_env, data); + return napi_generic_failure; + } + g_posted->push_back({callback, data, cleanup}); + return napi_ok; +} + +// Releases the queued tasks without running them, and every later one, as an +// embedder does when the env shuts down. +void CloseQueue() { + g_queue_closed = true; + std::vector tasks; + tasks.swap(*g_posted); + for (const PostedTask& task : tasks) { + if (task.cleanup != nullptr) task.cleanup(g_posting_env, task.data); + } +} + +// Closes the queue when it goes out of scope, a failed ASSERT included. +// Declared after the env, it closes the queue before the env's release, so +// that every task the hook was given is released. +struct QueueCloser { + ~QueueCloser() { CloseQueue(); } +}; + +// Runs the queued tasks, and those they queue, as an event loop turn would. +size_t RunPostedTasks(napi_env env) { + size_t ran = 0; + for (int round = 0; round < 16 && !g_posted->empty(); ++round) { + std::vector tasks; + tasks.swap(*g_posted); + for (const PostedTask& task : tasks) { + task.callback(env, task.data); + if (task.cleanup != nullptr) task.cleanup(env, task.data); + ++ran; + } + } + return ran; +} + +} // namespace + +// With an enqueue hook, V8 posts the drain of the finalizers as a task, and +// the task runs them also while the env terminates: the finalizer's call into +// JS is refused then, and it does not run again after the cancel. +TEST_F(Test72UnofficialMemoryPressure, V8PressureWhileTerminatingPostsTheFinalizers) { + std::vector posted; + g_posted = &posted; + g_queue_closed = false; + EnvScope s(runtime_.get()); + g_posting_env = s.env; + QueueCloser closer; + unofficial_napi_env_hooks hooks{}; + hooks.size = sizeof(hooks); + hooks.version = UNOFFICIAL_NAPI_ENV_HOOKS_VERSION; + hooks.enqueue_foreground_task_callback = QueueTask; + uint64_t accepted = 0; + ASSERT_EQ(unofficial_napi_attach_env(s.env, &hooks, &accepted), napi_ok); + ASSERT_NE(accepted & unofficial_napi_env_hook_enqueue_foreground_task, 0u); + MakeGarbageCallingJs(s.env); + RunPostedTasks(s.env); + + ASSERT_EQ(unofficial_napi_terminate_execution(s.env), napi_ok); + ASSERT_EQ(unofficial_napi_memory_pressure(s.env, kCritical), napi_ok); + EXPECT_EQ(g_js_finalized, 0) << "V8 ran a finalizer inside the call"; + EXPECT_GT(RunPostedTasks(s.env), 0u) << "the drain was not posted"; + EXPECT_EQ(g_js_finalized, 1) << "the posted task did not finalize while terminating"; + EXPECT_EQ(g_finalizer_get_status, napi_pending_exception) + << "the finalizer's call into JS was not refused"; + + ASSERT_EQ(unofficial_napi_cancel_terminate_execution(s.env), napi_ok); + uint32_t state = 0; + ASSERT_EQ(unofficial_napi_event_loop_checkpoint( + s.env, unofficial_napi_event_loop_checkpoint_microtasks, false, &state), + napi_ok); + RunPostedTasks(s.env); + EXPECT_EQ(g_js_finalized, 1); + EXPECT_EQ(RunScriptToString(s.env, "String(globalThis.finalizerRanJs)"), "undefined"); +} +#endif + #if defined(NAPI_TEST_ENGINE_V8) // The point of the call on V8: critical pressure keeps a script that ran // earlier compiled, and running it again uses that bytecode, where From 8a80a47f50c237ca1fe63bccb93a2375671beaeb Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Fri, 6 Nov 2026 04:03:38 -0800 Subject: [PATCH 145/150] Keep test_71's token log alive until the env is released test_71's MemoryPressureLeavesACollectedRealmsTokenToCollectGarbage, from "Say what memory_pressure finalizes, and that it frees no realm record", declared the TokenLog that the context-token callbacks write to after the EnvScope, so the log was destroyed before the env was released. When a failed ASSERT ends the test while the realm it makes is still alive, the release unassigns that realm's token and the callback writes to the destroyed log. A regression that the test should report as a failure became a memory error. The log is now declared before the env. Test-only. Fails first: with an ASSERT_TRUE(false) injected after the realm is made, the V8 Release+ASan build reported "AddressSanitizer: stack-use-after-scope ... in UnassignToken" (exit 134) before this change, and a plain test failure (exit 1) after it. Without the injection the test passes under ASan. Found by a Codex review of the merge's follow-ups. Co-Authored-By: Claude Opus 5.5 --- tests/runners/test_71_contextify_compat.cc | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/tests/runners/test_71_contextify_compat.cc b/tests/runners/test_71_contextify_compat.cc index d0ca668c84..2277e94e62 100644 --- a/tests/runners/test_71_contextify_compat.cc +++ b/tests/runners/test_71_contextify_compat.cc @@ -1892,8 +1892,10 @@ TEST_F(Test71ContextifyCompat, ContextTokensFollowRealms) { // unofficial_napi_collect_garbage frees the record. Token hooks are V8's // only. TEST_F(Test71ContextifyCompat, MemoryPressureLeavesACollectedRealmsTokenToCollectGarbage) { - EnvScope s(runtime_.get()); + // Declared before the env: the release unassigns the token of a realm still + // alive when a failed ASSERT ends the test, and the callback writes here. TokenLog log; + EnvScope s(runtime_.get()); log.env = s.env; unofficial_napi_env_hooks hooks{}; hooks.size = sizeof(hooks); From 80b591ecb547623a0033d783c66186bc029c9d32 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Fri, 6 Nov 2026 04:04:20 -0800 Subject: [PATCH 146/150] Say only V8's collect_garbage frees the records of collected realms The memory pressure doc, from "Say what memory_pressure finalizes, and that it frees no realm record", said that unlike unofficial_napi_collect_garbage the call frees no record of a collected realm. That is so on V8 only. QuickJS's unofficial_napi_collect_garbage runs JS_RunGC and nothing else (quickjs/src/unofficial_napi.cc), and outside the env's release QuickJS frees the records of collected realms only in prune_collected_records, whose one caller is create_context_record, which unofficial_napi_create_realm runs (quickjs/src/internal/napi_contextify.cc). The doc now says that the call frees no such record on either engine, that this differs from collect_garbage on V8, where a collected realm keeps its context token until the next create_realm or collect_garbage or the release, and that QuickJS frees them at the next create_realm. test_71's MemoryPressureLeavesACollectedRealmsTokenToCollectGarbage already pins the V8 part (no token callback in the call, the unassign in the next collect_garbage). A new QuickJS test in test_72, QuickJSFreesACollectedRealmsRecordAtTheNextRealm, pins the QuickJS part through the realm's host-defined option id, which the record holds until it is freed: the id's finalizer has not run after critical pressure collected the realm, nor after collect_garbage, and has run once the next create_realm returns. The test passes as the code is, and fails ("memory pressure freed the collected realm's record", "collect_garbage freed the collected realm's record") with QuickJS's memory_pressure changed to free the collected records after its collection. It passed 50 runs in a row. Found by a Codex review of the merge's follow-ups. Co-Authored-By: Claude Opus 5.5 --- include/unofficial_napi.h | 11 +-- .../test_72_unofficial_memory_pressure.cc | 72 +++++++++++++++++++ 2 files changed, 78 insertions(+), 5 deletions(-) diff --git a/include/unofficial_napi.h b/include/unofficial_napi.h index 7871ee660d..ccbe760c9c 100644 --- a/include/unofficial_napi.h +++ b/include/unofficial_napi.h @@ -490,11 +490,12 @@ typedef enum unofficial_napi_memory_pressure_level { // released (by a hook or finalizer that // unofficial_napi_release_env runs), both engines leave the finalizers of // external ArrayBuffers and Buffers to the release's pass, in its order, as -// for any collection then. Unlike unofficial_napi_collect_garbage, the call -// frees no record of a collected realm, so it runs no context-token callback -// (deprecated, V8 only): a realm it collects keeps its token until the next -// unofficial_napi_create_realm or unofficial_napi_collect_garbage, or the -// env's release. +// for any collection then. The call frees no record of a collected realm, so +// it runs no context-token callback (deprecated, V8 only). On V8 that differs +// from unofficial_napi_collect_garbage, which frees them: a realm the call +// collects keeps its token until the next unofficial_napi_create_realm or +// unofficial_napi_collect_garbage, or the env's release. QuickJS frees them +// in the next unofficial_napi_create_realm after either call. // // Host-JavaScript providers: napi_generic_failure for every valid level. NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_memory_pressure( diff --git a/tests/runners/test_72_unofficial_memory_pressure.cc b/tests/runners/test_72_unofficial_memory_pressure.cc index 4bc1322787..24b11f3492 100644 --- a/tests/runners/test_72_unofficial_memory_pressure.cc +++ b/tests/runners/test_72_unofficial_memory_pressure.cc @@ -420,3 +420,75 @@ TEST_F(Test72UnofficialMemoryPressure, V8CriticalPressureKeepsCompiledScripts) { g_big_script.clear(); } #endif + +#if defined(NAPI_TEST_ENGINE_QUICKJS) +namespace { + +// Counts the runs of the finalizer of a realm's host-defined option id, which +// the realm's record holds until it is freed. +int g_host_id_finalized = 0; +void CountHostIdFinalize(napi_env /*env*/, void* /*data*/, void* /*hint*/) { + ++g_host_id_finalized; +} + +// Makes a realm that nothing keeps, whose host-defined option id has a +// finalizer, and returns a weak reference to its global. +napi_ref MakeUnreachableRealm(napi_env env) { + napi_handle_scope scope = nullptr; + EXPECT_EQ(napi_open_handle_scope(env, &scope), napi_ok); + napi_value host_id = nullptr; + EXPECT_EQ(napi_create_object(env, &host_id), napi_ok); + EXPECT_EQ(napi_add_finalizer(env, host_id, nullptr, CountHostIdFinalize, nullptr, nullptr), + napi_ok); + unofficial_napi_realm_options options; + unofficial_napi_realm_options_init(&options); + options.host_defined_option_id = host_id; + unofficial_napi_realm realm = nullptr; + napi_value global = nullptr; + EXPECT_EQ(unofficial_napi_create_realm(env, &options, &realm, &global), napi_ok); + napi_ref weak = nullptr; + EXPECT_EQ(napi_create_reference(env, global, 0, &weak), napi_ok); + EXPECT_EQ(napi_close_handle_scope(env, scope), napi_ok); + return weak; +} + +bool Collected(napi_env env, napi_ref weak) { + napi_handle_scope scope = nullptr; + EXPECT_EQ(napi_open_handle_scope(env, &scope), napi_ok); + napi_value value = nullptr; + EXPECT_EQ(napi_get_reference_value(env, weak, &value), napi_ok); + EXPECT_EQ(napi_close_handle_scope(env, scope), napi_ok); + return value == nullptr; +} + +} // namespace + +// QuickJS frees the record of a collected realm, and with it the realm's +// host-defined option id, only when it next makes a realm: neither critical +// pressure nor unofficial_napi_collect_garbage frees it. +TEST_F(Test72UnofficialMemoryPressure, QuickJSFreesACollectedRealmsRecordAtTheNextRealm) { + EnvScope s(runtime_.get()); + g_host_id_finalized = 0; + napi_ref weak = MakeUnreachableRealm(s.env); + ASSERT_NE(weak, nullptr); + EXPECT_FALSE(Collected(s.env, weak)); + + ASSERT_EQ(unofficial_napi_memory_pressure(s.env, kCritical), napi_ok); + EXPECT_TRUE(Collected(s.env, weak)) << "critical pressure did not collect the realm"; + EXPECT_EQ(g_host_id_finalized, 0) << "memory pressure freed the collected realm's record"; + + ASSERT_EQ(unofficial_napi_collect_garbage(s.env), napi_ok); + EXPECT_EQ(g_host_id_finalized, 0) << "collect_garbage freed the collected realm's record"; + + { + napi_handle_scope scope = nullptr; + ASSERT_EQ(napi_open_handle_scope(s.env, &scope), napi_ok); + unofficial_napi_realm realm = nullptr; + napi_value global = nullptr; + ASSERT_EQ(unofficial_napi_create_realm(s.env, nullptr, &realm, &global), napi_ok); + ASSERT_EQ(napi_close_handle_scope(s.env, scope), napi_ok); + } + EXPECT_EQ(g_host_id_finalized, 1) << "the next realm did not free the collected realm's record"; + ASSERT_EQ(napi_delete_reference(s.env, weak), napi_ok); +} +#endif From 4a6e4b45e9cdc3ff8d2123fd99f24f36f82fc321 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Fri, 6 Nov 2026 07:33:53 -0800 Subject: [PATCH 147/150] Renumber the termination-until-cancelled runner to test_78 main now has its own tests/runners/test_76_env_cpu_profile.cc (V8, from "Write a V8 CPU profile per env when NAPI_V8_CPU_PROFILE_DIR is set"), so next's test_76 would share its number once main is merged. It moves to the next free number above every runner in either tree (main has 72, 73, 74 and 76; next has 75 and 77): - tests/runners/test_76_termination_until_cancelled.cc becomes test_78_termination_until_cancelled.cc, suite Test78TerminationUntilCancelled. tests/CMakeLists.txt registers it under the new name, with its NAPI_VERSION=10 definition. No doc, header, script or other test names it. The tests are unchanged otherwise. Test: both engines build; V8 327/327 and QuickJS 291/291 pass. The runner keeps its cases: 20 on V8 and 15 on QuickJS, which compiles out the V8-only ones. Co-Authored-By: Claude Opus 5.5 --- tests/CMakeLists.txt | 6 +-- ...=> test_78_termination_until_cancelled.cc} | 42 +++++++++---------- 2 files changed, 24 insertions(+), 24 deletions(-) rename tests/runners/{test_76_termination_until_cancelled.cc => test_78_termination_until_cancelled.cc} (97%) diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt index df64cf28da..99c8842e71 100644 --- a/tests/CMakeLists.txt +++ b/tests/CMakeLists.txt @@ -343,10 +343,10 @@ add_fixture_test(${_napi_test_prefix}_test_75_hooks_keep_termination runners/test_75_hooks_keep_termination.cc ) target_compile_definitions(${_napi_test_prefix}_test_75_hooks_keep_termination PRIVATE NAPI_VERSION=10) -add_fixture_test(${_napi_test_prefix}_test_76_termination_until_cancelled - runners/test_76_termination_until_cancelled.cc +add_fixture_test(${_napi_test_prefix}_test_78_termination_until_cancelled + runners/test_78_termination_until_cancelled.cc ) -target_compile_definitions(${_napi_test_prefix}_test_76_termination_until_cancelled PRIVATE NAPI_VERSION=10) +target_compile_definitions(${_napi_test_prefix}_test_78_termination_until_cancelled PRIVATE NAPI_VERSION=10) add_fixture_test(${_napi_test_prefix}_test_77_module_wrap_state runners/test_77_module_wrap_state.cc ) diff --git a/tests/runners/test_76_termination_until_cancelled.cc b/tests/runners/test_78_termination_until_cancelled.cc similarity index 97% rename from tests/runners/test_76_termination_until_cancelled.cc rename to tests/runners/test_78_termination_until_cancelled.cc index ac256db508..9e6c7b960f 100644 --- a/tests/runners/test_76_termination_until_cancelled.cc +++ b/tests/runners/test_78_termination_until_cancelled.cc @@ -27,7 +27,7 @@ #include #endif -class Test76TerminationUntilCancelled : public FixtureTestBase {}; +class Test78TerminationUntilCancelled : public FixtureTestBase {}; namespace { @@ -459,7 +459,7 @@ constexpr char kEvaluateModuleInTryCatch[] = // TryCatch records a termination as a null exception, which V8 would // otherwise throw into that JS as a catchable null; QuickJS drops its // uncatchable error at the cancel. -TEST_F(Test76TerminationUntilCancelled, CancelledInsideANativeFunction) { +TEST_F(Test78TerminationUntilCancelled, CancelledInsideANativeFunction) { EnvScope s(runtime_.get()); InstallHelpers(s.env); EXPECT_EQ(RunScript(s.env, @@ -493,7 +493,7 @@ napi_value ThrowTerminateCancel(napi_env env, napi_callback_info /*info*/) { } } // namespace -TEST_F(Test76TerminationUntilCancelled, CancelKeepsAnExceptionThrownBefore) { +TEST_F(Test78TerminationUntilCancelled, CancelKeepsAnExceptionThrownBefore) { EnvScope s(runtime_.get()); InstallHelpers(s.env); DefineGlobalFunction(s.env, "throwTerminateCancel", ThrowTerminateCancel); @@ -508,7 +508,7 @@ TEST_F(Test76TerminationUntilCancelled, CancelKeepsAnExceptionThrownBefore) { // The same inside the import.meta hook, which throws what its callback left // pending from the import.meta expression. -TEST_F(Test76TerminationUntilCancelled, CancelledInsideAModuleHook) { +TEST_F(Test78TerminationUntilCancelled, CancelledInsideAModuleHook) { EnvScope s(runtime_.get()); InstallHelpers(s.env); SetModuleHooks(s.env, nullptr, @@ -534,7 +534,7 @@ TEST_F(Test76TerminationUntilCancelled, CancelledInsideAModuleHook) { // timeout expires too: the termination is not the timeout's to cancel, and // must not come back as the timeout's catchable error. QuickJS has no // timeout, so only the termination stops the script there. -TEST_F(Test76TerminationUntilCancelled, ScriptTimeoutKeepsTheEmbeddersTermination) { +TEST_F(Test78TerminationUntilCancelled, ScriptTimeoutKeepsTheEmbeddersTermination) { EnvScope s(runtime_.get()); InstallHelpers(s.env); g_status = napi_ok; @@ -548,7 +548,7 @@ TEST_F(Test76TerminationUntilCancelled, ScriptTimeoutKeepsTheEmbeddersTerminatio // The run a termination stopped leaves it in effect: the next run fails too // until the termination is cancelled. V8 forgets a termination once the // outermost JS frame has unwound. -TEST_F(Test76TerminationUntilCancelled, TopLevelRunKeepsTheTerminationUntilCancelled) { +TEST_F(Test78TerminationUntilCancelled, TopLevelRunKeepsTheTerminationUntilCancelled) { EnvScope s(runtime_.get()); InstallHelpers(s.env); napi_value mark = Eval(s.env, "() => { afterCall = 'yes'; }"); @@ -566,7 +566,7 @@ TEST_F(Test76TerminationUntilCancelled, TopLevelRunKeepsTheTerminationUntilCance // of the termination. On V8 an N-API call that enters V8 clears the // termination, and the trampoline then threw the null the TryCatch recorded // for it, which the JS caught. -TEST_F(Test76TerminationUntilCancelled, NativeCallsAfterTheTermination) { +TEST_F(Test78TerminationUntilCancelled, NativeCallsAfterTheTermination) { for (int kind = 0; kind < kAfterCallCount; ++kind) { SCOPED_TRACE(kAfterCalls[kind]); EnvScope s(runtime_.get()); @@ -581,7 +581,7 @@ TEST_F(Test76TerminationUntilCancelled, NativeCallsAfterTheTermination) { // Native code whose call into JS a termination failed, and which then makes // an N-API call that runs JS. On V8 the termination is in effect when that // call enters V8, which clears it and runs the JS. -TEST_F(Test76TerminationUntilCancelled, CallsRunningJsAfterTheTermination) { +TEST_F(Test78TerminationUntilCancelled, CallsRunningJsAfterTheTermination) { for (int kind = 0; kind < kJsCallCount; ++kind) { SCOPED_TRACE(kJsCalls[kind]); EnvScope s(runtime_.get()); @@ -627,7 +627,7 @@ constexpr const char* kStoppedCalls[] = { }; constexpr int kStoppedCallCount = sizeof(kStoppedCalls) / sizeof(kStoppedCalls[0]); -TEST_F(Test76TerminationUntilCancelled, CallsTheTerminationStopsLeaveItPending) { +TEST_F(Test78TerminationUntilCancelled, CallsTheTerminationStopsLeaveItPending) { for (int kind = 0; kind < kStoppedCallCount; ++kind) { SCOPED_TRACE(kStoppedCalls[kind]); EnvScope s(runtime_.get()); @@ -680,7 +680,7 @@ TEST_F(Test76TerminationUntilCancelled, CallsTheTerminationStopsLeaveItPending) // The same native code, called from the module hooks test_75 covers: those // see what the native function threw. -TEST_F(Test76TerminationUntilCancelled, NativeCallsAfterTheTerminationInsideModuleHooks) { +TEST_F(Test78TerminationUntilCancelled, NativeCallsAfterTheTerminationInsideModuleHooks) { { SCOPED_TRACE("import.meta"); EnvScope s(runtime_.get()); @@ -753,7 +753,7 @@ void TerminatingFinalizer(napi_env env, void* /*data*/, void* /*hint*/) { } } // namespace -TEST_F(Test76TerminationUntilCancelled, FinalizerDrainedAtACheckpoint) { +TEST_F(Test78TerminationUntilCancelled, FinalizerDrainedAtACheckpoint) { EnvScope s(runtime_.get()); InstallHelpers(s.env); ASSERT_EQ(RunScript(s.env, "globalThis.markAfterCall = () => { afterCall = 'yes'; };"), @@ -797,7 +797,7 @@ napi_value MarkCleanup(napi_env /*env*/, napi_callback_info /*info*/) { } } // namespace -TEST_F(Test76TerminationUntilCancelled, FinalizationRegistryCleanupAtACheckpoint) { +TEST_F(Test78TerminationUntilCancelled, FinalizationRegistryCleanupAtACheckpoint) { EnvScope s(runtime_.get()); InstallHelpers(s.env); DefineGlobalFunction(s.env, "markCleanup", MarkCleanup); @@ -832,7 +832,7 @@ napi_value TerminateThenCheckpoint(napi_env env, napi_callback_info /*info*/) { } } // namespace -TEST_F(Test76TerminationUntilCancelled, CheckpointAfterTheTermination) { +TEST_F(Test78TerminationUntilCancelled, CheckpointAfterTheTermination) { EnvScope s(runtime_.get()); InstallHelpers(s.env); DefineGlobalFunction(s.env, "terminateThenCheckpoint", TerminateThenCheckpoint); @@ -870,7 +870,7 @@ void ReleaseFinalizer(napi_env env, void* /*data*/, void* /*hint*/) { } } // namespace -TEST_F(Test76TerminationUntilCancelled, TerminationRequestedInsideTheRelease) { +TEST_F(Test78TerminationUntilCancelled, TerminationRequestedInsideTheRelease) { g_release_runs.clear(); { EnvScope s(runtime_.get()); @@ -912,7 +912,7 @@ void ReleaseRunsJs(void* arg) { } } // namespace -TEST_F(Test76TerminationUntilCancelled, ReleaseAfterAnUncancelledTermination) { +TEST_F(Test78TerminationUntilCancelled, ReleaseAfterAnUncancelledTermination) { g_release_result.clear(); { EnvScope s(runtime_.get()); @@ -929,7 +929,7 @@ TEST_F(Test76TerminationUntilCancelled, ReleaseAfterAnUncancelledTermination) { // host-object hook (QuickJS's serdes binding calls none of the serializer's // hooks) and the deprecated context-token assign hook (only V8 accepts the // context-token hooks). -TEST_F(Test76TerminationUntilCancelled, NativeCallsAfterTheTerminationInsideV8Hooks) { +TEST_F(Test78TerminationUntilCancelled, NativeCallsAfterTheTerminationInsideV8Hooks) { { SCOPED_TRACE("prepare-stack-trace callback"); EnvScope s(runtime_.get()); @@ -1004,7 +1004,7 @@ napi_value CreateSandboxRealm(napi_env env, napi_callback_info /*info*/) { return global; } -TEST_F(Test76TerminationUntilCancelled, NativeCallsAfterTheTerminationInsideTheTokenAssignHook) { +TEST_F(Test78TerminationUntilCancelled, NativeCallsAfterTheTerminationInsideTheTokenAssignHook) { EnvScope s(runtime_.get()); InstallHelpers(s.env); AttachTokenHooks(s.env, true); @@ -1025,7 +1025,7 @@ TEST_F(Test76TerminationUntilCancelled, NativeCallsAfterTheTerminationInsideTheT // QuickJS has no counterpart of). No JS called it, so there is none to stop, // and V8 aborts on any JS run there: the provider must run none. The // termination stays in effect. -TEST_F(Test76TerminationUntilCancelled, NativeFunctionCalledFromCppWithJsDisallowed) { +TEST_F(Test78TerminationUntilCancelled, NativeFunctionCalledFromCppWithJsDisallowed) { EnvScope s(runtime_.get()); InstallHelpers(s.env); napi_value terminate = nullptr; @@ -1084,7 +1084,7 @@ void CleanupHookCancelledByAnUnassignHook(void* arg) { } } // namespace -TEST_F(Test76TerminationUntilCancelled, UnassignHookCancelsDuringTheRelease) { +TEST_F(Test78TerminationUntilCancelled, UnassignHookCancelsDuringTheRelease) { g_release_result.clear(); { EnvScope s(runtime_.get()); @@ -1101,7 +1101,7 @@ TEST_F(Test76TerminationUntilCancelled, UnassignHookCancelsDuringTheRelease) { EXPECT_EQ(g_release_result, "ok"); } -TEST_F(Test76TerminationUntilCancelled, CreateRealmAfterATerminatedUnassignHook) { +TEST_F(Test78TerminationUntilCancelled, CreateRealmAfterATerminatedUnassignHook) { for (bool with_sandbox : {true, false}) { SCOPED_TRACE(with_sandbox ? "with a sandbox" : "with a fresh global"); EnvScope s(runtime_.get()); @@ -1151,7 +1151,7 @@ napi_value RequestInterrupt(napi_env env, napi_callback_info /*info*/) { } } // namespace -TEST_F(Test76TerminationUntilCancelled, InterruptCallbackTerminated) { +TEST_F(Test78TerminationUntilCancelled, InterruptCallbackTerminated) { EnvScope s(runtime_.get()); InstallHelpers(s.env); ASSERT_EQ(napi_create_reference(s.env, Eval(s.env, "(() => { terminate(); tick(); })"), 1, From e45b11683d849bea4e1b21028699e205cc5e3406 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Fri, 6 Nov 2026 08:19:59 -0800 Subject: [PATCH 148/150] Wake the host at a cancel for the tasks a termination left queued The foreground task waker from "Wake the host when V8 queues a task only a checkpoint runs" (#139) is called when V8 posts an immediate task to the default platform's queue, which only unofficial_napi_event_loop_checkpoint runs, so that a host that sleeps until it is woken takes that checkpoint. Since "V8: keep a termination until it is cancelled", the checkpoint of an env that terminates refuses at once (napi_pending_exception) and runs no task. So a task posted just before or during a termination woke the host once, the host's turn was refused, and the cancel woke nothing: the task waited for an unrelated wake, as it did before #139. unofficial_napi_cancel_terminate_execution now calls the new EdgeV8Platform::WakeForQueuedForegroundTasks, which calls the waker on the env's thread when the isolate has used that queue, is not shutting down, and has tasks pending (the count the platform keeps for the isolate's shutdown is not 0). The count also holds delayed tasks and tasks handed to a bound target, so a cancel may wake a host that then finds nothing due and waits again, which the waker's contract already allows. A bound target is no reason to skip: tasks posted to the queue before it was bound stay there (found by a Codex review). A refused checkpoint still calls no waker, so a host does not spin while the env terminates. include/unofficial_napi.h, src/lib.rs and v8/src/edge_v8_platform.h say so. Test: test_78's CancelWakesTheHostForTheTasksLeftQueued (V8) posts a task with Atomics.notify on a same-thread Atomics.waitAsync, terminates, takes 100 refused checkpoints, cancels, and runs the task at a checkpoint. It counts the waker's calls on the env's thread: one for the post, none for the refused checkpoints, one for the cancel. Before this commit it failed at the cancel ("the cancel did not wake the host for the task left queued": 1 call, expected 2). It passed 50 runs in a row, and V8 342/342 and QuickJS 291/291 pass. QuickJS has no platform queue and no waker. Co-Authored-By: Claude Opus 5.5 --- include/unofficial_napi.h | 5 +- src/lib.rs | 9 ++- .../test_78_termination_until_cancelled.cc | 78 +++++++++++++++++++ v8/src/edge_v8_platform.cc | 14 ++++ v8/src/edge_v8_platform.h | 11 ++- v8/src/unofficial_napi.cc | 10 +++ 6 files changed, 122 insertions(+), 5 deletions(-) diff --git a/include/unofficial_napi.h b/include/unofficial_napi.h index 69aa890641..211f6bee3c 100644 --- a/include/unofficial_napi.h +++ b/include/unofficial_napi.h @@ -624,7 +624,10 @@ NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_terminate_execution(nap // current JS stack to unwind normally. Call it on the env's engine thread. A // pending exception that stands for the termination is dropped: nothing threw // it, so a native callback that cancels returns to its caller as after any -// call. Any other pending exception stays. +// call. Any other pending exception stays. V8: the checkpoints the termination +// refused left the engine's tasks queued, so when some wait for a checkpoint, +// this calls the host's foreground task waker (wasmer_napi's +// set_foreground_task_waker) again. NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_cancel_terminate_execution(napi_env env); typedef void (*unofficial_napi_interrupt_callback)(napi_env env, void* data); diff --git a/src/lib.rs b/src/lib.rs index 7c027a6240..1ef187fddb 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -161,9 +161,12 @@ extern "C" fn wake_for_foreground_task() { /// run guest code, and must not take a lock that the host holds around guest /// calls. It is called for every isolate's tasks, so a host running several /// guests wakes them all, and a guest with nothing to run waits again. Delayed -/// tasks don't call it: each runs at the first checkpoint after its delay. A -/// panic in the waker is caught, and its payload leaked, so that it never -/// unwinds into V8. +/// tasks don't call it: each runs at the first checkpoint after its delay. +/// While a guest's env terminates, its checkpoint refuses and runs no task, and +/// calls no waker, so the guest does not spin; +/// `unofficial_napi_cancel_terminate_execution` calls the waker again, on the +/// guest's thread, when tasks still wait. A panic in the waker is caught, and +/// its payload leaked, so that it never unwinds into V8. /// /// `None` removes the waker. A waker may call this function itself. A call /// that was already under way may still run the waker it replaced after this diff --git a/tests/runners/test_78_termination_until_cancelled.cc b/tests/runners/test_78_termination_until_cancelled.cc index 9e6c7b960f..a30f584a42 100644 --- a/tests/runners/test_78_termination_until_cancelled.cc +++ b/tests/runners/test_78_termination_until_cancelled.cc @@ -25,6 +25,10 @@ #if defined(NAPI_TEST_ENGINE_V8) #include + +#include + +#include "../../v8/src/edge_v8_platform.h" #endif class Test78TerminationUntilCancelled : public FixtureTestBase {}; @@ -1168,3 +1172,77 @@ TEST_F(Test78TerminationUntilCancelled, InterruptCallbackTerminated) { EXPECT_TRUE(calls == "0" || calls == "1") << "calls " << calls; napi_delete_reference(s.env, g_interrupt_fn); } + +#if defined(NAPI_TEST_ENGINE_V8) +// The foreground task waker (EdgeV8Platform::SetForegroundTaskWaker, which +// wasmer_napi::set_foreground_task_waker installs) is called when V8 posts a +// task that only a checkpoint runs, so that a host sleeping until it is woken +// takes that checkpoint. While the env terminates, the checkpoint refuses and +// runs no task; it calls no waker either, so that host takes one turn and +// sleeps again rather than spinning. The cancel then wakes it again, for the +// task the refused checkpoints left queued. +namespace { +std::thread::id g_waker_thread; +std::atomic g_env_thread_wakes{0}; +void CountEnvThreadWakes() { + // V8 may post tasks of its own from other threads meanwhile. + if (std::this_thread::get_id() == g_waker_thread) g_env_thread_wakes.fetch_add(1); +} +struct ScopedWaker { + ScopedWaker() { + g_waker_thread = std::this_thread::get_id(); + g_env_thread_wakes = 0; + EdgeV8Platform::SetForegroundTaskWaker(CountEnvThreadWakes); + } + ~ScopedWaker() { EdgeV8Platform::SetForegroundTaskWaker(nullptr); } + ScopedWaker(const ScopedWaker&) = delete; + ScopedWaker& operator=(const ScopedWaker&) = delete; +}; +napi_status Checkpoint(napi_env env, uint32_t* state_out = nullptr) { + uint32_t state = 0; + napi_status status = unofficial_napi_event_loop_checkpoint( + env, unofficial_napi_event_loop_checkpoint_microtasks, false, &state); + if (state_out != nullptr) *state_out = state; + return status; +} +} // namespace + +TEST_F(Test78TerminationUntilCancelled, CancelWakesTheHostForTheTasksLeftQueued) { + EnvScope s(runtime_.get()); + InstallHelpers(s.env); + // The tasks V8 queued while the env was made run first. + for (int i = 0; i < 64; ++i) { + uint32_t state = 0; + ASSERT_EQ(Checkpoint(s.env, &state), napi_ok); + if ((state & unofficial_napi_event_loop_checkpoint_state_host_tasks_admitted) == 0) break; + } + ScopedWaker waker; + // Atomics.notify on the waiter of a same-thread Atomics.waitAsync: V8 + // posts the task that resolves its promise. + ASSERT_EQ(RunScript(s.env, + "globalThis.resolved = 'no';\n" + "{ const i32 = new Int32Array(new SharedArrayBuffer(16));\n" + " Atomics.waitAsync(i32, 0, 0).value.then(() => { resolved = 'yes'; });\n" + " Atomics.notify(i32, 0, 1); }\n"), + napi_ok); + EXPECT_GE(g_env_thread_wakes.load(), 1) << "posting the task did not wake the host"; + + ASSERT_EQ(unofficial_napi_terminate_execution(s.env), napi_ok); + const int before_checkpoints = g_env_thread_wakes.load(); + for (int i = 0; i < 100; ++i) { + ASSERT_EQ(Checkpoint(s.env), napi_pending_exception); + } + EXPECT_EQ(g_env_thread_wakes.load(), before_checkpoints) + << "a checkpoint the termination refused woke the host"; + + const int before_cancel = g_env_thread_wakes.load(); + ASSERT_EQ(unofficial_napi_cancel_terminate_execution(s.env), napi_ok); + EXPECT_EQ(g_env_thread_wakes.load(), before_cancel + 1) + << "the cancel did not wake the host for the task left queued"; + EXPECT_EQ(GlobalText(s.env, "resolved"), "no") << "a refused checkpoint ran the task"; + for (int i = 0; i < 8 && GlobalText(s.env, "resolved") != "yes"; ++i) { + ASSERT_EQ(Checkpoint(s.env), napi_ok); + } + EXPECT_EQ(GlobalText(s.env, "resolved"), "yes"); +} +#endif diff --git a/v8/src/edge_v8_platform.cc b/v8/src/edge_v8_platform.cc index 1dbce227c1..4d4f9caf48 100644 --- a/v8/src/edge_v8_platform.cc +++ b/v8/src/edge_v8_platform.cc @@ -543,6 +543,20 @@ bool EdgeV8Platform::PumpPendingForegroundTasks(v8::Isolate* isolate) { return v8::platform::PumpMessageLoop(fallback_.get(), isolate); } +void EdgeV8Platform::WakeForQueuedForegroundTasks(v8::Isolate* isolate) { + std::shared_ptr state = GetState(isolate); + // Only the default queue waits for a checkpoint. Tasks posted there before + // a target was bound stay there, so a bound target is no reason to skip. + if (!state || !state->runner || !state->runner->used_fallback_runner()) return; + { + std::lock_guard lock(state->mutex); + if (state->finished || state->shutdown_started || state->pending_foreground_tasks == 0) { + return; + } + } + WakeForForegroundTask(); +} + int EdgeV8Platform::NumberOfWorkerThreads() { return fallback_ != nullptr ? fallback_->NumberOfWorkerThreads() : 0; } diff --git a/v8/src/edge_v8_platform.h b/v8/src/edge_v8_platform.h index d8b25e3662..4aee896b9c 100644 --- a/v8/src/edge_v8_platform.h +++ b/v8/src/edge_v8_platform.h @@ -49,7 +49,7 @@ class EdgeV8Platform final : public v8::Platform { // the first checkpoint after its delay. nullptr clears it. A thread that // read the previous function just before a change may still call it once // afterwards. It takes no data pointer, so that one atomic store publishes - // it. + // it. WakeForQueuedForegroundTasks calls it too. static void SetForegroundTaskWaker(void (*waker)()); ~EdgeV8Platform() override; @@ -71,6 +71,15 @@ class EdgeV8Platform final : public v8::Platform { // Run at most one ready fallback task. Returns true when a task ran so // the embedder can admit another loop turn before continuing provider work. bool PumpPendingForegroundTasks(v8::Isolate* isolate); + // Calls the function SetForegroundTaskWaker set, on this thread, when the + // isolate may have tasks waiting that only a checkpoint runs: it has used + // the default platform's queue and has tasks pending. Their posts called it + // once, but a checkpoint that refused to run them (while the env + // terminated) left them queued, and nothing calls it for them again. The + // pending tasks may also be delayed ones that aren't due yet, or ones + // handed to a bound target: the embedder then finds nothing to run and + // waits again. + void WakeForQueuedForegroundTasks(v8::Isolate* isolate); int NumberOfWorkerThreads() override; std::shared_ptr GetForegroundTaskRunner( diff --git a/v8/src/unofficial_napi.cc b/v8/src/unofficial_napi.cc index d3ad37aa31..76d8ab8d72 100644 --- a/v8/src/unofficial_napi.cc +++ b/v8/src/unofficial_napi.cc @@ -2344,6 +2344,16 @@ napi_status NAPI_CDECL unofficial_napi_cancel_terminate_execution(napi_env env) // left there, the native function that cancels would throw it into its // caller as a catchable null. napi_v8_drop_pending_termination(env); + // The checkpoints the termination refused ran none of the tasks V8 queued + // for them, and the host's foreground task waker was called only when each + // was posted: call it again, so that a host that sleeps until it is woken + // takes the checkpoint that runs them now. + EdgeV8Platform* platform = nullptr; + { + std::lock_guard lock(g_runtime_mu); + platform = g_runtime.platform.get(); + } + if (platform != nullptr) platform->WakeForQueuedForegroundTasks(env->isolate); return napi_ok; } From ab41860dbde7e58ca166f8cfebb93760d285d5f0 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Fri, 6 Nov 2026 09:53:34 -0800 Subject: [PATCH 149/150] Fix module lifetime, realm and termination review findings Guard the QuickJS require facade, keep active records alive through engine calls, and invalidate incoming links before a destroyed record can be reused. Use weak wrappers with GC-visible dependency edges, enforce module state and realm boundaries, and align async state and error handling across providers. Keep termination errors catchable after cancellation, preserve Buffer exceptions, and permit V8 error creation without a code during termination. Document the three retained termination differences and all 19 dispositions. Validation: V8 Release 356/356, QuickJS Release 306/306; V8 ASan 355 passed with one sanitizer-specific skip; QuickJS Debug+ASan 306/306. --- docs/pr127-review-followups.md | 50 +++ docs/realms.md | 34 ++ include/unofficial_napi.h | 34 +- quickjs/src/internal/napi_module_wrap.cc | 245 +++++++++++++-- quickjs/src/internal/napi_module_wrap.h | 4 + quickjs/src/internal/napi_util.cc | 3 +- quickjs/src/js_native_api_quickjs.cc | 8 +- quickjs/src/unofficial_napi.cc | 1 + tests/runners/test_77_module_wrap_state.cc | 295 +++++++++++++++++- .../test_78_termination_until_cancelled.cc | 27 +- v8/src/js_native_api_v8.cc | 6 +- v8/src/unofficial_napi_contextify.cc | 79 ++++- 12 files changed, 744 insertions(+), 42 deletions(-) create mode 100644 docs/pr127-review-followups.md diff --git a/docs/pr127-review-followups.md b/docs/pr127-review-followups.md new file mode 100644 index 0000000000..4e509807da --- /dev/null +++ b/docs/pr127-review-followups.md @@ -0,0 +1,50 @@ +# PR #127 review follow-ups + +The two local reviews of `fin/next` at `80b591e` reported 19 findings: +14 in `review-module-state.json` and five in `review-node-parity.json`. +The changes here start from published `next` at `e45b116`. + +The numbering below follows the module report first, then the parity report. +Sixteen items have implementation fixes; three existing termination differences +have explicit API documentation rather than behavior changes. + +| # | Finding | Disposition | +|---|---|---| +| 1 | QuickJS require facade bypasses termination | Check before running code and after evaluation; include the facade in both termination-call matrices. | +| 2 | Stored QuickJS module errors remain uncatchable after cancel; checkpoint exceptions cannot be taken | Clear stored errors' uncatchable flag on cancellation, and transfer failed-job exceptions into the env. | +| 3 | V8 facade instantiates in the current realm | Use the wrapped module's creation context. | +| 4 | Strong module wrapper references prevent collection | Use weak wrapper references and private JS edges for dependency wrappers; unreachable import cycles can be collected. The embedder still owns destruction of each native record. | +| 5 | QuickJS relinking after instantiation crashes | Refuse relinking after instantiation on both providers. | +| 6 | Destroyed V8 dependency record can resolve to a new module at the same address | Clear incoming record pointers at destruction. V8 refuses subsequent instantiation through them. | +| 7 | QuickJS destruction during terminated evaluation reads freed memory | Defer record destruction while linking, evaluating, or running synthetic steps. | +| 8 | QuickJS pending top-level await reports the wrong state and settledness | Map async evaluation to evaluated, inspect the linked graph for pending async evaluation, and warn with the module URL. Exact source positions remain unavailable. | +| 9 | V8 cached-data Buffer construction runs JS during termination and swallows exceptions | Guard termination and report Buffer getter/from exceptions; apply the shared helper's error status to bytecode serialization too. | +| 10 | QuickJS module creation/error construction runs JS during termination | Guard creation before binding lookups/setters, check source metadata setter failures and termination, and define module error codes as own properties. The engine's documented prepareStackTrace gap remains. | +| 11 | Throwing QuickJS error-code setter leaves an untakeable exception | Bypass the inherited setter when defining a module error's code. | +| 12 | QuickJS facade produces a spurious unhandled rejection | Mark the rejected facade promise handled before returning its reason. | +| 13 | Cross-realm links have different execution realms across engines | Refuse cross-realm links on both providers with ERR_VM_MODULE_DIFFERENT_CONTEXT. | +| 14 | Smaller module API result differences | Align link error codes/statuses, the absent source-object result, request-array realm, and evaluate_sync's async-module diagnostic. | +| 15 | V8 refuses error creation without a code during termination | Guard only the case with a code; document QuickJS's broader refusal. | +| 16 | Refusal status/pending state differs from Node's versioned shutdown preamble | Document the existing unofficial termination contract: napi_pending_exception and a pending marker for every module API version. | +| 17 | A retrieved QuickJS termination value remains uncatchable after cancel | Expose null from get_and_clear_last_exception for an internal termination marker, matching V8. | +| 18 | QuickJS resumes leftover promise jobs after cancel | Document existing queue persistence; embedders decide whether to run another checkpoint. | +| 19 | V8 builtins without user JS frames may finish after termination | Document V8's stack-check boundary and possible napi_ok result, preserving Node's behavior and DisallowJavascriptExecutionScope compatibility. | + +## Validation + +On macOS arm64, the complete native CTest suites pass: + +| Configuration | Result | +|---|---| +| V8 Release | 356 passed | +| QuickJS Release | 306 passed | +| V8 Release with AddressSanitizer | 355 passed, one sanitizer-specific skip | +| QuickJS Debug with AddressSanitizer | 306 passed | + +The ASan runs use `ASAN_OPTIONS=detect_leaks=0`; QuickJS Debug retains its +runtime leak assertions. Sixteen new test cases cover the reported failure +modes and wrapper/dependency GC behavior. The existing termination matrices +also exercise the facade before and during termination. + +This pass does not include an EdgeJS build, WASIX/host-JS integration tests, +or performance benchmarking. diff --git a/docs/realms.md b/docs/realms.md index 38dcdaece0..b93b7d1f3a 100644 --- a/docs/realms.md +++ b/docs/realms.md @@ -398,3 +398,37 @@ between the engines: - **The deprecated API** came back on top of realms, with its structs grown at the end instead of changed in place, so that code built against `main` keeps working until a major release removes it. + +## Module wrapper ownership + +A module record owns its engine module and realm until explicit destruction or +release of the env. Its reference to the JavaScript wrapper is weak. Embedders +that tie native records to JavaScript objects should destroy the module from +the wrapper's finalizer, as EdgeJS does. A raw module handle does not retain +that wrapper. Keep the wrapper reachable while using its handle. + +Links retain dependency wrappers through private properties on the importer's +wrapper. The collector can therefore reclaim an unreachable import cycle; +there is no native strong-reference cycle between wrappers. Destroying a +linked dependency explicitly invalidates native links to its record, so a +reused record address cannot resolve an import to a different module. V8 +refuses subsequent instantiation through such a link; QuickJS already owns +its linked engine module and may continue using it. Avoid explicit dependency +destruction while an importer still needs it. + +Linking after instantiation is refused with `ERR_VM_MODULE_ALREADY_LINKED`. +Cross-realm links are refused with `ERR_VM_MODULE_DIFFERENT_CONTEXT` on both +providers. A require facade always uses the wrapped module's creation realm. +QuickJS reports pending asynchronous evaluation as evaluated, as V8's public +module status does, and detects unsettled top-level await. Its warning gives +the module URL; exact stalled source positions remain unavailable. + +The unofficial termination API has its own status contract: refused calls +return `napi_pending_exception` for every N-API version and leave a pending +termination marker. This differs from Node's shutdown preamble, which returns +`napi_cannot_run_js` for N-API 10 and later without setting an exception. +Taking a termination exception returns null on both providers. Cancelling +also makes QuickJS's stored module-evaluation errors catchable. QuickJS keeps +promise jobs left after an interrupted checkpoint; V8 drops microtasks left +when a running microtask terminates. After cancelling a QuickJS termination, +embedders should run a checkpoint only if they intend those jobs to resume. diff --git a/include/unofficial_napi.h b/include/unofficial_napi.h index 211f6bee3c..13304b20e8 100644 --- a/include/unofficial_napi.h +++ b/include/unofficial_napi.h @@ -605,12 +605,26 @@ NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_create_uninitialized_ar // call this. // // A call the termination stops or refuses leaves it as the pending exception -// (null on V8, QuickJS's uncatchable error) unless another one is pending. +// unless another one is pending. napi_get_and_clear_last_exception returns +// null for a termination on both providers; QuickJS keeps its uncatchable +// engine marker internal. Cancelling also makes stored QuickJS module +// evaluation errors catchable. // When a native callback returns while the env terminates, what it left // pending is dropped and the JS that called it unwinds. V8 acts on a // termination requested from another thread at its next stack check, and on // one an interrupt callback's JS runs into at the stack check after the one -// that ran the callback. +// that ran the callback. On V8, a builtin called directly from native code +// (for example forEach or a promise reaction job), with no user JS below its +// native callback, may finish before another stack check. Such a call can +// return napi_ok after requesting termination. QuickJS stops it immediately. +// +// These unofficial termination helpers deliberately return +// napi_pending_exception for a refused call for every module_api_version and +// leave a pending termination marker. Node's shutdown preamble instead uses +// napi_cannot_run_js for modules targeting N-API >= 10 and leaves no exception. +// V8 permits error creation without a code while terminating; with a code it +// refuses because an inherited setter may run. QuickJS refuses both cases +// because constructing an error can read Error.prepareStackTrace. // // Known QuickJS gap: QuickJS-ng reads Error.prepareStackTrace, which may be a // getter, whenever it gives an error its stack, also while a termination @@ -627,7 +641,9 @@ NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_terminate_execution(nap // call. Any other pending exception stays. V8: the checkpoints the termination // refused left the engine's tasks queued, so when some wait for a checkpoint, // this calls the host's foreground task waker (wasmer_napi's -// set_foreground_task_waker) again. +// set_foreground_task_waker) again. QuickJS preserves promise jobs remaining +// after an interrupted checkpoint and runs them at a checkpoint after cancel; +// V8 drops the remaining microtasks when a running microtask is terminated. NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_cancel_terminate_execution(napi_env env); typedef void (*unofficial_napi_interrupt_callback)(napi_env env, void* data); @@ -1304,10 +1320,20 @@ NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_module_wrap_create( const unofficial_napi_module_create_options* options, unofficial_napi_module_create_result* result_out); +// Records retain their module and realm until destroy or env release. Their +// wrapper is weak: an embedder may destroy the record from its wrapper's +// finalizer. Linking retains dependency wrappers through private JS edges, +// so unreachable wrapper cycles can be collected. A native handle alone does +// not retain its wrapper; embedders must keep it alive while using the handle. +// Explicitly destroying a dependency invalidates its incoming native links; +// V8 refuses later instantiation through them, while QuickJS can continue +// with its retained engine module. Never use a destroyed module handle. NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_module_wrap_destroy( napi_env env, unofficial_napi_module module); +// Only uninstantiated modules may be linked. All dependencies must belong +// to the same realm, else ERR_VM_MODULE_DIFFERENT_CONTEXT is pending. NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_module_wrap_link( napi_env env, unofficial_napi_module module, @@ -1347,6 +1373,8 @@ NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_module_wrap_get_state( napi_value* error_out, bool* has_async_graph_out); +// QuickJS warnings identify the module URL; unlike V8, they do not include +// the source line and column of the stalled await. NAPI_EXTENSION_WASMER_EXTERN napi_status unofficial_napi_module_wrap_check_unsettled_top_level_await( napi_env env, unofficial_napi_module module, diff --git a/quickjs/src/internal/napi_module_wrap.cc b/quickjs/src/internal/napi_module_wrap.cc index 150b4b1c59..21e0519559 100644 --- a/quickjs/src/internal/napi_module_wrap.cc +++ b/quickjs/src/internal/napi_module_wrap.cc @@ -4,10 +4,12 @@ #include "internal/napi_env.h" #include "internal/napi_util.h" #include "internal/napi_value.h" +#include "internal/napi_ref.h" #include "node_api.h" #include #include +#include #include #include #include @@ -111,11 +113,13 @@ struct napi_module_wrap__::record JSContext *ctx = nullptr; JSModuleDef *module = nullptr; JSValue module_value = JS_UNDEFINED; - JSValue wrapper = JS_UNDEFINED; + napi_ref wrapper_ref = nullptr; JSValue host_defined_option_id = JS_UNDEFINED; JSValue synthetic_eval_steps = JS_UNDEFINED; JSValue source_object = JS_UNDEFINED; bool synthetic = false; + size_t active_calls = 0; + bool destroy_requested = false; // XXH3 of the module source text; written into the QJSB header by // create_cached_data so the consuming vm.SourceTextModule constructor's // deserialize validates source identity (filename stays unenforced). @@ -125,6 +129,25 @@ struct napi_module_wrap__::record std::vector linked_module_values; }; +// A callback reached while linking/evaluating may destroy its own module. +// Keep the record and its context alive until the engine call returns. +class napi_module_wrap__::record_scope +{ +public: + record_scope(napi_module_wrap__ *owner, record *entry) : owner_{owner}, entry_{entry} + { ++entry_->active_calls; } + ~record_scope() + { + if (--entry_->active_calls == 0 && entry_->destroy_requested) + owner_->free_record(entry_); + } + record_scope(const record_scope &) = delete; + record_scope &operator=(const record_scope &) = delete; +private: + napi_module_wrap__ *owner_; + record *entry_; +}; + struct napi_module_wrap__::script_referrer { std::string name; @@ -162,9 +185,16 @@ void napi_module_wrap__::teardown() import_module_dynamically_callback_ = JS_UNDEFINED; JS_FreeValue(ctx_, initialize_import_meta_callback_); initialize_import_meta_callback_ = JS_UNDEFINED; + JS_FreeAtom(ctx_, dependency_key_); + dependency_key_ = JS_ATOM_NULL; torn_down_ = true; } +JSValue napi_module_wrap__::get_wrapper(record *entry) const +{ + return entry->wrapper_ref != nullptr ? entry->wrapper_ref->dup_inner() : JS_UNDEFINED; +} + napi_module_wrap__::record *napi_module_wrap__::find(unofficial_napi_module module) const { auto *entry = reinterpret_cast(module); @@ -172,7 +202,7 @@ napi_module_wrap__::record *napi_module_wrap__::find(unofficial_napi_module modu return nullptr; for (record *candidate : records_) { - if (candidate == entry) + if (candidate == entry && !entry->destroy_requested) return entry; } return nullptr; @@ -194,7 +224,8 @@ napi_module_wrap__::record *napi_module_wrap__::find_by_wrapper(JSValueConst wra { for (record *entry : records_) { - if (entry != nullptr && JS_IsSameValue(ctx_, entry->wrapper, wrapper)) + if (entry != nullptr && entry->wrapper_ref != nullptr && + JS_IsSameValue(ctx_, entry->wrapper_ref->get_inner(), wrapper)) return entry; } return nullptr; @@ -212,13 +243,28 @@ void napi_module_wrap__::free_record(record *entry) if (entry == nullptr) return; + if (entry->active_calls != 0) + { + entry->destroy_requested = true; + return; + } remove(entry); + // A freed address must never become a link to a later record at that address. + for (record *dependent : records_) + for (record *&linked : dependent->linked_records) + if (linked == entry) + linked = nullptr; + JSValue wrapper = get_wrapper(entry); + if (JS_IsObject(wrapper) && dependency_key_ != JS_ATOM_NULL) + JS_DeleteProperty(ctx_, wrapper, dependency_key_, 0); + JS_FreeValue(ctx_, wrapper); for (auto &request : entry->requests) JS_FreeValue(ctx_, request.attributes); for (JSValue value : entry->linked_module_values) JS_FreeValue(ctx_, value); JS_FreeValue(ctx_, entry->module_value); - JS_FreeValue(ctx_, entry->wrapper); + if (entry->wrapper_ref != nullptr) + napi_delete_reference(env_, entry->wrapper_ref); JS_FreeValue(ctx_, entry->host_defined_option_id); JS_FreeValue(ctx_, entry->synthetic_eval_steps); JS_FreeValue(ctx_, entry->source_object); @@ -382,8 +428,15 @@ JSValue napi_module_wrap__::clone_attributes(JSValueConst value) const napi_status napi_module_wrap__::throw_error(const char *code, const char *message) { JSValue error = napi_util__::create_plain_error(ctx_, message); - if (code != nullptr) - JS_SetPropertyStr(ctx_, error, "code", JS_NewString(ctx_, code)); + if (JS_IsException(error)) + return return_pending_exception("Failed to create module error"); + // Define an own property: inherited setters must not run during shutdown. + if (code != nullptr && JS_DefinePropertyValueStr(ctx_, error, "code", + JS_NewString(ctx_, code), JS_PROP_C_W_E) < 0) + { + JS_FreeValue(ctx_, error); + return return_pending_exception("Failed to set module error code"); + } env_->set_last_exception(error); return napi_pending_exception; } @@ -447,6 +500,9 @@ napi_status napi_module_wrap__::create_source_text(JSContext *ctx, napi_value host_defined_option_id, unofficial_napi_module *module_out) { + napi_status terminating = napi_util__::fail_if_terminating(env_, ctx_); + if (terminating != napi_ok) + return terminating; (void)column_offset; if (ctx == nullptr || !napi_util__::check_value(env_, wrapper) || @@ -471,6 +527,12 @@ napi_status napi_module_wrap__::create_source_text(JSContext *ctx, url_string.c_str()); if (JS_IsException(host_id)) return return_pending_exception("Failed to create module host option"); + terminating = napi_util__::fail_if_terminating(env_, ctx_); + if (terminating != napi_ok) + { + JS_FreeValue(ctx_, host_id); + return terminating; + } JSValue module_value = JS_UNDEFINED; if (bytecode_record != nullptr && !JS_IsUndefined(bytecode_record->artifact) && @@ -516,8 +578,13 @@ napi_status napi_module_wrap__::create_source_text(JSContext *ctx, entry->ctx = ctx == ctx_ ? ctx : JS_DupContext(ctx); entry->module = module; entry->module_value = module_value; - entry->wrapper = JS_DupValue(ctx_, napi_quickjs_value_inner(env_, wrapper)); entry->host_defined_option_id = host_id; + napi_status wrapper_status = napi_create_reference(env_, wrapper, 0, &entry->wrapper_ref); + if (wrapper_status != napi_ok) + { + free_record(entry); + return wrapper_status; + } entry->source_hash = quickjs::detail::napi_bytecode_hash64(source_string.data(), source_string.size()); records_.push_back(entry); @@ -529,9 +596,29 @@ napi_status napi_module_wrap__::create_source_text(JSContext *ctx, return status; } - JS_SetPropertyStr(ctx_, napi_quickjs_value_inner(env_, wrapper), "sourceURL", - JS_NewString(ctx_, url_string.c_str())); - JS_SetPropertyStr(ctx_, napi_quickjs_value_inner(env_, wrapper), "sourceMapURL", JS_UNDEFINED); + if (JS_SetPropertyStr(ctx_, napi_quickjs_value_inner(env_, wrapper), "sourceURL", + JS_NewString(ctx_, url_string.c_str())) < 0) + { + free_record(entry); + return return_pending_exception("Failed to set module source URL"); + } + status = napi_util__::fail_if_terminating(env_, ctx_); + if (status != napi_ok) + { + free_record(entry); + return status; + } + if (JS_SetPropertyStr(ctx_, napi_quickjs_value_inner(env_, wrapper), "sourceMapURL", JS_UNDEFINED) < 0) + { + free_record(entry); + return return_pending_exception("Failed to set module source map URL"); + } + status = napi_util__::fail_if_terminating(env_, ctx_); + if (status != napi_ok) + { + free_record(entry); + return status; + } *module_out = reinterpret_cast(entry); return napi_ok; } @@ -543,6 +630,9 @@ napi_status napi_module_wrap__::create_synthetic(JSContext *ctx, napi_value synthetic_eval_steps, unofficial_napi_module *module_out) { + napi_status terminating = napi_util__::fail_if_terminating(env_, ctx_); + if (terminating != napi_ok) + return terminating; if (ctx == nullptr || !napi_util__::check_value(env_, wrapper) || !napi_util__::check_value(env_, url) || @@ -580,7 +670,12 @@ napi_status napi_module_wrap__::create_synthetic(JSContext *ctx, entry->ctx = ctx == ctx_ ? ctx : JS_DupContext(ctx); entry->module = module; entry->module_value = JS_DupModuleValue(ctx_, module); - entry->wrapper = JS_DupValue(ctx_, napi_quickjs_value_inner(env_, wrapper)); + napi_status wrapper_status = napi_create_reference(env_, wrapper, 0, &entry->wrapper_ref); + if (wrapper_status != napi_ok) + { + free_record(entry); + return wrapper_status; + } entry->host_defined_option_id = JS_UNDEFINED; entry->synthetic_eval_steps = JS_DupValue(ctx_, napi_quickjs_value_inner(env_, synthetic_eval_steps)); entry->synthetic = true; @@ -606,7 +701,7 @@ napi_status napi_module_wrap__::get_creation_metadata(unofficial_napi_module mod if (entry == nullptr || requests_out == nullptr || has_top_level_await_out == nullptr) return napi_util__::invalid_arg(env_); - JSValue array = JS_NewArray(ctx_); + JSValue array = JS_NewArray(env_->context()); if (JS_IsException(array)) return return_pending_exception("Failed to create module request array"); @@ -641,10 +736,23 @@ napi_status napi_module_wrap__::link(unofficial_napi_module module, const unofficial_napi_module *linked_modules) { record *entry = find(module); - if (entry == nullptr || (count > 0 && linked_modules == nullptr)) + if (entry == nullptr) return napi_util__::invalid_arg(env_); if (count != entry->requests.size()) - return throw_error("ERR_MODULE_LINK_MISMATCH", "Module link count mismatch"); + return throw_error("ERR_VM_MODULE_LINK_FAILURE", "linked modules array length mismatch"); + if (count > 0 && linked_modules == nullptr) + return throw_error("ERR_VM_MODULE_LINK_FAILURE", "linked module missing"); + if (JS_GetModuleStatus(ctx_, entry->module) != JS_MODULE_STATUS_UNLINKED) + return throw_error("ERR_VM_MODULE_ALREADY_LINKED", "Module is already linked"); + // Validate before replacing any existing links. + for (size_t i = 0; i < count; ++i) + { + record *linked = find(linked_modules[i]); + if (linked == nullptr) + return throw_error("ERR_VM_MODULE_LINK_FAILURE", "Linked module is invalid"); + if (linked->ctx != entry->ctx) + return throw_error("ERR_VM_MODULE_DIFFERENT_CONTEXT", "Linked modules must use the same realm"); + } for (JSValue value : entry->linked_module_values) JS_FreeValue(ctx_, value); @@ -680,6 +788,32 @@ napi_status napi_module_wrap__::link(unofficial_napi_module module, entry->linked_records.push_back(linked); entry->linked_module_values.push_back(JS_DupModuleValue(ctx_, linked->module)); } + if (dependency_key_ == JS_ATOM_NULL) + { + JSValue key = JS_NewPrivateSymbol(ctx_, "module dependencies"); + dependency_key_ = JS_ValueToAtom(ctx_, key); + JS_FreeValue(ctx_, key); + if (dependency_key_ == JS_ATOM_NULL) + return return_pending_exception("Failed to create module dependency key"); + } + JSValue dependencies = JS_NewArray(ctx_); + if (JS_IsException(dependencies)) + return return_pending_exception("Failed to create module dependencies"); + for (size_t i = 0; i < count; ++i) + { + if (JS_DefinePropertyValueUint32(ctx_, dependencies, static_cast(i), + get_wrapper(entry->linked_records[i]), JS_PROP_C_W_E) < 0) + { + JS_FreeValue(ctx_, dependencies); + return return_pending_exception("Failed to retain module dependency"); + } + } + JSValue wrapper = get_wrapper(entry); + int retained = JS_DefinePropertyValue(ctx_, wrapper, dependency_key_, dependencies, + JS_PROP_CONFIGURABLE | JS_PROP_WRITABLE); + JS_FreeValue(ctx_, wrapper); + if (retained < 0) + return return_pending_exception("Failed to retain module dependencies"); return napi_ok; } @@ -704,6 +838,7 @@ napi_status napi_module_wrap__::throw_if_linking() napi_status napi_module_wrap__::link_module(record *entry, JSContext *ctx, JSModuleDef *module, const char *failure) { + record_scope active{this, entry}; napi_status status = throw_if_linking(); if (status != napi_ok) return status; @@ -793,6 +928,7 @@ napi_status napi_module_wrap__::throw_if_importing_an_evaluating_synthetic_modul napi_status napi_module_wrap__::evaluate_unless_terminated(record *entry, JSValue *promise_out) { + record_scope active{this, entry}; napi_status status = napi_util__::fail_if_terminating(env_, ctx_); if (status != napi_ok) return status; @@ -848,8 +984,6 @@ napi_status napi_module_wrap__::evaluate_sync(unofficial_napi_module module, napi_value parent_filename, napi_value *result_out) { - (void)filename; - (void)parent_filename; record *entry = find(module); if (entry == nullptr || result_out == nullptr) return napi_util__::invalid_arg(env_); @@ -875,8 +1009,15 @@ napi_status napi_module_wrap__::evaluate_sync(unofficial_napi_module module, } JS_FreeValue(ctx_, promise); - return throw_error("ERR_REQUIRE_ASYNC_MODULE", - "require() cannot be used on an ESM graph with top-level await"); + std::string message = + "require() cannot be used on an ESM graph with top-level await. " + "Use import() instead. To see where the top-level await comes from, " + "use --experimental-print-required-tla."; + const std::string parent = parent_filename != nullptr ? napi_util__::to_utf8(env_, parent_filename) : ""; + const std::string file = filename != nullptr ? napi_util__::to_utf8(env_, filename) : ""; + if (!parent.empty()) message += "\n From " + parent + " "; + if (!file.empty()) message += "\n Requiring " + file + " "; + return throw_error("ERR_REQUIRE_ASYNC_MODULE", message.c_str()); } napi_status napi_module_wrap__::get_namespace(unofficial_napi_module module, @@ -929,9 +1070,9 @@ napi_status napi_module_wrap__::get_state(unofficial_napi_module module, status = kInstantiated; break; case JS_MODULE_STATUS_EVALUATING: - case JS_MODULE_STATUS_EVALUATING_ASYNC: status = kEvaluating; break; + case JS_MODULE_STATUS_EVALUATING_ASYNC: case JS_MODULE_STATUS_EVALUATED: status = kEvaluated; break; @@ -956,10 +1097,33 @@ napi_status napi_module_wrap__::check_unsettled_top_level_await(unofficial_napi_ bool warnings, bool *settled_out) { - (void)warnings; - if (find(module) == nullptr || settled_out == nullptr) + record *entry = find(module); + if (entry == nullptr || settled_out == nullptr) return napi_util__::invalid_arg(env_); *settled_out = true; + std::vector pending{entry}; + std::unordered_set seen; + while (!pending.empty()) + { + record *current = pending.back(); + pending.pop_back(); + if (current == nullptr || !seen.insert(current).second) + continue; + if (JS_GetModuleStatus(ctx_, current->module) == JS_MODULE_STATUS_EVALUATING_ASYNC) + { + *settled_out = false; + if (warnings) + { + JSAtom name = JS_GetModuleName(ctx_, current->module); + const char *url = JS_AtomToCString(ctx_, name); + std::fprintf(stderr, "Warning: Detected unsettled top-level await at %s\n", + url != nullptr ? url : ""); + JS_FreeCString(ctx_, url); + JS_FreeAtom(ctx_, name); + } + } + pending.insert(pending.end(), current->linked_records.begin(), current->linked_records.end()); + } return napi_ok; } @@ -1011,7 +1175,10 @@ napi_status napi_module_wrap__::get_module_source_object(unofficial_napi_module if (entry == nullptr || result_out == nullptr) return napi_util__::invalid_arg(env_); if (JS_IsUndefined(entry->source_object)) - return napi_generic_failure; + { + *result_out = nullptr; + return napi_ok; + } return wrap_owned(JS_DupValue(ctx_, entry->source_object), result_out); } @@ -1152,8 +1319,13 @@ 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_); + record_scope active{this, entry}; + *result_out = nullptr; + napi_status status = napi_util__::fail_if_terminating(env_, ctx_); + if (status != napi_ok) + return status; // The facade evaluates the module it wraps. - napi_status status = throw_if_evaluating(entry); + status = throw_if_evaluating(entry); if (status != napi_ok) return status; status = throw_if_importing_an_evaluating_synthetic_module(entry); @@ -1207,9 +1379,17 @@ napi_status napi_module_wrap__::create_required_module_facade(unofficial_napi_mo JS_FreeValue(ctx, facade_value); return return_pending_exception("Failed to evaluate required module facade"); } + if (env_->termination_requested()) + { + JS_PromiseMarkAsHandled(ctx, promise); + JS_FreeValue(ctx, promise); + JS_FreeValue(ctx, facade_value); + return napi_util__::fail_if_terminating(env_, ctx_); + } JSPromiseStateEnum state = JS_PromiseState(ctx, promise); if (state == JS_PROMISE_REJECTED) { + JS_PromiseMarkAsHandled(ctx, promise); JSValue reason = JS_PromiseResult(ctx, promise); JS_FreeValue(ctx, promise); JS_FreeValue(ctx, facade_value); @@ -1231,6 +1411,17 @@ napi_status napi_module_wrap__::create_required_module_facade(unofficial_napi_mo return wrap_owned(ns, result_out); } +void napi_module_wrap__::cancel_termination() +{ + for (record *entry : records_) + { + JSValue error = JS_GetModuleEvaluationException(ctx_, entry->module); + if (JS_IsUncatchableError(error)) + JS_ClearUncatchableError(ctx_, error); + JS_FreeValue(ctx_, error); + } +} + void napi_module_wrap__::register_dynamic_import_referrer(napi_value referrer_name, napi_value host_defined_option_id) { @@ -1286,10 +1477,12 @@ int napi_module_wrap__::initialize_synthetic_module(JSModuleDef *module) record *entry = find_by_module(module); if (entry == nullptr || !JS_IsFunction(ctx_, entry->synthetic_eval_steps)) return 0; + record_scope active{this, entry}; + JSValue wrapper = get_wrapper(entry); synthetic_steps_running_++; - JSValue result = JS_Call(ctx_, entry->synthetic_eval_steps, - entry->wrapper, 0, nullptr); + JSValue result = JS_Call(ctx_, entry->synthetic_eval_steps, wrapper, 0, nullptr); synthetic_steps_running_--; + JS_FreeValue(ctx_, wrapper); if (JS_IsException(result)) return -1; JS_FreeValue(ctx_, result); @@ -1305,7 +1498,7 @@ int napi_module_wrap__::initialize_import_meta(JSModuleDef *module, JSValueConst JSValue args[3] = { JS_DupValue(ctx_, entry->host_defined_option_id), JS_DupValue(ctx_, meta), - JS_DupValue(ctx_, entry->wrapper), + get_wrapper(entry), }; JSValue result = call_callback(initialize_import_meta_callback_, 3, args); for (JSValue arg : args) diff --git a/quickjs/src/internal/napi_module_wrap.h b/quickjs/src/internal/napi_module_wrap.h index 264b2e18aa..7b153264a9 100644 --- a/quickjs/src/internal/napi_module_wrap.h +++ b/quickjs/src/internal/napi_module_wrap.h @@ -20,6 +20,7 @@ class napi_module_wrap__ ~napi_module_wrap__(); void teardown(); + void cancel_termination(); // A module lives in the realm whose context `ctx` is. napi_status create_source_text(JSContext *ctx, @@ -98,8 +99,10 @@ class napi_module_wrap__ struct request_record; struct record; + class record_scope; struct script_referrer; + JSValue get_wrapper(record *entry) const; record *find(unofficial_napi_module module) const; record *find_by_module(JSModuleDef *module) const; record *find_by_wrapper(JSValueConst wrapper) const; @@ -142,6 +145,7 @@ class napi_module_wrap__ std::vector script_referrers_; std::vector pending_dynamic_imports_; uint64_t facade_counter_ = 0; + JSAtom dependency_key_ = JS_ATOM_NULL; // Synthetic modules whose evaluation steps are running. int synthetic_steps_running_ = 0; // Links running (see link_module). diff --git a/quickjs/src/internal/napi_util.cc b/quickjs/src/internal/napi_util.cc index 3259b3bfc8..d1ada563c2 100644 --- a/quickjs/src/internal/napi_util.cc +++ b/quickjs/src/internal/napi_util.cc @@ -452,7 +452,8 @@ napi_status napi_util__::run_pending_jobs(napi_env env) // so the embedder can take it with napi_get_and_clear_last_exception. if (env->termination_requested()) return fail_if_terminating(env, job_ctx != nullptr ? job_ctx : context(env)); - return napi_pending_exception; + return return_pending_if_caught(env, job_ctx != nullptr ? job_ctx : context(env), + "Pending job failed"); } } } diff --git a/quickjs/src/js_native_api_quickjs.cc b/quickjs/src/js_native_api_quickjs.cc index cd3334a801..b86a871c65 100644 --- a/quickjs/src/js_native_api_quickjs.cc +++ b/quickjs/src/js_native_api_quickjs.cc @@ -3126,7 +3126,13 @@ extern "C" // Take ownership of the exception before clearing JSValue ex = env->take_last_exception(); - + // The engine's uncatchable marker is internal control flow. Exposing it + // would let a later ordinary throw restart termination after a cancel. + if (JS_IsUncatchableError(ex)) + { + JS_FreeValue(env->context(), ex); + ex = JS_NULL; + } *result = env->wrap_value_in_current_scope(ex, true); return (*result == nullptr) ? napi_generic_failure : napi_ok; } diff --git a/quickjs/src/unofficial_napi.cc b/quickjs/src/unofficial_napi.cc index 6c4c475586..c72c99d2d4 100644 --- a/quickjs/src/unofficial_napi.cc +++ b/quickjs/src/unofficial_napi.cc @@ -483,6 +483,7 @@ extern "C" if (!napi_util__::check_env(env)) return napi_invalid_arg; env->cancel_termination(); + env->module_wrap().cancel_termination(); // Drop a termination still pending in the runtime or the env, so the // env can run its exit and cleanup callbacks. Other exceptions stay. JSContext *ctx = napi_util__::context(env); diff --git a/tests/runners/test_77_module_wrap_state.cc b/tests/runners/test_77_module_wrap_state.cc index 23746ef2b1..cd584ff955 100644 --- a/tests/runners/test_77_module_wrap_state.cc +++ b/tests/runners/test_77_module_wrap_state.cc @@ -43,7 +43,9 @@ napi_value Str(napi_env env, const char* value) { return out; } -unofficial_napi_module CreateSourceTextModule(napi_env env, const char* text) { +unofficial_napi_module CreateSourceTextModule(napi_env env, const char* text, + unofficial_napi_realm realm = nullptr, + napi_value* wrapper_out = nullptr) { napi_value wrapper = nullptr; napi_value undefined = nullptr; EXPECT_EQ(napi_create_object(env, &wrapper), napi_ok); @@ -54,6 +56,8 @@ unofficial_napi_module CreateSourceTextModule(napi_env env, const char* text) { options.version = UNOFFICIAL_NAPI_MODULE_CREATE_OPTIONS_VERSION; options.kind = unofficial_napi_module_source_text; options.wrapper = wrapper; + options.realm_or_null = realm; + if (wrapper_out != nullptr) *wrapper_out = wrapper; options.url = Str(env, "state.mjs"); options.payload.source_text.source = &source; options.payload.source_text.host_defined_option_id = undefined; @@ -955,3 +959,292 @@ TEST_F(Test77ModuleWrapState, InstantiatingAModuleWhileItEvaluates) { EXPECT_EQ(unofficial_napi_module_wrap_destroy(s.env, probe.module), napi_ok); } } + +TEST_F(Test77ModuleWrapState, RelinkingAnInstantiatedModuleIsRefused) { + EnvScope s(runtime_.get()); + auto importer = CreateSourceTextModule(s.env, "import {value} from 'dep'; export {value};"); + auto first = CreateSourceTextModule(s.env, "export const value = 'first';"); + auto second = CreateSourceTextModule(s.env, "export const value = 'second';"); + ASSERT_EQ(unofficial_napi_module_wrap_link(s.env, importer, 1, &first), napi_ok); + ASSERT_EQ(unofficial_napi_module_wrap_instantiate(s.env, importer), napi_ok); + EXPECT_EQ(unofficial_napi_module_wrap_link(s.env, importer, 1, &second), napi_pending_exception); + EXPECT_EQ(TakePendingMessage(s.env), "Module is already linked"); + napi_value ns = nullptr; + ASSERT_EQ(unofficial_napi_module_wrap_evaluate_sync(s.env, importer, nullptr, nullptr, &ns), napi_ok); + napi_value value = nullptr; + ASSERT_EQ(napi_get_named_property(s.env, ns, "value", &value), napi_ok); + EXPECT_EQ(ValueText(s.env, value), "first"); +} + +TEST_F(Test77ModuleWrapState, DestroyedDependencyCannotBecomeAnotherModule) { + EnvScope s(runtime_.get()); + auto importer = CreateSourceTextModule(s.env, "import {value} from 'dep'; globalThis.result = value;"); + auto dependency = CreateSourceTextModule(s.env, "export const value = 'original';"); + ASSERT_EQ(unofficial_napi_module_wrap_link(s.env, importer, 1, &dependency), napi_ok); + ASSERT_EQ(unofficial_napi_module_wrap_destroy(s.env, dependency), napi_ok); + auto unrelated = CreateSourceTextModule(s.env, "globalThis.wrongModuleRan = true; export const value = 'wrong';"); + ASSERT_NE(unrelated, nullptr); + napi_value promise = nullptr; +#if defined(NAPI_TEST_ENGINE_V8) + EXPECT_EQ(unofficial_napi_module_wrap_evaluate(s.env, importer, -1, false, &promise), napi_pending_exception); + EXPECT_FALSE(TakePendingMessage(s.env).empty()); +#else + // QuickJS keeps the actual linked JSModuleDef alive independently of its record. + EXPECT_EQ(unofficial_napi_module_wrap_evaluate(s.env, importer, -1, false, &promise), napi_ok); + EXPECT_EQ(RunText(s.env, "result"), "original"); +#endif + EXPECT_EQ(RunText(s.env, "typeof wrongModuleRan"), "undefined"); +} + +namespace { +struct DestroyingModule { unofficial_napi_module module = nullptr; }; +napi_value DestroyAndTerminateModule(napi_env env, napi_callback_info info) { + void* data = nullptr; + napi_get_cb_info(env, info, nullptr, nullptr, nullptr, &data); + auto* state = static_cast(data); + EXPECT_EQ(unofficial_napi_module_wrap_destroy(env, state->module), napi_ok); + EXPECT_EQ(unofficial_napi_terminate_execution(env), napi_ok); + return nullptr; +} +} + +TEST_F(Test77ModuleWrapState, DestroyDuringTerminatedEvaluationKeepsRecordAliveUntilReturn) { + EnvScope s(runtime_.get()); + DestroyingModule state; + napi_value global = nullptr, fn = nullptr; + ASSERT_EQ(napi_get_global(s.env, &global), napi_ok); + ASSERT_EQ(napi_create_function(s.env, "stop", NAPI_AUTO_LENGTH, DestroyAndTerminateModule, &state, &fn), napi_ok); + ASSERT_EQ(napi_set_named_property(s.env, global, "stop", fn), napi_ok); + for (bool facade : {false, true}) { + state.module = CreateSourceTextModule(s.env, "stop(); export default 42;"); + napi_value result = nullptr; + EXPECT_EQ(facade + ? unofficial_napi_module_wrap_create_required_module_facade(s.env, state.module, &result) + : unofficial_napi_module_wrap_evaluate(s.env, state.module, -1, false, &result), napi_pending_exception); + EXPECT_EQ(unofficial_napi_cancel_terminate_execution(s.env), napi_ok); + EXPECT_FALSE(ExceptionPending(s.env)); + EXPECT_EQ(RunText(s.env, "'still usable'"), "still usable"); + } +} + +TEST_F(Test77ModuleWrapState, PendingTopLevelAwaitHasEvaluatedStatusAndIsUnsettled) { + EnvScope s(runtime_.get()); + auto module = CreateSourceTextModule(s.env, "await new Promise(() => {}); export default 1;"); + napi_value promise = nullptr; + ASSERT_EQ(unofficial_napi_module_wrap_evaluate(s.env, module, -1, false, &promise), napi_ok); + EXPECT_EQ(Status(s.env, module), kEvaluated); + bool settled = true; + ASSERT_EQ(unofficial_napi_module_wrap_check_unsettled_top_level_await(s.env, module, false, &settled), napi_ok); + EXPECT_FALSE(settled); + napi_value again = nullptr; + EXPECT_EQ(unofficial_napi_module_wrap_evaluate(s.env, module, -1, false, &again), napi_ok); +} + +TEST_F(Test77ModuleWrapState, FacadeDoesNotRunWhileTerminating) { + EnvScope s(runtime_.get()); + auto module = CreateSourceTextModule(s.env, "globalThis.facadeRan = true; export default 42;"); + ASSERT_EQ(unofficial_napi_terminate_execution(s.env), napi_ok); + napi_value ns = nullptr; + EXPECT_EQ(unofficial_napi_module_wrap_create_required_module_facade(s.env, module, &ns), napi_pending_exception); + EXPECT_EQ(ns, nullptr); + ASSERT_EQ(unofficial_napi_cancel_terminate_execution(s.env), napi_ok); + EXPECT_EQ(RunText(s.env, "typeof facadeRan"), "undefined"); +} + +#if defined(NAPI_TEST_ENGINE_QUICKJS) +TEST_F(Test77ModuleWrapState, ModuleErrorCodeBypassesInheritedSetter) { + EnvScope s(runtime_.get()); + ASSERT_EQ(RunText(s.env, "Object.defineProperty(Error.prototype, 'code', {set() {throw Error('setter');}, configurable: true}); 'ok'"), "ok"); + auto module = CreateSourceTextModule(s.env, "export default 1;"); + EXPECT_EQ(unofficial_napi_module_wrap_link(s.env, module, 1, nullptr), napi_pending_exception); + EXPECT_EQ(TakePendingMessage(s.env), "linked modules array length mismatch"); + EXPECT_FALSE(ExceptionPending(s.env)); +} + +#endif + +TEST_F(Test77ModuleWrapState, FacadeRunsInModulesRealmAndCrossRealmLinksAreRefused) { + EnvScope s(runtime_.get()); + unofficial_napi_realm_options options; + unofficial_napi_realm_options_init(&options); + unofficial_napi_realm realm = nullptr; + napi_value global = nullptr; + ASSERT_EQ(unofficial_napi_create_realm(s.env, &options, &realm, &global), napi_ok); + ASSERT_EQ(napi_set_named_property(s.env, global, "marker", Str(s.env, "module realm")), napi_ok); + ASSERT_EQ(RunText(s.env, "globalThis.marker = 'env realm'"), "env realm"); + auto module = CreateSourceTextModule(s.env, "export default globalThis.marker;", realm); + napi_value ns = nullptr, value = nullptr; + ASSERT_EQ(unofficial_napi_module_wrap_create_required_module_facade(s.env, module, &ns), napi_ok); + ASSERT_EQ(napi_get_named_property(s.env, ns, "default", &value), napi_ok); + EXPECT_EQ(ValueText(s.env, value), "module realm"); + auto importer = CreateSourceTextModule(s.env, "import value from 'dep'; export default value;"); + EXPECT_EQ(unofficial_napi_module_wrap_link(s.env, importer, 1, &module), napi_pending_exception); + EXPECT_EQ(TakePendingMessage(s.env), "Linked modules must use the same realm"); +} + +namespace { +struct FinalizedModule { unofficial_napi_module module; int* finalized; }; +void DestroyFinalizedModule(napi_env env, void* data, void*) { + auto* state = static_cast(data); + EXPECT_EQ(unofficial_napi_module_wrap_destroy(env, state->module), napi_ok); + ++*state->finalized; + delete state; +} +} + +TEST_F(Test77ModuleWrapState, ModuleWrappersAndTheirDependencyCyclesCanBeCollected) { + int finalized = 0; + EnvScope s(runtime_.get()); + for (bool cycle : {false, true}) { + SCOPED_TRACE(cycle); + napi_handle_scope scope = nullptr; + ASSERT_EQ(napi_open_handle_scope(s.env, &scope), napi_ok); + napi_value a_wrapper = nullptr, b_wrapper = nullptr; + auto a = CreateSourceTextModule(s.env, "import 'b'; export const a = 1;", nullptr, &a_wrapper); + auto b = CreateSourceTextModule(s.env, cycle ? "import 'a'; export const b = 2;" : "export const b = 2;", nullptr, &b_wrapper); + ASSERT_EQ(napi_add_finalizer(s.env, a_wrapper, new FinalizedModule{a, &finalized}, DestroyFinalizedModule, nullptr, nullptr), napi_ok); + ASSERT_EQ(napi_add_finalizer(s.env, b_wrapper, new FinalizedModule{b, &finalized}, DestroyFinalizedModule, nullptr, nullptr), napi_ok); + ASSERT_EQ(unofficial_napi_module_wrap_link(s.env, a, 1, &b), napi_ok); + ASSERT_EQ(unofficial_napi_module_wrap_link(s.env, b, cycle ? 1 : 0, cycle ? &a : nullptr), napi_ok); + ASSERT_EQ(napi_close_handle_scope(s.env, scope), napi_ok); + for (int attempt = 0; attempt < 4 && finalized < (cycle ? 4 : 2); ++attempt) { + ASSERT_EQ(unofficial_napi_collect_garbage(s.env), napi_ok); + ASSERT_EQ(unofficial_napi_event_loop_checkpoint(s.env, unofficial_napi_event_loop_checkpoint_microtasks, true, nullptr), napi_ok); + } + EXPECT_EQ(finalized, cycle ? 4 : 2); + } +} + +TEST_F(Test77ModuleWrapState, LiveImporterRetainsItsDependencyWrapper) { + int finalized = 0; + EnvScope s(runtime_.get()); + auto importer = CreateSourceTextModule(s.env, "import {value} from 'dep'; export {value};"); + napi_handle_scope scope = nullptr; + ASSERT_EQ(napi_open_handle_scope(s.env, &scope), napi_ok); + napi_value wrapper = nullptr; + auto dependency = CreateSourceTextModule(s.env, "export const value = 42;", nullptr, &wrapper); + ASSERT_EQ(napi_add_finalizer(s.env, wrapper, new FinalizedModule{dependency, &finalized}, DestroyFinalizedModule, nullptr, nullptr), napi_ok); + ASSERT_EQ(unofficial_napi_module_wrap_link(s.env, importer, 1, &dependency), napi_ok); + ASSERT_EQ(napi_close_handle_scope(s.env, scope), napi_ok); + ASSERT_EQ(unofficial_napi_collect_garbage(s.env), napi_ok); + ASSERT_EQ(unofficial_napi_event_loop_checkpoint(s.env, unofficial_napi_event_loop_checkpoint_microtasks, true, nullptr), napi_ok); + EXPECT_EQ(finalized, 0); + napi_value ns = nullptr, value = nullptr; + ASSERT_EQ(unofficial_napi_module_wrap_evaluate_sync(s.env, importer, nullptr, nullptr, &ns), napi_ok); + ASSERT_EQ(napi_get_named_property(s.env, ns, "value", &value), napi_ok); + EXPECT_EQ(ValueText(s.env, value), "42"); +} + +namespace { +napi_value TerminateModule(napi_env env, napi_callback_info) { + EXPECT_EQ(unofficial_napi_terminate_execution(env), napi_ok); + return nullptr; +} +} + +TEST_F(Test77ModuleWrapState, CancelledModuleErrorIsCatchableAndCheckpointExceptionCanBeTaken) { + EnvScope s(runtime_.get()); + napi_value global = nullptr, stop = nullptr; + ASSERT_EQ(napi_get_global(s.env, &global), napi_ok); + ASSERT_EQ(napi_create_function(s.env, "stop", NAPI_AUTO_LENGTH, TerminateModule, nullptr, &stop), napi_ok); + ASSERT_EQ(napi_set_named_property(s.env, global, "stop", stop), napi_ok); + auto module = CreateSourceTextModule(s.env, "stop(); export default 1;"); + napi_value promise = nullptr; + ASSERT_EQ(unofficial_napi_module_wrap_evaluate(s.env, module, -1, false, &promise), napi_pending_exception); + napi_value taken = nullptr; + ASSERT_EQ(napi_get_and_clear_last_exception(s.env, &taken), napi_ok); + ASSERT_EQ(unofficial_napi_cancel_terminate_execution(s.env), napi_ok); + ASSERT_EQ(napi_set_named_property(s.env, global, "taken", taken), napi_ok); + EXPECT_EQ(RunText(s.env, "(() => {try {throw taken;} catch(e) {return 'caught';}})()"), "caught"); + napi_value error = nullptr; + ASSERT_EQ(unofficial_napi_module_wrap_get_state(s.env, module, nullptr, &error, nullptr), napi_ok); + ASSERT_EQ(napi_set_named_property(s.env, global, "moduleError", error), napi_ok); + EXPECT_EQ(RunText(s.env, "(() => {try {throw moduleError;} catch(e) {return 'caught';}})()"), "caught"); +#if defined(NAPI_TEST_ENGINE_QUICKJS) + ASSERT_EQ(unofficial_napi_module_wrap_evaluate(s.env, module, -1, false, &promise), napi_ok); + EXPECT_EQ(PromiseOutcome(s.env, promise).substr(0, 8), "rejected"); +#endif + EXPECT_FALSE(ExceptionPending(s.env)); +} + +#if defined(NAPI_TEST_ENGINE_V8) +TEST_F(Test77ModuleWrapState, CachedDataPropagatesBufferExceptionsAndRefusesTermination) { + EnvScope s(runtime_.get()); + auto module = CreateSourceTextModule(s.env, "export default 1;"); + ASSERT_EQ(RunText(s.env, "globalThis.Buffer = function Buffer() {}; Buffer.from = () => {throw Error('buffer failure');}; 'ok'"), "ok"); + napi_value cache = nullptr; + EXPECT_EQ(unofficial_napi_module_wrap_create_cached_data(s.env, module, &cache), napi_pending_exception); + EXPECT_EQ(TakePendingMessage(s.env), "buffer failure"); + ASSERT_EQ(RunText(s.env, "Object.defineProperty(globalThis, 'Buffer', {get() {globalThis.bufferGetterRan = true;}, configurable: true}); 'ok'"), "ok"); + ASSERT_EQ(unofficial_napi_terminate_execution(s.env), napi_ok); + EXPECT_EQ(unofficial_napi_module_wrap_create_cached_data(s.env, module, &cache), napi_pending_exception); + ASSERT_EQ(unofficial_napi_cancel_terminate_execution(s.env), napi_ok); + EXPECT_EQ(RunText(s.env, "typeof bufferGetterRan"), "undefined"); +} +#endif + +TEST_F(Test77ModuleWrapState, FacadeRejectionIsHandled) { + EnvScope s(runtime_.get()); + napi_value callback = nullptr; + ASSERT_EQ(napi_run_script(s.env, Str(s.env, + "globalThis.rejections = []; (type, promise, reason) => rejections.push(type)"), &callback), napi_ok); + ASSERT_EQ(unofficial_napi_set_promise_reject_callback(s.env, callback), napi_ok); + auto module = CreateSourceTextModule(s.env, "throw Error('expected'); export default 1;"); + napi_value ns = nullptr; + EXPECT_EQ(unofficial_napi_module_wrap_create_required_module_facade(s.env, module, &ns), napi_pending_exception); + EXPECT_EQ(TakePendingMessage(s.env), "expected"); + // Each notification that a rejection lacked a handler must be balanced. + EXPECT_EQ(RunText(s.env, "rejections.reduce((balance, type) => balance + (type === 0 ? 1 : type === 1 ? -1 : 0), 0)"), "0"); +} + +#if defined(NAPI_TEST_ENGINE_QUICKJS) +TEST_F(Test77ModuleWrapState, ModuleCreationDuringTerminationRunsNoBindingOrSetters) { + EnvScope s(runtime_.get()); + napi_value wrapper = nullptr; + ASSERT_EQ(napi_run_script(s.env, Str(s.env, + "globalThis.creationRan = false; globalThis.internalBinding = () => {creationRan = true; return {};};" + "({set sourceURL(v) {creationRan = true;}, set sourceMapURL(v) {creationRan = true;}})"), &wrapper), napi_ok); + auto source = unofficial_napi_js_source_from_text(Str(s.env, "export default 1;")); + unofficial_napi_module_create_options options{}; + options.size = sizeof(options); + options.version = UNOFFICIAL_NAPI_MODULE_CREATE_OPTIONS_VERSION; + options.kind = unofficial_napi_module_source_text; + options.wrapper = wrapper; + options.url = Str(s.env, "terminated.mjs"); + options.payload.source_text.source = &source; + unofficial_napi_module_create_result result{}; + ASSERT_EQ(unofficial_napi_terminate_execution(s.env), napi_ok); + EXPECT_EQ(unofficial_napi_module_wrap_create(s.env, &options, &result), napi_pending_exception); + EXPECT_EQ(result.module, nullptr); + ASSERT_EQ(unofficial_napi_cancel_terminate_execution(s.env), napi_ok); + EXPECT_EQ(RunText(s.env, "creationRan"), "false"); +} +#endif + +TEST_F(Test77ModuleWrapState, DestroyingImporterReleasesItsDependencyWrappers) { + int finalized = 0; + EnvScope s(runtime_.get()); + auto importer = CreateSourceTextModule(s.env, "import 'dep';"); + napi_handle_scope scope = nullptr; + ASSERT_EQ(napi_open_handle_scope(s.env, &scope), napi_ok); + napi_value wrapper = nullptr; + auto dependency = CreateSourceTextModule(s.env, "export default 1;", nullptr, &wrapper); + ASSERT_EQ(napi_add_finalizer(s.env, wrapper, new FinalizedModule{dependency, &finalized}, DestroyFinalizedModule, nullptr, nullptr), napi_ok); + ASSERT_EQ(unofficial_napi_module_wrap_link(s.env, importer, 1, &dependency), napi_ok); + ASSERT_EQ(napi_close_handle_scope(s.env, scope), napi_ok); + ASSERT_EQ(unofficial_napi_module_wrap_destroy(s.env, importer), napi_ok); + for (int attempt = 0; attempt < 4 && finalized == 0; ++attempt) { + ASSERT_EQ(unofficial_napi_collect_garbage(s.env), napi_ok); + ASSERT_EQ(unofficial_napi_event_loop_checkpoint(s.env, unofficial_napi_event_loop_checkpoint_microtasks, true, nullptr), napi_ok); + } + EXPECT_EQ(finalized, 1); +} + +TEST_F(Test77ModuleWrapState, RetainingDependenciesDoesNotCallArrayPrototypeSetters) { + EnvScope s(runtime_.get()); + auto importer = CreateSourceTextModule(s.env, "import 'dep';"); + auto dependency = CreateSourceTextModule(s.env, "export default 1;"); + ASSERT_EQ(RunText(s.env, "globalThis.setterRan = false; Object.defineProperty(Array.prototype, '0', {set() {setterRan = true;}, configurable: true}); 'ok'"), "ok"); + EXPECT_EQ(unofficial_napi_module_wrap_link(s.env, importer, 1, &dependency), napi_ok); + EXPECT_EQ(RunText(s.env, "delete Array.prototype[0]; String(setterRan)"), "false"); +} diff --git a/tests/runners/test_78_termination_until_cancelled.cc b/tests/runners/test_78_termination_until_cancelled.cc index a30f584a42..e333303668 100644 --- a/tests/runners/test_78_termination_until_cancelled.cc +++ b/tests/runners/test_78_termination_until_cancelled.cc @@ -207,6 +207,7 @@ constexpr const char* kJsCalls[] = { "unofficial_napi_compile_function (getter in the extensions)", "napi_create_buffer (Buffer getter)", "napi_create_error (code setter)", + "unofficial_napi_module_wrap_create_required_module_facade", "unofficial_napi_mark_promise_as_handled (reject callback)", }; constexpr int kJsCallCount = sizeof(kJsCalls) / sizeof(kJsCalls[0]); @@ -222,6 +223,7 @@ constexpr const char* kJsCallPayloads[] = { "(() => { const a = [{}]; Object.defineProperty(a, 0, { get() { afterCall = 'yes'; return {}; } }); return a; })()", "(Object.defineProperty(globalThis, 'Buffer', { get() { afterCall = 'yes'; return undefined; }, configurable: true }), undefined)", "(Object.defineProperty(Error.prototype, 'code', { set(v) { afterCall = 'yes'; }, configurable: true }), undefined)", + "undefined", "(() => { const p = Promise.reject(1); return p; })()", }; @@ -273,6 +275,8 @@ napi_status CallRunningJs(napi_env env, int kind, napi_value payload) { } case 9: return napi_create_error(env, Str(env, "E_CODE"), Str(env, "message"), &out); + case 10: + return unofficial_napi_module_wrap_create_required_module_facade(env, g_module, &out); default: return unofficial_napi_mark_promise_as_handled(env, payload); } @@ -590,7 +594,7 @@ TEST_F(Test78TerminationUntilCancelled, CallsRunningJsAfterTheTermination) { SCOPED_TRACE(kJsCalls[kind]); EnvScope s(runtime_.get()); InstallHelpers(s.env); - g_module = MakeModule(s.env, "globalThis.afterCall = 'yes';", nullptr); + g_module = MakeModule(s.env, "globalThis.afterCall = 'yes'; export default 1;", nullptr); ASSERT_NE(g_module, nullptr); // Called again, for a rejected promise a handler is added to. ASSERT_EQ(unofficial_napi_set_promise_reject_callback( @@ -625,6 +629,7 @@ constexpr const char* kStoppedCalls[] = { "unofficial_napi_module_wrap_evaluate", "unofficial_napi_module_wrap_evaluate_sync", "unofficial_napi_get_own_non_index_properties (proxy)", + "unofficial_napi_module_wrap_create_required_module_facade", #if defined(NAPI_TEST_ENGINE_V8) "unofficial_napi_create_realm (proxy sandbox)", #endif @@ -636,7 +641,7 @@ TEST_F(Test78TerminationUntilCancelled, CallsTheTerminationStopsLeaveItPending) SCOPED_TRACE(kStoppedCalls[kind]); EnvScope s(runtime_.get()); InstallHelpers(s.env); - unofficial_napi_module module = MakeModule(s.env, "terminateJs();", nullptr); + unofficial_napi_module module = MakeModule(s.env, "terminateJs(); export default 1;", nullptr); ASSERT_NE(module, nullptr); napi_value proxy = Eval(s.env, "new Proxy({}, { ownKeys() { terminateJs(); afterCall = 'yes'; return []; } })"); @@ -660,6 +665,9 @@ TEST_F(Test78TerminationUntilCancelled, CallsTheTerminationStopsLeaveItPending) case 3: status = unofficial_napi_get_own_non_index_properties(s.env, proxy, 0, &out); break; + case 4: + status = unofficial_napi_module_wrap_create_required_module_facade(s.env, module, &out); + break; default: { unofficial_napi_realm_options options; unofficial_napi_realm_options_init(&options); @@ -1246,3 +1254,18 @@ TEST_F(Test78TerminationUntilCancelled, CancelWakesTheHostForTheTasksLeftQueued) EXPECT_EQ(GlobalText(s.env, "resolved"), "yes"); } #endif + +TEST_F(Test78TerminationUntilCancelled, ErrorCreationWithoutCodeUsesProviderTerminationPolicy) { + EnvScope s(runtime_.get()); + napi_value message = Str(s.env, "reason"), error = nullptr; + ASSERT_EQ(unofficial_napi_terminate_execution(s.env), napi_ok); +#if defined(NAPI_TEST_ENGINE_V8) + EXPECT_EQ(napi_create_error(s.env, nullptr, message, &error), napi_ok); + bool is_error = false; + EXPECT_EQ(napi_is_error(s.env, error, &is_error), napi_ok); + EXPECT_TRUE(is_error); +#else + EXPECT_EQ(napi_create_error(s.env, nullptr, message, &error), napi_pending_exception); +#endif + EXPECT_EQ(unofficial_napi_cancel_terminate_execution(s.env), napi_ok); +} diff --git a/v8/src/js_native_api_v8.cc b/v8/src/js_native_api_v8.cc index 989dcaf084..11418932b2 100644 --- a/v8/src/js_native_api_v8.cc +++ b/v8/src/js_native_api_v8.cc @@ -3396,8 +3396,10 @@ static napi_status CreateErrorCommon(napi_env env, napi_value code, napi_value msg, napi_value* result) { - // Setting the code runs an inherited `code` setter. - NAPI_V8_RETURN_IF_TERMINATING(env); + // Only setting the code can run JS through an inherited setter. + if (code != nullptr) { + NAPI_V8_RETURN_IF_TERMINATING(env); + } if (!CheckEnv(env) || msg == nullptr || result == nullptr) return napi_invalid_arg; v8::Local msg_val = napi_v8_unwrap_value(msg); if (!msg_val->IsString()) return napi_string_expected; diff --git a/v8/src/unofficial_napi_contextify.cc b/v8/src/unofficial_napi_contextify.cc index 0134dc88d2..955a776847 100644 --- a/v8/src/unofficial_napi_contextify.cc +++ b/v8/src/unofficial_napi_contextify.cc @@ -81,6 +81,7 @@ struct ModuleWrapBindingState { napi_ref import_module_dynamically_ref = nullptr; napi_ref initialize_import_meta_ref = nullptr; std::vector modules; + v8::Global dependency_key; std::vector pending_dynamic_imports; ModuleWrapRecord* temporary_required_module_facade_original = nullptr; // Instantiations running (see InstantiationScope). @@ -624,12 +625,27 @@ void RemoveModuleRecord(napi_env env, ModuleWrapRecord* record) { if (state == nullptr) return; auto& modules = state->modules; modules.erase(std::remove(modules.begin(), modules.end(), record), modules.end()); + for (ModuleWrapRecord* dependent : modules) + for (ModuleWrapRecord*& linked : dependent->linked_requests) + if (linked == record) linked = nullptr; } void DestroyModuleRecord(ModuleWrapRecord* record) { if (record == nullptr || record->env == nullptr) return; napi_env env = record->env; RemoveModuleRecord(env, record); + auto* state = GetModuleWrapState(env); + if (state != nullptr && !state->dependency_key.IsEmpty()) { + v8::HandleScope scope(env->isolate); + napi_value wrapper = nullptr; + if (napi_get_reference_value(env, record->wrapper_ref, &wrapper) == napi_ok && wrapper != nullptr) { + v8::Local raw = napi_v8_unwrap_value(wrapper); + if (raw->IsObject()) { + (void)raw.As()->DeletePrivate(record->context.Get(env->isolate), + state->dependency_key.Get(env->isolate)); + } + } + } ResetRef(env, &record->wrapper_ref); ResetRef(env, &record->synthetic_eval_steps_ref); ResetRef(env, &record->source_object_ref); @@ -709,11 +725,17 @@ bool ReadArrayBufferViewBytes(v8::Local value, bool CreateNodeBufferFromBytes(napi_env env, const uint8_t* data, size_t size, napi_value* out) { if (out == nullptr) return false; *out = nullptr; + if (napi_v8_terminating(env)) { + napi_v8_fail_terminating(env); + return false; + } v8::Isolate* isolate = env->isolate; // Buffer is the env's: read and call it in the env's realm, never in the // current one, whose global its scripts control. v8::Local context = env->main_context(); + v8::Context::Scope context_scope(context); + v8::TryCatch caught(isolate); std::unique_ptr store = v8::ArrayBuffer::NewBackingStore(isolate, size); if (!store) return false; @@ -735,12 +757,21 @@ bool CreateNodeBufferFromBytes(napi_env env, const uint8_t* data, size_t size, n v8::Local argv[1] = {view}; v8::Local buffer_out; if (from_value.As()->Call(context, buffer_ctor_value, 1, argv).ToLocal(&buffer_out)) { + if (napi_v8_terminating(env)) { + napi_v8_fail_terminating(env); + return false; + } *out = napi_v8_wrap_value(env, buffer_out); return *out != nullptr; } } } + if (caught.HasCaught() || napi_v8_terminating(env)) { + if (napi_v8_terminating(env)) napi_v8_fail_terminating(env); + else ThrowTryCatchException(env, caught); + return false; + } *out = napi_v8_wrap_value(env, view); return *out != nullptr; } @@ -817,6 +848,7 @@ void CleanupModuleWrapState(void* arg) { ResetRef(env, &it->second.import_module_dynamically_ref); ResetRef(env, &it->second.initialize_import_meta_ref); + it->second.dependency_key.Reset(); for (auto& promise : it->second.pending_dynamic_imports) promise.value.Reset(); it->second.pending_dynamic_imports.clear(); g_module_wrap_states.erase(it); @@ -2134,7 +2166,7 @@ napi_status NAPI_CDECL unofficial_napi_bytecode_serialize( napi_value buffer = nullptr; if (!CreateNodeBufferFromBytes(env, record->bytes.data(), record->bytes.size(), &buffer) || buffer == nullptr) { - return napi_generic_failure; + return env->last_exception.IsEmpty() ? napi_generic_failure : napi_pending_exception; } v8::Local buffer_value = napi_v8_unwrap_value(buffer); if (buffer_value.IsEmpty()) return napi_generic_failure; @@ -2635,7 +2667,7 @@ static napi_status CreateSourceTextModule( record->env = env; record->context.Reset(isolate, context); record->module.Reset(isolate, module); - napi_create_reference(env, wrapper, 1, &record->wrapper_ref); + napi_create_reference(env, wrapper, 0, &record->wrapper_ref); napi_value host_id_value = napi_v8_wrap_value(env, host_id_symbol); if (host_id_value != nullptr) { @@ -2715,7 +2747,7 @@ static napi_status CreateSyntheticModule( record->env = env; record->context.Reset(isolate, context); record->module.Reset(isolate, module); - napi_create_reference(env, wrapper, 1, &record->wrapper_ref); + napi_create_reference(env, wrapper, 0, &record->wrapper_ref); napi_create_reference(env, synthetic_eval_steps, 1, &record->synthetic_eval_steps_ref); { @@ -2850,6 +2882,22 @@ napi_status NAPI_CDECL unofficial_napi_module_wrap_link( return napi_pending_exception; } + if (record->module.Get(env->isolate)->GetStatus() != v8::Module::kUninstantiated) { + ThrowCodeError(env, "ERR_VM_MODULE_ALREADY_LINKED", "Module is already linked"); + return napi_pending_exception; + } + for (size_t i = 0; i < count; ++i) { + ModuleWrapRecord* linked = linked_modules != nullptr + ? FindModuleRecordForHandle(env, linked_modules[i]) : nullptr; + if (linked == nullptr) { + ThrowCodeError(env, "ERR_VM_MODULE_LINK_FAILURE", "linked module missing"); + return napi_pending_exception; + } + if (linked->context.Get(env->isolate) != record->context.Get(env->isolate)) { + ThrowCodeError(env, "ERR_VM_MODULE_DIFFERENT_CONTEXT", "Linked modules must use the same realm"); + return napi_pending_exception; + } + } record->linked_requests.assign(count, nullptr); for (size_t i = 0; i < count; ++i) { ModuleWrapRecord* linked = @@ -2869,6 +2917,24 @@ napi_status NAPI_CDECL unofficial_napi_module_wrap_link( return napi_pending_exception; } } + auto* state = GetModuleWrapState(env); + v8::Isolate* isolate = env->isolate; + v8::HandleScope scope(isolate); + v8::Local context = record->context.Get(isolate); + v8::Local dependencies = v8::Array::New(isolate, static_cast(count)); + for (size_t i = 0; i < count; ++i) { + napi_value wrapper = GetRefValue(env, record->linked_requests[i]->wrapper_ref); + if (wrapper == nullptr || !dependencies->CreateDataProperty(context, static_cast(i), + napi_v8_unwrap_value(wrapper)).FromMaybe(false)) + return napi_invalid_arg; + } + napi_value wrapper = GetRefValue(env, record->wrapper_ref); + if (wrapper == nullptr) return napi_invalid_arg; + if (state->dependency_key.IsEmpty()) + state->dependency_key.Reset(isolate, v8::Private::New(isolate)); + if (!napi_v8_unwrap_value(wrapper).As()->SetPrivate( + context, state->dependency_key.Get(isolate), dependencies).FromMaybe(false)) + return napi_generic_failure; return napi_ok; } @@ -3234,19 +3300,20 @@ napi_status NAPI_CDECL unofficial_napi_module_wrap_create_cached_data( unofficial_napi_module module_handle, napi_value* result_out) { if (env == nullptr || module_handle == nullptr || result_out == nullptr) return napi_invalid_arg; + NAPI_V8_RETURN_IF_TERMINATING(env); ModuleWrapRecord* record = ModuleRecord(module_handle); v8::Isolate* isolate = env->isolate; v8::EscapableHandleScope handle_scope(isolate); v8::Local module = record->module.Get(isolate); napi_value out = nullptr; if (!module->IsSourceTextModule()) { - if (!CreateNodeBufferFromBytes(env, nullptr, 0, &out) || out == nullptr) return napi_generic_failure; + if (!CreateNodeBufferFromBytes(env, nullptr, 0, &out) || out == nullptr) return env->last_exception.IsEmpty() ? napi_generic_failure : napi_pending_exception; } else { std::unique_ptr cached_data( v8::ScriptCompiler::CreateCodeCache(module->GetUnboundModuleScript())); const uint8_t* bytes = cached_data ? cached_data->data : nullptr; const size_t size = cached_data ? static_cast(cached_data->length) : 0; - if (!CreateNodeBufferFromBytes(env, bytes, size, &out) || out == nullptr) return napi_generic_failure; + if (!CreateNodeBufferFromBytes(env, bytes, size, &out) || out == nullptr) return env->last_exception.IsEmpty() ? napi_generic_failure : napi_pending_exception; } v8::Local out_value = napi_v8_unwrap_value(out); if (out_value.IsEmpty()) return napi_generic_failure; @@ -3304,7 +3371,7 @@ napi_status NAPI_CDECL unofficial_napi_module_wrap_create_required_module_facade if (InstantiationScope::ThrowIfRunning(env)) return napi_pending_exception; v8::Isolate* isolate = env->isolate; v8::EscapableHandleScope handle_scope(isolate); - v8::Local context = env->context(); + v8::Local context = record->context.Get(isolate); v8::Context::Scope context_scope(context); const char* kFacadeUrl = "node:internal/require_module_default_facade"; From f564b7add39dddd97c0dd80b87f8a24626d5ad99 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Fri, 6 Nov 2026 09:59:36 -0800 Subject: [PATCH 150/150] Document all PR 127 review findings, fixes and remaining work --- docs/pr127-review-followups.md | 600 ++++++++++++++++++++++++++++++--- 1 file changed, 554 insertions(+), 46 deletions(-) diff --git a/docs/pr127-review-followups.md b/docs/pr127-review-followups.md index 4e509807da..9de66b3a0c 100644 --- a/docs/pr127-review-followups.md +++ b/docs/pr127-review-followups.md @@ -1,50 +1,558 @@ -# PR #127 review follow-ups +# PR #127: module-state and Node-parity review assessment -The two local reviews of `fin/next` at `80b591e` reported 19 findings: -14 in `review-module-state.json` and five in `review-node-parity.json`. -The changes here start from published `next` at `e45b116`. +Assessment date: 2026-11-06. Implementation and test results refer to +[`ab41860`](https://github.com/wasmerio/napi/commit/ab41860dbde7e58ca166f8cfebb93760d285d5f0), +which was pushed to `next` for [PR #127](https://github.com/wasmerio/napi/pull/127). +This document records the disposition of the findings; it does not imply that +all remaining engine differences or integration checks are complete. -The numbering below follows the module report first, then the parity report. -Sixteen items have implementation fixes; three existing termination differences -have explicit API documentation rather than behavior changes. +## Summary -| # | Finding | Disposition | -|---|---|---| -| 1 | QuickJS require facade bypasses termination | Check before running code and after evaluation; include the facade in both termination-call matrices. | -| 2 | Stored QuickJS module errors remain uncatchable after cancel; checkpoint exceptions cannot be taken | Clear stored errors' uncatchable flag on cancellation, and transfer failed-job exceptions into the env. | -| 3 | V8 facade instantiates in the current realm | Use the wrapped module's creation context. | -| 4 | Strong module wrapper references prevent collection | Use weak wrapper references and private JS edges for dependency wrappers; unreachable import cycles can be collected. The embedder still owns destruction of each native record. | -| 5 | QuickJS relinking after instantiation crashes | Refuse relinking after instantiation on both providers. | -| 6 | Destroyed V8 dependency record can resolve to a new module at the same address | Clear incoming record pointers at destruction. V8 refuses subsequent instantiation through them. | -| 7 | QuickJS destruction during terminated evaluation reads freed memory | Defer record destruction while linking, evaluating, or running synthetic steps. | -| 8 | QuickJS pending top-level await reports the wrong state and settledness | Map async evaluation to evaluated, inspect the linked graph for pending async evaluation, and warn with the module URL. Exact source positions remain unavailable. | -| 9 | V8 cached-data Buffer construction runs JS during termination and swallows exceptions | Guard termination and report Buffer getter/from exceptions; apply the shared helper's error status to bytecode serialization too. | -| 10 | QuickJS module creation/error construction runs JS during termination | Guard creation before binding lookups/setters, check source metadata setter failures and termination, and define module error codes as own properties. The engine's documented prepareStackTrace gap remains. | -| 11 | Throwing QuickJS error-code setter leaves an untakeable exception | Bypass the inherited setter when defining a module error's code. | -| 12 | QuickJS facade produces a spurious unhandled rejection | Mark the rejected facade promise handled before returning its reason. | -| 13 | Cross-realm links have different execution realms across engines | Refuse cross-realm links on both providers with ERR_VM_MODULE_DIFFERENT_CONTEXT. | -| 14 | Smaller module API result differences | Align link error codes/statuses, the absent source-object result, request-array realm, and evaluate_sync's async-module diagnostic. | -| 15 | V8 refuses error creation without a code during termination | Guard only the case with a code; document QuickJS's broader refusal. | -| 16 | Refusal status/pending state differs from Node's versioned shutdown preamble | Document the existing unofficial termination contract: napi_pending_exception and a pending marker for every module API version. | -| 17 | A retrieved QuickJS termination value remains uncatchable after cancel | Expose null from get_and_clear_last_exception for an internal termination marker, matching V8. | -| 18 | QuickJS resumes leftover promise jobs after cancel | Document existing queue persistence; embedders decide whether to run another checkpoint. | -| 19 | V8 builtins without user JS frames may finish after termination | Document V8's stack-check boundary and possible napi_ok result, preserving Node's behavior and DisallowJavascriptExecutionScope compatibility. | - -## Validation - -On macOS arm64, the complete native CTest suites pass: - -| Configuration | Result | +**Sixteen of the 19 findings have implementation fixes. Three Node-parity +findings received documentation changes while retaining their behavior.** + +| Source report | Findings | Implementation fixes | Behavior retained and documented | +|---|---:|---:|---:| +| Module state | 14 | 14 | 0 | +| Node parity | 5 | 2 | 3 | +| Total | 19 | 16 | 3 | + +The parity fixes are P1 and P3. Exact Node shutdown-status parity (P2) and +QuickJS microtask-discard parity (P4) remain unimplemented. P5 matches Node's +V8 behavior; the intended resolution is documentation, with no behavior change +planned in this follow-up. + +“Implementation fix” means code changed to address the reported failure. It +is not a claim of complete Node equivalence, unrestricted module lifetime +semantics, or validation on every embedder and provider. The qualifications +under each finding and the outstanding validation below are part of this +assessment. + +## Provenance and numbering + +The original reviews examined `fin/next` at +`80b591ecb547623a0033d783c66186bc029c9d32`. Their files were saved in the +WebkitWasm checkout under `docs/research/napi-pr120-review-2026-11-05/`: + +- `review-module-state.json`: 14 findings, identified here as M1–M14. +- `review-node-parity.json`: five findings, identified here as P1–P5. + +That directory's name refers to the earlier PR #120 review, but these two +reports reviewed the later `fin/next` snapshot. They are separate from the +larger, older `review-findings.json` in the same directory. + +The raw JSON reports remain local to WebkitWasm and were not included in the +napi push. This Markdown assessment and the implementation fixes are tracked +in napi. The implementation branch started at published `next` commit +`e45b11683d849bea4e1b21028699e205cc5e3406`. + +The earlier assessment used one sequence numbered 1–19. M1–M14 correspond to +1–14, and P1–P5 correspond to 15–19. Severities below are the original +reviewers' ratings, rather than a new severity ranking. Some findings predate +`next`; the count is not a count of 19 new PR regressions. + +## Findings at a glance + +| Source ID | Earlier # | Severity | Provider | Disposition | +|---|---:|---|---|---| +| M1 | 1 | High | QuickJS | Implementation fix: require facade termination checks | +| M2 | 2 | Medium | QuickJS | Implementation fix: catchable stored module errors after cancel and retrievable failed-job exceptions | +| M3 | 3 | Medium | V8 | Implementation fix: facade uses module's creation realm | +| M4 | 4 | Medium | Both | Implementation fix: weak wrappers and GC-visible dependency edges | +| M5 | 5 | Medium | QuickJS; aligned on V8 | Implementation fix: reject relinking after instantiation | +| M6 | 6 | Medium | V8 | Implementation fix: invalidate incoming pointers on destruction | +| M7 | 7 | Medium | QuickJS | Implementation fix: defer destruction during active engine calls | +| M8 | 8 | Medium | QuickJS | Implementation fix: async status and unsettled-await detection; source-position limitation remains | +| M9 | 9 | Low | V8 | Implementation fix: cached-data termination checks and Buffer exception propagation | +| M10 | 10 | Low | QuickJS | Implementation fix: guard module creation and bypass error-code setters; engine stack-formatting gap remains | +| M11 | 11 | Low | QuickJS | Implementation fix: eliminate inherited code-setter exception residue | +| M12 | 12 | Low | QuickJS | Implementation fix: mark rejected facade promise handled | +| M13 | 13 | Low | V8; aligned on QuickJS | Implementation fix: reject cross-realm links | +| M14 | 14 | Low | Both | Implementation fix: align smaller module API results | +| P1 | 15 | Medium | V8 | Implementation fix: permit error creation without a code during termination | +| P2 | 16 | Low | Both | Documented divergence: Node's version-dependent refusal status/pending state is not implemented | +| P3 | 17 | Low | QuickJS | Implementation fix: expose null instead of an uncatchable termination value | +| P4 | 18 | Low | QuickJS | Documented divergence: leftover promise jobs remain queued after termination | +| P5 | 19 | Low | V8 | Documented Node-compatible limitation: native-only builtin callbacks can continue until a stack check | + +## Module-state report: 14 implementation fixes + +The main implementations are +[`quickjs/src/internal/napi_module_wrap.cc`](../quickjs/src/internal/napi_module_wrap.cc) +and [`v8/src/unofficial_napi_contextify.cc`](../v8/src/unofficial_napi_contextify.cc). +New module regressions are in +[`tests/runners/test_77_module_wrap_state.cc`](../tests/runners/test_77_module_wrap_state.cc). +The extended termination matrices are in +[`tests/runners/test_78_termination_until_cancelled.cc`](../tests/runners/test_78_termination_until_cancelled.cc). + +### M1 — QuickJS require facade ignores termination + +**Original severity: high. Status: implementation fix.** + +The facade could link and evaluate a short module body after termination had +been requested, then return `napi_ok` and a namespace. QuickJS's periodic +interrupt polling did not reliably stop short bodies. Ordinary evaluation +already checked the termination flag, so this facade bypassed the provider's +shutdown contract. + +`create_required_module_facade` now calls `fail_if_terminating` before running +code and checks termination again after evaluation. An interrupted evaluation +marks the promise handled, releases its temporary values, and returns the +termination failure. The facade was added to the existing matrices for calls +made after termination and calls whose execution is stopped by termination. +`FacadeDoesNotRunWhileTerminating` directly checks that the body does not run. + +### M2 — Stored QuickJS module errors remain uncatchable after cancellation + +**Original severity: medium. Status: implementation fix.** + +A stopped module retained QuickJS's uncatchable interruption error as its +module-evaluation error. Cancellation cleared the environment's termination +flag but left the stored object uncatchable. Rethrowing that object or +encountering it through a module graph could bypass `catch` and `finally` +after cancellation. A failed pending job could also leave an exception in the +runtime without transferring it to the environment's exception slot. + +Cancellation now visits module records and clears the uncatchable flag on +stored evaluation errors. The failed-job path in +[`napi_util__::run_pending_jobs`](../quickjs/src/internal/napi_util.cc) +transfers a runtime exception into the environment when execution is no +longer terminating, making it available through the public exception API. + +`CancelledModuleErrorIsCatchableAndCheckpointExceptionCanBeTaken` checks that +taken and stored termination-related errors are catchable after cancellation; +on QuickJS it also checks replay of the errored module. The runtime-to-env +failed-job transfer was inspected, and the complete provider suites passed; +this follow-up does not claim a separate regression for every failed-job +variant from the original probe report. See P3 for the related +publicly retrieved termination value. + +### M3 — V8 facade uses the current realm instead of the module's realm + +**Original severity: medium. Status: implementation fix.** + +A facade could instantiate a previously uninstantiated module using the +current N-API context. A module explicitly created in realm R could therefore +run against the environment's global, or the reverse, depending on which +realm was entered when the facade was requested. + +The facade now scopes instantiation and evaluation to the wrapped module's +creation context. `FacadeRunsInModulesRealmAndCrossRealmLinksAreRefused` +checks the exported global marker when the facade is requested from another +realm. Cross-realm dependency links are handled separately under M13. + +### M4 — Strong wrapper ownership prevents module and realm collection + +**Original severity: medium. Status: implementation fix. Pre-existing.** + +Each native module record strongly retained its JavaScript wrapper. EdgeJS +expects the wrapper's finalizer to destroy that native record, so the native +reference prevented the finalizer from running and retained the record and +its realm until environment release. + +Both providers now hold the wrapper weakly. Dependency wrappers are retained +through private JavaScript references on the importing wrapper, making those +edges visible to the collector and allowing unreachable import cycles to be +collected. Explicit destruction also releases the importer's private +dependency references. Dependency-array construction defines own properties +so inherited array setters cannot intercept it. + +The ownership contract still matters: the embedder owns native-record +destruction and should call `unofficial_napi_module_wrap_destroy` from its +wrapper finalizer. A raw native module handle alone does not retain the +wrapper. Callers must keep the wrapper reachable while using that handle. +This change does not introduce automatic native-record destruction for an +embedder that installs no finalizer. + +Coverage includes collection of wrapper/dependency cycles, retention of a +dependency by a live importer, release of dependencies when the importer is +destroyed, and protection against inherited array setters. The complete +provider suites and ASan runs also cover the changed ownership paths. + +### M5 — QuickJS relinking after instantiation can crash evaluation + +**Original severity: medium. Status: implementation fix.** + +Relinking replaced QuickJS's module request underneath an already instantiated +graph. Later evaluation could recurse into an uninstantiated replacement, +assert in Debug, or crash in Release. V8 kept its previously instantiated +graph, producing different behavior for the same API sequence. + +Both providers now reject linking after instantiation with +`ERR_VM_MODULE_ALREADY_LINKED`. `RelinkingAnInstantiatedModuleIsRefused` +checks that the replacement is refused and evaluation still produces the +original dependency's value. Supplying links before instantiation remains +supported; this is a state-boundary check rather than a ban on all repeated +calls before instantiation. + +### M6 — Destroyed V8 dependency records can resolve to unrelated modules + +**Original severity: medium. Status: implementation fix.** + +An importer kept raw pointers to dependency records. Explicitly destroying a +dependency freed its record, and a later allocation could reuse that address. +The importer could then resolve its old request to the unrelated new module. +Slab allocation made a plain ASan check insufficient to detect this logical +identity error. + +Destruction now clears incoming native link pointers before the record can be +reused. V8 subsequently refuses instantiation through a missing dependency +instead of resolving it to a new record. The private wrapper edges from M4 +also keep normally linked wrappers alive until their importer no longer +retains them. + +`DestroyedDependencyCannotBecomeAnotherModule` checks that the unrelated +module never executes. Explicit destruction still differs between providers: +QuickJS retains its actual linked engine module and can continue using it; +V8 refuses later instantiation through the invalidated native link. This +boundary is documented. Embedders should avoid explicitly destroying a +dependency while an importer still needs it, and must never reuse a destroyed +native handle. + +### M7 — QuickJS destruction during terminated evaluation reads freed memory + +**Original severity: medium. Status: implementation fix.** + +A native callback reached from a module body could destroy that module and +request termination. After `JS_EvaluateModule` returned, the termination path +still read the freed record's context while handling the evaluation promise. + +A scoped active-call count now keeps the record and context alive during +linking, evaluation, facade execution, and synthetic evaluation steps. +Destruction requested while a call is active is deferred until its final +scope exits. The public lookup refuses a record already marked for +destruction. + +`DestroyDuringTerminatedEvaluationKeepsRecordAliveUntilReturn` exercises both +ordinary evaluation and the facade. It checks that cancellation leaves the +environment usable. The complete QuickJS Debug+ASan suite passes with these +paths enabled. + +### M8 — QuickJS pending top-level await reports incorrect state and settledness + +**Original severity: medium. Status: implementation fix with a diagnostic limitation.** + +QuickJS reported a module waiting on top-level await as “evaluating,” while +V8's public API reports it as “evaluated.” Its unsettled-await check always +returned settled. EdgeJS feeds those results into Node's module and exit +logic, so the mismatch could affect repeated evaluation and exit-time stalled +await detection. + +QuickJS now maps asynchronous evaluation to the evaluated public state. The +unsettled-await check walks the linked record graph and detects asynchronous +evaluations that remain pending. With warnings enabled it prints the module +URL. `PendingTopLevelAwaitHasEvaluatedStatusAndIsUnsettled` checks state, +settledness, and another evaluation request while the await remains pending. + +**Remaining limitation:** the QuickJS warning has no exact stalled source line +or column. An EdgeJS integration run confirming the final warning and exit +code has not been performed in this follow-up. + +### M9 — V8 cached-data creation runs JS during termination and swallows errors + +**Original severity: low. Status: implementation fix.** + +Creating the output Buffer used raw V8 property reads and a call to +`Buffer.from`. A getter or that function could run after termination, and an +exception from `Buffer.from` could be swallowed while the helper fell back to +a plain `Uint8Array`. + +Cached-data creation now refuses termination before the helper runs. The +shared Buffer helper also checks termination and captures JavaScript +exceptions, which are returned as pending exceptions instead of triggering a +silent fallback. Bytecode serialization, another caller of the same helper, +now preserves that pending-exception status too. + +`CachedDataPropagatesBufferExceptionsAndRefusesTermination` checks the thrown +Buffer error and verifies that a Buffer getter does not run during +termination. + +### M10 — QuickJS module creation and error paths run JS during termination + +**Original severity: low. Status: implementation fix with an engine limitation.** + +Module creation could call a JavaScript `internalBinding`, invoke wrapper +metadata setters, or run an inherited `Error.prototype.code` setter while the +environment was terminating. Raw engine calls bypassed the ordinary N-API +termination guards. + +Source and synthetic module creation now refuse an existing termination +before those creation steps. Source creation checks termination after the +host-option lookup and metadata setters, and reports setter failures rather +than ignoring them. Module error codes are defined as own properties, which +bypasses inherited setters. + +`ModuleCreationDuringTerminationRunsNoBindingOrSetters`, +`ModuleErrorCodeBypassesInheritedSetter`, and the termination suites cover +these paths. + +**Remaining engine limitation:** QuickJS-ng can read `Error.prepareStackTrace` +while constructing an error, including while interruption unwinds. This +provider fix does not repair that engine-level behavior. It remains explicitly +documented in the public termination contract. + +### M11 — A throwing QuickJS error-code setter leaves exception residue + +**Original severity: low. Status: implementation fix.** + +The module error helper ignored failure from setting `error.code`. If an +inherited setter threw, the environment held the intended module error while +the runtime retained another exception. After taking the module error, +“exception pending” could stay true and another take would fail. + +The helper now defines an own `code` property and checks failures. No inherited +setter runs. `ModuleErrorCodeBypassesInheritedSetter` verifies that the intended +module error can be taken and that nothing remains pending afterward. This +shares the error-helper change with M10 but addresses a distinct reported +failure. + +### M12 — QuickJS facade produces a spurious unhandled rejection + +**Original severity: low. Status: implementation fix.** + +When a module threw, the facade returned its error to the caller but left the +facade's rejected evaluation promise unhandled. An embedder could report an +unhandled rejection even though JavaScript caught the synchronous require +error. + +The facade now marks that promise handled before extracting its rejection +reason. `FacadeRejectionIsHandled` verifies that rejection notifications are +balanced and the intended error is still returned. + +### M13 — Cross-realm links execute differently across providers + +**Original severity: low. Status: implementation fix through a stricter contract.** + +V8 could instantiate a dependency in its importer's realm even when the +dependency had been created in another realm. QuickJS kept the dependency's +own realm. Node's vm layer rejects this cross-context arrangement before it +reaches the engine binding. + +Both providers now reject cross-realm links with +`ERR_VM_MODULE_DIFFERENT_CONTEXT`. This makes the accepted API behavior +consistent and avoids silently executing against an unintended global. The +combined facade/realm regression checks the refusal. + +Callers that previously supplied cross-realm graphs must instead create a +graph within one realm. This follow-up does not implement portable +cross-realm module execution. + +### M14 — Smaller module API result differences + +**Original severity: low. Status: implementation fixes.** + +The report grouped several observable differences under one finding. The +follow-up aligns them as follows: + +| Case | Result after the change | |---|---| -| V8 Release | 356 passed | -| QuickJS Release | 306 passed | -| V8 Release with AddressSanitizer | 355 passed, one sanitizer-specific skip | -| QuickJS Debug with AddressSanitizer | 306 passed | - -The ASan runs use `ASAN_OPTIONS=detect_leaks=0`; QuickJS Debug retains its -runtime leak assertions. Sixteen new test cases cover the reported failure -modes and wrapper/dependency GC behavior. The existing termination matrices -also exercise the facade before and during termination. - -This pass does not include an EdgeJS build, WASIX/host-JS integration tests, -or performance benchmarking. +| Link count mismatch | QuickJS uses V8's `ERR_VM_MODULE_LINK_FAILURE` and length-mismatch message. | +| NULL linked-module array with a matching nonzero count | QuickJS returns a pending link error, matching V8. | +| No module source object has been set | QuickJS returns `napi_ok` with a NULL result, matching V8. | +| Module-request array produced with a realm entered | QuickJS creates the array in the current N-API realm. | +| Async-module diagnostic from `evaluate_sync` | QuickJS includes the import hint and supplied filename/parent context used by V8's message. | + +These alignments target provider consistency for the reported cases. They do +not claim that every module API error exactly reproduces Node's behavior; +Node sometimes rejects input at a higher JavaScript layer. Validation used +the complete module/realm suites and the added link/error regressions, rather +than a separate new test for every subcase in this grouped finding. + +## Node-parity report: two implementation fixes, three retained behaviors + +### P1 — V8 refuses error creation without a code during termination + +**Original severity: medium. Earlier #15. Status: implementation fix.** + +The new guard rejected `napi_create_error`, `napi_create_type_error`, +`napi_create_range_error`, and `node_api_create_syntax_error` even when no +error code was supplied. On V8, constructing that error runs no JavaScript; +only setting a code can run an inherited setter. Node permits the no-code +case. The reviewer identified the broad refusal as a regression from `main`. + +V8's shared `CreateErrorCommon` now guards only the case where a code is +supplied. `ErrorCreationWithoutCodeUsesProviderTerminationPolicy` checks +successful no-code creation on V8 during termination. + +QuickJS still refuses no-code creation because its error construction can +read `Error.prepareStackTrace`. The test pins that provider policy too, and +the public header explains the reason for the remaining difference. + +### P2 — Refusal status and pending state differ from Node's shutdown preamble + +**Original severity: low. Earlier #16. Status: documented divergence; exact Node parity remains unimplemented.** + +The existing unofficial termination contract is retained: a refused call +returns `napi_pending_exception` for every `module_api_version` and leaves a +termination marker pending unless another exception already exists. Taking +that marker returns null on both native providers after P3. + +The review's Node reference used `napi_cannot_run_js` for N-API version 10 or +later, `napi_pending_exception` for older versions, and no pending exception +for a refusal that never entered JavaScript. The old provider status already +differed; `next` broadened the observable difference through sticky +termination, additional guarded calls, and pending-state handling. + +This follow-up **documents the divergence instead of changing that contract**. +An addon that specifically detects shutdown by comparing against +`napi_cannot_run_js` therefore still needs different handling here. + +If exact Node parity is required, outstanding work includes defining how the +module API version affects refusals, separating refusal from actual engine +interruption, updating the public contract, and testing status and pending +state for versions below 10 and at least 10. That behavior change has not been +implemented or scheduled by this assessment. + +### P3 — Retrieved QuickJS termination values stay uncatchable after cancel + +**Original severity: low. Earlier #17. Status: implementation fix. Pre-existing.** + +Native code could take QuickJS's uncatchable interruption error, cancel +termination, and later rethrow the saved object. Because taking the object +removed it from the environment's pending slot, cancellation did not find it; +its uncatchable flag survived and ordinary `catch`/`finally` could be bypassed. + +[`napi_get_and_clear_last_exception`](../quickjs/src/js_native_api_quickjs.cc) +now returns null for the internal uncatchable termination marker, matching +V8's public value. It does not expose the engine's control-flow object. M2 +separately handles evaluation errors still stored on module records. + +The cancellation regression saves the taken value, cancels termination, then +throws that value from JavaScript and verifies that it is caught normally. + +### P4 — QuickJS resumes leftover promise jobs after cancellation + +**Original severity: low. Earlier #18. Status: documented divergence; queue-discard parity remains unimplemented. Pre-existing.** + +When a QuickJS job terminates a checkpoint, `run_pending_jobs` stops and leaves +the remaining jobs queued. A checkpoint after cancellation can execute those +jobs, including work queued before shutdown. V8 discards remaining microtasks +when a running microtask terminates. + +This follow-up **documents QuickJS's queue persistence without changing it**. +Embedders should run another checkpoint after cancellation only if they +intend the queued jobs to resume. The review identified this as a possible +shutdown/cleanup concern, but did not prove that EdgeJS's teardown runs the +checkpoint needed to expose it. + +Matching V8 would require an engine-safe way to discard pending jobs without +executing their JavaScript or losing their context/resource cleanup. A future +change should test that subsequent jobs do not run after cancel, that their +contexts are released, and that newly queued work after cancellation still +runs normally. Neither queue discarding nor the embedder teardown validation +has been completed here. + +### P5 — V8 builtins can continue native callbacks after termination + +**Original severity: low. Earlier #19. Status: documented Node-compatible limitation; no behavior fix planned in this follow-up.** + +A builtin invoked directly from C++, such as `Array.prototype.forEach`, can +call native callbacks with no user-JavaScript frame beneath them. V8's stack +trace does not count the builtin as a user frame. After a callback requests +termination, the builtin may finish its callbacks before reaching another +stack check, and `napi_call_function` can return `napi_ok`. QuickJS stops the +corresponding sequence immediately. + +The reviewer measured the same behavior in Node. Termination remains +requested, so later calls into JavaScript are still refused. This is a +cross-engine limitation and an overbroad documentation promise, rather than +a demonstrated Node-compatibility regression. + +The public contract now describes that boundary. No forced-unwind behavior +was added: running extra JavaScript merely to trigger an unwind could conflict +with an embedder's `DisallowJavascriptExecutionScope`. A dedicated builtin +callback-count regression would be useful if this boundary is changed later, +but this follow-up does not change it. + +## Remaining work and limits + +### Behavior work not implemented + +| Item | Remaining work | Current treatment | +|---|---|---| +| P2 | Node-compatible refusal statuses and pending-state behavior by API version | Documented divergence; retain the existing unofficial API contract. | +| P4 | Discard interrupted QuickJS promise jobs safely instead of resuming them after cancel | Documented divergence; keep existing queue semantics. | +| P5 | No behavior change planned | Document the Node-compatible V8 stack-check limitation. | + +P2 and P4 remain behavior differences if strict Node/V8 parity is the goal. +P5's documentation is the selected resolution, so it should not be counted as +an unimplemented Node bug. “All 19 addressed” must not be read as “all 19 now +have identical engine behavior.” + +### Module and engine limitations that remain + +- QuickJS unsettled-await warnings identify a module URL, without exact source + line/column information (M8). +- QuickJS-ng's error stack construction can invoke `Error.prepareStackTrace` + during interruption; closing that gap requires engine work (M10/P1). +- Native module-record lifetime remains an embedder responsibility. A weak + wrapper does not automatically destroy a native record unless the embedder + arranges destruction, for example through its wrapper finalizer (M4). +- Explicitly destroying a dependency while an importer still needs it has + documented provider-specific outcomes. V8 refuses later instantiation; + QuickJS may use its retained engine module (M6). +- Cross-realm module links are now rejected, rather than given portable + cross-realm execution semantics (M13). + +## Validation completed + +The recorded runs tested implementation commit `ab41860` on macOS arm64. +These are native CTest results, not a claim that the original reviewers' +external probe files were all rerun unchanged. + +| Configuration | Passed | Failed | Skipped | +|---|---:|---:|---:| +| V8 Release | 356 | 0 | 0 | +| QuickJS Release | 306 | 0 | 0 | +| V8 Release with AddressSanitizer | 355 | 0 | 1 | +| QuickJS Debug with AddressSanitizer | 306 | 0 | 0 | + +The V8 ASan skip is +`Test66ForegroundTaskHandoff.UninitializedArrayBuffersAreFreedWithoutACheckpoint`, +an existing sanitizer-specific skip. ASan runs used +`ASAN_OPTIONS=detect_leaks=0`; QuickJS Debug retained its runtime leak +assertions. These runs therefore provide memory-access and Debug assertion +coverage, not a LeakSanitizer proof that every allocation is reclaimed. + +Sixteen new test cases were added across the module-state and termination +runners. They cover the principal facade, destruction, realm, state, +exception, rejection, and wrapper/dependency-collection cases. The existing +termination matrices were also extended to include the require facade. +Individual coverage qualifications, including grouped cases without a new +standalone test, are recorded above. + +Typical native rerun commands, after configuring the appropriate builds: + +```sh +ctest --test-dir build-napi-v8 --output-on-failure -j8 +ctest --test-dir build-napi-quickjs --output-on-failure -j8 +ASAN_OPTIONS=detect_leaks=0 ctest --test-dir build-review-v8-asan --output-on-failure -j8 +ASAN_OPTIONS=detect_leaks=0 ctest --test-dir build-review-qjs-asan --output-on-failure -j8 +``` + +## Validation still pending + +The following checks were not run as part of this implementation follow-up: + +- **EdgeJS integration:** build against the updated napi revision and exercise + module-wrapper finalization, vm modules, ESM require, pending top-level + await exit handling, worker shutdown, and process-exit cleanup. +- **WASIX/guest ABI and host-JS integration:** verify the relevant bridge, + guest, and host-JS paths against the updated native behavior. No new Rust, + WASIX manifest, wasm-bindgen, or host-JS integration run is claimed here. +- **Performance:** benchmark module creation, linking, facade evaluation, + graph destruction, and GC/realm retention with the new ownership edges. + Passing functional tests does not establish a performance result. +- **Full original-probe replay:** the reports' external probe suites are not + part of this napi commit; the added regressions and complete native suites + do not establish that every original probe was rerun. + +None of these pending checks is represented as passed by the native test +counts. Further engine changes for P2/P4 would also need their own focused +regressions and renewed integration validation. + +## API and design references + +The retained termination differences and module lifetime/linking contracts +are documented in [`include/unofficial_napi.h`](../include/unofficial_napi.h). +The realm and ownership overview is in [`docs/realms.md`](realms.md).