src: add GetBuildId helper function

[santigimeno]

To allow us to read the Build-Id from ELF headers in a specific binary.

Summary by CodeRabbit

• Chores

  • Updated Linux build configuration to include ELF utilities and link required libraries, with no impact on other platforms.
  • Refined linker behavior on Linux and OpenHarmony to improve compatibility.

• Tests

  • Added a Linux-only integration test that validates build ID retrieval via a native addon.
  • Introduced a supporting test addon to exercise the new Linux functionality.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Walkthrough

Adds Linux-only ELF build-id utilities (source and header), updates build configs to include them and adjust Linux/OpenHarmony linker flags, and introduces a Linux-specific test addon and test script that validates build-id retrieval from the Node executable using libelf.

Changes

Cohort / File(s)	Summary
Build configuration (Linux/OpenHarmony linking) node.gypi	Split Linux and OpenHarmony linker rules. Linux now links -lelf and conditionally -lrt based on nsolid_use_librt; OpenHarmony continues excluding -lrt.
nsolid Linux sources inclusion node.gyp	Adds Linux-specific sources to nsolid_sources: src/nsolid/nsolid_elf_utils.cc, src/nsolid/nsolid_elf_utils.h.
ELF build-id utility (implementation and API) src/nsolid/nsolid_elf_utils.cc, src/nsolid/nsolid_elf_utils.h	Introduces node::nsolid::elf_utils::GetBuildId(path, build_id) with in-process caching; parses .note.gnu.build-id via libelf and returns hex build-id or error. Header gated by NODE_WANT_INTERNALS.
Test addon and test script (Linux-only) test/addons/nsolid-elf-utils/binding.cc, test/addons/nsolid-elf-utils/binding.gyp, test/addons/nsolid-elf-utils/nsolid-elf-utils.js	Adds addon exposing getBuildId(path) and a test comparing its output to readelf -n on process.execPath. Build defines NODE_WANT_INTERNALS=1.

Sequence Diagram(s)

sequenceDiagram
  participant TestJS as Test (nsolid-elf-utils.js)
  participant Addon as Native Addon (binding.cc)
  participant Utils as elf_utils::GetBuildId
  participant LibELF as libelf
  TestJS->>Addon: getBuildId(process.execPath)
  Addon->>Utils: GetBuildId(path, &build_id)
  Utils->>LibELF: elf_version/elf_begin/iterate sections
  LibELF-->>Utils: .note.gnu.build-id data
  Utils-->>Addon: build_id (hex) or error
  Addon-->>TestJS: build_id string (on success)
  TestJS->>TestJS: assert equals readelf-derived ID

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

I nosed through notes in ELF-lit night,
Found a build-id shining bright.
With lil’ paws tapping C++ keys,
I cached the string with whiskered ease.
Tests hopped green—what a sight!
Carrot commits? Approved outright. 🥕✨

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (3)

src/nsolid/nsolid_elf_utils.h (1)

12-12: Consider documenting the return value semantics.

The function returns an int status code, but the expected values (0 for success, non-zero for failure) should be documented for API clarity.

Add a brief comment documenting the return value:

 namespace elf_utils {
+  // Returns 0 on success, non-zero on failure.
   int GetBuildId(const std::string& path, std::string* build_id);
 }  // namespace elf_utils

test/addons/nsolid-elf-utils/binding.cc (1)

14-29: Consider returning an error instead of undefined when GetBuildId fails.

When GetBuildId returns a non-zero error code, the function currently returns undefined by not setting any return value. This makes it difficult for JavaScript code to distinguish between different error conditions (file not found, invalid ELF, no build-id, etc.).

Consider throwing a JavaScript exception with the error code to provide better error context:

 static void GetBuildId(const FunctionCallbackInfo<Value>& args) {
 #if defined(__linux__)
   Isolate* isolate = args.GetIsolate();
   assert(args[0]->IsString());
   v8::String::Utf8Value path_utf8(isolate, args[0]);
   std::string path(*path_utf8, path_utf8.length());
   std::string build_id;
   int res = node::nsolid::elf_utils::GetBuildId(path, &build_id);
   if (res != 0) {
-    return;
+    std::string error_msg = "Failed to get build-id: error code " + std::to_string(res);
+    isolate->ThrowException(v8::Exception::Error(
+        String::NewFromUtf8(isolate, error_msg.c_str()).ToLocalChecked()));
+    return;
   }
 
   args.GetReturnValue().Set(
     String::NewFromUtf8(isolate, build_id.c_str()).ToLocalChecked());
 #endif
 }

src/nsolid/nsolid_elf_utils.cc (1)

29-35: Consider returning more specific error codes.

The function returns elf_errno() when elf_version(EV_CURRENT) fails. While this is technically correct, elf_errno() might return 0 if no error was previously set, which could be confusing.

Consider returning a more specific error code or ensuring elf_errno() is non-zero:

   ret = 0;
   if (elf_version(EV_CURRENT) == EV_NONE) {
-    return elf_errno();
+    int err = elf_errno();
+    return err ? err : ELF_E_VERSION;
   }

📜 Review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between cd19746 and a6d9f60.

📒 Files selected for processing (7)

• node.gyp (1 hunks)
• node.gypi (1 hunks)
• src/nsolid/nsolid_elf_utils.cc (1 hunks)
• src/nsolid/nsolid_elf_utils.h (1 hunks)
• test/addons/nsolid-elf-utils/binding.cc (1 hunks)
• test/addons/nsolid-elf-utils/binding.gyp (1 hunks)
• test/addons/nsolid-elf-utils/nsolid-elf-utils.js (1 hunks)

🧰 Additional context used

🧠 Learnings (5)

📓 Common learnings

Learnt from: santigimeno
PR: nodesource/nsolid#339
File: src/nsolid/nsolid_elf_utils.cc:18-18
Timestamp: 2025-07-08T16:05:45.341Z
Learning: In the NSolid project, the `GetBuildId` function in `src/nsolid/nsolid_elf_utils.cc` is designed to be called only from the NSolid thread, so the static cache doesn't require thread safety mechanisms like mutex protection.

📚 Learning: 2025-07-08T16:05:45.341Z

Learnt from: santigimeno
PR: nodesource/nsolid#339
File: src/nsolid/nsolid_elf_utils.cc:18-18
Timestamp: 2025-07-08T16:05:45.341Z
Learning: In the NSolid project, the `GetBuildId` function in `src/nsolid/nsolid_elf_utils.cc` is designed to be called only from the NSolid thread, so the static cache doesn't require thread safety mechanisms like mutex protection.

Applied to files:

• src/nsolid/nsolid_elf_utils.h
• test/addons/nsolid-elf-utils/nsolid-elf-utils.js
• src/nsolid/nsolid_elf_utils.cc
• test/addons/nsolid-elf-utils/binding.cc

📚 Learning: 2025-07-08T14:48:04.827Z

Learnt from: santigimeno
PR: nodesource/nsolid#339
File: test/addons/nsolid-elf-utils/binding.cc:13-28
Timestamp: 2025-07-08T14:48:04.827Z
Learning: In nsolid test native addons (e.g., `test/addons/*/binding.cc`), additional JavaScript-facing argument validation is typically omitted because the tests supply well-formed inputs.

Applied to files:

• test/addons/nsolid-elf-utils/binding.gyp
• test/addons/nsolid-elf-utils/nsolid-elf-utils.js
• test/addons/nsolid-elf-utils/binding.cc

📚 Learning: 2025-07-08T14:46:47.806Z

Learnt from: santigimeno
PR: nodesource/nsolid#339
File: test/addons/nsolid-elf-utils/nsolid-elf-utils.js:13-14
Timestamp: 2025-07-08T14:46:47.806Z
Learning: In the nsolid test suite, native addon bindings are expected to be built beforehand; tests do not add fs.existsSync guards to skip when bindings are missing.

Applied to files:

• test/addons/nsolid-elf-utils/binding.gyp
• test/addons/nsolid-elf-utils/nsolid-elf-utils.js
• test/addons/nsolid-elf-utils/binding.cc

📚 Learning: 2025-07-08T14:47:34.724Z

Learnt from: santigimeno
PR: nodesource/nsolid#339
File: test/addons/nsolid-elf-utils/nsolid-elf-utils.js:16-18
Timestamp: 2025-07-08T14:47:34.724Z
Learning: In the nsolid test suite, external tool invocations (e.g., execSync to run `readelf`) are intentionally left uncaught so that any failure causes the test to fail rather than being skipped.

Applied to files:

• test/addons/nsolid-elf-utils/nsolid-elf-utils.js

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (7)

• GitHub Check: build-tarball
• GitHub Check: lint-js-and-md
• GitHub Check: coverage-windows
• GitHub Check: test-macOS
• GitHub Check: build-docs
• GitHub Check: test-linux (ubuntu-24.04-arm)
• GitHub Check: test-linux (ubuntu-24.04)

🔇 Additional comments (13)

node.gypi (1)

553-565: LGTM! Cleaner separation of linker rules for OpenHarmony and Linux.

The refactoring properly splits the combined condition into two OS-specific blocks, making the linker configuration more maintainable and explicit for each platform. The Linux block now unconditionally links -lelf (required for the new ELF utilities) and conditionally handles -lrt based on nsolid_use_librt.

test/addons/nsolid-elf-utils/binding.gyp (1)

1-10: LGTM! Properly configured test addon target.

The binding target is correctly configured with the necessary NODE_WANT_INTERNALS=1 define to access the internal ELF utilities API, and properly includes the common build settings.

node.gyp (1)

581-586: LGTM! Correct Linux-specific inclusion of ELF utilities.

The conditional addition of ELF utility sources to nsolid_sources on Linux is properly implemented, aligning with the platform-specific nature of the Build-Id functionality.

test/addons/nsolid-elf-utils/nsolid-elf-utils.js (4)

1-11: LGTM! Proper platform check and early exit.

The platform check correctly skips the test on non-Linux systems with an informative message.

---

13-14: LGTM! Consistent with nsolid test suite conventions.

The binding loading follows the established pattern without fs.existsSync guards, as per the team's conventions documented in the learnings.

---

20-23: LGTM! Clear test assertion with helpful error message.

The test correctly validates the Build ID and provides a descriptive error message on mismatch, which aids in debugging.

---

16-18: Add a clear fallback when readelf is missing

To prevent cryptic ENOENT failures in CI environments where readelf isn’t installed, wrap the execSync invocation in a try/catch and emit a descriptive error (or provide alternate logic) if readelf isn’t found:

• File: test/addons/nsolid-elf-utils/nsolid-elf-utils.js
• Lines: 16–18

Suggested update:

let expected;
try {
  expected = execSync(
    `readelf -n ${process.execPath} | awk '/Build ID/ { print $3 }'`,
    { encoding: 'utf8' }
  ).trim();
} catch (err) {
  if (err.code === 'ENOENT') {
    throw new Error(
      'The `readelf` tool is required to run this test but was not found in your PATH.'
    );
  }
  throw err;
}

This ensures that missing dependencies produce a clear, actionable error.

⛔ Skipped due to learnings

Learnt from: santigimeno
PR: nodesource/nsolid#339
File: test/addons/nsolid-elf-utils/nsolid-elf-utils.js:16-18
Timestamp: 2025-07-08T14:47:34.724Z
Learning: In the nsolid test suite, external tool invocations (e.g., execSync to run `readelf`) are intentionally left uncaught so that any failure causes the test to fail rather than being skipped.

Learnt from: santigimeno
PR: nodesource/nsolid#339
File: test/addons/nsolid-elf-utils/nsolid-elf-utils.js:13-14
Timestamp: 2025-07-08T14:46:47.806Z
Learning: In the nsolid test suite, native addon bindings are expected to be built beforehand; tests do not add fs.existsSync guards to skip when bindings are missing.

src/nsolid/nsolid_elf_utils.h (1)

1-19: LGTM! Well-structured header with proper guards.

The header is properly organized with:

• Standard include guards
• NODE_WANT_INTERNALS conditional compilation
• Clear namespace hierarchy
• Clean API declaration

test/addons/nsolid-elf-utils/binding.cc (2)

1-7: LGTM!

The header includes and platform-specific guard are properly structured.

---

31-33: LGTM!

Module initialization correctly exports the function.

src/nsolid/nsolid_elf_utils.cc (3)

1-15: LGTM!

Headers are properly included and namespaces are correctly structured.

---

17-28: Thread safety consideration for the static cache.

Based on the retrieved learnings, the GetBuildId function is designed to be called only from the NSolid thread, so the static cache doesn't require thread safety mechanisms. This design constraint is valid for the current implementation.

---

85-90: Resource cleanup order looks correct.

The cleanup sequence properly handles both the ELF object and file descriptor in the correct order, ensuring resources are freed even on error paths.

[coderabbitai]

⚠️ Potential issue

Potential buffer overflow risk in ELF note parsing.

The code assumes the ELF note structure without validating that the computed offsets don't exceed the buffer bounds. While data->d_size >= 16 checks for minimum size, it doesn't ensure that name_end + descsz doesn't exceed data->d_size.

Add bounds checking before accessing the build-id data:

   *build_id = std::string("");
   while ((scn = elf_nextscn(e, scn)) != nullptr) {
     if (gelf_getshdr(scn, &shdr) != &shdr) {
       ret = elf_errno();
       goto end_error;
     }
 
     char* name = elf_strptr(e, shstrndx, shdr.sh_name);
     if (name && strcmp(name, ".note.gnu.build-id") == 0) {
       Elf_Data* data = elf_getdata(scn, nullptr);
       if (data && data->d_size >= 16) {
         // ELF Note header: namesz(4), descsz(4), type(4) + name padding
         // Compute offset to build-id properly
         uint32_t* note = reinterpret_cast<uint32_t*>(data->d_buf);
         uint32_t namesz = note[0];
         uint32_t descsz = note[1];
         // Name starts at offset 12
         // Descriptor (build-id) starts at next aligned offset
         size_t name_end = 12 + ((namesz + 3) & ~3);
+        // Ensure we don't read beyond the buffer
+        if (name_end + descsz > data->d_size) {
+          ret = ELF_E_DATA;
+          goto end_error;
+        }
         uint8_t* id = reinterpret_cast<uint8_t*>(data->d_buf) + name_end;
         *build_id = utils::buffer_to_hex(id, descsz);
         break;
       }
     }
   }

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	*build_id = std::string("");
	while ((scn = elf_nextscn(e, scn)) != nullptr) {
	if (gelf_getshdr(scn, &shdr) != &shdr) {
	ret = elf_errno();
	goto end_error;
	}
	char* name = elf_strptr(e, shstrndx, shdr.sh_name);
	if (name && strcmp(name, ".note.gnu.build-id") == 0) {
	Elf_Data* data = elf_getdata(scn, nullptr);
	if (data && data->d_size >= 16) {
	// ELF Note header: namesz(4), descsz(4), type(4) + name padding
	// Compute offset to build-id properly
	uint32_t* note = reinterpret_cast<uint32_t*>(data->d_buf);
	uint32_t namesz = note[0];
	uint32_t descsz = note[1];
	// Name starts at offset 12
	// Descriptor (build-id) starts at next aligned offset
	size_t name_end = 12 + ((namesz + 3) & ~3);
	uint8_t* id = reinterpret_cast<uint8_t*>(data->d_buf) + name_end;
	*build_id = utils::buffer_to_hex(id, descsz);
	break;
	}
	}
	}
	*build_id = std::string("");
	while ((scn = elf_nextscn(e, scn)) != nullptr) {
	if (gelf_getshdr(scn, &shdr) != &shdr) {
	ret = elf_errno();
	goto end_error;
	}
	char* name = elf_strptr(e, shstrndx, shdr.sh_name);
	if (name && strcmp(name, ".note.gnu.build-id") == 0) {
	Elf_Data* data = elf_getdata(scn, nullptr);
	if (data && data->d_size >= 16) {
	// ELF Note header: namesz(4), descsz(4), type(4) + name padding
	// Compute offset to build-id properly
	uint32_t* note = reinterpret_cast<uint32_t*>(data->d_buf);
	uint32_t namesz = note[0];
	uint32_t descsz = note[1];
	// Name starts at offset 12
	// Descriptor (build-id) starts at next aligned offset
	size_t name_end = 12 + ((namesz + 3) & ~3);
	// Ensure we don't read beyond the buffer
	if (name_end + descsz > data->d_size) {
	ret = ELF_E_DATA;
	goto end_error;
	}
	uint8_t* id = reinterpret_cast<uint8_t*>(data->d_buf) + name_end;
	*build_id = utils::buffer_to_hex(id, descsz);
	break;
	}
	}
	}

🤖 Prompt for AI Agents

In src/nsolid/nsolid_elf_utils.cc around lines 53 to 77, the ELF note parsing
computes name_end and then reads descsz bytes without verifying the computed
offsets fit inside data->d_size; add explicit bounds checks before accessing the
build-id: validate data and data->d_buf are non-null, cast namesz and descsz to
size_t and check namesz/descsz are reasonable (e.g. not absurdly large), compute
name_end = 12 + ((namesz + 3) & ~3) using size_t and ensure name_end <=
data->d_size and name_end + descsz <= data->d_size (also guard against overflow
when adding), and only then set *build_id from the id pointer; on failure, skip
this note or set an error/continue instead of reading out-of-bounds.