Skip to content

Latest commit

 

History

History
162 lines (128 loc) · 5.7 KB

0085-source-hash-sourcemap-keying.md

File metadata and controls

162 lines (128 loc) · 5.7 KB
Raw
  • Start Date: 2023-04-06
  • RFC Type: feature
  • RFC PR:
  • RFC Status: draft

Summary

This specification proposes the keying / discovering of source maps via the source hashes of the generated JavaScript files. This is an alternative lookup method to the proposed debug ID lookup. It's there to support the CallSite.getScriptHash browser API that Chrome and Edge already ship.

Motivation

We want to make processing / SourceMap-ing of JavaScript stack traces more reliable. Our preferred solution for this involes unique Debug IDs but supporting this requires bundler support as well. On the other hand source hashes for minified files are now possible to support in Chrome and Edge without toolchain changes.

Background

Looking up source maps and minified files by source hash is possible because Chrome and Edge support a callsite script hash lookup. For at least those browsers it would be possible to associate source maps purely by that content hash in recent versions.

The hashes are available via the Error.prepareStackTrace API by invoking the getScriptHash method on a call site object. There is no fallback possible for browsers not supporting script hashes.

The script hashes are documented to be SHA-256.

Implementation

To support this the changes in our pipeline are limited.

Protocol Changes

The sourcemap image type gains an additional key called hashes which holds an object with hashes where each key corresponds to the name of a hash algorithm and the value to the checksum in a format appropriate for that hash. Today only sha256 is specified where the value is a SHA-256 hash in hexadecimal format:

{
  "images": [
    {
      "type": "sourcemap",
      "code_file": "http://example.com/file.min.js",
      "hashes": {
        "sha256": "2d711642b726b04401627ca9fbac32f5c8530fb1903cc4db02258717921a4881"
      }
    }
  ]
}

SDK Changes

On the SDK side we need to capture the content hashes of the referenced frames and build up a map over time. The easiest solution for this is to maintain a growing list of hashes and to rely on Error.prepareStackTrace to capture this:

const scriptHashes = {};
const originalPrepareStackTrace = Error.prepareStackTrace;

// we use `Error.prepareStackTrace` exclusively for capturing the script hashes
// and we rely on `err.stack` parsing for the actual stack trace.  As documented
// getScriptHash() always returns a SHA-256 hash.
Error.prepareStackTrace = (err, callsites) => {
  for (var callsite of callsites) {
    if (!callsite.getScriptHash) {
      const filename = callsite.getFileName();
      if (!scriptHashes[filename]) {
        scriptHashes[filename] = callsite.getScriptHash();
      }
    }
  }
  return originalPrepareStackTrace ? originalPrepareStackTrace(err, callsites) : err.stack;
};

The SDK can then feed the script hashes into the sent image list as specified above.

Toolchain / Source Map Changes

For establishing the mapping from minified JavaScript to the source map, the source map needs to gain a content hash entry. As there is currently no specification for how that mapping is supposed to be established, we would reserve x-sentry-file-hash-sha256 (header) and x_sentry_fileHashSha256 (key):

{
  "file": "foo.min.js",
  "x_sentry_fileHashSha256": "2d711642b726b04401627ca9fbac32f5c8530fb1903cc4db02258717921a4881"
}

Note that they use of the embedded key for now is likely discouraged for the made up header as we do not plan on standardizing the file hashes.

To avoid re-calculating the SHA 256 hashes of the minified files constantly we also want to add them to the manifest. For this we could leverage the digest header, with the small suboptimal situation that the HTTP digest spec uses a base64 hash:

{
  "files/_/_/foo.min.js": {
    "url": "~/foo.min.js",
    "type": "minified_source",
    "headers": {
      "digest": "sha-256=LXEWQrcmsEQBYnyp+6wy9chTD7GQPMTbAiWHF5IaSIE=",
      "sourcemap": "foo.min.map"
    }
  },
  "files/_/_/foo.min.map": {
    "url": "~/foo.min.map",
    "type": "sourcemap",
    "headers": {
      "x-sentry-file-hash-sha256": "2d711642b726b04401627ca9fbac32f5c8530fb1903cc4db02258717921a4881"
    }
  }
}

Upon uploading sentry-cli would establish the associations as today, but in addition it would hash the file contents and add the necessary cross references into the manifest. In this case we can get away without any file rewriting and just associate the hashes with the manifest instead. Like with debug IDs we would require embedding of sources into the source map.

Sentry Mapping

On the Sentry side in addition to indexing by debug_id we add an additional database index to record files indexed by it's SHA-256 content hash. For potential future proofing this table should allow definiting a different hash than SHA-256 in the future.

Drawbacks

A drawback of this solution is that non-code changes in source files will generate files with identical hashes. Non-code changes for instance can be whitespace or, more problematic, comments. The risk of this happening is assumed to be pretty low by the original spec authors.

This also relies on Error.prepareStackTrace being under Sentry's control to capture the script hashes which might not always be possible.

Future Direction

This proposal leverages existing developments in the source map ecosystem and some potential improvements might be added at one point.

Source File Hashes

There is a pending proposal to add a sourcesHash array to the source map to add SHA-256 hashes of source files to the source map which could then be used to access sources.