node-ctypes 2.9.0 → 2.10.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +28 -1
- package/README.md +30 -0
- package/build/Release/ctypes-darwin-arm64.node +0 -0
- package/build/Release/ctypes-darwin-x64.node +0 -0
- package/build/Release/ctypes-linux-arm64-musl.node +0 -0
- package/build/Release/ctypes-linux-arm64.node +0 -0
- package/build/Release/ctypes-linux-x64-musl.node +0 -0
- package/build/Release/ctypes-linux-x64.node +0 -0
- package/build/Release/ctypes-win32-arm64.node +0 -0
- package/build/Release/ctypes-win32-x64.node +0 -0
- package/lib/core/callback.js +3 -3
- package/lib/memory/buffer.js +37 -2
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
7
7
|
|
|
8
8
|
## [Unreleased]
|
|
9
9
|
|
|
10
|
+
## [2.10.0] - 2026-11-06
|
|
11
|
+
|
|
12
|
+
### Fixed
|
|
13
|
+
|
|
14
|
+
- **Callback exception boundary**: a C++ exception other than a Node-API error
|
|
15
|
+
(for example `std::bad_alloc` while copying an aggregate) raised while
|
|
16
|
+
converting arguments or results, calling the JavaScript function, its error
|
|
17
|
+
handler or the warning fallback is recorded and yields a zero result instead
|
|
18
|
+
of crossing the native callback frame.
|
|
19
|
+
- **Callback snapshot pool isolation**: snapshots of callback arguments no
|
|
20
|
+
longer share their pool with native-call temporaries. Since 2.9.0, detaching
|
|
21
|
+
a snapshot's `ArrayBuffer` broke every later by-value structure argument and
|
|
22
|
+
structure callback, and could let JavaScript read, alter or release memory
|
|
23
|
+
still used by an in-flight native call. A detached pool is now replaced.
|
|
24
|
+
- **Detached buffer arguments**: a Buffer, typed array, DataView or ArrayBuffer
|
|
25
|
+
argument detached while native code could still use it (by a callback during
|
|
26
|
+
a synchronous call, or before a `callAsync()` completes) now makes the call
|
|
27
|
+
throw or reject instead of returning silently. Node-API cannot prevent the
|
|
28
|
+
detach; synchronous calls check only when a JavaScript callback ran.
|
|
29
|
+
|
|
30
|
+
### Documentation
|
|
31
|
+
|
|
32
|
+
- **Callback snapshot pool**: document the dedicated snapshot pool, how
|
|
33
|
+
retention affects memory and why the underlying `ArrayBuffer` should not be
|
|
34
|
+
exposed without copying.
|
|
35
|
+
|
|
10
36
|
## [2.9.0] - 2026-11-05
|
|
11
37
|
|
|
12
38
|
### Added
|
|
@@ -1130,7 +1156,8 @@ It contains breaking changes: see [Migrating from 1.x](README.md#migrating-from-
|
|
|
1130
1156
|
|
|
1131
1157
|
Initial releases.
|
|
1132
1158
|
|
|
1133
|
-
[Unreleased]: https://github.com/dmazzella/node-ctypes/compare/v2.
|
|
1159
|
+
[Unreleased]: https://github.com/dmazzella/node-ctypes/compare/v2.10.0...HEAD
|
|
1160
|
+
[2.10.0]: https://github.com/dmazzella/node-ctypes/compare/v2.9.0...v2.10.0
|
|
1134
1161
|
[2.9.0]: https://github.com/dmazzella/node-ctypes/compare/v2.8.0...v2.9.0
|
|
1135
1162
|
[2.8.0]: https://github.com/dmazzella/node-ctypes/compare/v2.7.0...v2.8.0
|
|
1136
1163
|
[2.7.0]: https://github.com/dmazzella/node-ctypes/compare/v2.6.0...v2.7.0
|
package/README.md
CHANGED
|
@@ -297,6 +297,25 @@ Existing callers retain their result-check snapshot and their own `errcheck`.
|
|
|
297
297
|
An installed `from_param` converter still resolves the method at call time,
|
|
298
298
|
as before.
|
|
299
299
|
|
|
300
|
+
Structure, union and scalar-instance arguments received by `callback()`,
|
|
301
|
+
`CFUNCTYPE` and `threadSafeCallback()` are owned snapshots: each one is a
|
|
302
|
+
distinct slice of an 8 KB off-heap pool reserved for callback snapshots.
|
|
303
|
+
Native-call temporaries use a separate pool that is never exposed, so a
|
|
304
|
+
snapshot cannot reveal or alter memory that native code is still using.
|
|
305
|
+
Slices are never reused, so a retained argument keeps its own bytes and
|
|
306
|
+
identity. Detaching a snapshot's `ArrayBuffer` (`transfer()`, a transfer list)
|
|
307
|
+
only affects the snapshots in that pool; later callbacks use a fresh one.
|
|
308
|
+
|
|
309
|
+
- Retaining any slice keeps its whole 8 KB backing `ArrayBuffer` alive. When
|
|
310
|
+
storing many small arguments for a long time, copy them, for example
|
|
311
|
+
`Buffer.from(value._buffer)` or a new instance built from its fields.
|
|
312
|
+
- `value._buffer.buffer` is the whole pool and can contain other callback
|
|
313
|
+
snapshots. Use `_buffer` itself (or `byteOffset` and `length`), and copy
|
|
314
|
+
before handing the underlying `ArrayBuffer` to untrusted code.
|
|
315
|
+
|
|
316
|
+
Values larger than 2 KB, layouts aligned to more than 8 bytes and raw native
|
|
317
|
+
callbacks keep a dedicated allocation.
|
|
318
|
+
|
|
300
319
|
Both callbacks and libraries implement `Symbol.dispose`, so they work
|
|
301
320
|
with the `using` declaration for scope-bound cleanup (also on `throw`):
|
|
302
321
|
|
|
@@ -593,6 +612,17 @@ still stop at its end; raw native addresses remain the caller's responsibility.
|
|
|
593
612
|
Scalar `from_buffer()` / `from_buffer_copy()` validate byte size and offset
|
|
594
613
|
before producing an instance and accept Buffer, typed views and ctypes memory.
|
|
595
614
|
|
|
615
|
+
Do not detach (`ArrayBuffer.prototype.transfer()`, a `postMessage` /
|
|
616
|
+
`structuredClone` transfer list) memory passed to a call that is still running:
|
|
617
|
+
a pending `callAsync()`, or the outer call while a callback runs. Native code
|
|
618
|
+
keeps its address and may access memory that now belongs to another
|
|
619
|
+
`ArrayBuffer` or has been released. Node-API cannot prevent the detach, so
|
|
620
|
+
node-ctypes reports it instead. A synchronous call during which a JavaScript
|
|
621
|
+
callback ran throws `argument N: memory was detached ...` after native code
|
|
622
|
+
returns, and a `callAsync()` whose Buffer, typed array, DataView or ArrayBuffer
|
|
623
|
+
argument was detached rejects. The check covers those arguments as passed,
|
|
624
|
+
not addresses stored inside structures or obtained with `addressof()`.
|
|
625
|
+
|
|
596
626
|
### Electron
|
|
597
627
|
|
|
598
628
|
Electron does not allow Buffers over memory that V8 did not allocate, so a
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
package/lib/core/callback.js
CHANGED
|
@@ -57,7 +57,7 @@ import { _toNativeReturnType, _toNativeTypes } from "./types.js";
|
|
|
57
57
|
import { adaptCallbackFunction, scalarResult } from "./conversions.js";
|
|
58
58
|
import { trackCallback } from "./callback-tracker.js";
|
|
59
59
|
import { callbackPointer } from "../structures/helpers/common.js";
|
|
60
|
-
import {
|
|
60
|
+
import { allocSnapshot } from "../memory/buffer.js";
|
|
61
61
|
|
|
62
62
|
function nativeContextHook(value, name, owners) {
|
|
63
63
|
if (value !== null && (typeof value === "object" || typeof value === "function")) {
|
|
@@ -176,7 +176,7 @@ export function callback(fn, returnType, argTypes = [], native, abi = undefined)
|
|
|
176
176
|
const args = [adaptCallbackFunction(fn, argTypes, returnType, native), _toNativeReturnType(returnType, native), _toNativeTypes(argTypes, native)];
|
|
177
177
|
const scalarArgs = argTypes.map(scalarResult);
|
|
178
178
|
const buffers = scalarArgs.some(Boolean) || args[2].some((type) => typeof type === "object" && type !== null);
|
|
179
|
-
if (buffers) args.push(abi ?? "default", scalarArgs, undefined,
|
|
179
|
+
if (buffers) args.push(abi ?? "default", scalarArgs, undefined, allocSnapshot);
|
|
180
180
|
else if (abi) args.push(abi);
|
|
181
181
|
const cb = new native.Callback(...args);
|
|
182
182
|
|
|
@@ -324,7 +324,7 @@ export function threadSafeCallback(fn, returnType, argTypes = [], native, option
|
|
|
324
324
|
const args = [dispatch, _toNativeReturnType(returnType, native), _toNativeTypes(argTypes, native)];
|
|
325
325
|
const scalarArgs = argTypes.map(scalarResult);
|
|
326
326
|
const buffers = scalarArgs.some(Boolean) || args[2].some((type) => typeof type === "object" && type !== null);
|
|
327
|
-
if (buffers) args.push(abi ?? "default", scalarArgs, context,
|
|
327
|
+
if (buffers) args.push(abi ?? "default", scalarArgs, context, allocSnapshot);
|
|
328
328
|
else if (context !== undefined) args.push(abi ?? "default", scalarArgs, context);
|
|
329
329
|
else if (scalarArgs.some(Boolean)) args.push(abi ?? "default", scalarArgs);
|
|
330
330
|
else if (abi) args.push(abi);
|
package/lib/memory/buffer.js
CHANGED
|
@@ -74,14 +74,19 @@ const kTransientPoolSize = 8192;
|
|
|
74
74
|
const FixedArrayBuffer = ArrayBuffer;
|
|
75
75
|
const bufferFrom = Buffer.from;
|
|
76
76
|
const zeroBuffer = Buffer.alloc;
|
|
77
|
+
|
|
77
78
|
let transientPool = new FixedArrayBuffer(kTransientPoolSize);
|
|
78
79
|
let transientOffset = 0;
|
|
80
|
+
let snapshotPool = new FixedArrayBuffer(kTransientPoolSize);
|
|
81
|
+
let snapshotOffset = 0;
|
|
79
82
|
|
|
80
83
|
/**
|
|
81
|
-
* Zero-filled buffer for a
|
|
84
|
+
* Zero-filled buffer for a value that only lives for one native call. A small
|
|
82
85
|
* Buffer.alloc lives on the V8 heap and must be externalized when native code
|
|
83
86
|
* reads it; slices of an off-heap pool avoid that. Slices are never reused, so
|
|
84
|
-
* a fresh pool is already zeroed.
|
|
87
|
+
* a fresh pool is already zeroed. The pool is never handed to user code:
|
|
88
|
+
* native code may still use these slices while JavaScript runs (callbacks,
|
|
89
|
+
* async calls).
|
|
85
90
|
*
|
|
86
91
|
* @param {number} size - Size in bytes to allocate
|
|
87
92
|
* @returns {Buffer} Zero-initialized buffer
|
|
@@ -97,6 +102,36 @@ export function allocTransient(size) {
|
|
|
97
102
|
return buf;
|
|
98
103
|
}
|
|
99
104
|
|
|
105
|
+
/**
|
|
106
|
+
* Zero-filled buffer for an owned callback argument snapshot, sliced as
|
|
107
|
+
* {@link allocTransient} from a separate pool: a snapshot's `.buffer` exposes
|
|
108
|
+
* only other snapshots, and detaching it cannot affect native-call temporaries.
|
|
109
|
+
* Retained slices keep their pool alive; a pool detached by user code
|
|
110
|
+
* (`transfer()`, a transfer list) is replaced.
|
|
111
|
+
*
|
|
112
|
+
* @param {number} size - Size in bytes to allocate
|
|
113
|
+
* @returns {Buffer} Zero-initialized buffer
|
|
114
|
+
*/
|
|
115
|
+
export function allocSnapshot(size) {
|
|
116
|
+
if (size > kTransientPoolSize >>> 2) return zeroBuffer(size);
|
|
117
|
+
if (snapshotOffset + size > kTransientPoolSize) {
|
|
118
|
+
snapshotPool = new FixedArrayBuffer(kTransientPoolSize);
|
|
119
|
+
snapshotOffset = 0;
|
|
120
|
+
}
|
|
121
|
+
let buf;
|
|
122
|
+
try {
|
|
123
|
+
buf = bufferFrom(snapshotPool, snapshotOffset, size);
|
|
124
|
+
} catch (error) {
|
|
125
|
+
// Un pool staccato ha byteLength 0: il controllo resta fuori dal percorso caldo.
|
|
126
|
+
if (!snapshotPool.detached) throw error;
|
|
127
|
+
snapshotPool = new FixedArrayBuffer(kTransientPoolSize);
|
|
128
|
+
snapshotOffset = 0;
|
|
129
|
+
buf = bufferFrom(snapshotPool, 0, size);
|
|
130
|
+
}
|
|
131
|
+
snapshotOffset += (size + 7) & ~7;
|
|
132
|
+
return buf;
|
|
133
|
+
}
|
|
134
|
+
|
|
100
135
|
/**
|
|
101
136
|
* Creates a buffer containing a null-terminated C string.
|
|
102
137
|
*
|