feat(handler): Add custom header to all AWS responses from LocalStack #12769

gregfurman · 2025-06-17T23:42:42Z

Motivation

This PR adds a custom header to all service responses -- allowing us to distinguish whether a request orignates from LocalStack or AWS.

Changes

Adds a LOCALSTACK_RESPONSE_HEADER_ENABLED environment variable that is opt-out by default.
When LOCALSTACK_RESPONSE_HEADER_ENABLED is truthy, a handler is added to the response chain that adds a x-localstack: true header to all responses from LocalStack gateway.

github-actions · 2025-06-17T23:51:48Z

S3 Image Test Results (AMD64 / ARM64)

2 files 2 suites 8m 25s ⏱️
510 tests 460 ✅ 50 💤 0 ❌
1 020 runs 920 ✅ 100 💤 0 ❌

Results for commit 6c75361.

♻️ This comment has been updated with latest results.

github-actions · 2025-06-17T23:53:12Z

Test Results - Preflight, Unit

21 727 tests ±0 20 070 ✅ ±0 6m 11s ⏱️ ±0s
1 suites ±0 1 657 💤 ±0
1 files ±0 0 ❌ ±0

Results for commit 6c75361. ± Comparison against base commit 3d56935.

♻️ This comment has been updated with latest results.

github-actions · 2025-06-18T00:01:59Z

Test Results (amd64) - Acceptance

7 tests ±0 5 ✅ ±0 3m 7s ⏱️ -1s
1 suites ±0 2 💤 ±0
1 files ±0 0 ❌ ±0

Results for commit 6c75361. ± Comparison against base commit 3d56935.

♻️ This comment has been updated with latest results.

github-actions · 2025-06-18T00:16:54Z

Test Results - Alternative Providers

988 tests +1 622 ✅ +33 34m 23s ⏱️ + 4m 59s
4 suites ±0 366 💤 - 32
4 files ±0 0 ❌ ± 0

Results for commit f3f9475. ± Comparison against base commit 67b3da6.

This pull request skips 1 and un-skips 34 tests.

tests.aws.services.cloudformation.v2.ported_from_v1.resources.test_stack_sets ‑ test_create_stack_set_with_stack_instances

tests.aws.services.cloudformation.v2.ported_from_v1.api.test_stacks.TestStacksApi ‑ test_update_stack_with_same_template_withoutchange
tests.aws.services.cloudformation.v2.ported_from_v1.api.test_templates ‑ test_create_stack_from_s3_template_url[http_host]
tests.aws.services.cloudformation.v2.ported_from_v1.api.test_templates ‑ test_create_stack_from_s3_template_url[http_invalid]
tests.aws.services.cloudformation.v2.ported_from_v1.api.test_templates ‑ test_create_stack_from_s3_template_url[http_path]
tests.aws.services.cloudformation.v2.ported_from_v1.api.test_templates ‑ test_create_stack_from_s3_template_url[s3_url]
tests.aws.services.cloudformation.v2.ported_from_v1.engine.test_conditions.TestCloudFormationConditions ‑ test_conditional_in_conditional[dev-us-west-2]
tests.aws.services.cloudformation.v2.ported_from_v1.engine.test_conditions.TestCloudFormationConditions ‑ test_conditional_in_conditional[production-us-east-1]
tests.aws.services.cloudformation.v2.ported_from_v1.engine.test_conditions.TestCloudFormationConditions ‑ test_simple_condition_evaluation_deploys_resource
tests.aws.services.cloudformation.v2.ported_from_v1.engine.test_conditions.TestCloudFormationConditions ‑ test_simple_condition_evaluation_doesnt_deploy_resource
tests.aws.services.cloudformation.v2.ported_from_v1.engine.test_mappings.TestCloudFormationMappings ‑ test_simple_mapping_working
…

♻️ This comment has been updated with latest results.

github-actions · 2025-06-18T00:37:44Z

Test Results (amd64) - Integration, Bootstrap

5 files 5 suites 2h 20m 51s ⏱️
5 251 tests 4 325 ✅ 926 💤 0 ❌
5 257 runs 4 325 ✅ 932 💤 0 ❌

Results for commit 6c75361.

♻️ This comment has been updated with latest results.

github-actions · 2025-06-18T00:40:46Z

LocalStack Community integration with Pro

2 files ±0 2 suites ±0 1h 44m 58s ⏱️ +8s
4 894 tests ±0 4 120 ✅ ±0 774 💤 ±0 0 ❌ ±0
4 896 runs ±0 4 120 ✅ ±0 776 💤 ±0 0 ❌ ±0

Results for commit 6c75361. ± Comparison against base commit 3d56935.

♻️ This comment has been updated with latest results.

tiurin

Reviewed and tested env variable in a pairing session.

anisaoshafi · 2025-06-20T09:52:09Z

localstack-core/localstack/config.py

@@ -1245,6 +1245,9 @@ def use_custom_dns():
 # This flag enables `connect_to` to be in-memory only and not do networking calls
 IN_MEMORY_CLIENT = is_env_true("IN_MEMORY_CLIENT")

+# This flag enables all responses from LocalStack to contain a `x-localstack` HTTP header.


dismiss: would rephrase this that flag "disables" this header from being set in response. default: True.

just a heads up to add the env var in public docs: https://docs.localstack.cloud/references/configuration/

anisaoshafi · 2025-06-20T09:57:31Z

tests/aws/conftest.py

@@ -107,6 +108,26 @@ def _infrastructure_setup(
    return _infrastructure_setup


+@pytest.hookimpl
+def pytest_runtest_setup(item):


would be nice to add a small high-level docstring/comment what this fixture was added for, so one can understand it in the code without having to open the PR where it was introduced for additional context.

e.g: """ fixture that skips header x-localstack from snapshot evaluation"""

anisaoshafi · 2025-06-20T10:06:00Z

tests/aws/conftest.py

+
+    # Otherwise, dynamically inject a path to the custom header inside all skip_snapshot_verify markers paths.
+    # If a path parameter is None, it's assumed that all paths are skipped.
+    for mark in skip_markers:


question: there are some snapshot tests example where path parameter is not explicitly set, but just the list with the item is passed. Is that covered by these conditions?

@markers.snapshot.skip_snapshot_verify( [ "$..Invalidation.Status", # In real AWS it can be still in progress "$..Location", # not currently supported ] )

Huh that is a good question 🤔 Let me see if the kwargs accounts for this

OK damn. You're correct. This is not accounted for. Nice catch!

Update on this... looks like paths are not skipped when added as args as opposed to kwargs 💀

That means the test you linked actually skips all paths.

anisaoshafi

nice and clean, good job @gregfurman 👏🏼
I liked the logic for skipping the x-localstack header check from snapshot matching.

dfangl

I like the new approach way more!
Just one question: Did you run an -ext run as well? And did you check if there are any lists of header keys where this could end up? (your logic only removes them from dicts)

dfangl

LGTM!

dfangl · 2025-06-25T16:37:26Z

tests/aws/conftest.py

@@ -118,6 +118,9 @@ def snapshot(request, _snapshot_session: SnapshotSession, account_id, region_nam
        RegexTransformer(f"arn:{get_partition(region_name)}:", "arn:<partition>:"), priority=2
    )

+    # Removes the 'x-localstack' header from all responses
+    _snapshot_session.add_transformer(_snapshot_session.transform.remove_key("x-localstack"))


Nit: We could reference the constant for the header here

Yeah fair. I originally did this but realised it's more explicit to add the string literal over referencing the constant. Will add in a follow-up.

gregfurman added this to the 4.6 milestone Jun 17, 2025

gregfurman requested a review from joe4dev June 17, 2025 23:42

gregfurman self-assigned this Jun 17, 2025

gregfurman added the semver: minor Non-breaking changes which can be included in minor releases, but not in patch releases label Jun 17, 2025

gregfurman marked this pull request as ready for review June 18, 2025 07:45

gregfurman requested a review from thrau as a code owner June 18, 2025 07:45

gregfurman requested review from MEPalma, bentsku and dominikschubert as code owners June 18, 2025 21:55

gregfurman force-pushed the add/infr/is-localstack-check branch from e3c1dcf to 0447cfd Compare June 19, 2025 08:31

gregfurman requested review from tiurin and anisaoshafi and removed request for dominikschubert, bentsku and MEPalma June 19, 2025 11:00

tiurin approved these changes Jun 20, 2025

View reviewed changes

anisaoshafi reviewed Jun 20, 2025

View reviewed changes

anisaoshafi approved these changes Jun 20, 2025

View reviewed changes

gregfurman requested a review from steffyP as a code owner June 23, 2025 13:13

gregfurman requested review from dfangl and removed request for thrau and steffyP June 23, 2025 13:15

dfangl reviewed Jun 25, 2025

View reviewed changes

gregfurman added 10 commits June 25, 2025 11:36

feat(handler): Add custom header to all AWS responses from LocalStack

93a42bd

Make the header opt-out

cbc48c7

Skip x-localstack header in all snapshot tests

86d31b6

Add fixture that adds x-localstack to all skip paths

043aa33

Skip x-localstack header in all snapshot tests

847b65c

Fix linting issue on rebase

a133369

Rework adding skip to all snapshot paths

b88543e

Only ever add extra path when snapshot fixture is used

e0cfd28

Address paths in args

cf47447

Use a generic transformer to entirely remove header from snapshot

6c75361

gregfurman force-pushed the add/infr/is-localstack-check branch from f3f9475 to 6c75361 Compare June 25, 2025 09:36

dfangl approved these changes Jun 25, 2025

View reviewed changes

gregfurman merged commit 25552f2 into master Jun 25, 2025
46 checks passed

gregfurman deleted the add/infr/is-localstack-check branch June 25, 2025 16:58

Uh oh!

feat(handler): Add custom header to all AWS responses from LocalStack #12769

feat(handler): Add custom header to all AWS responses from LocalStack #12769

Uh oh!

Conversation

gregfurman commented Jun 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

Changes

Uh oh!

github-actions bot commented Jun 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

S3 Image Test Results (AMD64 / ARM64)

Uh oh!

github-actions bot commented Jun 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Test Results - Preflight, Unit

Uh oh!

github-actions bot commented Jun 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Test Results (amd64) - Acceptance

Uh oh!

github-actions bot commented Jun 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Test Results - Alternative Providers

Uh oh!

github-actions bot commented Jun 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Test Results (amd64) - Integration, Bootstrap

Uh oh!

github-actions bot commented Jun 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

LocalStack Community integration with Pro

Uh oh!

tiurin left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

anisaoshafi left a comment

Choose a reason for hiding this comment

Uh oh!

dfangl left a comment

Choose a reason for hiding this comment

Uh oh!

dfangl left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

gregfurman commented Jun 17, 2025 •

edited

Loading

github-actions bot commented Jun 17, 2025 •

edited

Loading

github-actions bot commented Jun 17, 2025 •

edited

Loading

github-actions bot commented Jun 18, 2025 •

edited

Loading

github-actions bot commented Jun 18, 2025 •

edited

Loading

github-actions bot commented Jun 18, 2025 •

edited

Loading

github-actions bot commented Jun 18, 2025 •

edited

Loading

tiurin left a comment •

edited

Loading