Make protocol and auth traits

config/checkstyle/suppressions.xml

@@ -20,4 +20,5 @@
 <suppressions>
     <suppress checks="EqualsHashCode" files="shapes/*"/>
     <suppress checks="InnerAssignment" files="StringUtils"/>
+    <suppress checks="TypeName" files="AwsJson1_0Trait.java|AwsJson1_1Trait.java"/>
 </suppressions>

config/spotbugs/filter.xml

@@ -86,4 +86,10 @@
         <Class name="software.amazon.smithy.utils.IoUtils"/>
         <Bug pattern="RCN_REDUNDANT_NULLCHECK_WOULD_HAVE_BEEN_A_NPE"/>
     </Match>
+
+    <!-- This is a false positive. The value is guarded behind an Objects.requireNonNull -->
+    <Match>
+        <Class name="software.amazon.smithy.model.knowledge.ServiceIndex"/>
+        <Bug pattern="NP_NULL_ON_SOME_PATH_FROM_RETURN_VALUE"/>
+    </Match>
 </FindBugsFilter>

docs/source/guides/building-models/build-config.rst

@@ -437,54 +437,6 @@ orphaned shapes.
     This transformer does not remove shapes from the prelude.
 
 
-.. _includeAuth-transform:
-
-includeAuth
------------
-
-Removes authentication schemes from shapes that do not match one of the
-given arguments (a list of authentication schemes).
-
-.. tabs::
-
-    .. code-tab:: json
-
-        {
-            "version": "1.0",
-            "projections": {
-                "exampleProjection": {
-                    "transforms": [
-                        {"name": "includeAuth", "args": ["aws.v4", "http-basic"]}
-                    ]
-                }
-            }
-        }
-
-
-.. _includeProtocols-transform:
-
-includeProtocols
-----------------
-
-Removes protocols from service shapes that do not match one of the given
-arguments (a list of protocol names).
-
-.. tabs::
-
-    .. code-tab:: json
-
-        {
-            "version": "1.0",
-            "projections": {
-                "exampleProjection": {
-                    "transforms": [
-                        {"name": "includeProtocols", "args": ["aws.rest-json"]}
-                    ]
-                }
-            }
-        }
-
-
 .. _includeTags-transform:
 
 includeTags

docs/source/guides/converting-to-openapi.rst

@@ -114,7 +114,7 @@ The Smithy Gradle plugin relies on a ``smithy-build.json`` file found at the
 root of a project to define the actual process of building the OpenAPI
 specification. The following example defines a ``smithy-build.json`` file
 that builds an OpenAPI specification from a service for the
-``smithy.example#Weather`` service using the ``aws.rest-json-1.1`` protocol:
+``smithy.example#Weather`` service using the ``aws.protocols#restJson1`` protocol:
 
 .. code-block:: json
     :caption: smithy-build.json
@@ -125,7 +125,7 @@ that builds an OpenAPI specification from a service for the
         "plugins": {
             "openapi": {
                 "service": "smithy.example#Weather",
-                "protocol": "aws.rest-json-1.1"
+                "protocol": "aws.protocols#restJson1"
             }
         }
     }
@@ -155,14 +155,18 @@ service (string)
     **Required**. The Smithy service :ref:`shape ID <shape-id>` to convert.
 
 protocol (string)
-    The protocol name to use when converting Smithy to OpenAPI (for example,
-    ``aws.rest-json-1.1``.
+    The protocol shape ID to use when converting Smithy to OpenAPI (for
+    example, ``aws.protocols#restJson1``).
 
     Smithy will try to match the provided protocol name with an implementation
     of ``software.amazon.smithy.openapi.fromsmithy.OpenApiProtocol``
     registered with a service provider implementation of
     ``software.amazon.smithy.openapi.fromsmithy.CoreExtension``.
 
+    .. important::
+
+        This property is required if a service supports multiple protocols.
+
 openapi.tags (boolean)
     Whether or not to include Smithy :ref:`tags <tags-trait>` in the result.
 
@@ -197,8 +201,8 @@ openapi.keepUnusedComponents (boolean)
     created specification.
 
 openapi.aws.jsonContentType (string)
-    Sets the media-type to associate with the JSON payload of ``aws.json-*``
-    and ``aws.rest-json-*`` protocols
+    Sets a custom media-type to associate with the JSON payload of
+    JSON-based protocols.
 
 openapi.forbidGreedyLabels (boolean)
     Set to true to forbid greedy URI labels. By default, greedy labels will
@@ -485,9 +489,6 @@ Other traits that influence API Gateway
 ``aws.api#service``
     TODO
 
-``protocols``
-    TODO
-
 ``aws.apigateway#apiKeySource``
     Specifies the source of the caller identifier that will be used to
     throttle API methods that require a key. This trait is converted into
@@ -532,7 +533,7 @@ Next, you need to create and configure an ``OpenApiConverter``:
     OpenApiConverter converter = OpenApiConverter.create();
 
     // Add any necessary settings...
-    converter.putSetting(OpenApiConstants.PROTOCOL, "aws.rest-json-1.1");
+    converter.putSetting(OpenApiConstants.PROTOCOL, "aws.protocols#restJson1");
 
     // Create a shape ID that points to the service.
     ShapeId serviceShapeId = ShapeId.from("smithy.example#Weather");

docs/source/quickstart.rst

@@ -67,7 +67,7 @@ Smithy supports the following types:
     * - timestamp
       - An instant in time with no UTC offset or timezone. The
         serialization of a timestamp is determined by a
-        :ref:`protocol <protocols-trait>`.
+        :ref:`protocol <protocolDefinition-trait>`.
     * - :ref:`document <document-type>`
       - An untyped JSON-like value.
     * - :ref:`list`
@@ -137,9 +137,9 @@ weather service.
     tools to make them easier to use by other tooling.
 
 Smithy is a *protocol agnostic* IDL, meaning the model defines the interface of
-the API but not its serialization. A :ref:`protocol <protocols-trait>` defines
-how clients and servers communicate and how messages are passed back and forth.
-:ref:`Traits <traits>` can be used to influence how a protocol serializes
+the API but not its serialization. A :ref:`protocol <protocolDefinition-trait>`
+defines how clients and servers communicate and how messages are passed back and
+forth. :ref:`Traits <traits>` can be used to influence how a protocol serializes
 shapes.
 
 

docs/source/spec/amazon-apigateway.rst

@@ -108,9 +108,10 @@ An *authorizer* definition is an object that supports the following properties:
       - Description
     * - scheme
       - ``string``
-      - **Required**. A Smithy authentication scheme name that identifies how
-        a client authenticates. This value MUST reference one of the ``auth``
-        schemes of the :ref:`protocols-trait` attached to the service.
+      - **Required**. A Smithy authentication scheme shape ID that identifies
+        how a client authenticates. This value MUST reference one of the
+        :ref:`authentication schemes <authDefinition-trait>` attached to the
+        service.
     * - type
       - ``string``
       - The type of the authorizer. If specifying information beyond the
@@ -122,7 +123,8 @@ An *authorizer* definition is an object that supports the following properties:
       - ``string``
       - The ``authType`` of the authorizer. This value is used in APIGateway
         exports as ``x-amazon-apigateway-authtype``. This value is set to
-        ``custom`` by default, or ``awsSigv4`` if your scheme is ``aws.v4``.
+        ``custom`` by default, or ``awsSigv4`` if your scheme is
+        :ref:`aws.auth#sigv4 <aws.auth#sigv4-trait>`.
     * - uri
       - ``string``
       - Specifies the authorizer's Uniform Resource Identifier
@@ -182,42 +184,33 @@ An *authorizer* definition is an object that supports the following properties:
         API Gateway will cache authorizer responses. If this field is not set,
         the default value is 300. The maximum value is 3600, or 1 hour.
 
-..
-    TODO: Add IDL example
+.. tabs::
 
-.. code-block:: json
+    .. code-tab:: smithy
 
-    {
-        "smithy": "0.5.0",
-        "shapes": {
-            "ns.foo#Weather": {
-                "type": "service",
-                "version": "2018-03-17",
-                "traits": {
-                    "smithy.api#protocols": [
-                        {
-                            "name": "aws.rest-json",
-                            "auth": [
-                                "aws.v4"
-                            ]
-                        }
-                    ],
-                    "aws.apigateway#authorizer": "arbitrary-name",
-                    "aws.apigateway#authorizers": {
-                        "arbitrary-name": {
-                            "scheme": "aws.v4",
-                            "type": "request",
-                            "uri": "arn:foo:baz",
-                            "credentials": "arn:foo:bar",
-                            "identitySource": "mapping.expression",
-                            "identityValidationExpression": "[A-Z]+",
-                            "resultTtlInSeconds": 100
-                        }
-                    }
-                }
-            }
+        namespace ns.foo
+
+        use aws.apigateway#authorizer
+        use aws.apigateway#authorizers
+        use aws.auth#sigv4
+        use aws.protocols#restJson1
+
+        @restJson1
+        @sigv4(name: "weather")
+        @authorizer("arbitrary-name")
+        @authorizers(
+            "arbitrary-name": {
+                scheme: sigv4,
+                type: "request",
+                uri: "arn:foo:baz",
+                credentials: "arn:foo:bar",
+                identitySource: "mapping.expression",
+                identityValidationExpression: "[A-Z]+",
+                resultTtlInSeconds: 100
+            })
+        service Weather {
+            version: "2018-03-17"
         }
-    }
 
 .. note::
 
@@ -434,14 +427,10 @@ operation within the service.
                 "type": "service",
                 "version": "2018-03-17",
                 "traits": {
-                    "smithy.api#protocols": [
-                        {
-                            "name": "aws.rest-json",
-                            "auth": [
-                                "aws.v4"
-                            ]
-                        }
-                    ],
+                    "aws.protocols#restJson1": true,
+                    "aws.auth#sigv4": {
+                        "name": "weather"
+                    },
                     "aws.apigateway#integration": {
                         "type": "aws",
                         "uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:012345678901:function:HelloWorld/invocations",

docs/source/spec/aws-auth.rst

@@ -0,0 +1,125 @@
+.. _aws-authentication:
+
+=========================
+AWS Authentication Traits
+=========================
+
+This document defines AWS authentication schemes.
+
+.. contents:: Table of contents
+    :depth: 2
+    :local:
+    :backlinks: none
+
+
+.. _aws.auth#sigv4-trait:
+
+``aws.auth#sigv4`` trait
+========================
+
+Trait summary
+    The ``aws.auth#sigv4`` trait adds support for `AWS signature version 4`_
+    to a service.
+Trait selector
+    ``service``
+Trait value
+    An ``object`` that supports the following properties:
+
+    .. list-table::
+        :header-rows: 1
+        :widths: 10 20 70
+
+        * - Property
+          - Type
+          - Description
+        * - name
+          - ``string``
+          - **Required**. The signature version 4 service signing name to use
+            in the `credential scope`_ when signing requests. This value
+            SHOULD match the ``arnNamespace`` property of the
+            :ref:`aws.api#service-trait`.
+
+.. tabs::
+
+    .. code-tab:: smithy
+
+        namespace aws.fooBaz
+
+        use aws.api#service
+        use aws.auth#sigv4
+        use aws.protocols#restJson1
+
+        @service(sdkId: "Some Value")
+        @sigv4(name: "foobaz")
+        @restJson1
+        service FooBaz {
+            version: "2018-03-17",
+        }
+
+    .. code-tab:: json
+
+        {
+            "smithy": "0.5.0",
+            "shapes": {
+                "aws.fooBaz#FooBaz": {
+                    "type": "service",
+                    "version": "2018-03-17",
+                    "traits": {
+                        "aws.protocols#restJson1": true,
+                        "aws.api#service": {
+                            "sdkId": "Some Value"
+                        },
+                        "aws.auth#sigv4": {
+                            "name": "foobaz"
+                        }
+                    }
+                }
+            }
+        }
+
+
+.. _aws.auth#cognitoUserPools-trait:
+
+aws.auth#cognitoUserPools
+=========================
+
+Trait summary
+    The ``aws.auth#cognitoUserPools`` trait adds support for
+    `Amazon Cognito User Pools`_ to a service.
+Trait selector
+    ``service``
+Trait value
+    An ``object`` that supports the following properties:
+
+    .. list-table::
+        :header-rows: 1
+        :widths: 10 20 70
+
+        * - Property
+          - Type
+          - Description
+        * - providerArns
+          - ``[string]``
+          - A list of the Amazon Cognito user pool ARNs. Each element is
+            of this format: ``arn:aws:cognito-idp:{region}:{account_id}:userpool/{user_pool_id}``.
+
+.. code-block:: smithy
+
+    namespace aws.fooBaz
+
+    use aws.api#service
+    use aws.auth#cognitoUserPools
+    use aws.protocols#restJson1
+
+    @service(sdkId: "Some Value")
+    @cognitoUserPools(
+        providerArns: ["arn:aws:cognito-idp:us-east-1:123:userpool/123"])
+    @restJson1
+    service FooBaz {
+        version: "2018-03-17",
+    }
+
+
+.. _AWS signature version 4: https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html
+.. _credential scope: https://docs.aws.amazon.com/general/latest/gr/sigv4-create-string-to-sign.html
+.. _Amazon Cognito User Pools: https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-identity-pools.html