node-api: use v-table to reverse module dependencies

[vmoroz]

Disclaimer

Please consider this PR as a proof of concept and a discussion starter. We discussed this design a bit in the latest Node-API meeting with @legendecas and @KevinEady, and this PR provides the specific implementation details to visualize the new ideas.

The issue

The recent investigation of the issue nodejs/abi-stable-node#471 had shown that the current way how Node-API modules depend on API exposed by Node.js has a number of limitations and issues that are not simple to overcome especially if the modules are distributed as pre-built libraries.
To be specific we have the following picture:

• On Windows the .node modules are compiled with the delay loading dependency on the node.exe process. Each modules is compiled with the win_delay_load_hook.cc source file where we define a global __pfnDliNotifyHook2 that allows to bind to Node-API functions from current process if its name is different from node.exe, or from the libnode.dll. If a module was compiled without defining such hook, then such module cannot bind to Node-API functions for non-node.exe runtimes.
• On Linux & MacOS the .node uses weak function binding that allows to bind to any function with the same name present in the process. This does not work on Android where the modules are required to have a strong binding.
• The current system does not allow to use in the same process multiple JS runtimes that may load Node-API modules. For example, if Word.exe uses libnode.dll and React Native for Windows with Hermes JS VM, then it is not possible to specify the target runtime for a module.
• When we implement Node-API bindings in other languages such as C# or Java, it is quite expensive to resolve all the ~160 Node-API functions by name.

The proposed solution

The proposal is to reverse the dependency. Instead of .node to depend on Node-API, we should make it to be the responsibility of the runtime to load the .node module and to inject its API into the module. This way it does not matter what is the name of the process or the embedded runtime DLL name. The same pre-built module can be loaded from different JS runtimes such as libnode.dll or hermes.dll.

This PR shows how such injection can be implemented:

• js_native_api_types.h and node_api_types.h define the node_api_js_native_vtable and node_api_module_vtable structs with entries for all Node-API functions. They are sorted so that all new function pointers are added in the end of the struct. The main requirement is that we must never change the position of the entries except for the experimental functions.
• We have to have two different v-tables because the js_native_api.h and node_api.h are two sets of functions that can be used in different scenarios independently.
• js_native_api_v8.cc and node_api.cc initialize the struct instances with all Node-API function pointers.
• The node_api.h changes the NAPI_MODULE_INIT macro so that each .node module defines global const node_api_module_vtable* g_node_api_module_vtable and const node_api_js_native_vtable* g_node_api_js_native_vtable variables and exports the new node_api_module_set_vtable_v1 function that is called from the node_binding.cc to inject the Node-API v-tables.
• The js_native_api.h and node_api.h also contain the implementation of all Node-API functions as static inline functions that use the global variables. These functions become part of the .node module after compilation. They do not exist when we compile Node.js code. The new macro NODE_API_MODULE_USE_VTABLE controls whether the header files define Node-API function prototypes or the new static inline functions. It also controls if the node_api_module_set_vtable_v1 function and the global vtable variables are defined.

After this change all test modules compile and run without changes.
To test the vtable approach the NODE_API_MODULE_USE_VTABLE is added to two tests: node-api\1_hello_world and js-native-api\7_factory_wrap. When we look at the imports of the modules that use the v-table approach, we do not see any imports from the node.exe. It means that we can stop using the win_delay_load_hook.cc and be able to load the pre-built .node module from any runtime that supports Node-API.

The idea to use a v-table for the API is not new. E.g. Java JNI API is also based on a v-table.

[nodejs-github-bot]

Review requested:

• @nodejs/gyp
• @nodejs/node-api

[kraenhansen]

From the PR description this seems super valuable and a great built-in alternative to the weak-node-api library we've been working on to add Node-API support to React Native. As such, I'd be happy for us to adopt this approach over the stuff we have now 👍

The limitation around the module being bound to a single runtime, might not be an issue as a multi-runtime host can inject functions that deal with that internally.

I'm left wondering how (if at all) add-ons which are statically linked into the process are affected by this proposal? I guess not at all, as they can still register themselves and call into the global Node-API functions resolved at link time.

[devsnek]

nice! node-api symbol visibility has been a pain for us in deno so we'd love to adopt this approach as well.

[legendecas]

We should still support addons compiled with legacy Node-API headers. Could this new v-table approach be opt-in?

[vmoroz]

I agree, we should make it opt-in to start with and play with it a bit.
If it works well, then we can promote it to be default at some point.
I considered to use the NAPI_EXPERIMENTAL, but it seems it is not the right approach since we use the NAPI_EXPERIMENTAL for new Node-API functions, and the module loading is an orthogonal process. Thus, a special opt-in flag would be better.

[vmoroz]

I have added a new macro NODE_API_MODULE_USE_VTABLE. It is currently used only by two tests.

[kraenhansen]

For anyone wondering, this was moved into the node_api_types.h.

[vmoroz]

I had to move it because the new vtable struct uses it.

[kraenhansen]

There might be a potential a potential coordination problem, where the addon tries to initialize itself before the vtable gets injected (set) by the host. I don't see that as an issue when the addon relies on "symbol based" module registration, since the host can ensure to call the initialize function after setting the vtable, but how about an addon trying to call napi_module_register when loaded?

[devsnek]

but how about an addon trying to call napi_module_register when loaded?

these should probably be exclusive modes, so napi_module_register wouldn't be called, or could only be called from within the host call to the inject function.

[addaleax]

Should this be const?

[vmoroz]

Good point! I will fix it.

[vmoroz]

I have added const for the global variables related to the v-tables.

[vmoroz]

There might be a potential a potential coordination problem, where the addon tries to initialize itself before the vtable gets injected (set) by the host. I don't see that as an issue when the addon relies on "symbol based" module registration, since the host can ensure to call the initialize function after setting the vtable, but how about an addon trying to call napi_module_register when loaded?

The napi_module_register usage is deprecated. No new code is supposed to use it anymore.
We used to have a deprecated attribute, but we found that some developers use it to register modules explictly. E.g. when the modules are part of the host executable.
I do not have a good answer to that besides that the exisitng public API is still there and user can use as before.

I am going to add a conditional flag and restore the deleted test as @legendecas suggested. This test is using the napi_module_register method and it can be used as a show case how to use the Node-API directly when needed.

[vmoroz]

I'm left wondering how (if at all) add-ons which are statically linked into the process are affected by this proposal? I guess not at all, as they can still register themselves and call into the global Node-API functions resolved at link time.

Right, I would expect it too, but we should verify and test this scenario.

[vmoroz]

The issues that I am facing on Mac and Linux are due to the use of real "C" compilers where the inline keyword has a different semantic than in "C++". Changing it to static inline generates its own set of issues. Thus, I am still working on it.

[RobinWuu]

Nice!👍 In Lynx/PrimJS, we are currently using a similar vtable approach to address the needs of multi-runtime injection. However, our previous API was not fully aligned with the Node-API standard, which is a problem I have been working to fix recently.
We’re thrilled to see this solution will potentially be natively integrated into Node.js, and we’re also more than happy to adopt this approach.

[vmoroz]

Nice!👍 In Lynx/PrimJS, we are currently using a similar vtable approach to address the needs of multi-runtime injection. However, our previous API was not fully aligned with the Node-API standard, which is a problem I have been working to fix recently. We’re thrilled to see this solution will potentially be natively integrated into Node.js, and we’re also more than happy to adopt this approach.

It is great to hear it! Any suggestions to improve code in this PR to fit your scenario are welcome.

[codecov]

Codecov Report

❌ Patch coverage is 98.72774% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 88.45%. Comparing base (bcdf2e0) to head (d3bd284).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
src/node_api.cc	97.02%	1 Missing and 2 partials ⚠️
src/js_native_api_v8.cc	99.63%	0 Missing and 1 partial ⚠️
src/js_native_api_v8.h	94.11%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #60916      +/-   ##
==========================================
- Coverage   88.53%   88.45%   -0.09%     
==========================================
  Files         704      704              
  Lines      208759   208919     +160     
  Branches    40281    40394     +113     
==========================================
- Hits       184816   184789      -27     
+ Misses      15947    15944       -3     
- Partials     7996     8186     +190     

Files with missing lines	Coverage Δ
src/js_native_api_v8_internals.h	0.00% <ø> (ø)
src/node_api_internals.h	100.00% <ø> (ø)
src/js_native_api_v8.cc	69.79% <99.63%> (-6.70%)	⬇️
src/js_native_api_v8.h	89.28% <94.11%> (-0.14%)	⬇️
src/node_api.cc	73.48% <97.02%> (-1.67%)	⬇️

... and 24 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[legendecas]

We can add a new target named binding_vtable and verify that the hello_world test can be kept and run in the same process with the new vtable binding.

[vmoroz]

Thank you for the suggestion! I had duplicated all the targets and added there the "_vtable" suffix.

[legendecas]

Could we add a test that contains two compilation units and this global variable can be properly defined?

[vmoroz]

All tests are changed to build addons with and without optional support for v-table. They show that the tests can run in both modes. In one case node-api/1_hello_world I have added a test that supports v-table, but does not implement a fallback implementation when it is missing. It passes in new version of Node.js, but fails in old version.
All other tests pass in the old versions on Node.sj except for the cases when the tests are using APIs that are not part of the previous Node.js version, e.g. Float16.
IMHO, we should run the Node-API tests against the new and old Node.js versions, but it is a subject for another discussion.

[mani3xis]

👍
Just as a comment, I was working on something very similar, but I must admit that imho this is the most flexible approach, which opens new possibilities, like enabling validation layers and middlewares (the runtime can "replace" or "patch" the original Node-API function pointer with functions that perform extra validation or logging, etc. completely transparently to the "consumer") -- a little bit like optional Validation Layers in Vulkan API. Lastly, V-table approach also decreases the cost of dynamic symbol resolution, etc.

From ABI stability, adding new function pointers at the end of the struct/V-table is ABI-stable. Lastly, there are some runtimes that support multiple JS engines, and they would need to dispatch to the correct V-table (based on the node_env) -- I believe both PrimJS and OpenHarmony's Native Engine are doing this. This is also one reason why JS engines should not provide Node-API symbols, otherwise they will trigger symbol conflicts.

What might be good to consider is adding a function that returns a V-table for a given version. This way, if a Node Addon is using say N-API version 8, and the runtime supports, say, N-API version 10, such node_api_get_vtable(NAPI_VERSION_8, flags) might return a properly initialized V-Table with newer functions replaced with an assertion or something. Just a random idea inspired by an old blog post...

edit: If we can bump NAPI_MODULE_VERSION then maybe its the best time to introduce napi_register_module_v2() which takes a 3rd argument: a versioned struct/v-table with function pointers to query the host/runtime (e.g. ask for V-Tables, require other addons, etc.). WDYT?

[vmoroz]

edit: If we can bump NAPI_MODULE_VERSION then maybe its the best time to introduce napi_register_module_v2() which takes a 3rd argument: a versioned struct/v-table with function pointers to query the host/runtime (e.g. ask for V-Tables, require other addons, etc.). WDYT?

@mani3xis , thank you for the feedback and great ideas! In the last few weeks I was working on improving the code and was able to achieve good results that should now enable multiple runtimes in the same executable since the v-table is now exposed from the napi_env as you suggested.
As for the versioning, I played with the idea to add the napi_register_module_v2, but seemed to be unnecessary.
When we currently load a Node-API module we first look for an optional function with the name node_api_module_get_api_version_v1. This function must return the Node-API version supported by the module. If the function is not present, then we assume the Node-API version 8. The version 8 was there when we added this mechanism. Then, the internal napi_env created with the module version inside. Based on that version Node.js adjusts the behavior of the Node-API.
So, when the napi_register_module_v1 is called with the napi_env, that napi_env is already adjusted for the requested version.
Since the v-table in the latest iteration of this PR is a field of napi_env__, it can have the adjusted v-table if needed.