feat(sam nodejs debug): don't break on async_hooks #3846

Problem:
Debugging a nodejs sam lambda always breaks at the nodejs internal
module `internal/async_hooks` before reaching the first user-specified
breakpoint. This is an old problem with `--inspect-brk`. #2758

Solution:
- For "Image" packagetype, send `NODE_OPTIONS=--inspect=…` in the
  container environment variables instead of  `--inspect-brk`.
- For "Zip" packagetype set the `continueOnAttach` vscode nodejs
  debugger option, to workaround sam cli's hardcoded NODE_OPTIONS:
  https://github.com/aws/aws-sam-cli/blob/1adc080b82476288804c41c553c5e2ad86f28298/samcli/local/docker/lambda_debug_settings.py#L165

Author: justinmk3

.changes/next-release/Bug Fix-9fb78a30-8692-4ed2-925b-18906bef1da8.json

@@ -0,0 +1,4 @@
+{
+	"type": "Bug Fix",
+	"description": "SAM: Debugging a nodejs Lambda always hits breakpoint in nodejs async_hooks module before reaching the user-specified breakpoint"
+}

src/shared/sam/debugger/typescriptSamDebug.ts

@@ -79,8 +79,9 @@ export async function makeTypescriptConfig(config: SamLaunchRequestArgs): Promis
     const isImageLambda = isImageLambdaConfig(config)
 
     if (isImageLambda && !config.noDebug) {
+        // Need --inspect to enable debugging. SAM CLI doesn't send env vars for "Image" packagetype.
         config.containerEnvVars = {
-            NODE_OPTIONS: `--inspect-brk=0.0.0.0:${config.debugPort} --max-http-header-size 81920`,
+            NODE_OPTIONS: `--inspect=0.0.0.0:${config.debugPort} --max-http-header-size 81920`,
         }
     }
 
@@ -110,7 +111,11 @@ export async function makeTypescriptConfig(config: SamLaunchRequestArgs): Promis
         remoteRoot: remoteRoot ?? '/var/task',
         protocol: 'inspector',
         // Stop at first user breakpoint, not the runtime bootstrap file.
-        stopOnEntry: config.stopOnEntry === undefined ? false : !!config.stopOnEntry,
+        stopOnEntry: config.stopOnEntry ?? false,
+        // See `continueOnAttach` at: https://code.visualstudio.com/docs/nodejs/nodejs-debugging
+        // Workaround SAM CLI's outdated settings: https://github.com/aws/aws-sam-cli/blob/1adc080b82476288804c41c553c5e2ad86f28298/samcli/local/docker/lambda_debug_settings.py#L165
+        // Not needed (but harmless) for "Image" packagetype: we set "NODE_OPTIONS:--inspect=…" above.
+        continueOnAttach: config.continueOnAttach ?? true,
         skipFiles: ['/var/runtime/node_modules/**/*.js', '<node_internals>/**/*.js'],
     }
 

src/test/shared/sam/debugger/samDebugConfigProvider.test.ts

@@ -586,6 +586,7 @@ describe('SamDebugConfigurationProvider', async function () {
                 protocol: 'inspector',
                 remoteRoot: '/var/task',
                 skipFiles: ['/var/runtime/node_modules/**/*.js', '<node_internals>/**/*.js'],
+                continueOnAttach: true,
                 stopOnEntry: false,
             }
 
@@ -739,6 +740,7 @@ describe('SamDebugConfigurationProvider', async function () {
                 protocol: 'inspector',
                 remoteRoot: '/var/task',
                 skipFiles: ['/var/runtime/node_modules/**/*.js', '<node_internals>/**/*.js'],
+                continueOnAttach: true,
                 stopOnEntry: false,
             }
 
@@ -893,6 +895,7 @@ describe('SamDebugConfigurationProvider', async function () {
                 protocol: 'inspector',
                 remoteRoot: '/var/task',
                 skipFiles: ['/var/runtime/node_modules/**/*.js', '<node_internals>/**/*.js'],
+                continueOnAttach: true,
                 stopOnEntry: false,
             }
 
@@ -995,7 +998,7 @@ describe('SamDebugConfigurationProvider', async function () {
                 baseBuildDir: actual.baseBuildDir, // Random, sanity-checked by assertEqualLaunchConfigs().
                 containerEnvFile: `${actual.baseBuildDir}/container-env-vars.json`,
                 containerEnvVars: {
-                    NODE_OPTIONS: `--inspect-brk=0.0.0.0:${actual.debugPort} --max-http-header-size 81920`,
+                    NODE_OPTIONS: `--inspect=0.0.0.0:${actual.debugPort} --max-http-header-size 81920`,
                 },
                 envFile: undefined,
                 eventPayloadFile: undefined,
@@ -1025,14 +1028,15 @@ describe('SamDebugConfigurationProvider', async function () {
                 protocol: 'inspector',
                 remoteRoot: '/var/task',
                 skipFiles: ['/var/runtime/node_modules/**/*.js', '<node_internals>/**/*.js'],
+                continueOnAttach: true,
                 stopOnEntry: false,
                 parameterOverrides: undefined,
             }
 
             assertEqualLaunchConfigs(actual, expected)
             assertFileText(
                 expected.containerEnvFile!,
-                `{"NODE_OPTIONS":"--inspect-brk=0.0.0.0:${actual.debugPort} --max-http-header-size 81920"}`
+                `{"NODE_OPTIONS":"--inspect=0.0.0.0:${actual.debugPort} --max-http-header-size 81920"}`
             )
 
             //
@@ -1159,6 +1163,7 @@ describe('SamDebugConfigurationProvider', async function () {
                 protocol: 'inspector',
                 remoteRoot: '/var/task',
                 skipFiles: ['/var/runtime/node_modules/**/*.js', '<node_internals>/**/*.js'],
+                continueOnAttach: true,
                 stopOnEntry: false,
                 parameterOverrides: undefined,
             }
@@ -2928,6 +2933,7 @@ describe('SamDebugConfigurationProvider', async function () {
                 runtime: 'nodejs12.x',
                 runtimeFamily: lambdaModel.RuntimeFamily.NodeJS,
                 skipFiles: ['/var/runtime/node_modules/**/*.js', '<node_internals>/**/*.js'],
+                continueOnAttach: true,
                 stopOnEntry: false,
             }