Allow sources to be hidden in DevTools sources panel (#662)

Wrangler currently uses the non-standard `x_google_ignoreList` source
map field to hide middleware and injected code from the sources
panel. As part of the work to enable breakpoint debugging in
Wrangler, we now defer to Miniflare to serve local source maps. This
ensures source maps have the correct source paths on disk.

We'd like to keep this ignoring behaviour though. We could intercept
`Network.loadNetworkResource` and rewrite the source map in Wrangler,
but that feels wasteful, as we're already parsing/stringifying the
source map in Miniflare.

Instead, this change adds a `unsafeSourceMapIgnoreSourcePredicate`
option, that controls which sources, if any, are added to
`x_google_ignoreList`. This allows DevTools to fetch source maps
directly from Miniflare, without proxying through Wrangler.

Author: mrbbot

packages/miniflare/src/index.ts

@@ -863,7 +863,11 @@ export class Miniflare {
 
     sharedOpts.core.cf = await setupCf(this.#log, sharedOpts.core.cf);
 
-    const sourceMapRegistry = new SourceMapRegistry(this.#log, loopbackPort);
+    const sourceMapRegistry = new SourceMapRegistry(
+      this.#log,
+      loopbackPort,
+      sharedOpts.core.unsafeSourceMapIgnoreSourcePredicate
+    );
     const durableObjectClassNames = getDurableObjectClassNames(allWorkerOpts);
     const queueConsumers = getQueueConsumers(allWorkerOpts);
     const allWorkerRoutes = getWorkerRoutes(allWorkerOpts);

packages/miniflare/src/plugins/core/index.ts

@@ -29,6 +29,7 @@ import { getCacheServiceName } from "../cache";
 import { DURABLE_OBJECTS_STORAGE_SERVICE_NAME } from "../do";
 import {
   HEADER_CF_BLOB,
+  IgnoreSourcePredicateSchema,
   Plugin,
   SERVICE_LOOPBACK,
   SourceMapRegistry,
@@ -141,6 +142,8 @@ export const CoreSharedOptionsSchema = z.object({
   cf: z.union([z.boolean(), z.string(), z.record(z.any())]).optional(),
 
   liveReload: z.boolean().optional(),
+
+  unsafeSourceMapIgnoreSourcePredicate: IgnoreSourcePredicateSchema.optional(),
 });
 
 export const CORE_PLUGIN_NAME = "core";

packages/miniflare/src/plugins/shared/registry.ts

@@ -3,9 +3,16 @@ import fs from "fs/promises";
 import path from "path";
 import { fileURLToPath, pathToFileURL } from "url";
 import type { RawSourceMap } from "source-map";
+import { z } from "zod";
 import { Response } from "../../http";
 import { Log } from "../../shared";
 
+export const IgnoreSourcePredicateSchema = z
+  .function()
+  .args(z.string())
+  .returns(z.boolean());
+export type IgnoreSourcePredicate = z.infer<typeof IgnoreSourcePredicateSchema>;
+
 function maybeParseURL(url: string): URL | undefined {
   if (path.isAbsolute(url)) return;
   try {
@@ -18,7 +25,8 @@ export class SourceMapRegistry {
 
   constructor(
     private readonly log: Log,
-    private readonly loopbackPort: number
+    private readonly loopbackPort: number,
+    private readonly ignoreSourcePredicate?: IgnoreSourcePredicate
   ) {}
 
   readonly #map = new Map<string /* id */, string /* sourceMapPath */>();
@@ -78,7 +86,7 @@ export class SourceMapRegistry {
       );
       return;
     }
-    let map: RawSourceMap;
+    let map: RawSourceMap & { x_google_ignoreList?: number[] };
     try {
       map = JSON.parse(contents);
     } catch (e) {
@@ -96,6 +104,18 @@ export class SourceMapRegistry {
         ? sourceMapDir
         : path.resolve(sourceMapDir, map.sourceRoot);
 
+    // Allow specific source files to be hidden from the DevTools sources panel.
+    // (e.g. Wrangler middleware and injected code)
+    // See https://docs.google.com/document/d/1U1RGAehQwRypUTovF1KRlpiOFze0b-_2gc6fAH0KY0k/edit#heading=h.mt2g20loc2ct
+    // for more details.
+    if (this.ignoreSourcePredicate !== undefined && map.sources !== undefined) {
+      const ignoreList: number[] = [];
+      for (let i = 0; i < map.sources.length; i++) {
+        if (this.ignoreSourcePredicate(map.sources[i])) ignoreList.push(i);
+      }
+      map.x_google_ignoreList = ignoreList;
+    }
+
     return Response.json(map, {
       // This source map will be served from the loopback server to DevTools,
       // which will likely be on a different origin.

packages/miniflare/test/plugins/core/errors/index.spec.ts

@@ -60,6 +60,9 @@ test("source maps workers", async (t) => {
 
   const mf = new Miniflare({
     inspectorPort,
+    unsafeSourceMapIgnoreSourcePredicate(source) {
+      return source.includes("nested/dep.ts");
+    },
     workers: [
       {
         bindings: { MESSAGE: "unnamed" },
@@ -215,6 +218,13 @@ addEventListener("fetch", (event) => {
   // Check does nothing with URL source mapping URLs
   const sourceMapURL = await getSourceMapURL(inspectorPort, "core:user:h");
   t.regex(sourceMapURL, /^data:application\/json;base64/);
+
+  // Check adds ignored sources to `x_google_ignoreList`
+  const sourceMap = await getSourceMap(inspectorPort, "core:user:g");
+  assert(sourceMap.sourceRoot !== undefined);
+  assert(sourceMap.x_google_ignoreList?.length === 1);
+  const ignoredSource = sourceMap.sources[sourceMap.x_google_ignoreList[0]];
+  t.is(path.resolve(sourceMap.sourceRoot, ignoredSource), DEP_ENTRY_PATH);
 });
 
 function getSourceMapURL(
@@ -250,14 +260,22 @@ function getSourceMapURL(
   return promise;
 }
 
-async function getSources(inspectorPort: number, serviceName: string) {
+async function getSourceMap(inspectorPort: number, serviceName: string) {
   const sourceMapURL = await getSourceMapURL(inspectorPort, serviceName);
   // The loopback server will be listening on `127.0.0.1`, which
   // `localhost` should resolve to, but `undici` only looks at the first
   // DNS entry, which will be `::1` on Node 17+.
-  // noinspection JSObjectNullOrUndefined
   const res = await fetch(sourceMapURL.replace("localhost", "127.0.0.1"));
-  const { sourceRoot, sources } = (await res.json()) as RawSourceMap;
+  return (await res.json()) as RawSourceMap & {
+    x_google_ignoreList?: number[];
+  };
+}
+
+async function getSources(inspectorPort: number, serviceName: string) {
+  const { sourceRoot, sources } = await getSourceMap(
+    inspectorPort,
+    serviceName
+  );
   assert(sourceRoot !== undefined);
   return sources.map((source) => path.resolve(sourceRoot, source)).sort();
 }