Repository navigation
Initialize linked modules within the current JS value scope - #512
René Larch (r-Larch) wants to merge 5 commits into
Conversation
|
Azure Pipelines: There may be pipelines that require an authorized user to comment /azp run to run. |
There was a problem hiding this comment.
🟡 Changes recommended
Handle-scope initialization and error forwarding to the module environment remain unresolved.
2 open issues
What changed in this PR
Fixes linked-module initialization by sharing the current JavaScript runtime context. Includes the UTF-8 buffer fixes stacked from #510.
Changes:
- Uses callback scopes for linked-module initialization when a scope is active.
- Explicitly terminates UTF-8 strings and disposes module-name buffers.
- Adds buffer, error-propagation, and linked-module regression tests.
| File | Description |
|---|---|
| test/Utf8BufferTests.cs | Tests UTF-8 termination and null handling. |
| test/TestUtils.cs | Adds a helper to dirty pooled buffers. |
| test/test-linked-module.mjs | Exercises linked binding from an ES module. |
| test/NodejsEmbeddingTests.cs | Adds error and linked-module integration tests. |
| src/NodeApi/Runtime/Utf8StringArray.cs | Writes string terminators explicitly. |
| src/NodeApi/Runtime/PooledBuffer.cs | Terminates UTF-8 buffers and distinguishes empty from null. |
| src/NodeApi/Runtime/NodejsRuntime.Embedding.cs | Disposes the module-name buffer. |
| src/NodeApi/Runtime/NodeEmbedding.cs | Initializes linked modules within the current context. |
Review effort: Balanced
Addresses review feedback on microsoft#512: - Node-API tracks pending exceptions per napi_env, and Node.js only reports those of the module's env to the caller of process._linkedBinding(). Errors thrown by the initializer within the runtime's scope were only logged as "Uncaught N-API callback exception" (DEP0168). Move a pending exception from the scope's env to the module's env before returning. - A callback scope cannot be nested in a handle or escapable scope, so initializing a module while one is current threw outside the adapter's try/catch. Use the current scope as is in that case. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Addresses review feedback on microsoft#512: - Node-API tracks pending exceptions per napi_env, and Node.js only reports those of the module's env to the caller of process._linkedBinding(). Errors thrown by the initializer within the runtime's scope were only logged as "Uncaught N-API callback exception" (DEP0168). Move a pending exception from the scope's env to the module's env before returning. - A callback scope cannot be nested in a handle or escapable scope, so initializing a module while one is current threw outside the adapter's try/catch. Use the current scope as is in that case. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
824d31b to
0e133ff
Compare
Addresses review feedback on microsoft#512: - Node-API tracks pending exceptions per napi_env, and Node.js only reports those of the module's env to the caller of process._linkedBinding(). Errors thrown by the initializer within the runtime's scope were only logged as "Uncaught N-API callback exception" (DEP0168). Move a pending exception from the scope's env to the module's env before returning. - A callback scope cannot be nested in a handle or escapable scope, so initializing a module while one is current threw outside the adapter's try/catch. Use the current scope as is in that case. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
0e133ff to
d330c63
Compare
|
René Larch (@r-Larch) , could you please rebase this PR to fix the merge conflicts. |
Addresses review feedback on microsoft#512: - Node-API tracks pending exceptions per napi_env, and Node.js only reports those of the module's env to the caller of process._linkedBinding(). Errors thrown by the initializer within the runtime's scope were only logged as "Uncaught N-API callback exception" (DEP0168). Move a pending exception from the scope's env to the module's env before returning. - A callback scope cannot be nested in a handle or escapable scope, so initializing a module while one is current threw outside the adapter's try/catch. Use the current scope as is in that case. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
d330c63 to
8c2f65a
Compare
|
Vladimir Morozov (@vmoroz) rebased onto main, thanks for the review. One change came with the move to LibNode 26 (#517): the error thrown by a linked module's init function no longer reaches the caller of So |
|
René Larch (@r-Larch) , while reviewing this PR and its relationship to #500, I also saw this issue with exceptions. |
|
Vladimir Morozov (@vmoroz) thanks, that's the same root cause. I tried LibNode 26.1.2 locally: with it, Should I bump LibNode to 26.1.2 in this PR and restore that assertion, or keep this PR as it is and do it in a follow-up? (I also pushed a115ca4 to fix the import order that broke the format check.) On the Node.js side, nodejs/node#67571 covers only |
|
René Larch (@r-Larch) , I am currently working on the PR for this repo to use 26.1.2 plus a few more changes to pipelines. It may take a few hours. If you have time now, then please add the use of 26.1.2 into your PR. It should help us to merge this PR sooner. As for the Node.js, I will create a PR as soon as the two PRs mentioned above are done. |
|
Actually, if you can adapt my changes to LibNode to your Node.js PR it would be the best. I can sign off your PR in Node.js and hopefully get it merged sooner. Otherwise, as I just realized, if I create the Node.js PR, it may not look good because I would duplicate your effort and many Node.js team members may be unhappy with such doing. |
|
René Larch (@r-Larch) , the PR #520 that updates the LibNode version is merged. |
Calling process._linkedBinding() for a module registered through NodeEmbeddingRuntimeSettings.Modules failed or crashed the process (microsoft#464): - From a script run via NodeEmbeddingThreadRuntime.Run: "A Root scope cannot be created within another scope." - From MainScript: the nested root scope dropped its parent on dispose, so the thread was left without a current scope ("There is no active JS value scope", reported as a stack overflow in the issue). - From an ES module imported via ImportAsync: native assertion "(v8_scope_data_->nest_level()) == (nest_level)" in CloseV8Scope. ModuleInitializeCallbackAdapter always opened a new root scope for the napi_env that Node.js creates for each linked module. Modules are initialized lazily, while the runtime's scope is normally current on the JS thread, so open a callback scope within it instead and only fall back to a root scope when no scope is current. The module's exports then share the runtime's context, and later calls from JS into the exported .NET callbacks find a matching parent scope. Fixes microsoft#464. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Addresses review feedback on microsoft#512: - Node-API tracks pending exceptions per napi_env, and Node.js only reports those of the module's env to the caller of process._linkedBinding(). Errors thrown by the initializer within the runtime's scope were only logged as "Uncaught N-API callback exception" (DEP0168). Move a pending exception from the scope's env to the module's env before returning. - A callback scope cannot be nested in a handle or escapable scope, so initializing a module while one is current threw outside the adapter's try/catch. Use the current scope as is in that case. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
With LibNode 26 the error thrown by a linked module's init function no longer reaches the caller of process._linkedBinding(): Node.js GetLinkedBinding() reads module.exports after the init function returns, and that V8 API call clears the pending exception. This affects every linked binding and is fixed in nodejs/node#67571. The test now checks that the error does not stay pending on the runtime's env, which fails without moving it to the module's env. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
LibNode 26.1.2 includes the fix for the init error being cleared in GetLinkedBinding() (microsoft/v8-jsi#289), so the error reaches the caller of process._linkedBinding() again. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
a115ca4 to
1a01c64
Compare
|
Vladimir Morozov (@vmoroz) rebased onto main with LibNode 26.1.2 and restored the assertion in 1a01c64: For Node.js, I adapted your change into nodejs/node#67571: the |

Fixes #464.
Calling
process._linkedBinding()for a module registered throughNodeEmbeddingRuntimeSettings.Modulesfailed or crashed the process:NodeEmbeddingThreadRuntime.RunInvalidOperationException: A Root scope cannot be created within another scope.MainScriptJSInvalidThreadAccessException: There is no active JS value scope(the stack overflow in the issue)ImportAsync(v8_scope_data_->nest_level()) == (nest_level)inCloseV8Scope, exit code 134Cause:
ModuleInitializeCallbackAdapteralways opened a new root scope for thenapi_envthat Node.js creates for each linked module (node_napi_env__::NewinEmbeddedRuntime::RegisterModule). Linked modules are initialized lazily, while the runtime's scope is normally current on the JS thread. A nested root scope either throws, or drops its parent and leavesJSValueScope.Currentnull when it is disposed.Fix: if a scope is current, open a callback scope within it (the same as for JS→.NET callbacks); otherwise fall back to a root scope as before. The module's exports then share the runtime's context (sync context,
require, marshaller), and later calls from JS into the exported .NET functions find a matching parent scope. This is close to the workaround in the issue, which removes the scope entirely, but keeps a scope.Note: draft PR #500 also rewrites this adapter (
TryEnterRuntimeScope(env)) as part of a larger scope refactor. This PR is deliberately minimal so it can land on currentmainon its own. Happy to close it if #500 lands first and covers #464.Tests
NodejsEmbeddingTests.LinkedModuleFromScript,LinkedModuleFromMainScriptandLinkedModuleFromESModule(plustest/test-linked-module.mjs). Each one registers a linked module with a dirty array pool, calls the module, and then checks that the JS thread is still usable. All three fail onmain; two of them crash the test host.From review:
LinkedModuleInitializationErrorchecks that an error thrown by the initializer reaches the caller of_linkedBinding(). The adapter moves a pending exception from the runtime's env to the module's env.LinkedModuleFromHandleScopeinitializes a module while a handle scope is current.Local run (Windows x64, .NET SDK 10.0.402): net10.0 160/162, net9.0 129/130, net8.0 129/130. The only failure,
napi-dotnet/overloads, fails the same way onmain. I could not run net472 locally.🤖 Generated with Claude Code