/s3-endpoint-url-testing

Testing endpoint URL behavior for AWS SDKs

Primary LanguageJavaScriptMIT LicenseMIT

AWS SDK Testing endpoint URL for S3

The test suite for the javascript-aws-sdk-v3 demonstrates the different default behavior compared to python-botocore for virtual-host vs. path-style S3 requests.

Background: Path-Style and Virtual Hosted-Style Requests

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

JavaScript offers a boolean option forcePathStyle = true | false rather than a more flexible string-based option for addressing_style → hence forcing virtual doesn’t exist in the SDK

The two failures in the default case (i.e., undefined) are unexpected and should work following the AWS documentation of AWS_ENDPOINT_URL.

Endpoint URL forcePathStyle Actual Addressing Style Test Result Request URL
http://localhost.localstack.cloud:4566 undefined virtual ❌ http://my-unique-localstack-bucket-name.localhost.localstack.cloud:4566/
http://localhost.localstack.cloud:4566 false virtual ❌ http://my-unique-localstack-bucket-name.localhost.localstack.cloud:4566/
http://localhost.localstack.cloud:4566 true path ✅ http://localhost.localstack.cloud:4566/my-unique-localstack-bucket-name/HelloWorld.txt
http://s3.localhost.localstack.cloud:4566 undefined virtual ✅ http://my-unique-localstack-bucket-name.s3.localhost.localstack.cloud:4566/HelloWorld.txt
http://s3.localhost.localstack.cloud:4566 false virtual ✅ http://my-unique-localstack-bucket-name.s3.localhost.localstack.cloud:4566/HelloWorld.txt
http://s3.localhost.localstack.cloud:4566 true path ✅ http://s3.localhost.localstack.cloud:4566/my-unique-localstack-bucket-name/HelloWorld.txt
http://localhost:4566 undefined virtual ❌ http://my-unique-localstack-bucket-name.localhost:4566/
http://localhost:4566 false virtual ❌ http://my-unique-localstack-bucket-name.localhost:4566/
http://localhost:4566 true path ✅ http://localhost:4566/my-unique-localstack-bucket-name/HelloWorld.txt
http://127.0.0.1:4566 undefined path ✅ http://127.0.0.1:4566/my-unique-localstack-bucket-name/HelloWorld.txt
http://127.0.0.1:4566 false path ✅ http://127.0.0.1:4566/my-unique-localstack-bucket-name/HelloWorld.txt
http://127.0.0.1:4566 true path ✅ http://127.0.0.1:4566/my-unique-localstack-bucket-name/HelloWorld.txt

Python botocore 1.38.38

The two failures are expected:

  • The failure for http://my-unique-localstack-bucket-name.localhost.localstack.cloud:4566/ is expected because without the s3. endpoint prefix, LocalStack cannot reliably determine whether such virtual-host-style requests are actual S3 requests.
  • The failure for http://my-unique-localstack-bucket-name.localhost:4566/ depends on the system configuration (testing on macOS 14.6.1). Some systems can resolve subdomains for localhost.
Endpoint URL Addressing Style Actual Addressing Style Test Result Request URL
http://localhost.localstack.cloud:4566 auto path ✅ http://localhost.localstack.cloud:4566/my-unique-localstack-bucket-name/HelloWorld.txt
http://localhost.localstack.cloud:4566 virtual virtual ❌ http://my-unique-localstack-bucket-name.localhost.localstack.cloud:4566/
http://localhost.localstack.cloud:4566 path path ✅ http://localhost.localstack.cloud:4566/my-unique-localstack-bucket-name/HelloWorld.txt
http://s3.localhost.localstack.cloud:4566 auto path ✅ http://s3.localhost.localstack.cloud:4566/my-unique-localstack-bucket-name/HelloWorld.txt
http://s3.localhost.localstack.cloud:4566 virtual virtual ✅ http://my-unique-localstack-bucket-name.s3.localhost.localstack.cloud:4566/HelloWorld.txt
http://s3.localhost.localstack.cloud:4566 path path ✅ http://s3.localhost.localstack.cloud:4566/my-unique-localstack-bucket-name/HelloWorld.txt
http://localhost:4566 auto path ✅ http://localhost:4566/my-unique-localstack-bucket-name/HelloWorld.txt
http://localhost:4566 virtual virtual ❌ http://my-unique-localstack-bucket-name.localhost:4566/
http://localhost:4566 path path ✅ http://localhost:4566/my-unique-localstack-bucket-name/HelloWorld.txt
http://127.0.0.1:4566 auto path ✅ http://127.0.0.1:4566/my-unique-localstack-bucket-name/HelloWorld.txt
http://127.0.0.1:4566 virtual path ✅ http://127.0.0.1:4566/my-unique-localstack-bucket-name/HelloWorld.txt
http://127.0.0.1:4566 path path ✅ http://127.0.0.1:4566/my-unique-localstack-bucket-name/HelloWorld.txt