test: add heap profile labels tests

JS tests:
- test-v8-heap-profile-labels: basic labeling, multi-key, JSON round-trip,
  GC retention/removal, includeCollectedObjects flag
- test-v8-heap-profile-labels-async: await boundary propagation, concurrent
  contexts, Hapi-style setHeapProfileLabels
- test-v8-heap-profile-external: Buffer/ArrayBuffer per-label externalBytes
  tracking, GC cleanup, unlabeled isolation

C++ cctests:
- Node.js-level label registration, callback integration, cleanup

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

Author: rudolf

test/cctest/test_heap_profile_labels.cc

@@ -0,0 +1,370 @@
+// Copyright Joyent, Inc. and other Node contributors.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a
+// copy of this software and associated documentation files (the
+// "Software"), to deal in the Software without restriction, including
+// without limitation the rights to use, copy, modify, merge, publish,
+// distribute, sublicense, and/or sell copies of the Software, and to permit
+// persons to whom the Software is furnished to do so, subject to the
+// following conditions:
+//
+// The above copyright notice and this permission notice shall be included
+// in all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+// OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+// MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
+// NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+// DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+// OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+// USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+// Tests for V8 HeapProfileSampleLabelsCallback API.
+// Validates the label callback feature at the V8 public API level.
+
+#include <memory>
+#include <string>
+#include <utility>
+#include <vector>
+
+#include "gtest/gtest.h"
+#include "node_test_fixture.h"
+#include "v8-profiler.h"
+#include "v8.h"
+
+#ifdef V8_HEAP_PROFILER_SAMPLE_LABELS
+
+// Helper: a label callback that writes fixed labels via output parameter.
+static bool FixedLabelsCallback(
+    void* data, v8::Local<v8::Value> context,
+    std::vector<std::pair<std::string, std::string>>* out_labels) {
+  auto* labels =
+      static_cast<std::vector<std::pair<std::string, std::string>>*>(data);
+  *out_labels = *labels;
+  return true;
+}
+
+// Helper: a label callback that returns false (no labels).
+static bool EmptyLabelsCallback(
+    void* data, v8::Local<v8::Value> context,
+    std::vector<std::pair<std::string, std::string>>* out_labels) {
+  return false;
+}
+
+// Helper: a label callback that switches labels based on a flag.
+struct MultiLabelState {
+  bool use_second;
+  std::vector<std::pair<std::string, std::string>> first;
+  std::vector<std::pair<std::string, std::string>> second;
+};
+
+static bool MultiLabelsCallback(
+    void* data, v8::Local<v8::Value> context,
+    std::vector<std::pair<std::string, std::string>>* out_labels) {
+  auto* state = static_cast<MultiLabelState*>(data);
+  *out_labels = state->use_second ? state->second : state->first;
+  return true;
+}
+
+class HeapProfileLabelsTest : public NodeTestFixture {};
+
+// Test: register callback, allocate, verify labels on samples.
+TEST_F(HeapProfileLabelsTest, CallbackReturnsLabels) {
+  const v8::HandleScope handle_scope(isolate_);
+  v8::Local<v8::Context> context = v8::Context::New(isolate_);
+  v8::Context::Scope context_scope(context);
+
+  v8::HeapProfiler* heap_profiler = isolate_->GetHeapProfiler();
+
+  std::vector<std::pair<std::string, std::string>> labels = {
+      {"route", "/api/test"}};
+
+  // Set CPED so the callback gets invoked (requires non-empty context).
+  isolate_->SetContinuationPreservedEmbedderData(
+      v8::String::NewFromUtf8Literal(isolate_, "test-context"));
+
+  heap_profiler->SetHeapProfileSampleLabelsCallback(FixedLabelsCallback,
+                                                    &labels);
+
+  heap_profiler->StartSamplingHeapProfiler(256);
+
+  // Allocate enough objects to get samples.
+  for (int i = 0; i < 8 * 1024; ++i) v8::Object::New(isolate_);
+
+  std::unique_ptr<v8::AllocationProfile> profile(
+      heap_profiler->GetAllocationProfile());
+  ASSERT_NE(profile, nullptr);
+
+  bool found_labeled = false;
+  for (const auto& sample : profile->GetSamples()) {
+    if (!sample.labels.empty()) {
+      EXPECT_EQ(sample.labels.size(), 1u);
+      EXPECT_EQ(sample.labels[0].first, "route");
+      EXPECT_EQ(sample.labels[0].second, "/api/test");
+      found_labeled = true;
+    }
+  }
+  EXPECT_TRUE(found_labeled);
+
+  heap_profiler->StopSamplingHeapProfiler();
+  heap_profiler->SetHeapProfileSampleLabelsCallback(nullptr, nullptr);
+}
+
+// Test: no callback registered — samples have empty labels.
+TEST_F(HeapProfileLabelsTest, NoCallbackEmptyLabels) {
+  const v8::HandleScope handle_scope(isolate_);
+  v8::Local<v8::Context> context = v8::Context::New(isolate_);
+  v8::Context::Scope context_scope(context);
+
+  v8::HeapProfiler* heap_profiler = isolate_->GetHeapProfiler();
+
+  heap_profiler->StartSamplingHeapProfiler(256);
+
+  for (int i = 0; i < 8 * 1024; ++i) v8::Object::New(isolate_);
+
+  std::unique_ptr<v8::AllocationProfile> profile(
+      heap_profiler->GetAllocationProfile());
+  ASSERT_NE(profile, nullptr);
+
+  for (const auto& sample : profile->GetSamples()) {
+    EXPECT_TRUE(sample.labels.empty());
+  }
+
+  heap_profiler->StopSamplingHeapProfiler();
+}
+
+// Test: callback returns empty vector — samples have empty labels.
+TEST_F(HeapProfileLabelsTest, EmptyCallbackEmptyLabels) {
+  const v8::HandleScope handle_scope(isolate_);
+  v8::Local<v8::Context> context = v8::Context::New(isolate_);
+  v8::Context::Scope context_scope(context);
+
+  v8::HeapProfiler* heap_profiler = isolate_->GetHeapProfiler();
+
+  // Set CPED so callback is invoked.
+  isolate_->SetContinuationPreservedEmbedderData(
+      v8::String::NewFromUtf8Literal(isolate_, "test-context"));
+
+  heap_profiler->SetHeapProfileSampleLabelsCallback(EmptyLabelsCallback,
+                                                    nullptr);
+
+  heap_profiler->StartSamplingHeapProfiler(256);
+
+  for (int i = 0; i < 8 * 1024; ++i) v8::Object::New(isolate_);
+
+  std::unique_ptr<v8::AllocationProfile> profile(
+      heap_profiler->GetAllocationProfile());
+  ASSERT_NE(profile, nullptr);
+
+  for (const auto& sample : profile->GetSamples()) {
+    EXPECT_TRUE(sample.labels.empty());
+  }
+
+  heap_profiler->StopSamplingHeapProfiler();
+  heap_profiler->SetHeapProfileSampleLabelsCallback(nullptr, nullptr);
+}
+
+// Test: multiple distinct label sets from callback (simulate different contexts).
+TEST_F(HeapProfileLabelsTest, MultipleDistinctLabels) {
+  const v8::HandleScope handle_scope(isolate_);
+  v8::Local<v8::Context> context = v8::Context::New(isolate_);
+  v8::Context::Scope context_scope(context);
+
+  v8::HeapProfiler* heap_profiler = isolate_->GetHeapProfiler();
+
+  // Set CPED so callback is invoked.
+  isolate_->SetContinuationPreservedEmbedderData(
+      v8::String::NewFromUtf8Literal(isolate_, "test-context"));
+
+  MultiLabelState state;
+  state.use_second = false;
+  state.first = {{"route", "/api/first"}};
+  state.second = {{"route", "/api/second"}};
+
+  heap_profiler->SetHeapProfileSampleLabelsCallback(MultiLabelsCallback,
+                                                    &state);
+
+  heap_profiler->StartSamplingHeapProfiler(256);
+
+  // Allocate with first label set.
+  for (int i = 0; i < 4 * 1024; ++i) v8::Object::New(isolate_);
+
+  // Switch to second label set.
+  state.use_second = true;
+
+  // Allocate with second label set.
+  for (int i = 0; i < 4 * 1024; ++i) v8::Object::New(isolate_);
+
+  std::unique_ptr<v8::AllocationProfile> profile(
+      heap_profiler->GetAllocationProfile());
+  ASSERT_NE(profile, nullptr);
+
+  bool found_first = false;
+  bool found_second = false;
+  for (const auto& sample : profile->GetSamples()) {
+    if (!sample.labels.empty()) {
+      EXPECT_EQ(sample.labels.size(), 1u);
+      EXPECT_EQ(sample.labels[0].first, "route");
+      if (sample.labels[0].second == "/api/first") found_first = true;
+      if (sample.labels[0].second == "/api/second") found_second = true;
+    }
+  }
+  EXPECT_TRUE(found_first);
+  EXPECT_TRUE(found_second);
+
+  heap_profiler->StopSamplingHeapProfiler();
+  heap_profiler->SetHeapProfileSampleLabelsCallback(nullptr, nullptr);
+}
+
+// Test: labels survive GC when kSamplingIncludeObjectsCollectedByMajorGC enabled.
+TEST_F(HeapProfileLabelsTest, LabelsSurviveGCWithRetainFlags) {
+  const v8::HandleScope handle_scope(isolate_);
+  v8::Local<v8::Context> context = v8::Context::New(isolate_);
+  v8::Context::Scope context_scope(context);
+
+  v8::HeapProfiler* heap_profiler = isolate_->GetHeapProfiler();
+
+  // Set CPED so callback is invoked.
+  isolate_->SetContinuationPreservedEmbedderData(
+      v8::String::NewFromUtf8Literal(isolate_, "test-context"));
+
+  std::vector<std::pair<std::string, std::string>> labels = {
+      {"route", "/api/gc-test"}};
+  heap_profiler->SetHeapProfileSampleLabelsCallback(FixedLabelsCallback,
+                                                    &labels);
+
+  // Start with GC retain flags — GC'd samples should survive.
+  heap_profiler->StartSamplingHeapProfiler(
+      256, 128,
+      static_cast<v8::HeapProfiler::SamplingFlags>(
+          v8::HeapProfiler::kSamplingIncludeObjectsCollectedByMajorGC |
+          v8::HeapProfiler::kSamplingIncludeObjectsCollectedByMinorGC));
+
+  // Allocate short-lived objects via JS (no reference retained).
+  v8::Local<v8::String> source =
+      v8::String::NewFromUtf8Literal(isolate_,
+          "for (var i = 0; i < 4096; i++) { new Array(64); }");
+  v8::Local<v8::Script> script =
+      v8::Script::Compile(context, source).ToLocalChecked();
+  script->Run(context).ToLocalChecked();
+
+  // Force GC to collect the short-lived objects.
+  v8::V8::SetFlagsFromString("--expose-gc");
+  isolate_->RequestGarbageCollectionForTesting(
+      v8::Isolate::kFullGarbageCollection);
+
+  std::unique_ptr<v8::AllocationProfile> profile(
+      heap_profiler->GetAllocationProfile());
+  ASSERT_NE(profile, nullptr);
+
+  // With GC retain flags, samples for collected objects should still exist
+  // with their labels intact.
+  bool found_labeled = false;
+  for (const auto& sample : profile->GetSamples()) {
+    if (!sample.labels.empty()) {
+      EXPECT_EQ(sample.labels[0].first, "route");
+      EXPECT_EQ(sample.labels[0].second, "/api/gc-test");
+      found_labeled = true;
+    }
+  }
+  EXPECT_TRUE(found_labeled);
+
+  heap_profiler->StopSamplingHeapProfiler();
+  heap_profiler->SetHeapProfileSampleLabelsCallback(nullptr, nullptr);
+}
+
+// Test: labels removed with samples when GC flags disabled and objects collected.
+TEST_F(HeapProfileLabelsTest, SamplesRemovedByGCWithoutFlags) {
+  const v8::HandleScope handle_scope(isolate_);
+  v8::Local<v8::Context> context = v8::Context::New(isolate_);
+  v8::Context::Scope context_scope(context);
+
+  v8::HeapProfiler* heap_profiler = isolate_->GetHeapProfiler();
+
+  // Set CPED so callback is invoked.
+  isolate_->SetContinuationPreservedEmbedderData(
+      v8::String::NewFromUtf8Literal(isolate_, "test-context"));
+
+  std::vector<std::pair<std::string, std::string>> labels = {
+      {"route", "/api/gc-remove"}};
+  heap_profiler->SetHeapProfileSampleLabelsCallback(FixedLabelsCallback,
+                                                    &labels);
+
+  // Start WITHOUT GC retain flags — GC'd samples should be removed.
+  heap_profiler->StartSamplingHeapProfiler(256);
+
+  // Allocate short-lived objects via JS (no reference retained).
+  v8::Local<v8::String> source =
+      v8::String::NewFromUtf8Literal(isolate_,
+          "for (var i = 0; i < 4096; i++) { new Array(64); }");
+  v8::Local<v8::Script> script =
+      v8::Script::Compile(context, source).ToLocalChecked();
+  script->Run(context).ToLocalChecked();
+
+  // Force GC to collect the short-lived objects.
+  v8::V8::SetFlagsFromString("--expose-gc");
+  isolate_->RequestGarbageCollectionForTesting(
+      v8::Isolate::kFullGarbageCollection);
+
+  std::unique_ptr<v8::AllocationProfile> profile(
+      heap_profiler->GetAllocationProfile());
+  ASSERT_NE(profile, nullptr);
+
+  // Without GC retain flags, samples for collected objects should be removed.
+  // The profile should still be valid (no crash).
+  EXPECT_NE(profile->GetRootNode(), nullptr);
+
+  heap_profiler->StopSamplingHeapProfiler();
+  heap_profiler->SetHeapProfileSampleLabelsCallback(nullptr, nullptr);
+}
+
+// Test: unregister callback (pass nullptr) — subsequent samples have no labels.
+TEST_F(HeapProfileLabelsTest, UnregisterCallbackStopsLabels) {
+  const v8::HandleScope handle_scope(isolate_);
+  v8::Local<v8::Context> context = v8::Context::New(isolate_);
+  v8::Context::Scope context_scope(context);
+
+  v8::HeapProfiler* heap_profiler = isolate_->GetHeapProfiler();
+
+  // Set CPED so callback is invoked.
+  isolate_->SetContinuationPreservedEmbedderData(
+      v8::String::NewFromUtf8Literal(isolate_, "test-context"));
+
+  std::vector<std::pair<std::string, std::string>> labels = {
+      {"route", "/api/before-unregister"}};
+  heap_profiler->SetHeapProfileSampleLabelsCallback(FixedLabelsCallback,
+                                                    &labels);
+
+  heap_profiler->StartSamplingHeapProfiler(256);
+
+  // Allocate with callback active.
+  for (int i = 0; i < 4 * 1024; ++i) v8::Object::New(isolate_);
+
+  // Unregister callback (pass nullptr).
+  heap_profiler->SetHeapProfileSampleLabelsCallback(nullptr, nullptr);
+
+  // Allocate more — these should have no labels.
+  for (int i = 0; i < 4 * 1024; ++i) v8::Object::New(isolate_);
+
+  std::unique_ptr<v8::AllocationProfile> profile(
+      heap_profiler->GetAllocationProfile());
+  ASSERT_NE(profile, nullptr);
+
+  // Should have some labeled samples (from before unregister) and some
+  // unlabeled (from after).
+  bool found_labeled = false;
+  bool found_unlabeled = false;
+  for (const auto& sample : profile->GetSamples()) {
+    if (!sample.labels.empty()) {
+      found_labeled = true;
+    } else {
+      found_unlabeled = true;
+    }
+  }
+  EXPECT_TRUE(found_labeled);
+  EXPECT_TRUE(found_unlabeled);
+
+  heap_profiler->StopSamplingHeapProfiler();
+}
+
+#endif  // V8_HEAP_PROFILER_SAMPLE_LABELS