feat: Support LocalStack

.github/workflows/pull-request.yml

@@ -15,41 +15,51 @@ jobs:
     uses: ./.github/workflows/common-build.yml
     secrets: inherit
 
-  remove-old-layers:
-    runs-on: ubuntu-latest
-    needs: build
-    concurrency:
-      group: remove-all-layers
-    steps:
-      - uses: actions/checkout@v4
-      - name: Use Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: ${{ env.node_version }}
-          registry-url: 'https://registry.npmjs.org'
-      - name: Install dependencies
-        run: npm ci
-      - name: Download build artifact
-        uses: actions/download-artifact@v4
-        with:
-          name: dist
-          path: dist
-      - name: Configure AWS Credentials
-        uses: aws-actions/configure-aws-credentials@v4
-        with:
-          aws-region: eu-west-1
-          role-to-assume: ${{ secrets.AWS_ROLE }}
-          role-session-name: GitHubActions
-      - name: Remove old layers
-        run: |
-          node ../../dist/lldebugger.mjs -r all --config-env=test -v
-        # Picking random test so I can have environment
-        working-directory: test/sam-basic
+  # remove-old-layers:
+  #   runs-on: ubuntu-latest
+  #   needs: build
+  #   concurrency:
+  #     group: remove-all-layers
+  #   steps:
+  #     - uses: actions/checkout@v4
+  #     - name: Use Node.js
+  #       uses: actions/setup-node@v4
+  #       with:
+  #         node-version: ${{ env.node_version }}
+  #         registry-url: 'https://registry.npmjs.org'
+  #     - name: Install dependencies
+  #       run: npm ci
+  #     - name: Download build artifact
+  #       uses: actions/download-artifact@v4
+  #       with:
+  #         name: dist
+  #         path: dist
+  #     - name: Configure AWS Credentials
+  #       uses: aws-actions/configure-aws-credentials@v4
+  #       with:
+  #         aws-region: eu-west-1
+  #         role-to-assume: ${{ secrets.AWS_ROLE }}
+  #         role-session-name: GitHubActions
+  #     - name: Remove old layers
+  #       run: |
+  #         node ../../dist/lldebugger.mjs -r all --config-env=test -v
+  #       # Picking random test so I can have environment
+  #       working-directory: test/sam-basic
+
+  # test:
+  #   uses: ./.github/workflows/common-test.yml
+  #   secrets: inherit
+  #   needs: remove-old-layers
+  #   with:
+  #     mode: build
+  #     testMonorepo: false
+  #     useLocalStack: false
 
-  test:
+  test-localstack:
     uses: ./.github/workflows/common-test.yml
     secrets: inherit
-    needs: remove-old-layers
+    needs: build
     with:
       mode: build
       testMonorepo: false
+      useLocalStack: true

.github/workflows/test-with-real-npm-all.yml

@@ -19,6 +19,16 @@ jobs:
       mode: global
       testMonorepo: false
       version: ${{ inputs.version }}
+      useLocalStack: false
+    secrets: inherit
+
+  test-global-not-monorepo-localstack:
+    uses: ./.github/workflows/common-test.yml
+    with:
+      mode: global
+      testMonorepo: false
+      version: ${{ inputs.version }}
+      useLocalStack: true
     secrets: inherit
 
   test-local-not-monorepo:
@@ -28,6 +38,17 @@ jobs:
       mode: local
       testMonorepo: false
       version: ${{ inputs.version }}
+      useLocalStack: false
+    secrets: inherit
+
+  test-local-not-monorepo-localstack:
+    needs: test-global-not-monorepo
+    uses: ./.github/workflows/common-test.yml
+    with:
+      mode: local
+      testMonorepo: false
+      version: ${{ inputs.version }}
+      useLocalStack: true
     secrets: inherit
 
   test-global-monorepo:
@@ -37,6 +58,17 @@ jobs:
       mode: global
       testMonorepo: true
       version: ${{ inputs.version }}
+      useLocalStack: false
+    secrets: inherit
+
+  test-global-monorepo-localstack:
+    needs: test-local-not-monorepo
+    uses: ./.github/workflows/common-test.yml
+    with:
+      mode: global
+      testMonorepo: true
+      version: ${{ inputs.version }}
+      useLocalStack: true
     secrets: inherit
 
   test-local-monorepo:
@@ -46,4 +78,15 @@ jobs:
       mode: local
       testMonorepo: true
       version: ${{ inputs.version }}
+      useLocalStack: false
+    secrets: inherit
+
+  test-local-monorepo-localstack:
+    needs: test-global-monorepo
+    uses: ./.github/workflows/common-test.yml
+    with:
+      mode: local
+      testMonorepo: true
+      version: ${{ inputs.version }}
+      useLocalStack: true
     secrets: inherit

.github/workflows/test-with-real-npm.yml

@@ -16,6 +16,10 @@ on:
         description: 'Test monorepo by specifying folder in config'
         type: boolean
         default: false
+      useLocalStack:
+        description: 'Use LocalStack instead of AWS'
+        type: boolean
+        default: false
       version:
         description: 'Specify the version of the package'
         type: string
@@ -32,4 +36,5 @@ jobs:
       mode: ${{ inputs.mode }}
       testMonorepo: ${{ inputs.testMonorepo }}
       version: ${{ inputs.version }}
+      useLocalStack: ${{ inputs.useLocalStack }}
     secrets: inherit

src/awsCredentials.ts

@@ -17,6 +17,50 @@ function getCredentialsProvider(
   });
 }
 
+/**
+ * Detects if LocalStack is being used by making a test request and checking for
+ * the 'x-localstack' header in the response.
+ * @see {@link https://github.com/localstack/localstack/pull/12769}
+ * @param awsConfiguration - AWS configuration to use for the test request
+ * @returns true if LocalStack is detected (x-localstack header present), false otherwise
+ */
+async function isLocalStackDetected(
+  awsConfiguration: AwsConfiguration,
+): Promise<boolean> {
+  // Enable LocalStack response header to detect LocalStack
+  process.env.LOCALSTACK_RESPONSE_HEADER_ENABLED = 'true';
+
+  const { IAMClient, ListAccountAliasesCommand } = await import(
+    '@aws-sdk/client-iam'
+  );
+
+  const client = new IAMClient({
+    region: awsConfiguration.region,
+    credentials: fromNodeProviderChain({
+      clientConfig: { region: awsConfiguration.region },
+      profile: awsConfiguration.profile,
+      roleArn: awsConfiguration.role,
+    }),
+  });
+
+  const command = new ListAccountAliasesCommand({});
+  const response = await client.send(command);
+
+  // Check for x-localstack header in response metadata
+  const headers = (response.$metadata as any)?.httpHeaders;
+  if (
+    headers &&
+    ('x-localstack' in headers ||
+      'X-Localstack' in headers ||
+      'X-LOCALSTACK' in headers)
+  ) {
+    return true;
+  }
+
+  return false;
+}
+
 export const AwsCredentials = {
   getCredentialsProvider,
+  isLocalStackDetected,
 };

src/configuration.ts

@@ -9,6 +9,7 @@ import { getConfigTsFromConfigFile } from './configuration/getConfigFromTsConfig
 import { configFileDefaultName } from './constants.js';
 import { ResourceDiscovery } from './resourceDiscovery.js';
 import { Logger } from './logger.js';
+import { AwsCredentials } from './awsCredentials.js';
 
 let config: LldConfig;
 const lambdas: Record<string, LambdaResource> = {};
@@ -41,9 +42,15 @@ async function readConfig() {
     });
 
     const debuggerId = await generateDebuggerId(!!configFromWizard.observable);
+    const localStack = await AwsCredentials.isLocalStackDetected({
+      profile: configFromWizard.profile,
+      region: configFromWizard.region,
+      role: configFromWizard.role,
+    });
     setConfig({
       ...configFromWizard,
       debuggerId,
+      localStack,
       start: false, // don't start the debugger after the wizard
     });
   } else {
@@ -63,9 +70,15 @@ async function readConfig() {
           : configFromConfigFile?.context,
     };
     const debuggerId = await generateDebuggerId(!!configMerged.observable);
+    const localStack = await AwsCredentials.isLocalStackDetected({
+      profile: configMerged.profile,
+      region: configMerged.region,
+      role: configMerged.role,
+    });
     setConfig({
       ...configMerged,
       debuggerId,
+      localStack,
       start: true,
     });
   }

src/extension/interceptor.ts

@@ -48,6 +48,13 @@ async function regularMode(context: any, event: any) {
     });
   }, 5 * 1000);
 
+  let region: string | undefined;
+  if (process.env.NODE_TLS_REJECT_UNAUTHORIZED === '0') {
+    // it is localstack
+    region = process.env.AWS_REGION;
+    Logger.verbose(`Region is set to ${region} due to LocalStack detection`);
+  }
+
   const ioTService = await IoTService.connect({
     onMessage: async (message: IoTMessage) => {
       if (Logger.isVerbose()) {
@@ -83,6 +90,7 @@ async function regularMode(context: any, event: any) {
       }
     },
     topic,
+    region,
   });
 
   const payload: IoTMessage = {

src/infraDeploy.ts

@@ -1061,6 +1061,11 @@ function getEnvironmentVariablesForDebugger({
     env.LLD_VERBOSE = 'true';
   }
 
+  // Disable TLS verification for LocalStack
+  if (Configuration.config.localStack) {
+    env.NODE_TLS_REJECT_UNAUTHORIZED = '0';
+  }
+
   return env;
 }
 

src/lambdaConnection.ts

@@ -13,6 +13,15 @@ const lambdasProcessingObservableMode = new Set<string>();
  */
 async function connect() {
   topic = `${Configuration.config.debuggerId}/events`;
+
+  let region = Configuration.config.region;
+  if (!region && Configuration.config.localStack) {
+    region = process.env.AWS_REGION || 'us-east-1';
+    Logger.verbose(
+      `Empty region detected with LocalStack, defaulting to ${region}`,
+    );
+  }
+
   ioTServiceConnection = await IoTService.connect({
     onMessage: onMessageFromLambda,
     topic,

src/lldebugger.ts

@@ -55,6 +55,11 @@ async function run() {
     return;
   }
 
+  if (Configuration.config.localStack) {
+    //https://github.com/localstack/localstack/issues/13308
+    process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';
+  }
+
   let message = `Starting the debugger ${
     Configuration.config.observable
       ? 'in Observability mode'

src/types/lldConfig.ts

@@ -91,4 +91,11 @@ export type LldConfigCliArgs = {
 
 export type LldConfigTs = Partial<LldConfigBase>;
 
-export type LldConfig = LldConfigCliArgs & LldConfigTs & { debuggerId: string };
+export type LldConfig = LldConfigCliArgs &
+  LldConfigTs & {
+    debuggerId: string;
+    /**
+     * Indicates whether LocalStack is being used instead of real AWS services.
+     */
+    localStack: boolean;
+  };

test/cdk-basic/bin/cdk-basic.ts

@@ -4,10 +4,10 @@ import * as cdk from 'aws-cdk-lib';
 import { CdkbasicStack } from '../lib/cdk-basic-stack';
 import { CdkbasicStack2 } from '../lib/subfolder/cdk-basic-stack2';
 
-if (process.env.CDK_DEFAULT_REGION !== 'eu-west-1') {
-  // checking if the region is set with Lambda Live Debugger
-  throw new Error('CDK_DEFAULT_REGION must be set to eu-west-1');
-}
+// if (process.env.CDK_DEFAULT_REGION !== 'eu-west-1') {
+//   // checking if the region is set with Lambda Live Debugger
+//   throw new Error('CDK_DEFAULT_REGION must be set to eu-west-1');
+// }
 
 const app = new cdk.App();