/host-prefix-testing

Testing host prefix behavior for AWS SDKs when using custom endpoint

Primary LanguageJavaScriptMIT LicenseMIT

AWS SDK Testing for Host Prefixes using a custom Endpoint

The test suites for javascript-aws-sdk-v3 and python-botocore demonstrate that host prefixes break with incompatible custom endpoints such as sync-127.0.0.1 or sync-localhost.

AWS reference guide for custom endpoints: https://docs.aws.amazon.com/sdkref/latest/guide/feature-ss-endpoints.html

Reproducer

Requirements: Node.js (e.g., v22.14.0) and Python (e.g., 3.11.7)

  1. Install and start LocalStack (community version is sufficient)
  2. Install dependencies via make install
  3. Run tests via make test

JavaScript AWS SDK 3.830.0

The test case test_host_prefix_endpoint_url demonstrates the two failure scenarios for the custom endpoints:

  • ❌ http://127.0.0.1:4566 creates a technically unresolvable host sync-127.0.0.1
  • ❌ http://localhost:4566 creates a technically unresolvable host sync-localhost (unless modifying /etc/hosts)
  • ✅ http://localhost.localstack.cloud:4566 works unless DNS rebind protection blocks resolving the DNS name to 127.0.0.1 using public LocalStack DNS entries. In this example, our DNS entry resolves sync-localhost.localstack.cloud to 127.0.0.1. Background blog post: How we are making connecting to LocalStack easier

The test case test_no_host_prefix_endpoint_url succeeds to demonstrate that disabling the host prefix using disableHostPrefix: true (hostPrefixEnabled is deprecated) works.

Python botocore 1.38.38

The test case test_host_prefix_endpoint_url demonstrates the two failure scenarios for the custom endpoints:

  • ❌ http://127.0.0.1:4566 creates a technically unresolvable host sync-127.0.0.1
  • ❌ http://localhost:4566 creates a technically unresolvable host sync-localhost (unless modifying /etc/hosts)
  • ✅ http://localhost.localstack.cloud:4566 works unless DNS rebind protection blocks resolving the DNS name to 127.0.0.1 using public LocalStack DNS entries. In this example, our DNS entry resolves sync-localhost.localstack.cloud to 127.0.0.1. Background blog post: How we are making connecting to LocalStack easier

The test case test_no_host_prefix_endpoint_url succeeds to demonstrate that omitting the host prefix using inject_host_prefix=False works.