2d1e4144b3
* fix: prevent crashing when napi_register_module_v1 is called twice Currently napi-rs addons can lead to the Node.js process aborting with the following error when initialising the addon on Windows: ``` c:\ws\src\cleanup_queue-inl.h:32: Assertion `(insertion_info.second) == (true)' failed. ``` This happens because `napi_add_env_cleanup_hook` must not be called with the same arguments multiple times unless the previously scheduled cleanup hook with the same arguments was already executed. However, the cleanup hook added by `napi_register_module_v1` in napi-rs on Windows was always created with `ptr::null_mut()` as an argument. One case where this causes a problem is when using the addon from multiple contexts (e.g. Node.js worker threads) at the same time. However, Node.js doesn't provide any guarantees that the N-API addon initialisation code will run only once even per thread and context. In fact, it's totally valid to run `process.dlopen()` multiple times from JavaScript land in Node.js, and this will lead to the initialisation code being run multiple times as different `exports` objects may need to be populated. This may happen in numerous cases, e.g.: - When it's not possible or not desirable to use `require()` and users must resort to using `process.dlopen()` (one use case is passing non-default flags to `dlopen(3)`, another is ES modules). Caching the results of `process.dlopen()` to avoid running it more than once may not always be possible reliably in all cases (for example, because of Jest sandbox). - When the `require` cache is cleared. - On Windows: `require("./addon.node")` and then `require(path.toNamespacedPath("./addon.node"))`. Another issue is fixed inside `napi::tokio_runtime::drop_runtime`: there's no need to call `napi_remove_env_cleanup_hook` (it's only useful to cancel the hooks that haven't been executed yet). Null pointer retrieved from `arg` was being passed as the `env` argument of that function, so it didn't do anything and just returned `napi_invalid_arg`. This patch makes `napi_register_module_v1` use a counter as the cleanup hook argument, so that the value is always different. An alternative might have been to use a higher-level abstraction around `sys::napi_env_cleanup_hook` that would take ownership of a boxed closure, if there is something like this in the API already. Another alternative could have been to heap-allocate a value so that we would have a unique valid memory address. The patch also contains a minor code cleanup related to `RT_REFERENCE_COUNT` along the way: the counter is encapsulated inside its module and `ensure_runtime` takes care of incrementing it, and less strict memory ordering is now used as there's no need for `SeqCst` here. If desired, it can be further optimised to `Ordering::Release` and a separate acquire fence inside the if statement in `drop_runtime`, as `AcqRel` for every decrement is also a bit stricter than necessary (although simpler). These changes are not necessary to fix the issue and can be extracted to a separate patch. At first it was tempting to use the loaded value of `RT_REFERENCE_COUNT` as the argument for the cleanup hook but it would have been wrong: a simple counterexample is the following sequence: 1. init in the first context (queue: 0) 2. init in the second context (queue: 0, 1) 3. destroy the first context (queue: 1) 4. init in the third context (queue: 1, 1) * test(napi): unload test was excluded unexpected --------- Co-authored-by: LongYinan <lynweklm@gmail.com> |
||
---|---|---|
.github | ||
.husky | ||
.yarn/releases | ||
bench | ||
cli | ||
crates | ||
examples | ||
images | ||
memory-testing | ||
triples | ||
.cirrus.yml | ||
.dockerignore | ||
.editorconfig | ||
.eslintignore | ||
.eslintrc.yml | ||
.gitattributes | ||
.gitignore | ||
.npmignore | ||
.prettierignore | ||
.yarnrc.yml | ||
alpine-zig.Dockerfile | ||
alpine.Dockerfile | ||
Cargo.toml | ||
CODE_OF_CONDUCT.md | ||
debian-aarch64.Dockerfile | ||
debian-zig.Dockerfile | ||
debian.Dockerfile | ||
lerna.json | ||
LICENSE | ||
package.json | ||
README.md | ||
renovate.json | ||
rustfmt.toml | ||
tsconfig.json | ||
tsconfig.root-lint.json | ||
yarn.lock |
napi-rs
This project was initialized from xray
A framework for building compiled Node.js
add-ons in Rust
via Node-API. Website: https://napi.rs
Platform Support
MSRV
Rust 1.57.0
node12 | node14 | node16 | node18 | |
---|---|---|---|---|
Windows x64 | ✓ | ✓ | ✓ | ✓ |
Windows x86 | ✓ | ✓ | ✓ | ✓ |
Windows arm64 | ✓ | ✓ | ✓ | ✓ |
macOS x64 | ✓ | ✓ | ✓ | ✓ |
macOS aarch64 | ✓ | ✓ | ✓ | ✓ |
Linux x64 gnu | ✓ | ✓ | ✓ | ✓ |
Linux x64 musl | ✓ | ✓ | ✓ | ✓ |
Linux aarch64 gnu | ✓ | ✓ | ✓ | ✓ |
Linux aarch64 musl | ✓ | ✓ | ✓ | ✓ |
Linux arm gnueabihf | ✓ | ✓ | ✓ | ✓ |
Linux aarch64 android | ✓ | ✓ | ✓ | ✓ |
Linux armv7 android | ✓ | ✓ | ✓ | ✓ |
FreeBSD x64 | ✓ | ✓ | ✓ | ✓ |
This library depends on Node-API and requires Node@10.0.0
or later.
We already have some packages written by napi-rs
: node-rs
One nice feature is that this crate allows you to build add-ons purely with the Rust/JavaScript
toolchain and without involving node-gyp
.
Taste
You can start from package-template to play with
napi-rs
Define JavaScript functions
/// import the preludes
use napi::bindgen_prelude::*;
use napi_derive::napi;
/// module registration is done by the runtime, no need to explicitly do it now.
#[napi]
fn fibonacci(n: u32) -> u32 {
match n {
1 | 2 => 1,
_ => fibonacci(n - 1) + fibonacci(n - 2),
}
}
/// use `Fn`, `FnMut` or `FnOnce` traits to defined JavaScript callbacks
/// the return type of callbacks can only be `Result`.
#[napi]
fn get_cwd<T: Fn(String) -> Result<()>>(callback: T) {
callback(env::current_dir().unwrap().to_string_lossy().to_string()).unwrap();
}
/// or, define the callback signature in where clause
#[napi]
fn test_callback<T>(callback: T)
where T: Fn(String) -> Result<()>
{}
/// async fn, require `async` feature enabled.
/// [dependencies]
/// napi = {version="2", features=["async"]}
#[napi]
async fn read_file_async(path: String) -> Result<Buffer> {
tokio::fs::read(path)
.map(|r| match r {
Ok(content) => Ok(content.into()),
Err(e) => Err(Error::new(
Status::GenericFailure,
format!("failed to read file, {}", e),
)),
})
.await
}
more examples at examples
Building
This repository is a Cargo
crate. Any napi-based add-on should contain Cargo.toml
to make it a Cargo crate.
In your Cargo.toml
you need to set the crate-type
to "cdylib"
so that cargo builds a C-style shared library that can be dynamically loaded by the Node executable. You'll also need to add this crate as a dependency.
[package]
name = "awesome"
[lib]
crate-type = ["cdylib"]
[dependencies]
napi = "2"
napi-derive = "2"
[build-dependencies]
napi-build = "1"
And create build.rs
in your own project:
// build.rs
extern crate napi_build;
fn main() {
napi_build::setup();
}
So far, the napi
build script has only been tested on macOS
Linux
Windows x64 MSVC
and FreeBSD
.
Install the @napi-rs/cli
to help you build your Rust
codes and copy Dynamic lib
file to .node
file in case you can require
it in your program.
{
"package": "awesome-package",
"devDependencies": {
"@napi-rs/cli": "^1.0.0"
},
"napi": {
"name": "jarvis" // <----------- Config the name of native addon, or the napi command will use the name of `Cargo.toml` for the binary file name.
},
"scripts": {
"build": "napi build --release",
"build:debug": "napi build"
}
}
Then you can require your native binding:
require('./jarvis.node')
The module_name
would be your package
name in your Cargo.toml
.
xxx => ./xxx.node
xxx-yyy => ./xxx_yyy.node
You can also copy Dynamic lib
file to an appointed location:
napi build [--release] ./dll
napi build [--release] ./artifacts
There are documents which contains more details about the @napi-rs/cli
usage.
Testing
Because libraries that depend on this crate must be loaded into a Node executable in order to resolve symbols, all tests are written in JavaScript in the test_module
subdirectory.
To run tests:
yarn build:test
yarn test
Related projects
Features table
Rust Type | Node Type | NAPI Version | Minimal Node version | Enable by napi feature |
---|---|---|---|---|
u32 | Number | 1 | v8.0.0 | |
i32/i64 | Number | 1 | v8.0.0 | |
f64 | Number | 1 | v8.0.0 | |
bool | Boolean | 1 | v8.0.0 | |
String/&'a str | String | 1 | v8.0.0 | |
Latin1String | String | 1 | v8.0.0 | latin1 |
UTF16String | String | 1 | v8.0.0 | |
Object | Object | 1 | v8.0.0 | |
serde_json::Map | Object | 1 | v8.0.0 | serde-json |
serde_json::Value | any | 1 | v8.0.0 | serde-json |
Array | Array | 1 | v8.0.0 | |
Vec | Array | 1 | v8.0.0 | |
Buffer | Buffer | 1 | v8.0.0 | |
External | External | 1 | v8.0.0 | |
Null | null | 1 | v8.0.0 | |
Undefined/() | undefined | 1 | v8.0.0 | |
Result<()> | Error | 1 | v8.0.0 | |
T: Fn(...) -> Result | Function | 1 | v8.0.0 | |
Async/Future | Promise | 4 | v10.6.0 | async |
AsyncTask | Promise | 1 | v8.5.0 | |
JsGlobal | global | 1 | v8.0.0 | |
JsSymbol | Symbol | 1 | v8.0.0 | |
Int8Array/Uint8Array ... | TypedArray | 1 | v8.0.0 | |
JsFunction | threadsafe function | 4 | v10.6.0 | napi4 |
BigInt | BigInt | 6 | v10.7.0 | napi6 |