How to Resolve Symbol Conflicts Between weak-node-api and Other NAPI Implementations

[RobinWuu]

In some cases, it is inevitable to have both weak-node-api and other NAPI implementations coexist within a single process space. For example:

• In Electron-like frameworks, both Node.js NAPI and weak-node-api are present simultaneously;

• In HarmonyOS, both OpenHarmony NAPI and weak-node-api coexist in the same process.

Does anyone have good ideas on how to resolve this symbol conflict issue🤔?

One approach is to rename the symbols of weak-node-api by adding a specific suffix (e.g., _weak—we'll use this suffix as an example below) to avoid symbol conflicts.

If we adopt the symbol renaming solution, how to quickly rename all symbols of weak-node-api is also a topic worthy of discussion. One method is to include a header file with macro definitions at the beginning of code files, which renames symbols during the preprocessing stage. Of course, an "undefine" header file is also needed to cancel these macros at the end of the code header files, preventing impacts on other code. Here are some examples:

// weak-napi-defines.hpp  ----- Header file with renaming macros
#define napi_env napi_env_weak
#define napi_env__ napi_env_weak__
#define napi_value napi_value_weak
#define napi_value__ napi_value_weak__

#define napi_create_object napi_create_object_weak
#define napi_create_int32 napi_create_int32_weak

// weak-napi-undefs.hpp  ----- Header file to undefine renaming macros
#undef napi_env
#undef napi_env__
#undef napi_value
#undef napi_value__

#undef napi_create_object
#undef napi_create_int32

// weak_node_api.cpp

#include "weak_node_api.hpp"

#include "weak-napi-defines.hpp" // Include the renaming header file

// ......

extern "C" napi_status napi_create_object(napi_env arg0, napi_value *arg1) {
  if (g_host.napi_create_object == nullptr) {
    fprintf(stderr, "Node-API function 'napi_create_object' called before it "
                    "was injected!\n");
    abort();
  }
  return g_host.napi_create_object(arg0, arg1);
};

extern "C" napi_status napi_create_int32(napi_env arg0, int32_t arg1,
                                         napi_value *arg2) {
  if (g_host.napi_create_int32 == nullptr) {
    fprintf(stderr, "Node-API function 'napi_create_int32' called before it "
                    "was injected!\n");
    abort();
  }
  return g_host.napi_create_int32(arg0, arg1, arg2);
};

// ......

// js_native_api.h
// ......

#include "js_native_api_types.h"
#include "weak-napi-defines.hpp" // Include the renaming header file

NAPI_EXTERN napi_status NAPI_CDECL napi_create_object(napi_env env,
                                                      napi_value* result);

NAPI_EXTERN napi_status NAPI_CDECL napi_create_int32(napi_env env,
                                                     int32_t value,
                                                     napi_value* result);

// ......
#include "weak-napi-undefs.hpp" // Include the header file to undefine macros

// demo.cpp
#include "js_native_api.h"
#include "weak-napi-defines.hpp" // Code using weak-node-api also needs to include the renaming header file


static napi_env env;
void Test() {
    napi_value v = napi_create_object(env);
}

By the way, if the PR at nodejs/node#60916 is merged into Node.js in the future, NAPI will no longer need to expose numerous napi_xxx-series symbols—and thus, the symbol conflict issue will naturally be resolved. However, for the time being, we still have to tackle this problem head-on.

[RobinWuu]

The problem I'm facing may be rather niche, so I'm not sure if it can be regarded as a general issue.
If the solution I proposed above is feasible, I'm considering publishing a standalone npm package. This package will depend on weak-node-api, apply the aforementioned symbol and type definition renaming modifications to its source code, then compile and build the precompiled dynamic libraries for distribution.
Ultimately, this npm package will include the header files and dynamic libraries with the renamed symbols and type definitions.

[RobinWuu]

I'm planning to publish an experimental version of the npm package first to test it out, and it might be named @lynx-js/weak-node-api. What do you think about this, @kraenhansen?

[kraenhansen]

Does anyone have good ideas on how to resolve this symbol conflict issue🤔?

I think all of my experiments so far has been relying on the actual Node-API implementations being loaded after the weak-node-api dynamic library. On iOS the weak-node-api dylib from the Xcframework gets added to the Xcode project in a way that preloads on app startup and on Android it seems the linker is more restrictive in providing access to global symbols, which helps disambiguate.

On the surface, I agree that using your "defines header" approach to rename the symbols could be a pretty transparent way of solving the disambiguation issue as it requires a minimal change from the POW of an addon author. That being said, I am a bit sad if that if this is where we land long term - it would be great if building for non-Node.js runtimes using weak-node-api required no changes to the addon source-code.

Feel free to publish an experimental version in your own package scope (please provide proper context in the README). I don't think have the capacity right now to help you land a better solution 😞 Hoping for nodejs/node#60916 to merge soon as that would help alleviate all of this.

[RobinWuu]

On the surface, I agree that using your "defines header" approach to rename the symbols could be a pretty transparent way of solving the disambiguation issue as it requires a minimal change from the POW of an addon author. That being said, I am a bit sad if that if this is where we land long term - it would be great if building for non-Node.js runtimes using weak-node-api required no changes to the addon source-code.

I agree with your point—symbol renaming is only a stopgap measure. I’m thinking that perhaps I should directly start experimenting with the dependency inversion approach (nodejs/node#60916).

[RobinWuu]

Feel free to publish an experimental version in your own package scope (please provide proper context in the README). I don't think have the capacity right now to help you land a better solution 😞

Thanks❤️! Your replies have been incredibly helpful to me. I’d be more than happy to keep in touch and continue our discussions. All the best!