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 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.9.0...HEAD
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
@@ -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 { allocTransient } from "../memory/buffer.js";
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, allocTransient);
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, allocTransient);
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);
@@ -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 native-call temporary or an owned callback snapshot. A small
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. Retained slices keep their backing store alive.
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
  *
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "node-ctypes",
3
- "version": "2.9.0",
3
+ "version": "2.10.0",
4
4
  "description": "Python ctypes-like FFI for Node.js using libffi",
5
5
  "author": "Damiano Mazzella",
6
6
  "license": "MIT",