fix(bundler-plugins): Stamp debug IDs onto emitted source maps when disable-upload is set

Author: msonnb

packages/bundler-plugins/src/core/debug-id-upload.ts

@@ -93,7 +93,7 @@ export async function prepareBundleForDebugIdUpload(
  *
  * The string pattern is injected via the debug ID injection snipped.
  */
-function determineDebugIdFromBundleSource(code: string): string | undefined {
+export function determineDebugIdFromBundleSource(code: string): string | undefined {
   const match = code.match(
     /sentry-dbid-([0-9a-fA-F]{8}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{12})/,
   );
@@ -119,13 +119,135 @@ function addDebugIdToBundleSource(bundleSource: string, debugId: string): string
   }
 }
 
+function setDebugIdOnSourceMap(map: Record<string, unknown>, debugId: string): void {
+  // For now we write both fields until we know what will become the standard - if ever.
+  map['debug_id'] = debugId;
+  map['debugId'] = debugId;
+}
+
+export type StampedArtifacts = {
+  bundleSource: string;
+  sourceMapSource: string;
+};
+
+/**
+ * Stamps the debug ID injected into `bundleSource` into both the bundle (as `//# debugId=` comment)
+ * and its source map (as `debug_id`/`debugId` fields).
+ *
+ * This exists for `sourcemaps.disable: "disable-upload"`: the regular upload path only stamps
+ * temporary copies of the artifacts (see `prepareBundleForDebugIdUpload`), so without this the
+ * emitted artifacts would carry no debug ID and a later manual upload could not match them.
+ * Callers must apply the result inside the bundler's asset pipeline (or, for bundlers without one,
+ * before the build resolves) so that integrity hashes computed by later build steps include it.
+ *
+ * @returns the stamped artifacts, or `undefined` if the bundle carries no debug ID or the map
+ * isn't valid JSON.
+ */
+export function addDebugIdToBundleAndSourceMap(
+  bundleSource: string,
+  sourceMapSource: string,
+): StampedArtifacts | undefined {
+  const debugId = determineDebugIdFromBundleSource(bundleSource);
+  if (debugId === undefined) {
+    return undefined;
+  }
+
+  let map: unknown;
+  try {
+    map = JSON.parse(sourceMapSource);
+  } catch {
+    return undefined;
+  }
+
+  if (!map || typeof map !== 'object') {
+    return undefined;
+  }
+
+  setDebugIdOnSourceMap(map as Record<string, unknown>, debugId);
+
+  return {
+    bundleSource: addDebugIdToBundleSource(bundleSource, debugId),
+    sourceMapSource: JSON.stringify(map),
+  };
+}
+
+/**
+ * Warns about bundles whose source map is inlined into the bundle. Those have no separate map
+ * to stamp, so they can't be symbolicated after a manual upload.
+ */
+export function warnAboutInlineSourceMaps(bundleFileNames: string[], logger: Logger): void {
+  if (bundleFileNames.length === 0) {
+    return;
+  }
+
+  logger.warn(
+    `${bundleFileNames.length} bundle(s) inline their source map, which can't be stamped with a debug ID. Emit source maps as separate files so they can be symbolicated after a manual upload: ${bundleFileNames.join(', ')}`,
+  );
+}
+
+export type EmittedArtifactsStampResult = 'stamped' | 'inline-source-map' | 'skipped';
+
+/**
+ * Stamps the debug ID of an emitted bundle into the bundle and its source map on disk.
+ *
+ * Used by bundlers that offer no hook to modify assets before they are written (esbuild).
+ */
+export async function addDebugIdToEmittedArtifacts(
+  bundleFilePath: string,
+  logger: Logger,
+  resolveSourceMapHook: ResolveSourceMapHook | undefined,
+): Promise<EmittedArtifactsStampResult> {
+  let bundleSource: string;
+  try {
+    bundleSource = await fs.promises.readFile(bundleFilePath, 'utf8');
+  } catch (e) {
+    logger.error(`Could not read bundle to stamp debug ID: ${bundleFilePath}`, e);
+    return 'skipped';
+  }
+
+  const sourceMapPath = await determineSourceMapPathFromBundle(
+    bundleFilePath,
+    bundleSource,
+    logger,
+    resolveSourceMapHook,
+  );
+  if (!sourceMapPath) {
+    return bundleHasInlineSourceMap(bundleSource) ? 'inline-source-map' : 'skipped';
+  }
+
+  let sourceMapSource: string;
+  try {
+    sourceMapSource = await fs.promises.readFile(sourceMapPath, 'utf8');
+  } catch (e) {
+    logger.error(`Could not read source map to stamp debug ID: ${sourceMapPath}`, e);
+    return 'skipped';
+  }
+
+  const stamped = addDebugIdToBundleAndSourceMap(bundleSource, sourceMapSource);
+  if (stamped === undefined) {
+    logger.debug(`Could not stamp debug ID (no debug ID in bundle or invalid source map): ${bundleFilePath}`);
+    return 'skipped';
+  }
+
+  try {
+    await Promise.all([
+      fs.promises.writeFile(sourceMapPath, stamped.sourceMapSource, 'utf8'),
+      fs.promises.writeFile(bundleFilePath, stamped.bundleSource, 'utf8'),
+    ]);
+    return 'stamped';
+  } catch (e) {
+    logger.error(`Could not write debug ID into build artifacts: ${bundleFilePath}`, e);
+    return 'skipped';
+  }
+}
+
 /**
  * Whether the bundle carries its source map inlined as `sourceMappingURL=data:`
  * URI, rather than referencing a separate `.map` file. Such bundles must still
  * be uploaded even when no `.map` file is found, because the source file itself
  * contains the map.
  */
-function bundleHasInlineSourceMap(bundleSource: string): boolean {
+export function bundleHasInlineSourceMap(bundleSource: string): boolean {
   return /^\s*\/\/# sourceMappingURL=data:/m.test(bundleSource);
 }
 
@@ -223,9 +345,7 @@ async function prepareSourceMapForDebugIdUpload(
   let map: Record<string, unknown>;
   try {
     map = JSON.parse(sourceMapFileContent) as { sources: unknown; [key: string]: unknown };
-    // For now we write both fields until we know what will become the standard - if ever.
-    map['debug_id'] = debugId;
-    map['debugId'] = debugId;
+    setDebugIdOnSourceMap(map, debugId);
   } catch {
     logger.error(`Failed to parse source map for debug ID upload: ${sourceMapPath}`);
     return;

packages/bundler-plugins/src/core/index.ts

@@ -147,4 +147,10 @@ export {
   generateModuleMetadataInjectorCode,
 } from './utils';
 export { createSentryBuildPluginManager } from './build-plugin-manager';
-export { createDebugIdUploadFunction } from './debug-id-upload';
+export {
+  createDebugIdUploadFunction,
+  addDebugIdToBundleAndSourceMap,
+  addDebugIdToEmittedArtifacts,
+  bundleHasInlineSourceMap,
+  warnAboutInlineSourceMaps,
+} from './debug-id-upload';

packages/bundler-plugins/src/core/types.ts

@@ -114,8 +114,13 @@ export interface Options {
     /**
      * Disables all functionality related to sourcemaps if set to `true`.
      *
-     * If set to `"disable-upload"`, the plugin will not upload sourcemaps to Sentry, but will inject debug IDs into the build artifacts.
-     * This is useful if you want to manually upload sourcemaps to Sentry at a later point in time.
+     * If set to `"disable-upload"`, the plugin will not upload sourcemaps to Sentry, but will still inject debug IDs
+     * into the build artifacts: the bundles receive the runtime debug ID snippet and a `//# debugId=` comment, and the
+     * emitted source maps receive the matching `debug_id` field. This happens inside the bundler's build pipeline, so
+     * hashes computed by later build steps (e.g. for subresource integrity) include the debug IDs.
+     *
+     * This is useful if you want to manually upload sourcemaps to Sentry at a later point in time, e.g. with
+     * `sentry sourcemap upload`. The artifacts already carry their debug IDs, so no `inject` step is needed.
      *
      * @default false
      */

packages/bundler-plugins/src/esbuild/index.ts

@@ -6,6 +6,9 @@ import {
   getDebugIdSnippet,
   createDebugIdUploadFunction,
   CodeInjection,
+  addDebugIdToEmittedArtifacts,
+  isJsFile,
+  warnAboutInlineSourceMaps,
 } from '../core';
 import * as path from 'node:path';
 import { createRequire } from 'node:module';
@@ -51,6 +54,8 @@ interface EsbuildInitialOptions {
   inject?: string[];
   metafile?: boolean;
   define?: Record<string, string>;
+  write?: boolean;
+  absWorkingDir?: string;
 }
 
 interface EsbuildPluginBuild {
@@ -283,9 +288,33 @@ export function sentryEsbuildPlugin(userOptions: Options = {}): any {
         try {
           await sentryBuildPluginManager.createRelease();
 
-          if (sourcemapsEnabled && options.sourcemaps?.disable !== 'disable-upload') {
+          if (sourcemapsEnabled) {
             const buildArtifacts = result.metafile ? Object.keys(result.metafile.outputs) : [];
-            await upload(buildArtifacts);
+
+            if (options.sourcemaps?.disable !== 'disable-upload') {
+              await upload(buildArtifacts);
+            } else if (initialOptions.write === false) {
+              logger.debug('Build output is not written to disk. Skipping debug ID injection into build artifacts.');
+            } else {
+              // The upload routine (which stamps debug IDs into temp copies of the artifacts) is
+              // skipped with `disable-upload`. esbuild has no hook to modify outputs before they are
+              // written, so the emitted artifacts get stamped on disk instead.
+              const outputDir = initialOptions.absWorkingDir ?? process.cwd();
+              const bundles = buildArtifacts.filter(isJsFile);
+              const results = await Promise.all(
+                bundles.map(bundle =>
+                  addDebugIdToEmittedArtifacts(
+                    path.resolve(outputDir, bundle),
+                    logger,
+                    options.sourcemaps?.resolveSourceMap,
+                  ),
+                ),
+              );
+              warnAboutInlineSourceMaps(
+                bundles.filter((_, index) => results[index] === 'inline-source-map'),
+                logger,
+              );
+            }
           }
         } finally {
           freeGlobalDependencyOnBuildArtifacts();

packages/bundler-plugins/src/rollup/index.ts

@@ -13,6 +13,9 @@ import {
   createComponentNameAnnotateHooks,
   replaceBooleanFlagsInCode,
   CodeInjection,
+  addDebugIdToBundleAndSourceMap,
+  bundleHasInlineSourceMap,
+  warnAboutInlineSourceMaps,
 } from '../core';
 import type {
   ComponentAnnotationTransformMeta,
@@ -28,6 +31,13 @@ import { createRequire } from 'node:module';
 // because `rollup` is an optional dependency.
 type TransformResult = { code: string; map?: SourceMap | string | { mappings: string } | null } | null | undefined;
 
+// The subset of Rollup's `OutputBundle` this plugin's `generateBundle` hook reads.
+type OutputBundle = Record<
+  string,
+  | { type: 'chunk'; fileName: string; code: string; sourcemapFileName?: string | null }
+  | { type: 'asset'; fileName: string; source: string | Uint8Array }
+>;
+
 type ViteModule = {
   parseAstAsync?: (code: string, options: { lang: 'jsx' | 'tsx' }) => Promise<unknown>;
 };
@@ -284,6 +294,34 @@ export function _rollupPluginInternal(
     };
   }
 
+  // `disable-upload` skips the upload routine (which stamps debug IDs into temp copies), so the emitted artifacts
+  // get stamped here instead. Not in `renderChunk`: minifiers running after it would strip the comment.
+  function generateBundle(_outputOptions: unknown, bundle: OutputBundle): void {
+    const inlineSourceMapBundles: string[] = [];
+
+    for (const output of Object.values(bundle)) {
+      if (output.type !== 'chunk' || !isJsFile(output.fileName)) {
+        continue;
+      }
+
+      const sourceMap = bundle[output.sourcemapFileName ?? `${output.fileName}.map`];
+      if (sourceMap?.type !== 'asset' || typeof sourceMap.source !== 'string') {
+        if (bundleHasInlineSourceMap(output.code)) {
+          inlineSourceMapBundles.push(output.fileName);
+        }
+        continue;
+      }
+
+      const stamped = addDebugIdToBundleAndSourceMap(output.code, sourceMap.source);
+      if (stamped !== undefined) {
+        output.code = stamped.bundleSource;
+        sourceMap.source = stamped.sourceMapSource;
+      }
+    }
+
+    warnAboutInlineSourceMaps(inlineSourceMapBundles, logger);
+  }
+
   async function writeBundle(
     outputOptions: { dir?: string; file?: string },
     bundle: { [fileName: string]: unknown },
@@ -318,29 +356,20 @@ export function _rollupPluginInternal(
   }
 
   const name = `sentry-${buildTool}-plugin`;
-
-  if (shouldTransform) {
-    const transformHook =
-      buildTool === 'vite'
-        ? {
-            filter: { id: JS_MODULE_ID_FILTER },
-            handler: transform,
-          }
-        : transform;
-
-    return {
-      name,
-      buildStart,
-      transform: transformHook,
-      renderChunk,
-      writeBundle,
-    };
-  }
+  const transformHook =
+    buildTool === 'vite'
+      ? {
+          filter: { id: JS_MODULE_ID_FILTER },
+          handler: transform,
+        }
+      : transform;
 
   return {
     name,
     buildStart,
+    ...(shouldTransform ? { transform: transformHook } : {}),
     renderChunk,
+    ...(options.sourcemaps?.disable === 'disable-upload' ? { generateBundle } : {}),
     writeBundle,
   };
 }