feat(s3-deployment): add contentEncodingByExtension property for per-file-extension encoding

[pahud]

Issue # (if applicable)

Closes #7090.

Reason for this change

Users serving pre-compressed static websites from S3+CloudFront need to set different Content-Encoding headers based on file extension. Currently, the contentEncoding property applies a single encoding to ALL files in the deployment, which breaks browser decompression when serving mixed content (e.g., .br files with Brotli, .gz files with Gzip, and uncompressed files).

The current workaround requires creating multiple BucketDeployment constructs with prune: false and complex exclude/include filters, resulting in:

• Multiple Lambda invocations (increased cost and deployment time)
• Inability to use the pruning feature
• Complex, error-prone configuration

This feature has strong community interest with 19 👍 reactions on the issue (open since March 2020).

Description of changes

Added a new contentEncodingByExtension property to BucketDeploymentProps that accepts an array of file pattern to encoding mappings. The Lambda handler executes multiple aws s3 sync commands with appropriate --include/--exclude filters and --content-encoding values.

Key changes:

• Added ContentEncodingMapping interface with include (file pattern) and encoding (Content-Encoding value) properties
• Added contentEncodingByExtension optional property to BucketDeploymentProps
• Modified Lambda handler to run multiple sync commands:
  1. First sync excludes files matching encoding patterns (with prune if enabled)
  2. Subsequent syncs handle each encoding pattern with its specific Content-Encoding header
• Added comprehensive unit tests (5 new tests)
• Updated README.md with documentation and usage examples

Usage example:

new s3deploy.BucketDeployment(this, 'DeployWebsite', {
  sources: [s3deploy.Source.asset('./website')],
  destinationBucket: bucket,
  contentEncodingByExtension: [
    { include: '*.br', encoding: 'br' },
    { include: '*.gz', encoding: 'gzip' },
  ],
});

Files modified:

File	Changes
packages/aws-cdk-lib/aws-s3-deployment/lib/bucket-deployment.ts	Added ContentEncodingMapping interface and contentEncodingByExtension property
packages/@aws-cdk/custom-resource-handlers/lib/aws-s3-deployment/bucket-deployment-handler/index.py	Added multi-sync logic for per-extension encoding
packages/aws-cdk-lib/aws-s3-deployment/test/bucket-deployment.test.ts	Added 5 new unit tests
packages/aws-cdk-lib/aws-s3-deployment/README.md	Added documentation section

Describe any new or updated permissions being added

N/A - No IAM permission changes. The Lambda handler continues to use the same S3 permissions it already has for the s3 sync operation.

Description of how you validated changes

• Unit tests: Added 5 new unit tests covering:
  • contentEncodingByExtension property is passed to custom resource
  • contentEncodingByExtension with single mapping
  • contentEncodingByExtension is not set when not specified
  • contentEncodingByExtension can be used with other system metadata
  • contentEncodingByExtension with directory pattern
• Build validation: TypeScript compilation successful, no linting errors
• Test results: All 85 tests passed (including 5 new tests)

Checklist

• My code adheres to the CONTRIBUTING GUIDE and DESIGN GUIDELINES

---

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

[aws-cdk-automation]

The pull request linter fails with the following errors:

❌ Features must contain a change to an integration test file and the resulting snapshot.

If you believe this pull request should receive an exemption, please comment and provide a justification. A comment requesting an exemption should contain the text Exemption Request. Additionally, if clarification is needed, add Clarification Request to a comment.

[pahud]

This PR is going to have impact on existing deployment. I think we should consider #36790 before we are able to continue this PR to minimize the risk on existing deployments.

[github-actions]

⚠️ Experimental Feature: This security report is currently in experimental phase. Results may include false positives and the rules are being actively refined.
Please try merge from main to avoid findings unrelated to the PR.

---

	Tests	Passed ✅	Skipped	Failed
Security Guardian Results	480 ran	480 passed

Test	Result
No test annotations available

• View Security Guardian Results

[github-actions]

⚠️ Experimental Feature: This security report is currently in experimental phase. Results may include false positives and the rules are being actively refined.
Please try merge from main to avoid findings unrelated to the PR.

---

	Tests	Passed ☑️	Skipped	Failed ❌️
Security Guardian Results with resolved templates	480 ran	477 passed		3 failed

Test	Result
Security Guardian Results with resolved templates
packages/@aws-cdk-testing/framework-integ/test/aws-codepipeline-actions/test/integ.pipeline-commands.js.snapshot/aws-cdk-codepipeline-commands.template.json
iam-role-root-principal-needs-conditions.guard	❌ failure
packages/@aws-cdk-testing/framework-integ/test/aws-codepipeline-actions/test/integ.pipeline-ecr-image-scan-action.js.snapshot/codepipeline-ecr-image-scan-action.template.json
iam-role-root-principal-needs-conditions.guard	❌ failure
packages/@aws-cdk-testing/framework-integ/test/aws-codepipeline-actions/test/integ.pipeline-elastic-beanstalk-deploy.js.snapshot/aws-cdk-codepipeline-elastic-beanstalk-deploy.template.json
iam-role-root-principal-needs-conditions.guard	❌ failure

• View Security Guardian Results with resolved templates