Amazon S3 Customizations#

S3 Bucket Addressing#

Clients for Amazon S3 SHOULD expose multiple levels of configuration for bucket addressing: environment, file, client, and operation. Settings for bucket addressing should be resolved closest to the operation. Most bucket addressing configuration settings compose together. The following table is a non-exhaustive list of combinations showing the expected precedence orders for the S3 Bucket Virtual Hosting settings:

Environment	File	Client	Operation	Resolved
virtual-host	unset	unset	unset	virtual-host
path	virtual-host	unset	unset	virtual-host
unset	unset	virtual-host	path	path
path	virtual-host	unset	unset	virtual-host
unset	virtual-host	path	unset	path

S3 Bucket Virtual Hosting#

A client for Amazon S3 MUST expose the option to use virtual hosting for addressing a bucket. Configurations MUST support the default of using virtual hosting, explicitly configuring virtual hosting, and explicitly configuring the path-style requests. When set to virtual hosting, clients MUST remove the bucket name from the request URI and MUST prepend it to the request host. When set to path-style, clients MUST NOT perform this action and MUST use the modeled HTTP bindings for the request.

Style	Host	URI
virtual	bucketname.s3.us-west-2.amazonaws.com	/
path	s3.us-west-2.amazonaws.com	/bucketname

S3 Dual-Stack Endpoints#

A client for Amazon S3 MUST expose the option to use dual-stack endpoints for addressing a bucket. Configurations MUST default this setting to being disabled. When enabled, the string literal ".dualstack" is placed after S3's endpointPrefix of "s3" and before the region in the host for the request. Clients MUST have the S3 Bucket Virtual Hosting setting resolved to "virtual" to enable this setting.

DualStack Setting	Host
Disabled	bucketname.s3.us-west-2.amazonaws.com
Enabled	bucketname.s3.dualstack.us-west-2.amazonaws.com

S3 Transfer Acceleration Endpoints#

A client for Amazon S3 MUST expose the option to use S3 transfer acceleration for addressing a bucket. Configurations MUST default this setting to being disabled. When enabled, the string literal "s3-accelerate" MUST replace the S3's endpointPrefix of "s3" and MUST remove the resolved region from the host. Clients MUST have the S3 Bucket Virtual Hosting setting resolved to "virtual" to enable this setting.

Transfer Acceleration Setting	Host
Disabled	bucketname.s3.us-west-2.amazonaws.com
Enabled	bucketname.s3-accelerate.us-west-2.amazonaws.com

TODO: Add the other bucket addressing customizations and more.

S3 Traits#

`aws.customizations#s3UnwrappedXmlOutput` trait#

Summary: Indicates the response body from S3 is not wrapped in the AWS restXml protocol operation-level XML node.
Trait selector: operation
Value type: Annotation trait

Consider the following abridged model of S3's GetBucketLocation operation:

$version: "2"

use aws.customizations#s3UnwrappedXmlOutput

@http(uri: "/GetBucketLocation", method: "GET")
@s3UnwrappedXmlOutput
operation GetBucketLocation {
    input: GetBucketLocationInput
    output: GetBucketLocationOutput
}

@output
@xmlName("LocationConstraint")
structure GetBucketLocationOutput {
    LocationConstraint: BucketLocationConstraint
}

enum BucketLocationConstraint {
    us_west_2 = "us-west-2"
}

Since this operation is modeled with @s3UnwrappedXmlOutput, an Amazon S3 client should expect the response from S3 to be unwrapped as shown below:

<LocationConstraint xmlns="http://s3.amazonaws.com/doc/2006-03-01/">us-west-2</LocationConstraint>

Without @s3UnwrappedXmlOutput on the operation, the response would be expected to be wrapped with the AWS restXml protocol operation-level XML node:

<LocationConstraint xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <LocationConstraint>us-west-2</LocationConstraint>
</LocationConstraint>

A client for Amazon S3 MUST understand the @s3UnwrappedXmlOutput trait in order to properly handle the output for the GetBucketLocation operation.