Issue Review: cloudflare/workers-sdk#9997

Summary

Debugging breakpoints fail for files with special characters (brackets) in their paths because the source.path in DAP messages is sent without the file:// scheme prefix.

Findings

• Created: 2025-07-17
• Updated: 2025-07-17
• Version: v4.24 -> v4.60.0
• Component: wrangler (debugging/inspector proxy)
• Labels: bug
• Comments: 0

Key Evidence

• No PRs reference or fix this issue (#9997)
• No changelog entry mentions this issue
• Issue describes clear reproduction steps with files named [foo].ts
• Problem: source.path is /path/to/%5Bfoo%5D.ts instead of file:///path/to/%5Bfoo%5D.ts
• The source-url.ts file correctly uses pathToFileURL() which produces proper file:// URLs
• The handleRuntimeScriptParsed function in inspector proxies handles sourceMapURL but not the main script url in the DAP Debugger.scriptParsed event
• Related code exists in multiple places: InspectorProxyWorker.ts, inspector-proxy.ts, and source-url.ts

Root Cause Analysis

The issue appears to be in how URLs with special characters (like brackets []) are handled by VSCode's JS debug adapter when the path doesn't have a proper file:// scheme.

1. Source URL Generation (packages/wrangler/src/deployment-bundle/source-url.ts:4-6):

   function withSourceURL(source: string, sourcePath: string) {
     return `${source}\n//# sourceURL=${pathToFileURL(sourcePath)}`;
   }
   

   This correctly produces file:///path/to/[foo].ts URLs.

2. URL Handling in Inspector Proxy (packages/wrangler/templates/startDevWorker/InspectorProxyWorker.ts:243-264):
   The handleRuntimeScriptParsed function only processes sourceMapURL and not the main url parameter. When VSCode's debug adapter receives paths with URL-encoded characters (like %5B for [), it may not properly resolve them without the file:// scheme.

3. Possible Cause: The issue might be in workerd/V8's inspector output, or in how the URL is decoded/re-encoded in the proxy layer. The URL-encoded characters (%5B, %5D) in the path need the file:// scheme for VSCode to correctly interpret them.

Proposed Solution

The fix should ensure that when Debugger.scriptParsed events pass through the inspector proxy, paths with special characters are properly formatted with the file:// scheme.

Option A: Validate and fix URL in handleRuntimeScriptParsed

In packages/wrangler/templates/startDevWorker/InspectorProxyWorker.ts:

handleRuntimeScriptParsed(msg: DevToolsEvent<"Debugger.scriptParsed">) {
  // Ensure the main script URL has a proper file:// scheme
  // This is necessary for paths with special characters (brackets, etc.)
  if (msg.params.url && !msg.params.url.includes(':')) {
    // URL appears to be a bare path, convert to file:// URL
    try {
      const fileUrl = new URL('file://' + encodeURI(msg.params.url));
      msg.params.url = fileUrl.href;
    } catch {
      // If conversion fails, leave as-is
    }
  }

  // ... existing sourceMapURL handling
}

Option B: Fix at source-url.ts level

Ensure all paths passed to the inspector are consistent file:// URLs and investigate if workerd strips the scheme somewhere.

Recommendation

Status: KEEP OPEN

Reasoning: This is a valid bug with clear reproduction steps. No fix has been merged, and debugging is a critical developer experience feature. The issue affects any file with special characters in its name (brackets, spaces, etc.).

Action:

1. Investigate where the file:// scheme is being stripped or not added
2. Check if workerd/V8 sends bare paths in Debugger.scriptParsed events
3. Add URL normalization in the inspector proxy to ensure proper file:// scheme

Implementation Details

Files to Modify:

• packages/wrangler/templates/startDevWorker/InspectorProxyWorker.ts - Add URL normalization in handleRuntimeScriptParsed
• packages/miniflare/src/plugins/core/inspector-proxy/inspector-proxy.ts - Mirror fix for miniflare's inspector proxy
• packages/wrangler/src/deployment-bundle/source-url.ts - Verify pathToFileURL is being used consistently

Implementation Difficulty: Medium

• The fix itself is relatively simple (URL normalization)
• However, it requires:
  1. Understanding the exact point where the scheme is lost
  2. Testing across multiple debug scenarios (VSCode, WebStorm, Chrome DevTools)
  3. Ensuring the fix doesn't break existing debugging workflows
  4. Handling edge cases (already valid URLs, relative paths, etc.)

Testing Recommendations:

1. Create a test worker with a file named [foo].ts containing a simple function
2. Set a breakpoint in VSCode and verify it binds correctly
3. Test stepping into the function from another file
4. Test with other special characters: spaces, parentheses, unicode
5. Verify Chrome DevTools still works correctly
6. Add unit tests for URL normalization in inspector proxy tests