Add @s3UnwrappedXmlOutput trait to support S3's GetBucketLocation

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

@@ -130,3 +130,104 @@ resolved to "virtual" to enable this setting.
 .. _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
+
+S3 Traits
+=========
+
+``aws.customizations#s3UnwrappedXmlOutput`` trait
+-------------------------------------------------
+
+Summary
+    Indicates the response body from S3 is not wrapped in the :ref:`aws-restxml-protocol` operation-level XML node.
+
+Trait selector
+    ``operation``
+
+Value type
+    Annotation trait
+
+Consider the following *abridged* model of S3's ``GetBucketLocation`` operation:
+
+.. tabs::
+
+    .. code-tab:: smithy
+
+        use aws.customizations#s3UnwrappedXmlOutput
+
+        @enum([
+            { value: "us-west-2", name: "us_west_2" }
+        ])
+        string BucketLocationConstraint
+
+        @xmlName("LocationConstraint")
+        structure GetBucketLocationOutput {
+            LocationConstraint: BucketLocationConstraint,
+        }
+
+        @http(uri: "/GetBucketLocation", method: "GET")
+        @s3UnwrappedXmlOutput
+        operation GetBucketLocation {
+            output: GetBucketLocationOutput,
+        }
+
+    .. code-tab:: json
+
+        {
+            "smithy": "1.0",
+            "shapes": {
+                "smithy.example#BucketLocationConstraint": {
+                    "type": "string",
+                    "traits": {
+                        "smithy.api#enum": [
+                            {
+                                "value": "us-west-2",
+                                "name": "us_west_2"
+                            }
+                        ]
+                    }
+                },
+                "smithy.example#GetBucketLocationOutput": {
+                    "type": "structure",
+                    "members": {
+                        "LocationConstraint": {
+                            "target": "smithy.example#BucketLocationConstraint"
+                        }
+                    },
+                    "traits": {
+                        "smithy.api#xmlName": "LocationConstraint"
+                    }
+                },
+                "smithy.example#GetBucketLocation": {
+                    "type": "operation",
+                    "output": {
+                        "target": "smithy.example#GetBucketLocationOutput"
+                    },
+                    "traits": {
+                        "smithy.api#http": {
+                            "uri": "/GetBucketLocation",
+                            "method": "GET"
+                        },
+                        "aws.customizations#s3UnwrappedXmlOutput": {}
+                    }
+                }
+            }
+        }
+
+Since this operation is modeled with ``@s3UnwrappedXmlOutput``,
+an Amazon S3 client should expect the response from S3 to be unwrapped as shown below:
+
+.. code-block:: xml
+
+    <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 :ref:`aws-restxml-protocol` operation-level XML node:
+
+.. code-block:: xml
+
+    <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.

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

@@ -15,8 +15,10 @@ namespace com.amazonaws.s3
 
 use aws.api#service
 use aws.auth#sigv4
+use aws.customizations#s3UnwrappedXmlOutput
 use aws.protocols#restXml
 use smithy.test#httpRequestTests
+use smithy.test#httpResponseTests
 
 @service(
     sdkId: "S3",
@@ -268,6 +270,27 @@ operation ListObjectsV2 {
     ],
 }
 
+
+@httpResponseTests([{
+        id: "GetBucketLocationUnwrappedOutput",
+        documentation: """
+            S3 clients should use the @s3UnwrappedXmlOutput trait to determine
+            that the response shape is not wrapped in a restxml operation-level XML node.
+        """,
+        code: 200,
+        body: "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<LocationConstraint xmlns=\"http://s3.amazonaws.com/doc/2006-03-01/\">us-west-2</LocationConstraint>",
+        params: {
+            "LocationConstraint": "us-west-2"
+        },
+        protocol: restXml
+}])
+@http(uri: "/GetBucketLocation", method: "GET")
+@s3UnwrappedXmlOutput
+operation GetBucketLocation {
+    output: GetBucketLocationOutput,
+}
+
+
 structure CommonPrefix {
     Prefix: Prefix,
 }
@@ -452,3 +475,14 @@ integer Size
 string StartAfter
 
 string Token
+
+@enum([
+    { value: "us-west-2", name: "us_west_2" }
+])
+string BucketLocationConstraint
+
+@xmlName("LocationConstraint")
+structure GetBucketLocationOutput {
+    LocationConstraint: BucketLocationConstraint,
+}
+

smithy-aws-traits/src/main/java/software/amazon/smithy/aws/traits/customizations/S3UnwrappedXmlOutputTrait.java

@@ -0,0 +1,39 @@
+/*
+ * Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ * You may not use this file except in compliance with the License.
+ * A copy of the License is located at
+ *
+ *  http://aws.amazon.com/apache2.0
+ *
+ * or in the "license" file accompanying this file. This file is distributed
+ * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+ * express or implied. See the License for the specific language governing
+ * permissions and limitations under the License.
+ */
+
+package software.amazon.smithy.aws.traits.customizations;
+
+import software.amazon.smithy.model.node.Node;
+import software.amazon.smithy.model.node.ObjectNode;
+import software.amazon.smithy.model.shapes.ShapeId;
+import software.amazon.smithy.model.traits.AnnotationTrait;
+
+public final class S3UnwrappedXmlOutputTrait extends AnnotationTrait {
+    public static final ShapeId ID = ShapeId.from("aws.customizations#s3UnwrappedXmlOutput");
+
+    public S3UnwrappedXmlOutputTrait(ObjectNode node) {
+        super(ID, node);
+    }
+
+    public S3UnwrappedXmlOutputTrait() {
+        this(Node.objectNode());
+    }
+
+    public static final class Provider extends AnnotationTrait.Provider<S3UnwrappedXmlOutputTrait> {
+        public Provider() {
+            super(ID, S3UnwrappedXmlOutputTrait::new);
+        }
+    }
+}

smithy-aws-traits/src/main/resources/META-INF/services/software.amazon.smithy.model.traits.TraitService

@@ -9,6 +9,7 @@ software.amazon.smithy.aws.traits.auth.UnsignedPayloadTrait$Provider
 software.amazon.smithy.aws.traits.clientendpointdiscovery.ClientEndpointDiscoveryTrait$Provider
 software.amazon.smithy.aws.traits.clientendpointdiscovery.ClientEndpointDiscoveryIdTrait$Provider
 software.amazon.smithy.aws.traits.clientendpointdiscovery.ClientDiscoveredEndpointTrait$Provider
+software.amazon.smithy.aws.traits.customizations.S3UnwrappedXmlOutputTrait$Provider
 software.amazon.smithy.aws.traits.protocols.AwsQueryErrorTrait$Provider
 software.amazon.smithy.aws.traits.protocols.AwsQueryTrait$Provider
 software.amazon.smithy.aws.traits.protocols.Ec2QueryNameTrait$Provider

smithy-aws-traits/src/main/resources/META-INF/smithy/aws.customizations.json

@@ -0,0 +1,15 @@
+{
+    "smithy": "1.0",
+    "shapes": {
+        "aws.customizations#s3UnwrappedXmlOutput": {
+            "type": "structure",
+            "members": {},
+            "traits": {
+                "smithy.api#trait": {
+                    "selector": "operation"
+                },
+                "smithy.api#documentation": "Indicates the response body from S3 is not wrapped in the aws-restxml-protocol operation-level XML node. Intended to only be used by AWS S3."
+            }
+        }
+    }
+}

smithy-aws-traits/src/main/resources/META-INF/smithy/manifest

@@ -1,3 +1,4 @@
 aws.api.json
 aws.auth.json
+aws.customizations.json
 aws.protocols.json