Skip to content

embedding: allow NewContext to create inspectable context

Rodrigo Muino Tomonari requested to merge github/fork/Dragiyski/v13.x-staging into v13.x-staging

NodeJS should allow C++ users to create contexts, whose compiled script can be debugged through the inspector agent. Currently this functionality is only available for JavaScript modules through VM module. Unfortunately, VM creates a context whose global is completely new and hidden v8::FunctionTemplate. C++ users might already have v8::FunctionTemplate or v8::ObjectTemplate from which they create a context.

The only option now is to call V8 API directly: v8::Context::New(...). The created context is not associated with any node::Environment and code executed in that context cannot be debugged in the inspector agent (the context is missing debug_context_id as this is provided when the agent is notified by ContextCreated). This might actually be an intended behavior. The node::NewContext also create a context and do not report it to any agent (agent is a part of node::Environment and node::NewContext does not access any environments.

This is a proposal of a new feature to allow mitigate that gap. It provides another form of node::NewContext where node::Environment is accepted as the first parameter instead of v8::Isolate. When such an environment is available, it will create a context with a specific v8::ObjectTemplate and then call v8::Environment::AssignToContext. The latter will report the newly created context to the environment's inspector agent (if one is available) and add some embedders properties to allow proper handling of stack traces.

Without this feature, C++ modules can create v8::Context and use v8::ScriptCompiler to compile functions and scripts. Those scripts are not reported to the inspector agent and functions has [[FunctionLocation]] internal slot set to <unknown> even when v8::Source specify resource name, line and column offset, etc. If a context is reported to the inspector agent, it receives a debug_context_id. If this is available, compilation of new scripts and functions in that context will report to the inspector agent, which will send the source to the inspector frontend. Furthermore, the environment that has setup PrepareStackTraceCallback calls for Environment::GetCurrent(context). If an exception occurs into a context not assigned to environment, stack trace would be ignored, even when it is available.

This feature can be implemented using the following principles:

  • Additive: do not change any behavior and code of existing NodeJS implementation;
  • Minimal: do not add large amount of new code;
  • Efficient: does not require additional variables, objects, etc to be stored into memory; does not require additional processing when the feature is not used;
  • Useful: it allows access to huge amount of V8 API. C++ addons can use that API now, but with a limitation towards debugging and stack trace generation.
Checklist
  • make -j4 test (UNIX), or vcbuild test (Windows) passes
  • tests and/or benchmarks are included
  • documentation is changed or added
  • commit message follows commit guidelines

Merge request reports