lib: add withHeapProfileLabels and setHeapProfileLabels to v8 module

JS API for heap profile label attribution:
- withHeapProfileLabels(labels, fn): scoped labels via AsyncLocalStorage
  with automatic cleanup on sync return, promise settle, or exception
- setHeapProfileLabels(labels): enterWith semantics for frameworks where
  the handler runs after the extension returns (e.g., Hapi)
- Expose startSamplingHeapProfiler, stopSamplingHeapProfiler,
  getAllocationProfile from the v8 binding

Signed-off-by: Rudolf Meijering <skaapgif@gmail.com>

Author: rudolf

lib/v8.js

@@ -16,6 +16,7 @@
 
 const {
   Array,
+  ArrayPrototypePush,
   BigInt64Array,
   BigUint64Array,
   DataView,
@@ -26,7 +27,10 @@ const {
   Int32Array,
   Int8Array,
   JSONParse,
+  ObjectKeys,
   ObjectPrototypeToString,
+  SafePromisePrototypeFinally,
+  String,
   SymbolDispose,
   Uint16Array,
   Uint32Array,
@@ -38,7 +42,10 @@ const {
 } = primordials;
 
 const { Buffer } = require('buffer');
+const { AsyncLocalStorage } = require('async_hooks');
 const {
+  validateFunction,
+  validateObject,
   validateString,
   validateUint32,
   validateOneOf,
@@ -47,6 +54,7 @@ const {
   Serializer,
   Deserializer,
 } = internalBinding('serdes');
+const { isPromise } = internalBinding('types');
 const {
   namespace: startupSnapshot,
 } = require('internal/v8/startup_snapshot');
@@ -156,6 +164,12 @@ const {
   heapSpaceStatisticsBuffer,
   getCppHeapStatistics: _getCppHeapStatistics,
   detailLevel,
+
+  startSamplingHeapProfiler: _startSamplingHeapProfiler,
+  stopSamplingHeapProfiler: _stopSamplingHeapProfiler,
+  getAllocationProfile: _getAllocationProfile,
+  registerHeapProfileLabels: _registerHeapProfileLabels,
+  unregisterHeapProfileLabels: _unregisterHeapProfileLabels,
 } = binding;
 
 const kNumberOfHeapSpaces = kHeapSpaces.length;
@@ -494,6 +508,91 @@ class GCProfiler {
   }
 }
 
+// --- Heap profile labels API ---
+// Internal AsyncLocalStorage for propagating labels through async context.
+// Requires --experimental-async-context-frame (Node 22) or Node 24+.
+const _heapProfileLabelsALS = new AsyncLocalStorage();
+
+/**
+ * Convert a labels object to a flat array [key1, val1, key2, val2, ...].
+ * @param {Record<string, string>} labels
+ * @returns {string[]}
+ */
+function labelsToFlat(labels) {
+  const keys = ObjectKeys(labels);
+  const flat = [];
+  for (let i = 0; i < keys.length; i++) {
+    ArrayPrototypePush(flat, String(keys[i]), String(labels[keys[i]]));
+  }
+  return flat;
+}
+
+/**
+ * Starts the V8 sampling heap profiler.
+ * @param {number} [sampleInterval] - Average bytes between samples (default 512 KB).
+ * @param {number} [stackDepth] - Maximum stack depth for samples (default 16).
+ * @param {object} [options] - Options object.
+ * @param {boolean} [options.includeCollectedObjects] - If true, retain
+ *   samples for objects collected by GC (allocation-rate mode).
+ */
+function startSamplingHeapProfiler(sampleInterval, stackDepth, options) {
+  if (sampleInterval !== undefined) validateUint32(sampleInterval, 'sampleInterval');
+  if (stackDepth !== undefined) validateUint32(stackDepth, 'stackDepth');
+  if (options !== undefined) validateObject(options, 'options');
+  return _startSamplingHeapProfiler(sampleInterval, stackDepth, options);
+}
+
+/**
+ * Runs `fn` with the given heap profile labels active. Labels propagate
+ * across `await` boundaries via AsyncLocalStorage. If `fn` returns a
+ * Promise, labels remain active until the Promise settles.
+ *
+ * @param {Record<string, string>} labels
+ * @param {Function} fn
+ * @returns {*} The return value of `fn`.
+ */
+function withHeapProfileLabels(labels, fn) {
+  validateObject(labels, 'labels');
+  validateFunction(fn, 'fn');
+  const flat = labelsToFlat(labels);
+  return _heapProfileLabelsALS.run(flat, () => {
+    _registerHeapProfileLabels(flat);
+    try {
+      const result = fn();
+      if (isPromise(result)) {
+        return SafePromisePrototypeFinally(
+          result,
+          () => _unregisterHeapProfileLabels(),
+        );
+      }
+      _unregisterHeapProfileLabels();
+      return result;
+    } catch (err) {
+      _unregisterHeapProfileLabels();
+      throw err;
+    }
+  });
+}
+
+/**
+ * Sets heap profile labels for the current async scope using
+ * `enterWith` semantics. Labels persist until overwritten or the
+ * async scope ends. Useful for frameworks (e.g. Hapi) where the
+ * handler runs after the extension returns.
+ *
+ * @param {Record<string, string>} labels
+ */
+function setHeapProfileLabels(labels) {
+  validateObject(labels, 'labels');
+  const flat = labelsToFlat(labels);
+  // Unregister previous entry before enterWith creates a new CPED context,
+  // otherwise the old entry leaks in the label map (enterWith creates a new
+  // AsyncContextFrame each call, orphaning the previous CPED identity).
+  _unregisterHeapProfileLabels();
+  _heapProfileLabelsALS.enterWith(flat);
+  _registerHeapProfileLabels(flat);
+}
+
 module.exports = {
   cachedDataVersionTag,
   getHeapSnapshot,
@@ -518,4 +617,9 @@ module.exports = {
   GCProfiler,
   isStringOneByteRepresentation,
   startCpuProfile,
+  startSamplingHeapProfiler,
+  stopSamplingHeapProfiler: _stopSamplingHeapProfiler,
+  getAllocationProfile: _getAllocationProfile,
+  withHeapProfileLabels,
+  setHeapProfileLabels,
 };