Skip to content

Conversation

@skyrpex
Copy link
Contributor

@skyrpex skyrpex commented Nov 14, 2025

Problem

The AWS SDK v2 to v3 migration in PR #8183 introduced breaking changes for LocalStack compatibility and Lambda debugging is not working anymore:

  1. User Agent format changed: The migration changed from string-based user agents to AWS SDK v3's UserAgent pairs format ([name, version] tuples), but several places still used the old string format, breaking LocalStack's custom user agent for Lambda debugging
  2. Response headers no longer accessible: AWS SDK v3 removed access to HTTP response headers via $response.httpResponse.headers, breaking LocalStack connection detection which relies on the x-localstack-request-url header

These issues were not caught most likely because LocalStack compatibility was not tested during the SDK v3 migration.

Solution

  1. Add response headers middleware for AWS SDK v3

    • Added captureHeadersMiddleware to AWSClientBuilderV3 that attaches HTTP response headers to the output via $httpHeaders property
    • Updated loginManager to check for LocalStack connection using $httpHeaders instead of the removed $response.httpResponse.headers
  2. Fix user agent format for AWS SDK v3

    • Migrated from string-based user agents to proper UserAgent pairs format:
      • Changed from "LAMBDA-DEBUG/1.0.0 AWS-Toolkit/..." (string)
      • To [['LAMBDA-DEBUG', '1.0.0'], ['AWS-Toolkit', '2.0'], ...] (pairs)
    • Updated awsClientBuilderV3 to use customUserAgent instead of userAgent

AWS SDK v3 Breaking Changes

User Agent Format

SDK v2:

// String format in client options
const options = {
    region: 'us-east-1',
    userAgent: 'LAMBDA-DEBUG/1.0.0 AWS-Toolkit/2.0.0'
}

SDK v3:

// Array of [name, version] tuples
const options = {
    region: 'us-east-1',
    customUserAgent: [
        ['LAMBDA-DEBUG', '1.0.0'],
        ['AWS-Toolkit', '2.0.0']
    ]
}

Response Headers Access

SDK v2:

const response = await client.send(command)
// Headers directly accessible
const headers = response.$response.httpResponse.headers
const localStackUrl = headers['x-localstack-request-url']

SDK v3:

const response = await client.send(command)
// Headers NOT accessible by default - requires custom middleware
const headers = response.$httpHeaders  // undefined without middleware

Supersedes #8289 as @carole-lavillonniere is OOO today and can't edit their PR.

@skyrpex skyrpex marked this pull request as ready for review November 14, 2025 12:27
@skyrpex skyrpex requested a review from a team as a code owner November 14, 2025 12:27
laileni-aws added a commit that referenced this pull request Nov 19, 2025
## Problem
The AWS SDK v2 to v3 migration in PR #8183 introduced breaking changes
for LocalStack compatibility and Lambda debugging is not working
anymore:

1. **User Agent format changed:** The migration changed from
string-based user agents to AWS SDK v3's `UserAgent` pairs format
(`[name, version]` tuples), but several places still used the old string
format, breaking LocalStack's custom user agent for Lambda debugging and
part of the integration with IoT
2. **Response headers no longer accessible**: AWS SDK v3 removed access
to HTTP response headers via `$response.httpResponse.headers`, breaking
LocalStack connection detection which relies on the
`x-localstack-request-url` header

These issues were not caught most likely because LocalStack
compatibility was not tested during the SDK v3 migration.

## Solution
1. Fix user agent format for AWS SDK v3
* Migrated from string-based user agents to proper UserAgent pairs
format:
     
     * Changed from "LAMBDA-DEBUG/1.0.0 AWS-Toolkit/..." (string)
* To [['LAMBDA-DEBUG', '1.0.0'], ['AWS-Toolkit', '2.0'], ...] (pairs)
* Updated awsClientBuilderV3 to use customUserAgent instead of userAgent


2. Add response headers middleware for AWS SDK v3 
* Added `captureHeadersMiddleware` to `AWSClientBuilderV3` that attaches
HTTP response headers to the output via `$httpHeaders` property
* Updated `loginManager` to check for LocalStack connection using
`$httpHeaders` instead of the removed `$response.httpResponse.headers`

## AWS SDK v3 Breaking Changes
### User Agent Format
**SDK v2**:

```ts
// String format in client options
const options = {
    region: 'us-east-1',
    userAgent: 'LAMBDA-DEBUG/1.0.0 AWS-Toolkit/2.0.0'
}
```

**SDK v3:**

```ts
// Array of [name, version] tuples
const options = {
    region: 'us-east-1',
    customUserAgent: [
        ['LAMBDA-DEBUG', '1.0.0'],
        ['AWS-Toolkit', '2.0.0']
    ]
}
```

### Response Headers Access
**SDK v2**:

```ts
const response = await client.send(command)
// Headers directly accessible
const headers = response.$response.httpResponse.headers
const localStackUrl = headers['x-localstack-request-url']
```

**SDK v3**:

```ts
const response = await client.send(command)
// Headers NOT accessible by default - requires custom middleware
const headers = response.$httpHeaders  // undefined without middleware
```

Supersedes #8289 and #8291


---

- Treat all work as PUBLIC. Private `feature/x` branches will not be
squash-merged at release time.
- Your code changes must meet the guidelines in
[CONTRIBUTING.md](https://github.com/aws/aws-toolkit-vscode/blob/master/CONTRIBUTING.md#guidelines).
- License: I confirm that my contribution is made under the terms of the
Apache 2.0 license.

---------

Co-authored-by: carole-lavillonniere <[email protected]>
Co-authored-by: Cristian Pallarés <[email protected]>
Co-authored-by: Laxman Reddy <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants