Add start of S3 customizations

This commit updates the S3 configuration to model virtual-hosting.
It adds test cases and documentation for a subset of the bucket
addressing methods: virtual hosts, path-style, dual-stack, and
transfer acceleration.

docs/source/1.0/spec/aws/customizations/index.rst

@@ -10,3 +10,4 @@ AWS Service Customizations
     apigateway-customizations
     glacier-customizations
     machinelearning-customizations
+    s3-customizations

docs/source/1.0/spec/aws/customizations/s3-customizations.rst

@@ -0,0 +1,132 @@
+========================
+Amazon S3 Customizations
+========================
+
+.. contents:: Table of contents
+    :depth: 2
+    :local:
+    :backlinks: none
+
+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 :ref:`s3-bucket-virtual-hosting` settings:
+
+.. list-table::
+    :header-rows: 1
+    :widths: 20 20 20 20 20
+
+    * - 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:
+
+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.
+
+.. list-table::
+    :header-rows: 1
+    :widths: 20 60 20
+
+    * - 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
+:ref:`service-endpoint-prefix` of "s3" and before the region in the host for
+the request. Clients MUST have the :ref:`s3-bucket-virtual-hosting` setting
+resolved to "virtual" to enable this setting.
+
+.. list-table::
+    :header-rows: 1
+    :widths: 20 80
+
+    * - 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 :ref:`service-endpoint-prefix` of "s3" and MUST remove the resolved region
+from the host. Clients MUST have the :ref:`s3-bucket-virtual-hosting` setting
+resolved to "virtual" to enable this setting.
+
+.. list-table::
+    :header-rows: 1
+    :widths: 20 80
+
+    * - 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.*
+
+
+.. _virtual hosting: https://docs.aws.amazon.com/AmazonS3/latest/dev/VirtualHosting.html
+.. _path-style requests: https://docs.aws.amazon.com/AmazonS3/latest/dev/VirtualHosting.html#path-style-access
+.. _dual-stack endpoints: https://docs.aws.amazon.com/AmazonS3/latest/dev/dual-stack-endpoints.html
+.. _transfer acceleration: https://docs.aws.amazon.com/AmazonS3/latest/dev/transfer-acceleration.html

smithy-aws-protocol-tests/model/aws-config.smithy

@@ -69,6 +69,7 @@ structure FileConfigSettings {
 
 /// Configuration specific to S3.
 structure S3Config {
+    addressing_style: S3AddressingStyle,
     use_accelerate_endpoint: Boolean,
     use_dualstack_endpoint: Boolean,
 }
@@ -95,6 +96,23 @@ structure RetryConfig {
     max_attempts: Short,
 }
 
+/// Controls the S3 addressing bucket style.
+@enum([
+    {
+        value: "auto",
+        name: "AUTO",
+    },
+    {
+        value: "path",
+        name: "PATH",
+    },
+    {
+        value: "virtual",
+        name: "VIRTUAL",
+    }
+])
+string S3AddressingStyle
+
 /// Controls the strategy used for retries.
 @enum([
     {

smithy-aws-protocol-tests/model/restXml/services/s3.smithy

@@ -42,6 +42,214 @@ service AmazonS3 {
     ],
 }
 
+
+// TODO This needs more test cases to enforce the setting
+// resolution of config options, ARN based addressing, and more.
+@httpRequestTests([
+    {
+        id: "S3DefaultAddressing",
+        documentation: "S3 clients should map the default addressing style to virtual host.",
+        protocol: restXml,
+        method: "GET",
+        uri: "/",
+        host: "s3.us-west-2.amazonaws.com",
+        resolvedHost: "mybucket.s3.us-west-2.amazonaws.com",
+        body: "",
+        queryParams: [
+            "list-type=2",
+        ],
+        params: {
+            Bucket: "mybucket",
+        },
+        vendorParamsShape: aws.protocoltests.config#AwsConfig,
+        vendorParams: {
+            scopedConfig: {
+                client: {
+                    region: "us-west-2",
+                },
+            },
+        },
+    },
+    {
+        id: "S3VirtualHostAddressing",
+        documentation: "S3 clients should support the explicit virtual host addressing style.",
+        protocol: restXml,
+        method: "GET",
+        uri: "/",
+        host: "s3.us-west-2.amazonaws.com",
+        resolvedHost: "mybucket.s3.us-west-2.amazonaws.com",
+        body: "",
+        queryParams: [
+            "list-type=2",
+        ],
+        params: {
+            Bucket: "mybucket",
+        },
+        vendorParamsShape: aws.protocoltests.config#AwsConfig,
+        vendorParams: {
+            scopedConfig: {
+                client: {
+                    region: "us-west-2",
+                    s3: {
+                        addressing_style: "virtual",
+                    },
+                },
+            },
+        },
+    },
+    {
+        id: "S3PathAddressing",
+        documentation: "S3 clients should support the explicit path addressing style.",
+        protocol: restXml,
+        method: "GET",
+        uri: "/mybucket",
+        host: "s3.us-west-2.amazonaws.com",
+        resolvedHost: "s3.us-west-2.amazonaws.com",
+        body: "",
+        queryParams: [
+            "list-type=2",
+        ],
+        params: {
+            Bucket: "mybucket",
+        },
+        vendorParamsShape: aws.protocoltests.config#AwsConfig,
+        vendorParams: {
+            scopedConfig: {
+                client: {
+                    region: "us-west-2",
+                    s3: {
+                        addressing_style: "path",
+                    },
+                },
+            },
+        },
+    },
+    {
+        id: "S3VirtualHostDualstackAddressing",
+        documentation: """
+            S3 clients should support the explicit virtual host
+            addressing style with Dualstack.""",
+        protocol: restXml,
+        method: "GET",
+        uri: "/",
+        host: "s3.us-west-2.amazonaws.com",
+        resolvedHost: "mybucket.s3.dualstack.us-west-2.amazonaws.com",
+        body: "",
+        queryParams: [
+            "list-type=2",
+        ],
+        params: {
+            Bucket: "mybucket",
+        },
+        vendorParamsShape: aws.protocoltests.config#AwsConfig,
+        vendorParams: {
+            scopedConfig: {
+                client: {
+                    region: "us-west-2",
+                    s3: {
+                        addressing_style: "virtual",
+                        use_dualstack_endpoint: true,
+                    },
+                },
+            },
+        },
+    },
+    {
+        id: "S3VirtualHostAccelerateAddressing",
+        documentation: """
+            S3 clients should support the explicit virtual host
+            addressing style with S3 Accelerate.""",
+        protocol: restXml,
+        method: "GET",
+        uri: "/",
+        host: "s3.us-west-2.amazonaws.com",
+        resolvedHost: "mybucket.s3-accelerate.amazonaws.com",
+        body: "",
+        queryParams: [
+            "list-type=2",
+        ],
+        params: {
+            Bucket: "mybucket",
+        },
+        vendorParamsShape: aws.protocoltests.config#AwsConfig,
+        vendorParams: {
+            scopedConfig: {
+                client: {
+                    region: "us-west-2",
+                    s3: {
+                        addressing_style: "virtual",
+                        use_accelerate_endpoint: true,
+                    },
+                },
+            },
+        },
+    },
+    {
+        id: "S3VirtualHostDualstackAccelerateAddressing",
+        documentation: """
+            S3 clients should support the explicit virtual host
+            addressing style with Dualstack and S3 Accelerate.""",
+        protocol: restXml,
+        method: "GET",
+        uri: "/",
+        host: "s3.us-west-2.amazonaws.com",
+        resolvedHost: "mybucket.s3-accelerate.dualstack.amazonaws.com",
+        body: "",
+        queryParams: [
+            "list-type=2",
+        ],
+        params: {
+            Bucket: "mybucket",
+        },
+        vendorParamsShape: aws.protocoltests.config#AwsConfig,
+        vendorParams: {
+            scopedConfig: {
+                client: {
+                    region: "us-west-2",
+                    s3: {
+                        addressing_style: "virtual",
+                        use_dualstack_endpoint: true,
+                        use_accelerate_endpoint: true,
+                    },
+                },
+            },
+        },
+    },
+    {
+        id: "S3OperationAddressingPreferred",
+        documentation: """
+            S3 clients should resolve to the addressing style of the
+            operation if defined on both the client and operation.""",
+        protocol: restXml,
+        method: "GET",
+        uri: "/",
+        host: "s3.us-west-2.amazonaws.com",
+        resolvedHost: "mybucket.s3.us-west-2.amazonaws.com",
+        body: "",
+        queryParams: [
+            "list-type=2",
+        ],
+        params: {
+            Bucket: "mybucket",
+        },
+        vendorParamsShape: aws.protocoltests.config#AwsConfig,
+        vendorParams: {
+            scopedConfig: {
+                client: {
+                    region: "us-west-2",
+                    s3: {
+                        addressing_style: "path",
+                    },
+                },
+                operation: {
+                    s3: {
+                        addressing_style: "virtual",
+                    },
+                },
+            },
+        },
+    },
+])
 @http(
     method: "GET",
     uri: "/{Bucket}?list-type=2",