src: expose node::MakeContextify to make a node managed vm context

legendecas · legendecas · commit 7a31490804f7 · 2026-03-20T15:25:42.000-04:00
diff --git a/src/api/environment.cc b/src/api/environment.cc
@@ -6,6 +6,7 @@
 #include "node.h"
 #include "node_builtins.h"
 #include "node_context_data.h"
+#include "node_contextify.h"
 #include "node_debug.h"
 #include "node_errors.h"
 #include "node_exit_code.h"
@@ -1057,6 +1058,66 @@ Maybe<bool> InitializeContext(Local<Context> context) {
   return Just(true);
 }
 
+ContextifyOptions::ContextifyOptions(Local<String> name,
+                                     Local<String> origin,
+                                     bool allow_code_gen_strings,
+                                     bool allow_code_gen_wasm,
+                                     MicrotaskMode microtask_mode)
+    : name_(name),
+      origin_(origin),
+      allow_code_gen_strings_(allow_code_gen_strings),
+      allow_code_gen_wasm_(allow_code_gen_wasm),
+      microtask_mode_(microtask_mode) {}
+
+MaybeLocal<Context> MakeContextify(Environment* env,
+                                   Local<Object> context_object,
+                                   const ContextifyOptions& options) {
+  Isolate* isolate = env->isolate();
+  EscapableHandleScope scope(isolate);
+  std::unique_ptr<v8::MicrotaskQueue> microtask_queue;
+  if (options.microtask_mode() ==
+      ContextifyOptions::MicrotaskMode::kAfterEvaluate) {
+    microtask_queue = v8::MicrotaskQueue::New(env->isolate(),
+                                              v8::MicrotasksPolicy::kExplicit);
+  }
+
+  contextify::ContextOptions ctxOptions{
+      .name = options.name(),
+      .origin = options.origin(),
+      .allow_code_gen_strings =
+          Boolean::New(isolate, options.allow_code_gen_strings()),
+      .allow_code_gen_wasm =
+          Boolean::New(isolate, options.allow_code_gen_wasm()),
+      .own_microtask_queue = std::move(microtask_queue),
+      .host_defined_options_id = env->vm_dynamic_import_no_callback(),
+      .vanilla = context_object.IsEmpty(),
+  };
+
+  TryCatchScope try_catch(env);
+  contextify::ContextifyContext* context_ptr =
+      contextify::ContextifyContext::New(env, context_object, &ctxOptions);
+
+  if (try_catch.HasCaught()) {
+    if (!try_catch.HasTerminated()) try_catch.ReThrow();
+    // Allocation failure, maximum call stack size reached, termination, etc.
+    return {};
+  }
+
+  return scope.Escape(context_ptr->context());
+}
+
+MaybeLocal<Context> GetContextified(Environment* env,
+                                    Local<Object> context_object) {
+  Isolate* isolate = env->isolate();
+  EscapableHandleScope scope(isolate);
+  contextify::ContextifyContext* context_ptr =
+      contextify::ContextifyContext::Get(context_object);
+  if (context_ptr == nullptr) {
+    return {};
+  }
+  return scope.Escape(context_ptr->context());
+}
+
 uv_loop_t* GetCurrentEventLoop(Isolate* isolate) {
   HandleScope handle_scope(isolate);
   Local<Context> context = isolate->GetCurrentContext();
diff --git a/src/node.h b/src/node.h
@@ -571,6 +571,44 @@ NODE_EXTERN v8::Local<v8::Context> NewContext(
 // Return value indicates success of operation
 NODE_EXTERN v8::Maybe<bool> InitializeContext(v8::Local<v8::Context> context);
 
+class ContextifyOptions {
+ public:
+  enum class MicrotaskMode {
+    kDefault,
+    kAfterEvaluate,
+  };
+
+  ContextifyOptions(v8::Local<v8::String> name,
+                    v8::Local<v8::String> origin,
+                    bool allow_code_gen_strings,
+                    bool allow_code_gen_wasm,
+                    MicrotaskMode microtask_mode);
+
+  v8::Local<v8::String> name() const { return name_; }
+  v8::Local<v8::String> origin() const { return origin_; }
+  bool allow_code_gen_strings() const { return allow_code_gen_strings_; }
+  bool allow_code_gen_wasm() const { return allow_code_gen_wasm_; }
+  MicrotaskMode microtask_mode() const { return microtask_mode_; }
+
+ private:
+  v8::Local<v8::String> name_;
+  v8::Local<v8::String> origin_;
+  bool allow_code_gen_strings_;
+  bool allow_code_gen_wasm_;
+  MicrotaskMode microtask_mode_;
+};
+
+// Create a Node.js managed v8::Context with the `context_object`. If the
+// `contextObject` is an empty handle, the v8::Context is created without
+// wrapping its global object with an object in a Node.js-specific manner.
+// The created context is supported in Node.js inspector.
+NODE_EXTERN v8::MaybeLocal<v8::Context> MakeContextify(
+    Environment* env,
+    v8::Local<v8::Object> context_object,
+    const ContextifyOptions& options);
+NODE_EXTERN v8::MaybeLocal<v8::Context> GetContextified(
+    Environment* env, v8::Local<v8::Object> context_object);
+
 // If `platform` is passed, it will be used to register new Worker instances.
 // It can be `nullptr`, in which case creating new Workers inside of
 // Environments that use this `IsolateData` will not work.
diff --git a/src/node_contextify.h b/src/node_contextify.h
@@ -131,10 +131,11 @@ class ContextifyContext final : CPPGC_MIXIN(ContextifyContext) {
 
   static void InitializeGlobalTemplates(IsolateData* isolate_data);
 
- private:
   static ContextifyContext* New(Environment* env,
                                 v8::Local<v8::Object> sandbox_obj,
                                 ContextOptions* options);
+
+ private:
   // Initialize a context created from CreateV8Context()
   static ContextifyContext* New(v8::Local<v8::Context> ctx,
                                 Environment* env,
diff --git a/test/addons/new-context-inspector/binding.cc b/test/addons/new-context-inspector/binding.cc
@@ -0,0 +1,79 @@
+#include <node.h>
+#include <v8.h>
+
+namespace {
+
+using v8::Context;
+using v8::FunctionCallbackInfo;
+using v8::HandleScope;
+using v8::Isolate;
+using v8::Local;
+using v8::Object;
+using v8::Script;
+using v8::String;
+using v8::Value;
+
+void MakeContext(const FunctionCallbackInfo<Value>& args) {
+  Isolate* isolate = Isolate::GetCurrent();
+  HandleScope handle_scope(isolate);
+  Local<Context> context = isolate->GetCurrentContext();
+  node::Environment* env = node::GetCurrentEnvironment(context);
+  assert(env);
+
+  node::ContextifyOptions options(
+      String::NewFromUtf8Literal(isolate, "Addon Context"),
+      String::NewFromUtf8Literal(isolate, "addon://about"),
+      false,
+      false,
+      node::ContextifyOptions::MicrotaskMode::kDefault);
+  // Create a new context with Node.js-specific vm setup.
+  v8::MaybeLocal<Context> maybe_context =
+      node::MakeContextify(env, {}, options);
+  v8::Local<Context> vm_context;
+  if (!maybe_context.ToLocal(&vm_context)) {
+    return;
+  }
+
+  // Return the global proxy object.
+  args.GetReturnValue().Set(vm_context->Global());
+}
+
+void RunInContext(const FunctionCallbackInfo<Value>& args) {
+  Isolate* isolate = Isolate::GetCurrent();
+  HandleScope handle_scope(isolate);
+  Local<Context> context = isolate->GetCurrentContext();
+  node::Environment* env = node::GetCurrentEnvironment(context);
+  assert(env);
+
+  Local<Object> sandbox_obj = args[0].As<Object>();
+  v8::MaybeLocal<Context> maybe_context =
+      node::GetContextified(env, sandbox_obj);
+  v8::Local<Context> vm_context;
+  if (!maybe_context.ToLocal(&vm_context)) {
+    return;
+  }
+  Context::Scope context_scope(vm_context);
+
+  if (args.Length() < 2 || !args[1]->IsString()) {
+    return;
+  }
+  Local<String> source = args[1].As<String>();
+  Local<Script> script;
+  Local<Value> result;
+
+  if (Script::Compile(vm_context, source).ToLocal(&script) &&
+      script->Run(vm_context).ToLocal(&result)) {
+    args.GetReturnValue().Set(result);
+  }
+}
+
+void Initialize(Local<Object> exports,
+                Local<Value> module,
+                Local<Context> context) {
+  NODE_SET_METHOD(exports, "makeContext", MakeContext);
+  NODE_SET_METHOD(exports, "runInContext", RunInContext);
+}
+
+}  // anonymous namespace
+
+NODE_MODULE_CONTEXT_AWARE(NODE_GYP_MODULE_NAME, Initialize)
diff --git a/test/addons/new-context-inspector/binding.gyp b/test/addons/new-context-inspector/binding.gyp
@@ -0,0 +1,9 @@
+{
+  'targets': [
+    {
+      'target_name': 'binding',
+      'sources': ['binding.cc'],
+      'includes': ['../common.gypi'],
+    },
+  ]
+}
diff --git a/test/addons/new-context-inspector/test-inspector.js b/test/addons/new-context-inspector/test-inspector.js
@@ -0,0 +1,51 @@
+'use strict';
+
+const common = require('../../common');
+common.skipIfInspectorDisabled();
+
+const assert = require('node:assert');
+const { once } = require('node:events');
+const { Session } = require('node:inspector');
+
+const binding = require(`./build/${common.buildType}/binding`);
+
+const session = new Session();
+session.connect();
+
+(async function() {
+  const mainContextPromise =
+      once(session, 'Runtime.executionContextCreated');
+  session.post('Runtime.enable', assert.ifError);
+  await mainContextPromise;
+
+  // Addon-created context should be reported to the inspector.
+  {
+    const addonContextPromise =
+        once(session, 'Runtime.executionContextCreated');
+
+    const ctx = binding.makeContext();
+    const result = binding.runInContext(ctx, '1 + 1');
+    assert.strictEqual(result, 2);
+
+    const { 0: contextCreated } = await addonContextPromise;
+    const { name, origin, auxData } = contextCreated.params.context;
+    assert.strictEqual(name, 'Addon Context',
+                       JSON.stringify(contextCreated));
+    assert.strictEqual(origin, 'addon://about',
+                       JSON.stringify(contextCreated));
+    assert.strictEqual(auxData.isDefault, false,
+                       JSON.stringify(contextCreated));
+  }
+
+  // `debugger` statement should pause in addon-created context.
+  {
+    session.post('Debugger.enable', assert.ifError);
+
+    const pausedPromise = once(session, 'Debugger.paused');
+    const ctx = binding.makeContext();
+    binding.runInContext(ctx, 'debugger');
+    await pausedPromise;
+
+    session.post('Debugger.resume');
+  }
+})().then(common.mustCall());
diff --git a/test/addons/new-context-inspector/test.js b/test/addons/new-context-inspector/test.js
@@ -0,0 +1,43 @@
+'use strict';
+
+const common = require('../../common');
+const assert = require('assert');
+const vm = require('vm');
+
+const binding = require(`./build/${common.buildType}/binding`);
+
+// This verifies that the addon-created context has an independent
+// global object.
+{
+  const ctx = binding.makeContext();
+  const result = binding.runInContext(ctx, `
+  globalThis.foo = 'bar';
+  foo;
+  `);
+  assert.strictEqual(result, 'bar');
+  assert.strictEqual(globalThis.foo, undefined);
+
+  // Verifies that eval can be disabled in the addon-created context.
+  assert.throws(() => binding.runInContext(ctx, `
+  eval('"foo"');
+  `), { name: 'EvalError' });
+
+  // Verifies that the addon-created context does not setup import loader.
+  const p = binding.runInContext(ctx, `
+  const p = import('node:fs');
+  p;
+  `);
+  p.catch(common.mustCall((e) => {
+    assert.throws(() => { throw e; }, { code: 'ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING' });
+  }));
+}
+
+
+// Verifies that the addon can unwrap the context from a vm context
+{
+  const ctx = vm.createContext(vm.constants.DONT_CONTEXTIFY);
+  vm.runInContext('globalThis.foo = {}', ctx);
+  const result = binding.runInContext(ctx, 'globalThis.foo');
+  // The return value identities should be equal.
+  assert.strictEqual(result, vm.runInContext('globalThis.foo', ctx));
+}
