feat(lambda): allow debugging Lambda functions when connected to LocalStack

- Add LocalStack detection for Lambda debugging webview, by refactoring into two
sub classes to handle the lifecycle of the debugging process.
- Hide and disable version publishing
- Await debugger start to slightly mitigate the race condition
- Add LocalStack Lambda Debug Mode config deletion upon stopping debugging
- Wait for function to be active before launching debugger
- Add user-agent integration
- Add temporary workaround to mitigate debugger attach timing issue
- Fix debugger attach race condition by waiting using the new GET API
- Add LDM error handling
- Handle LocalStack Lambda hot reloading gracefully
- Disable code download upon LocalStack hot reloading
- Skip file watcher for hot-reloaded Lambda function
- Disable Convert to SAM application for LocalStack
- Show message in Remote Invoke WebView when connected to Localstack
- Add telemetry for LocalStack case (including refactor some old telemetry)

Author: valerena

packages/core/src/lambda/explorer/lambdaFunctionNode.ts

@@ -21,6 +21,14 @@ import { LambdaFunctionFileNode } from './lambdaFunctionFileNode'
 
 export const contextValueLambdaFunction = 'awsRegionFunctionNode'
 export const contextValueLambdaFunctionImportable = 'awsRegionFunctionNodeDownloadable'
+// Without "Convert to SAM application"
+export const contextValueLambdaFunctionDownloadOnly = 'awsRegionFunctionNodeDownloadableOnly'
+
+function isLambdaFunctionDownloadable(contextValue?: string): boolean {
+    return (
+        contextValue === contextValueLambdaFunctionImportable || contextValue === contextValueLambdaFunctionDownloadOnly
+    )
+}
 
 export class LambdaFunctionNode extends AWSTreeNodeBase implements AWSResourceNode {
     public constructor(
@@ -32,7 +40,7 @@ export class LambdaFunctionNode extends AWSTreeNodeBase implements AWSResourceNo
     ) {
         super(
             `${configuration.FunctionArn}`,
-            contextValue === contextValueLambdaFunctionImportable
+            isLambdaFunctionDownloadable(contextValue)
                 ? vscode.TreeItemCollapsibleState.Collapsed
                 : vscode.TreeItemCollapsibleState.None
         )
@@ -72,7 +80,7 @@ export class LambdaFunctionNode extends AWSTreeNodeBase implements AWSResourceNo
     }
 
     public override async getChildren(): Promise<AWSTreeNodeBase[]> {
-        if (!(this.contextValue === contextValueLambdaFunctionImportable)) {
+        if (!isLambdaFunctionDownloadable(this.contextValue)) {
             return []
         }
 

packages/core/src/lambda/explorer/lambdaNodes.ts

@@ -14,13 +14,15 @@ import { AWSTreeNodeBase } from '../../shared/treeview/nodes/awsTreeNodeBase'
 import { PlaceholderNode } from '../../shared/treeview/nodes/placeholderNode'
 import { makeChildrenNodes } from '../../shared/treeview/utils'
 import { toArrayAsync, toMap, updateInPlace } from '../../shared/utilities/collectionUtils'
-import { listLambdaFunctions } from '../utils'
+import { listLambdaFunctions, isHotReloadingFunction } from '../utils'
 import {
     contextValueLambdaFunction,
     contextValueLambdaFunctionImportable,
+    contextValueLambdaFunctionDownloadOnly,
     LambdaFunctionNode,
 } from './lambdaFunctionNode'
 import { samLambdaImportableRuntimes } from '../models/samLambdaRuntime'
+import { isLocalStackConnection } from '../../auth/utils'
 
 /**
  * An AWS Explorer node representing the Lambda Service.
@@ -71,9 +73,15 @@ function makeLambdaFunctionNode(
     regionCode: string,
     configuration: Lambda.FunctionConfiguration
 ): LambdaFunctionNode {
-    const contextValue = samLambdaImportableRuntimes.contains(configuration.Runtime ?? '')
-        ? contextValueLambdaFunctionImportable
-        : contextValueLambdaFunction
+    let contextValue = contextValueLambdaFunction
+    const isImportableRuntime = samLambdaImportableRuntimes.contains(configuration.Runtime ?? '')
+    if (isLocalStackConnection()) {
+        if (isImportableRuntime && !isHotReloadingFunction(configuration?.CodeSha256)) {
+            contextValue = contextValueLambdaFunctionDownloadOnly
+        }
+    } else if (isImportableRuntime) {
+        contextValue = contextValueLambdaFunctionImportable
+    }
     const node = new LambdaFunctionNode(parent, regionCode, configuration, contextValue)
 
     return node

packages/core/src/lambda/remoteDebugging/lambdaDebugger.ts

@@ -0,0 +1,73 @@
+/*!
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import * as vscode from 'vscode'
+import globals from '../../shared/extensionGlobals'
+import type { Lambda } from 'aws-sdk'
+import { getLogger } from '../../shared/logger/logger'
+
+const logger = getLogger()
+
+export const remoteDebugSnapshotString = 'aws.lambda.remoteDebugSnapshot'
+
+export interface DebugConfig {
+    functionArn: string
+    functionName: string
+    port: number | undefined
+    localRoot: string
+    remoteRoot: string
+    skipFiles: string[]
+    shouldPublishVersion: boolean
+    lambdaRuntime?: string // Lambda runtime (e.g., nodejs18.x)
+    debuggerRuntime?: string // VS Code debugger runtime (e.g., node)
+    outFiles?: string[]
+    sourceMap?: boolean
+    justMyCode?: boolean
+    projectName?: string
+    otherDebugParams?: string
+    lambdaTimeout?: number
+    layerArn?: string
+    handlerFile?: string
+    isLambdaRemote: boolean // false if LocalStack connection
+}
+
+/**
+ * Interface for debugging AWS Lambda functions remotely.
+ *
+ * This interface defines the contract for implementing remote debugging
+ * for Lambda functions.
+ *
+ * Implementations of this interface handle the lifecycle of remote debugging sessions,
+ * including checking health, set up, necessary deployment, and later clean up
+ */
+export interface LambdaDebugger {
+    checkHealth(): Promise<void>
+    setup(
+        progress: vscode.Progress<{ message?: string; increment?: number }>,
+        functionConfig: Lambda.FunctionConfiguration,
+        region: string
+    ): Promise<void>
+    waitForSetup(
+        progress: vscode.Progress<{ message?: string; increment?: number }>,
+        functionConfig: Lambda.FunctionConfiguration,
+        region: string
+    ): Promise<void>
+    waitForFunctionUpdates(progress: vscode.Progress<{ message?: string; increment?: number }>): Promise<void>
+    cleanup(functionConfig: Lambda.FunctionConfiguration): Promise<void>
+}
+
+// this should be called when the debug session is started
+export async function persistLambdaSnapshot(config: Lambda.FunctionConfiguration | undefined): Promise<void> {
+    try {
+        await globals.globalState.update(remoteDebugSnapshotString, config)
+    } catch (error) {
+        // TODO raise toolkit error
+        logger.error(`Error persisting debug sessions: ${error}`)
+    }
+}
+
+export function getLambdaSnapshot(): Lambda.FunctionConfiguration | undefined {
+    return globals.globalState.get<Lambda.FunctionConfiguration>(remoteDebugSnapshotString)
+}

packages/core/src/lambda/remoteDebugging/ldkClient.ts

@@ -26,7 +26,7 @@ export function isTunnelInfo(data: TunnelInfo): data is TunnelInfo {
     )
 }
 
-interface TunnelInfo {
+export interface TunnelInfo {
     tunnelID: string
     sourceToken: string
     destinationToken: string