From 616a9bd0589127c63d86092a0b2dff3d64cb314b Mon Sep 17 00:00:00 2001
From: theanarkh <theratliter@gmail.com>
Date: Thu, 11 Sep 2025 00:51:08 +0800
Subject: [PATCH] worker: add heap profile API

---
 doc/api/v8.md                                 |  27 +++
 doc/api/worker_threads.md                     |  43 ++++
 lib/internal/worker.js                        |  42 ++++
 src/async_wrap.h                              |   1 +
 src/env_properties.h                          |   1 +
 src/node_errors.h                             |   2 +
 src/node_worker.cc                            | 183 ++++++++++++++++++
 src/node_worker.h                             |   3 +
 test/parallel/test-worker-heap-profile.js     |  36 ++++
 test/sequential/test-async-wrap-getasyncid.js |   1 +
 tools/doc/type-parser.mjs                     |   1 +
 typings/internalBinding/worker.d.ts           |   6 +
 12 files changed, 346 insertions(+)
 create mode 100644 test/parallel/test-worker-heap-profile.js

diff --git a/doc/api/v8.md b/doc/api/v8.md
index 0e18b6b6c59522..d7536490d728b2 100644
--- a/doc/api/v8.md
+++ b/doc/api/v8.md
@@ -1425,6 +1425,33 @@ added: REPLACEME
 
 Stopping collecting the profile and the profile will be discarded.
 
+## Class: `HeapProfileHandle`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+### `heapProfileHandle.stop()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Returns: {Promise}
+
+Stopping collecting the profile, then return a Promise that fulfills with an error or the
+profile data.
+
+### `heapProfileHandle[Symbol.asyncDispose]()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Returns: {Promise}
+
+Stopping collecting the profile and the profile will be discarded.
+
 ## `v8.isStringOneByteRepresentation(content)`
 
 <!-- YAML
diff --git a/doc/api/worker_threads.md b/doc/api/worker_threads.md
index 3c2cb983b185ca..d8f7207ba36f2b 100644
--- a/doc/api/worker_threads.md
+++ b/doc/api/worker_threads.md
@@ -2001,6 +2001,49 @@ w.on('online', async () => {
 });
 ```
 
+### `worker.startHeapProfile()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Returns: {Promise}
+
+Starting a Heap profile then return a Promise that fulfills with an error
+or an `HeapProfileHandle` object. This API supports `await using` syntax.
+
+```cjs
+const { Worker } = require('node:worker_threads');
+
+const worker = new Worker(`
+  const { parentPort } = require('worker_threads');
+  parentPort.on('message', () => {});
+  `, { eval: true });
+
+worker.on('online', async () => {
+  const handle = await worker.startHeapProfile();
+  const profile = await handle.stop();
+  console.log(profile);
+  worker.terminate();
+});
+```
+
+`await using` example.
+
+```cjs
+const { Worker } = require('node::worker_threads');
+
+const w = new Worker(`
+  const { parentPort } = require('worker_threads');
+  parentPort.on('message', () => {});
+  `, { eval: true });
+
+w.on('online', async () => {
+  // Stop profile automatically when return and profile will be discarded
+  await using handle = await w.startHeapProfile();
+});
+```
+
 ### `worker.stderr`
 
 <!-- YAML
diff --git a/lib/internal/worker.js b/lib/internal/worker.js
index 0a9c72653dd362..ed940b5e2c4208 100644
--- a/lib/internal/worker.js
+++ b/lib/internal/worker.js
@@ -165,6 +165,35 @@ class CPUProfileHandle {
   }
 }
 
+class HeapProfileHandle {
+  #worker = null;
+  #promise = null;
+
+  constructor(worker) {
+    this.#worker = worker;
+  }
+
+  stop() {
+    if (this.#promise) {
+      return this.#promise;
+    }
+    const stopTaker = this.#worker[kHandle]?.stopHeapProfile();
+    return this.#promise = new Promise((resolve, reject) => {
+      if (!stopTaker) return reject(new ERR_WORKER_NOT_RUNNING());
+      stopTaker.ondone = (err, profile) => {
+        if (err) {
+          return reject(err);
+        }
+        resolve(profile);
+      };
+    });
+  };
+
+  async [SymbolAsyncDispose]() {
+    await this.stop();
+  }
+}
+
 class Worker extends EventEmitter {
   constructor(filename, options = kEmptyObject) {
     throwIfBuildingSnapshot('Creating workers');
@@ -551,6 +580,19 @@ class Worker extends EventEmitter {
       };
     });
   }
+
+  startHeapProfile() {
+    const startTaker = this[kHandle]?.startHeapProfile();
+    return new Promise((resolve, reject) => {
+      if (!startTaker) return reject(new ERR_WORKER_NOT_RUNNING());
+      startTaker.ondone = (err) => {
+        if (err) {
+          return reject(err);
+        }
+        resolve(new HeapProfileHandle(this));
+      };
+    });
+  }
 }
 
 /**
diff --git a/src/async_wrap.h b/src/async_wrap.h
index 1d7522f6ffe6e2..efb56a61a3e2d3 100644
--- a/src/async_wrap.h
+++ b/src/async_wrap.h
@@ -81,6 +81,7 @@ namespace node {
   V(WORKER)                                                                    \
   V(WORKERCPUPROFILE)                                                          \
   V(WORKERCPUUSAGE)                                                            \
+  V(WORKERHEAPPROFILE)                                                         \
   V(WORKERHEAPSNAPSHOT)                                                        \
   V(WORKERHEAPSTATISTICS)                                                      \
   V(WRITEWRAP)                                                                 \
diff --git a/src/env_properties.h b/src/env_properties.h
index 7ef519960070c0..4ff8e6275cd647 100644
--- a/src/env_properties.h
+++ b/src/env_properties.h
@@ -471,6 +471,7 @@
   V(write_wrap_template, v8::ObjectTemplate)                                   \
   V(worker_cpu_profile_taker_template, v8::ObjectTemplate)                     \
   V(worker_cpu_usage_taker_template, v8::ObjectTemplate)                       \
+  V(worker_heap_profile_taker_template, v8::ObjectTemplate)                    \
   V(worker_heap_snapshot_taker_template, v8::ObjectTemplate)                   \
   V(worker_heap_statistics_taker_template, v8::ObjectTemplate)                 \
   V(x509_constructor_template, v8::FunctionTemplate)
diff --git a/src/node_errors.h b/src/node_errors.h
index f741c9f698f2f6..f24cc250303bd1 100644
--- a/src/node_errors.h
+++ b/src/node_errors.h
@@ -87,6 +87,8 @@ void OOMErrorHandler(const char* location, const v8::OOMDetails& details);
   V(ERR_FS_CP_SOCKET, Error)                                                   \
   V(ERR_FS_CP_FIFO_PIPE, Error)                                                \
   V(ERR_FS_CP_UNKNOWN, Error)                                                  \
+  V(ERR_HEAP_PROFILE_HAVE_BEEN_STARTED, Error)                                 \
+  V(ERR_HEAP_PROFILE_NOT_STARTED, Error)                                       \
   V(ERR_ILLEGAL_CONSTRUCTOR, Error)                                            \
   V(ERR_INVALID_ADDRESS, Error)                                                \
   V(ERR_INVALID_ARG_VALUE, TypeError)                                          \
diff --git a/src/node_worker.cc b/src/node_worker.cc
index 9518ab9d812f21..7bae29747d8cd8 100644
--- a/src/node_worker.cc
+++ b/src/node_worker.cc
@@ -20,6 +20,7 @@
 
 using node::kAllowedInEnvvar;
 using node::kDisallowedInEnvvar;
+using v8::AllocationProfile;
 using v8::Array;
 using v8::ArrayBuffer;
 using v8::Boolean;
@@ -32,6 +33,7 @@ using v8::Float64Array;
 using v8::FunctionCallbackInfo;
 using v8::FunctionTemplate;
 using v8::HandleScope;
+using v8::HeapProfiler;
 using v8::HeapStatistics;
 using v8::Integer;
 using v8::Isolate;
@@ -1031,6 +1033,169 @@ void Worker::StopCpuProfile(const FunctionCallbackInfo<Value>& args) {
   }
 }
 
+class WorkerHeapProfileTaker final : public AsyncWrap {
+ public:
+  WorkerHeapProfileTaker(Environment* env, Local<Object> obj)
+      : AsyncWrap(env, obj, AsyncWrap::PROVIDER_WORKERHEAPPROFILE) {}
+
+  SET_NO_MEMORY_INFO()
+  SET_MEMORY_INFO_NAME(WorkerHeapProfileTaker)
+  SET_SELF_SIZE(WorkerHeapProfileTaker)
+};
+
+void Worker::StartHeapProfile(const FunctionCallbackInfo<Value>& args) {
+  Worker* w;
+  ASSIGN_OR_RETURN_UNWRAP(&w, args.This());
+  Environment* env = w->env();
+
+  AsyncHooks::DefaultTriggerAsyncIdScope trigger_id_scope(w);
+  Local<Object> wrap;
+  if (!env->worker_heap_profile_taker_template()
+           ->NewInstance(env->context())
+           .ToLocal(&wrap)) {
+    return;
+  }
+
+  BaseObjectPtr<WorkerHeapProfileTaker> taker =
+      MakeDetachedBaseObject<WorkerHeapProfileTaker>(env, wrap);
+
+  bool scheduled = w->RequestInterrupt([taker = std::move(taker),
+                                        env](Environment* worker_env) mutable {
+    v8::HeapProfiler* profiler = worker_env->isolate()->GetHeapProfiler();
+    bool success = profiler->StartSamplingHeapProfiler();
+    env->SetImmediateThreadsafe(
+        [taker = std::move(taker),
+         success = success](Environment* env) mutable {
+          Isolate* isolate = env->isolate();
+          HandleScope handle_scope(isolate);
+          Context::Scope context_scope(env->context());
+          AsyncHooks::DefaultTriggerAsyncIdScope trigger_id_scope(taker.get());
+          Local<Value> argv[] = {
+              Null(isolate),  // error
+          };
+          if (!success) {
+            argv[0] = ERR_HEAP_PROFILE_HAVE_BEEN_STARTED(
+                isolate, "heap profiler have been started");
+          }
+          taker->MakeCallback(env->ondone_string(), arraysize(argv), argv);
+        },
+        CallbackFlags::kUnrefed);
+  });
+
+  if (scheduled) {
+    args.GetReturnValue().Set(wrap);
+  }
+}
+
+static void buildHeapProfileNode(Isolate* isolate,
+                                 const AllocationProfile::Node* node,
+                                 JSONWriter* writer) {
+  size_t selfSize = 0;
+  for (const auto& allocation : node->allocations)
+    selfSize += allocation.size * allocation.count;
+
+  writer->json_keyvalue("selfSize", selfSize);
+  writer->json_keyvalue("id", node->node_id);
+  writer->json_objectstart("callFrame");
+  writer->json_keyvalue("scriptId", node->script_id);
+  writer->json_keyvalue("lineNumber", node->line_number - 1);
+  writer->json_keyvalue("columnNumber", node->column_number - 1);
+  node::Utf8Value name(isolate, node->name);
+  node::Utf8Value script_name(isolate, node->script_name);
+  writer->json_keyvalue("functionName", *name);
+  writer->json_keyvalue("url", *script_name);
+  writer->json_objectend();
+
+  writer->json_arraystart("children");
+  for (const auto* child : node->children) {
+    writer->json_start();
+    buildHeapProfileNode(isolate, child, writer);
+    writer->json_end();
+  }
+  writer->json_arrayend();
+}
+
+static bool serializeProfile(Isolate* isolate, std::ostringstream& out_stream) {
+  HandleScope scope(isolate);
+  HeapProfiler* profiler = isolate->GetHeapProfiler();
+  std::unique_ptr<AllocationProfile> profile(profiler->GetAllocationProfile());
+  if (!profile) {
+    return false;
+  }
+  JSONWriter writer(out_stream, false);
+  writer.json_start();
+
+  writer.json_arraystart("samples");
+  for (const auto& sample : profile->GetSamples()) {
+    writer.json_start();
+    writer.json_keyvalue("size", sample.size * sample.count);
+    writer.json_keyvalue("nodeId", sample.node_id);
+    writer.json_keyvalue("ordinal", static_cast<double>(sample.sample_id));
+    writer.json_end();
+  }
+  writer.json_arrayend();
+
+  writer.json_objectstart("head");
+  buildHeapProfileNode(isolate, profile->GetRootNode(), &writer);
+  writer.json_objectend();
+
+  writer.json_end();
+  profiler->StopSamplingHeapProfiler();
+  return true;
+}
+
+void Worker::StopHeapProfile(const FunctionCallbackInfo<Value>& args) {
+  Worker* w;
+  ASSIGN_OR_RETURN_UNWRAP(&w, args.This());
+
+  Environment* env = w->env();
+  AsyncHooks::DefaultTriggerAsyncIdScope trigger_id_scope(w);
+  Local<Object> wrap;
+  if (!env->worker_heap_profile_taker_template()
+           ->NewInstance(env->context())
+           .ToLocal(&wrap)) {
+    return;
+  }
+
+  BaseObjectPtr<WorkerHeapProfileTaker> taker =
+      MakeDetachedBaseObject<WorkerHeapProfileTaker>(env, wrap);
+
+  bool scheduled = w->RequestInterrupt([taker = std::move(taker),
+                                        env](Environment* worker_env) mutable {
+    std::ostringstream out_stream;
+    bool success = serializeProfile(worker_env->isolate(), out_stream);
+    env->SetImmediateThreadsafe(
+        [taker = std::move(taker),
+         out_stream = std::move(out_stream),
+         success = success](Environment* env) mutable {
+          Isolate* isolate = env->isolate();
+          HandleScope handle_scope(isolate);
+          Context::Scope context_scope(env->context());
+          AsyncHooks::DefaultTriggerAsyncIdScope trigger_id_scope(taker.get());
+          Local<Value> argv[] = {
+              Null(isolate),       // error
+              Undefined(isolate),  // profile
+          };
+          if (success) {
+            Local<Value> result;
+            if (!ToV8Value(env->context(), out_stream.str(), isolate)
+                     .ToLocal(&result)) {
+              return;
+            }
+            argv[1] = result;
+          } else {
+            argv[0] = ERR_HEAP_PROFILE_NOT_STARTED(isolate,
+                                                   "heap profile not started");
+          }
+          taker->MakeCallback(env->ondone_string(), arraysize(argv), argv);
+        },
+        CallbackFlags::kUnrefed);
+  });
+
+  if (scheduled) {
+    args.GetReturnValue().Set(wrap);
+  }
+}
 class WorkerHeapStatisticsTaker : public AsyncWrap {
  public:
   WorkerHeapStatisticsTaker(Environment* env, Local<Object> obj)
@@ -1328,6 +1493,8 @@ void CreateWorkerPerIsolateProperties(IsolateData* isolate_data,
     SetProtoMethod(isolate, w, "cpuUsage", Worker::CpuUsage);
     SetProtoMethod(isolate, w, "startCpuProfile", Worker::StartCpuProfile);
     SetProtoMethod(isolate, w, "stopCpuProfile", Worker::StopCpuProfile);
+    SetProtoMethod(isolate, w, "startHeapProfile", Worker::StartHeapProfile);
+    SetProtoMethod(isolate, w, "stopHeapProfile", Worker::StopHeapProfile);
 
     SetConstructorFunction(isolate, target, "Worker", w);
   }
@@ -1387,6 +1554,20 @@ void CreateWorkerPerIsolateProperties(IsolateData* isolate_data,
         wst->InstanceTemplate());
   }
 
+  {
+    Local<FunctionTemplate> wst = NewFunctionTemplate(isolate, nullptr);
+
+    wst->InstanceTemplate()->SetInternalFieldCount(
+        WorkerHeapProfileTaker::kInternalFieldCount);
+    wst->Inherit(AsyncWrap::GetConstructorTemplate(isolate_data));
+
+    Local<String> wst_string =
+        FIXED_ONE_BYTE_STRING(isolate, "WorkerHeapProfileTaker");
+    wst->SetClassName(wst_string);
+    isolate_data->set_worker_heap_profile_taker_template(
+        wst->InstanceTemplate());
+  }
+
   SetMethod(isolate, target, "getEnvMessagePort", GetEnvMessagePort);
 }
 
@@ -1466,6 +1647,8 @@ void RegisterExternalReferences(ExternalReferenceRegistry* registry) {
   registry->Register(Worker::CpuUsage);
   registry->Register(Worker::StartCpuProfile);
   registry->Register(Worker::StopCpuProfile);
+  registry->Register(Worker::StartHeapProfile);
+  registry->Register(Worker::StopHeapProfile);
 }
 
 }  // anonymous namespace
diff --git a/src/node_worker.h b/src/node_worker.h
index 28f3ca3eedd4ef..873029096c465e 100644
--- a/src/node_worker.h
+++ b/src/node_worker.h
@@ -5,6 +5,7 @@
 
 #include <optional>
 #include <unordered_map>
+#include "json_utils.h"
 #include "node_exit_code.h"
 #include "node_messaging.h"
 #include "uv.h"
@@ -84,6 +85,8 @@ class Worker : public AsyncWrap {
   static void CpuUsage(const v8::FunctionCallbackInfo<v8::Value>& args);
   static void StartCpuProfile(const v8::FunctionCallbackInfo<v8::Value>& args);
   static void StopCpuProfile(const v8::FunctionCallbackInfo<v8::Value>& args);
+  static void StartHeapProfile(const v8::FunctionCallbackInfo<v8::Value>& args);
+  static void StopHeapProfile(const v8::FunctionCallbackInfo<v8::Value>& args);
 
  private:
   bool CreateEnvMessagePort(Environment* env);
diff --git a/test/parallel/test-worker-heap-profile.js b/test/parallel/test-worker-heap-profile.js
new file mode 100644
index 00000000000000..e5aff1f78978ef
--- /dev/null
+++ b/test/parallel/test-worker-heap-profile.js
@@ -0,0 +1,36 @@
+'use strict';
+const common = require('../common');
+const assert = require('assert');
+const { Worker } = require('worker_threads');
+
+const worker = new Worker(`
+  const { parentPort } = require('worker_threads');
+  parentPort.on('message', () => {});
+  `, { eval: true });
+
+worker.on('online', common.mustCall(async () => {
+  {
+    const handle = await worker.startHeapProfile();
+    JSON.parse(await handle.stop());
+    // Stop again
+    JSON.parse(await handle.stop());
+  }
+
+  {
+    const handle = await worker.startHeapProfile();
+    try {
+      await worker.startHeapProfile();
+    } catch (err) {
+      assert.strictEqual(err.code, 'ERR_HEAP_PROFILE_HAVE_BEEN_STARTED');
+    }
+    JSON.parse(await handle.stop());
+  }
+
+  worker.terminate();
+}));
+
+worker.once('exit', common.mustCall(async () => {
+  await assert.rejects(worker.startHeapProfile(), {
+    code: 'ERR_WORKER_NOT_RUNNING'
+  });
+}));
diff --git a/test/sequential/test-async-wrap-getasyncid.js b/test/sequential/test-async-wrap-getasyncid.js
index 7f4acbf966c76f..5db4a77631582c 100644
--- a/test/sequential/test-async-wrap-getasyncid.js
+++ b/test/sequential/test-async-wrap-getasyncid.js
@@ -65,6 +65,7 @@ const { getSystemErrorName } = require('util');
     delete providers.WORKERHEAPSTATISTICS;
     delete providers.WORKERCPUUSAGE;
     delete providers.WORKERCPUPROFILE;
+    delete providers.WORKERHEAPPROFILE;
     delete providers.BLOBREADER;
     delete providers.RANDOMPRIMEREQUEST;
     delete providers.CHECKPRIMEREQUEST;
diff --git a/tools/doc/type-parser.mjs b/tools/doc/type-parser.mjs
index 5ddd1992125760..65a076556d026a 100644
--- a/tools/doc/type-parser.mjs
+++ b/tools/doc/type-parser.mjs
@@ -348,6 +348,7 @@ const customTypesMap = {
   'LockManager': 'worker_threads.html#class-lockmanager',
   'LockManagerSnapshot': 'https://developer.mozilla.org/en-US/docs/Web/API/LockManagerSnapshot',
   'CPUProfileHandle': 'v8.html#class-cpuprofilehandle',
+  'HeapProfileHandle': 'v8.html#class-heapprofilehandle',
 };
 
 const arrayPart = /(?:\[])+$/;
diff --git a/typings/internalBinding/worker.d.ts b/typings/internalBinding/worker.d.ts
index 6f894df16c98f2..e98cd62b21f868 100644
--- a/typings/internalBinding/worker.d.ts
+++ b/typings/internalBinding/worker.d.ts
@@ -18,6 +18,7 @@ declare namespace InternalWorkerBinding {
     getHeapStatistics(): Promise<object>;
     cpuUsage(): Promise<object>;
     startCpuProfile(): Promise<CPUProfileHandle>;
+    startHeapProfile(): Promise<HeapProfileHandle>;
     loopIdleTime(): number;
     loopStartTime(): number;
   }
@@ -28,6 +29,11 @@ export interface CPUProfileHandle {
   [Symbol.asyncDispose](): Promise<void>;
 }
 
+export interface HeapProfileHandle {
+  stop(): Promise<string>;
+  [Symbol.asyncDispose](): Promise<void>;
+}
+
 export interface WorkerBinding {
   Worker: typeof InternalWorkerBinding.Worker;
   getEnvMessagePort(): InternalMessagingBinding.MessagePort;