src: restore ability to run under NAPI_EXPERIMENTAL

Since we made the default for Node.js core finalizers synchronous for
users running with `NAPI_EXPERIMENTAL` and introduced
`env->CheckGCAccess()` in Node.js core, we must now defer all
finalizers in node-addon-api, because our users likely make
non-gc-safe Node-API calls from existing finalizers. To that end,

  * Use the NAPI_VERSION environment variable to detect whether
    `NAPI_EXPERIMENTAL` should be on, and add it to the defines if
    `NAPI_VERSION` is set to `NAPI_VERSION_EXPERIMENTAL`, i.e.
    2147483647.
  * When building with `NAPI_EXPERIMENTAL`,
    * render all finalizers asynchronous, and
    * expect `napi_cannot_run_js` instead of `napi_exception_pending`.

.github/workflows/ci.yml

@@ -13,6 +13,9 @@ jobs:
  timeout-minutes: 30
  strategy:
  matrix:
+ api_version:
+ - standard
+ - experimental
  node-version: [ 18.x, 20.x, 21.x ]
  os:
  - macos-latest
@@ -43,6 +46,9 @@ jobs:
  npm install
  - name: npm test
  run: |
+ if [ "${{ matrix.api_version }}" = "experimental" ]; then
+ export NAPI_VERSION=2147483647
+ fi
  if [ "${{ matrix.compiler }}" = "gcc" ]; then
  export CC="gcc" CXX="g++"
  fi

common.gypi

@@ -5,6 +5,7 @@
  },
  'conditions': [
  ['NAPI_VERSION!=""', { 'defines': ['NAPI_VERSION=<@(NAPI_VERSION)'] } ],
+ ['NAPI_VERSION==2147483647', { 'defines': ['NAPI_EXPERIMENTAL'] } ],
  ['disable_deprecated=="true"', {
  'defines': ['NODE_ADDON_API_DISABLE_DEPRECATED']
  }],

napi-inl.h

@@ -180,11 +180,36 @@ napi_value TemplatedInstanceVoidCallback(napi_env env, napi_callback_info info)
  });
 }
 
+inline void DeferredCallback(const char* placeOfFailure,
+ napi_env env,
+ void* data,
+ void* hint,
+ napi_finalize fini) {
+#ifdef NAPI_EXPERIMENTAL
+ napi_status status = node_api_post_finalizer(env, fini, data, hint);
+ NAPI_FATAL_IF_FAILED(
+ status, placeOfFailure, "DeferredCallback -> node_api_post_finalizer");
+#else
+ (void)placeOfFailure;
+ fini(env, data, hint);
+#endif
+}
+
 template <typename T, typename Finalizer, typename Hint = void>
 struct FinalizeData {
  static inline void Wrapper(napi_env env,
  void* data,
  void* finalizeHint) NAPI_NOEXCEPT {
+ DeferredCallback("FinalizeData::Wrapper",
+ env,
+ data,
+ finalizeHint,
+ FinalizeData<T, Finalizer>::SyncWrapper);
+ }
+
+ static inline void SyncWrapper(napi_env env,
+ void* data,
+ void* finalizeHint) NAPI_NOEXCEPT {
  WrapVoidCallback([&] {
  FinalizeData* finalizeData = static_cast<FinalizeData*>(finalizeHint);
  finalizeData->callback(Env(env), static_cast<T*>(data));
@@ -195,6 +220,16 @@ struct FinalizeData {
  static inline void WrapperWithHint(napi_env env,
  void* data,
  void* finalizeHint) NAPI_NOEXCEPT {
+ DeferredCallback("FinalizeData::WrapperWithHint",
+ env,
+ data,
+ finalizeHint,
+ FinalizeData<T, Finalizer, Hint>::SyncWrapperWithHint);
+ }
+
+ static inline void SyncWrapperWithHint(napi_env env,
+ void* data,
+ void* finalizeHint) NAPI_NOEXCEPT {
  WrapVoidCallback([&] {
  FinalizeData* finalizeData = static_cast<FinalizeData*>(finalizeHint);
  finalizeData->callback(
@@ -2731,7 +2766,7 @@ inline Buffer<T> Buffer<T>::NewOrCopy(napi_env env,
 #endif // NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED
  // If we can't create an external buffer, we'll just copy the data.
  Buffer<T> ret = Buffer<T>::Copy(env, data, length);
- details::FinalizeData<T, Finalizer>::Wrapper(env, data, finalizeData);
+ details::FinalizeData<T, Finalizer>::SyncWrapper(env, data, finalizeData);
  return ret;
 #ifndef NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED
  }
@@ -2766,7 +2801,7 @@ inline Buffer<T> Buffer<T>::NewOrCopy(napi_env env,
 #endif
  // If we can't create an external buffer, we'll just copy the data.
  Buffer<T> ret = Buffer<T>::Copy(env, data, length);
- details::FinalizeData<T, Finalizer, Hint>::WrapperWithHint(
+ details::FinalizeData<T, Finalizer, Hint>::SyncWrapperWithHint(
  env, data, finalizeData);
  return ret;
 #ifndef NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED
@@ -3054,7 +3089,13 @@ inline void Error::ThrowAsJavaScriptException() const {
 
  status = napi_throw(_env, Value());
 
- if (status == napi_pending_exception) {
+#ifdef NAPI_EXPERIMENTAL
+ napi_status expected_failure_mode = napi_cannot_run_js;
+#else
+ napi_status expected_failure_mode = napi_pending_exception;
+#endif
+
+ if (status == expected_failure_mode) {
  // The environment must be terminating as we checked earlier and there
  // was no pending exception. In this case continuing will result
  // in a fatal error and there is nothing the author has done incorrectly
@@ -4879,10 +4920,16 @@ template <typename T>
 inline void ObjectWrap<T>::FinalizeCallback(napi_env env,
  void* data,
  void* /*hint*/) {
- HandleScope scope(env);
- T* instance = static_cast<T*>(data);
- instance->Finalize(Napi::Env(env));
- delete instance;
+ details::DeferredCallback("ObjectWrap<T>::FinalizeCallback",
+ env,
+ data,
+ nullptr,
+ [](napi_env env, void* data, void* /*hint*/) {
+ HandleScope scope(env);
+ T* instance = static_cast<T*>(data);
+ instance->Finalize(Napi::Env(env));
+ delete instance;
+ });
 }
 
 template <typename T>