Merge branch 'main' into mert/create-logger-api/node-core

Author: mertcanaltin

.github/dependabot.yml

@@ -52,6 +52,8 @@ updates:
       semver-major-days: 5
       semver-minor-days: 5
       semver-patch-days: 5
+      exclude:
+        - '@node-core/doc-kit'
     commit-message:
       prefix: tools
     open-pull-requests-limit: 10

README.md

@@ -747,8 +747,6 @@ maintaining the Node.js project.
   **Sangchul Lee** <<[email protected]>> (he/him)
 * [atlowChemi](https://github.com/atlowChemi) -
   **Chemi Atlow** <<[email protected]>> (he/him)
-* [Ayase-252](https://github.com/Ayase-252) -
-  **Qingyu Deng** <<[email protected]>>
 * [bjohansebas](https://github.com/bjohansebas) -
   **Sebastian Beltran** <<[email protected]>>
 * [bmuenzenmeyer](https://github.com/bmuenzenmeyer) -
@@ -773,8 +771,6 @@ maintaining the Node.js project.
   **Kevin Eady** <<[email protected]>> (he/him)
 * [marsonya](https://github.com/marsonya) -
   **Akhil Marsonya** <<[email protected]>> (he/him)
-* [meixg](https://github.com/meixg) -
-  **Xuguang Mei** <<[email protected]>> (he/him)
 * [milesguicent](https://github.com/milesguicent) -
   **Miles Guicent** <<[email protected]>> (he/him)
 * [preveen-stack](https://github.com/preveen-stack) -

benchmark/ffi/getpid.js

@@ -0,0 +1,25 @@
+'use strict';
+
+const common = require('../common.js');
+const ffi = require('node:ffi');
+
+const bench = common.createBenchmark(main, {
+  n: [1e7],
+}, {
+  flags: ['--experimental-ffi'],
+});
+
+const { lib, functions } = ffi.dlopen(null, {
+  uv_os_getpid: { result: 'i32', parameters: [] },
+});
+
+const getpid = functions.uv_os_getpid;
+
+function main({ n }) {
+  bench.start();
+  for (let i = 0; i < n; ++i)
+    getpid();
+  bench.end(n);
+
+  lib.close();
+}

common.gypi

@@ -15,6 +15,7 @@
     'python%': 'python',
 
     'node_shared%': 'false',
+    'node_enable_experimentals%': 'false',
     'force_dynamic_crt%': 0,
     'node_use_v8_platform%': 'true',
     'node_use_bundled_v8%': 'true',
@@ -437,6 +438,9 @@
       }],
       # The defines bellow must include all things from the external_v8_defines
       # list in v8/BUILD.gn.
+      ['node_enable_experimentals == "true"', {
+        'defines': ['EXPERIMENTALS_DEFAULT_VALUE=true'],
+      }],
       ['v8_enable_v8_checks == 1', {
         'defines': ['V8_ENABLE_CHECKS'],
       }],

configure.py

@@ -797,6 +797,12 @@
     default=None,
     help='Enable the --trace-maps flag in V8 (use at your own risk)')
 
+parser.add_argument('--enable-all-experimentals',
+    action='store_true',
+    dest='enable_all_experimentals',
+    default=None,
+    help='Enable all experimental features by default')
+
 parser.add_argument('--experimental-enable-pointer-compression',
     action='store_true',
     dest='enable_pointer_compression',
@@ -1803,6 +1809,7 @@ def configure_node_cctest_sources(o):
 def configure_node(o):
   if options.dest_os == 'android':
     o['variables']['OS'] = 'android'
+  o['variables']['node_enable_experimentals'] = b(options.enable_all_experimentals)
   o['variables']['node_prefix'] = options.prefix
   o['variables']['node_install_npm'] = b(not options.without_npm)
   o['variables']['node_install_corepack'] = b(options.with_corepack)

doc/api/debugger.md

@@ -90,6 +90,157 @@ steps to the next line. Type `help` to see what other commands are available.
 Pressing `enter` without typing a command will repeat the previous debugger
 command.
 
+## Probe mode
+
+<!-- YAML
+added:
+  - REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+`node inspect` supports a non-interactive probe mode for inspecting runtime values
+in an application via the flag `--probe`. Probe mode launches the application,
+sets one or more source breakpoints, evaluates one expression whenever a
+matching breakpoint is hit, and prints one final report when the session ends
+(either on normal completion or timeout). This allows developers to perform
+printf-style debugging without having to modify the application code and
+clean up afterwards, and it supports structured output for tool use.
+
+```console
+$ node inspect [--json] [--preview] [--timeout=<ms>] [--port=<port>] \
+    --probe app.js:10 --expr 'x' \
+    [--probe app.js:20 --expr 'y' ...] \
+    [--] [<node-option> ...] <script.js> [args...]
+```
+
+* `--probe <file>:<line>[:<col>]`: Source location to probe. Line and column number
+  are 1-based.
+* `--timeout=<ms>`: A global wall-clock deadline for the entire probe session.
+  The default is `30000`. This can be used to probe a long-running application
+  that can be terminated externally.
+* `--json`: If used, prints a structured JSON report instead of the default text report.
+* `--preview`: If used, non-primitive values will include CDP property previews for
+  object-like JSON probe values.
+* `--port=<port>`: Selects the local inspector port used for the `--inspect-brk`
+  launch path. Probe mode defaults to `0`, which requests a random port.
+* `--` is optional unless the child needs its own Node.js flags.
+
+Additional rules about the `--probe` and `--expr` arguments:
+
+* `--probe <file>:<line>[:<col>]` and `--expr <expr>` are strict pairs. Each
+  `--probe` must be followed immediately by exactly one `--expr`.
+* `--timeout`, `--json`, `--preview`, and `--port` are global probe options
+  for the whole probe session. They may appear before or between probe pairs,
+  but not between a `--probe` and its matching `--expr`.
+
+If a single probe needs to evaluate more than one value,
+evaluate a structured value in `--expr`, for example `--expr "{ foo, bar }"`
+or `--expr "[foo, bar]"`, and use `--preview` to include property previews for
+any object-like values in the output.
+
+Probe mode only prints the final probe report to stdout, and otherwise silences
+stdout/stderr from the child process. If the child exits with an error after the
+probe session starts, the final report records a terminal `error` event with the
+exit code and captured child stderr. Invalid arguments and fatal launch or
+connect failures may still print diagnostics to stderr without a final probe
+result.
+
+Consider this script:
+
+```js
+// cli.js
+let maxRSS = 0;
+for (let i = 0; i < 2; i++) {
+  const { rss } = process.memoryUsage();
+  maxRSS = Math.max(maxRSS, rss);
+}
+```
+
+If `--json` is not used, the output is printed in a human-readable text format:
+
+```console
+$ node inspect --probe cli.js:5 --expr 'rss' cli.js
+Hit 1 at cli.js:5
+  rss = 54935552
+Hit 2 at cli.js:5
+  rss = 55083008
+Completed
+```
+
+Primitive results are printed directly, while objects and arrays use Chrome
+DevTools Protocol preview data when available. Other non-primitive values
+fall back to the Chrome DevTools Protocol `description` string.
+Expression failures are recorded as `[error] ...` lines and do not fail
+the overall session. If richer text formatting is needed, wrap the expression
+in `JSON.stringify(...)` or `util.inspect(...)`.
+
+When `--json` is used, the output shape looks like this:
+
+```console
+$ node inspect --json --probe cli.js:5 --expr 'rss' cli.js
+{"v":1,"probes":[{"expr":"rss","target":["cli.js",5]}],"results":[{"probe":0,"event":"hit","hit":1,"result":{"type":"number","value":55443456,"description":"55443456"}},{"probe":0,"event":"hit","hit":2,"result":{"type":"number","value":55574528,"description":"55574528"}},{"event":"completed"}]}
+```
+
+```json
+{
+  "v": 1, // Probe JSON schema version.
+  "probes": [
+    {
+      "expr": "rss", // The expression paired with --probe.
+      "target": ["cli.js", 5] // [file, line] or [file, line, col].
+    }
+  ],
+  "results": [
+    {
+      "probe": 0, // Index into probes[].
+      "event": "hit", // Hit events are recorded in observation order.
+      "hit": 1, // 1-based hit count for this probe.
+      "result": {
+        "type": "number",
+        "value": 55443456,
+        "description": "55443456"
+      }
+      // If the expression throws, "error" is present instead of "result".
+    },
+    {
+      "probe": 0,
+      "event": "hit",
+      "hit": 2,
+      "result": {
+        "type": "number",
+        "value": 55574528,
+        "description": "55574528"
+      }
+    },
+    {
+      "event": "completed"
+      // The final entry is always a terminal event, for example:
+      // 1. { "event": "completed" }
+      // 2. { "event": "miss", "pending": [0, 1] }
+      // 3. {
+      //      "event": "timeout",
+      //      "pending": [0],
+      //      "error": {
+      //       "code": "probe_timeout",
+      //       "message": "Timed out after 30000ms waiting for probes: app.js:10"
+      //      }
+      //    }
+      // 4. {
+      //      "event": "error",
+      //      "pending": [0],
+      //      "error": {
+      //       "code": "probe_target_exit",
+      //       "exitCode": 1,
+      //       "stderr": "[Error: boom]",
+      //       "message": "Target exited with code 1 before probes: app.js:10"
+      //      }
+      //    }
+    }
+  ]
+}
+```
+
 ## Watchers
 
 It is possible to watch expression and variable values while debugging. On

doc/api/dns.md

@@ -277,9 +277,15 @@ changes:
 * `callback` {Function}
   * `err` {Error}
   * `address` {string} A string representation of an IPv4 or IPv6 address.
+    Not provided when `options.all` is `true`.
   * `family` {integer} `4` or `6`, denoting the family of `address`, or `0` if
     the address is not an IPv4 or IPv6 address. `0` is a likely indicator of a
     bug in the name resolution service used by the operating system.
+    Not provided when `options.all` is `true`.
+  * `addresses` {Object\[]} An array of address objects when `options.all` is
+    `true`. Each object has the following properties:
+    * `address` {string} A string representation of an IPv4 or IPv6 address.
+    * `family` {integer} `4` or `6`, denoting the family of `address`.
 
 Resolves a host name (e.g. `'nodejs.org'`) into the first found A (IPv4) or
 AAAA (IPv6) record. All `option` properties are optional. If `options` is an

doc/api/errors.md

@@ -1332,6 +1332,24 @@ added: v14.0.0
 Used when a feature that is not available
 to the current platform which is running Node.js is used.
 
+<a id="ERR_FFI_CALL_FAILED"></a>
+
+### `ERR_FFI_CALL_FAILED`
+
+A low-level FFI call failed.
+
+<a id="ERR_FFI_INVALID_POINTER"></a>
+
+### `ERR_FFI_INVALID_POINTER`
+
+An invalid pointer was passed to an FFI operation.
+
+<a id="ERR_FFI_LIBRARY_CLOSED"></a>
+
+### `ERR_FFI_LIBRARY_CLOSED`
+
+An operation was attempted on an FFI dynamic library after it was closed.
+
 <a id="ERR_FS_CP_DIR_TO_NON_DIR"></a>
 
 ### `ERR_FS_CP_DIR_TO_NON_DIR`

doc/api/ffi.md

@@ -165,12 +165,15 @@ const path = `libsqlite3.${suffix}`;
 added: REPLACEME
 -->
 
-* `path` {string} Path to a dynamic library.
+* `path` {string|null} Path to a dynamic library, or `null` to resolve symbols
+  from the current process image.
 * `definitions` {Object} Symbol definitions to resolve immediately.
 * Returns: {Object}
 
 Loads a dynamic library and resolves the requested function definitions.
 
+On Windows passing `null` is not supported.
+
 When `definitions` is omitted, `functions` is returned as an empty object until
 symbols are resolved explicitly.
 
@@ -237,10 +240,13 @@ Represents a loaded dynamic library.
 
 ### `new DynamicLibrary(path)`
 
-* `path` {string} Path to a dynamic library.
+* `path` {string|null} Path to a dynamic library, or `null` to resolve symbols
+  from the current process image.
 
 Loads the dynamic library without resolving any functions eagerly.
 
+On Windows passing `null` is not supported.
+
 ```cjs
 const { DynamicLibrary } = require('node:ffi');
 
@@ -603,6 +609,55 @@ available storage. This function does not allocate memory on its own.
 
 `buffer` must be a Node.js `Buffer`.
 
+## `ffi.exportArrayBuffer(arrayBuffer, pointer, length)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `arrayBuffer` {ArrayBuffer}
+* `pointer` {bigint}
+* `length` {number}
+
+Copies bytes from an `ArrayBuffer` into native memory.
+
+`length` must be at least `arrayBuffer.byteLength`.
+
+`pointer` must refer to writable native memory with at least `length` bytes of
+available storage. This function does not allocate memory on its own.
+
+## `ffi.exportArrayBufferView(arrayBufferView, pointer, length)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `arrayBufferView` {ArrayBufferView}
+* `pointer` {bigint}
+* `length` {number}
+
+Copies bytes from an `ArrayBufferView` into native memory.
+
+`length` must be at least `arrayBufferView.byteLength`.
+
+`pointer` must refer to writable native memory with at least `length` bytes of
+available storage. This function does not allocate memory on its own.
+
+## `ffi.getRawPointer(source)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `source` {Buffer|ArrayBuffer|ArrayBufferView}
+* Returns: {bigint}
+
+Returns the raw memory address of JavaScript-managed byte storage.
+
+This is unsafe and dangerous. The returned pointer can become invalid if the
+underlying memory is detached, resized, transferred, or otherwise invalidated.
+Using stale pointers can cause memory corruption or process crashes.
+
 ## Safety notes
 
 The `node:ffi` module does not track pointer validity, memory ownership, or

doc/api/n-api.md

@@ -6569,11 +6569,13 @@ NAPI_EXTERN napi_status napi_get_uv_event_loop(node_api_basic_env env,
 * `[in] env`: The environment that the API is invoked under.
 * `[out] loop`: The current libuv loop instance.
 
-Note: While libuv has been relatively stable over time, it does
-not provide an ABI stability guarantee. Use of this function should be avoided.
-Its use may result in an addon that does not work across Node.js versions.
-[asynchronous-thread-safe-function-calls](https://nodejs.org/docs/latest/api/n-api.html#asynchronous-thread-safe-function-calls)
-are an alternative for many use cases.
+Note: While libuv only [guarantees ABI stability](https://github.com/libuv/libuv?tab=readme-ov-file#versioning)
+in a major version, its use may result in an addon that does not work across
+Node.js major versions.
+
+[ThreadSafeFunction](#asynchronous-thread-safe-function-calls)
+is an ABI-stable alternative for many use cases to calling into the
+JavaScript thread from another thread.
 
 ## Asynchronous thread-safe function calls