Self Identifying JavaScript/Hermes Source Maps (Debug IDs)

[krystofwoldrich]

At Sentry, we handle a significant number of React Native stack traces, which require access to source maps. Therefore our users need to upload their source map to our server, so we can provide them with a symbolicated stack trace. But how do we know which source map is the correct one? How does the user know?

Current state

Currently, there is no way of identifying a source map and linking it to a generated bundle. This is an issue also on the web, if interested you can read https://sentry.engineering/blog/the-case-for-debug-ids with more details on the proposed Debug IDs.

The only way of knowing a generated bundle and source maps belong together is to pack them together when a release of an app is created. This doesn't always work as a developer might have source maps disabled or lose the source map file of the released app.

Before writing this post we briefly discussed this with @tmikov who suggested Hermes Epilog as a possible carrier of the debugId identifying the bundle and its source map.

For me and anyone else not familiar with it, Hermes Epilog is content appended to the Hermes Bundle after the Hermes Bytecode. I believe the preferred variant is a plain text JSON object.

Future

Although we are in the Hermes repository, this definitely involves React Native, to my knowledge hermesc doesn't create Hermes Epilog thus it must be appended to the bundle file afterward in the process of creating React Native app.

The next steps describe the whole process of creating the final Hermes bundle including Metro to paint a complete picture of the possible use of Debug IDs in React Native.

Example

1. Metro generates plain text js bundle and its source map.

The Bundle has //# debugId=DEBUG_ID at the end of the file.
The Source map has a new debugId attribute that holds the Debug ID.
RN provides API to retrieve the Debug ID in runtime. Can be filled at the beginning of the bundle into a global variable by Metro. For multiple bundles map (stack trace to debug id) should be injected. Example Metro Serializer Virtual Debug ID module https://github.com/getsentry/sentry-react-native/pull/3164/files#diff-440358ee49d94fb2d6ea2ce7df3c96f0e10de487e8ed35e15ad937af85061fddR19-R34

// This is non minified version the debug id injection snippet used in the Metro plugin.
var _debugIds;
var _debugIdIdentifier;

if (typeof _debugIds === "undefined") {
  _debugIds = {};
}

var _hermesEpilog = Hermes.getEpilog(); // pseudocode this function does not exist
if (_hermesEpilog.debugId) {
  _debugIdIdentifier = _hermesEpilog.debugId;
}

try {
  var stack = new Error().stack;
  if (stack) {
    if (_debugIdIdentifier) {
      _debugIds[stack] = _debugIdIdentifier;
    } else {
      _debugIds[stack] = '__DEBUG_ID__';
      _debugIdIdentifier = 'dbid-__DEBUG_ID__';
    }
  }
} catch (e) {
  /**/
}

2. hermesc generates a Hermes bytecode bundle and source map.
3. combine-source-map.js combines Metro and Hermes source maps.
4. NEW STEP Add Hermes Epilog { "debugId": "HERMES_BUNDLE_FILE_HASH" } and remove plain js debug id from the combined source map if present and add "debugId": "HERMES_BUNDLE_FILE_HASH".

Use in runtime

Currently, Hermes offers API to read the Epilog in runtime in Java and C++. Ideally, the Debug ID can be read directly in JS right at the start before any polyfills and RN are loaded. This is important as the Debug ID will be reported with a captured error therefore must be available when the error happens.

HermesInternal.getEpilog();
// { debugId: "hermes_bundle_file_debug_id" }

Current API

Requires to load Hermes Bytecode bundle manually then it extracts the epilog.

hermes/API/hermes/hermes.h

Lines 66 to 71 in 7af9729

	// Assuming that \p data is valid HBC bytecode data, returns a pointer to the
	// first element of the epilogue, data append to the end of the bytecode
	// stream. Return pair contain ptr to data and header.
	static std::pair<const uint8_t *, size_t> getBytecodeEpilogue(
	const uint8_t *data,
	size_t len);

Discussion

We are happy to hear if this solves issues for you too.

• Do you as RN users find this useful?
• Do you see any shortcomings both conceptual and implementation?
• To read the Hermes Epilog is it necessary to read the Hermes bundle or is it present somewhere in the runtime, so it doesn’t have to be read again?
• Could HermesInternal.getEpilog(); be added to Hermes?

Do you have any other comments? Please, share them under this post.

[tmikov]

Thank you for the detailed write up! After giving it some thought, I see two significant complications for a potential JS API exported in HermesInternal:

1. There could be multiple bundles loaded in the VM at the same time. How would HermesInternal.getEpilogue() know which one to use? I was thinking that it might try walking the runtime stack and use the first one it encounters, but that starts to get a bit iffy, especially if the call is wrapped in a library, which is in one bundle.
2. Even when we get to the bundle, the epilogue is technically not part of it. getEpilogueFromBytecode() expects someone external with knowledge of the size of the entire file to give it the information, then it simply subtracts the size of the bundle encoded in the header. Even if we could find the bundle in 1), we wouldn't know how large the epilogue is.

This is just the opening of the discussion, I don't have any final opinions yet.

[krystofwoldrich]

Hi, thank you for the answer, I've been thinking about the most common RN use case too much, thus focusing only on one bundle.

I've been exploring the Hermes source code a bit more and I've found BytecodeFileFooter. From the struct description, the footer contains a hash of the file above it, that's a perfect Debug ID.

hermes/include/hermes/BCGen/HBC/BytecodeFileFormat.h

Lines 151 to 164 in 6d04fa1

	/**
	* Footer of binary file. Used for summary information that is *not*
	* read during normal execution (since that would hurt locality).
	*/
	struct BytecodeFileFooter {
	uint8_t fileHash[SHA1_NUM_BYTES]; // Hash of everything above the footer.
	// NOTE: If we ever add any non-byte fields, we need to ensure alignment
	// everywhere this struct is written.
	BytecodeFileFooter(const SHA1 &fileHash) {
	std::copy(fileHash.begin(), fileHash.end(), this->fileHash);
	}
	};

I suppose, there is the same issue as with the Epilog, the footer is not read by the Hermes VM. And to read it someone with knowledge of the bundle file is needed. Considering this it seems to me like a function that could live in ReactContext in RN for example.

Based on your second point, does Hermes VM keep any information about the loaded bundles? Something from their header?

[tmikov]

@krystofwoldrich BytecodeFileFooter is part of the bytecode file and could be exposed. We don't want to access it unnecessarily due to locality (don't want to load the end of the bundle into memory), but if needed it can be accessed.

So, the main problem that remains to be solved is identifying the bundle.

We do keep track of the loaded "bundles" - instances of RuntimeModule. There are usually multiple of them:

• Builtin functionality implemented in JS like Promise
• The main RN bundle
• The results eval() or new Function()

These do get garbage collected when they are not used, but ordinarily there are at least two.

I wonder whether it makes sense to expose an API that simply returns a list of the hashes of all loaded bundles where that hash is non-zero. We can ensure that eval() , new Function() and the builtin functionality have zero hashes. So, you will get a list of hashes of the RN bundles.