Relax httpPrefixHeaders constraint

This commit relaxes the constraint on the `@httpPrefixHeaders` trait
when the prefix is set to an empty string, lowering the validation's
severity to a NOTE. This case is usualy meant for proxying all headers
through a request or response, where conflicts are well understood.

This change comes with updated guidance to simplify the strategy for
serializing HTTP messages, examples for these use cases, guidance on
how to do this in a readable way, and other minor HTTP binding
specification cleanup.

Author: kstich

docs/source-2.0/spec/http-bindings.rst

@@ -643,8 +643,8 @@ Conflicts with
    :ref:`httpPayload-trait`,
    :ref:`httpResponseCode-trait`
 
-``httpHeader`` serialization rules:
------------------------------------
+Serialization rules
+-------------------
 
 * When a :ref:`list <list>` shape is targeted, each member of the shape is
   serialized as a separate HTTP header either by concatenating the values
@@ -792,8 +792,8 @@ Applying the ``httpLabel`` trait to members
 * If the corresponding URI label in the operation is greedy, then the
   ``httpLabel`` trait MUST target a member that targets a ``string`` shape.
 
-``httpLabel`` serialization rules
----------------------------------
+Serialization rules
+-------------------
 
 - ``boolean`` values are serialized as ``true`` or ``false``.
 - ``timestamp`` values are serialized as an :rfc:`3339` string by default
@@ -935,7 +935,6 @@ Structurally exclusive
 
 Given the following Smithy model:
 
-
 .. code-block:: smithy
 
     @readonly
@@ -975,6 +974,56 @@ An example HTTP request would be serialized as:
     X-Foo-first: hi
     X-Foo-second: there
 
+Given the following Smithy model that also uses the ``httpHeader`` trait:
+
+.. code-block:: smithy
+
+    @readonly
+    @http(method: "GET", uri: "/myOperation")
+    operation MyOperation {
+        input: MyOperationInput
+    }
+
+    @input
+    structure MyOperationInput {
+        @httpPrefixHeaders("X-Foo-")
+        headers: MapOfStrings
+
+        @httpHeader("X-Foo-Value")
+        foo: String
+    }
+
+    map MapOfStrings {
+        key: String
+        value: String
+    }
+
+And given the following input to ``MyOperation``:
+
+.. code-block:: json
+
+    {
+        "headers": {
+            "Value": "not sent"
+        }
+        "foo": "resolved"
+    }
+
+An example HTTP request would be serialized as:
+
+::
+
+    GET /myOperation
+    Host: <server>
+    X-Foo-Value: resolved
+
+.. note::
+
+    If using both ``httpPrefixHeaders`` and ``httpHeader``, placing the member
+    that uses ``httpPrefixHeaders`` ahead of those that use ``httpHeader`` can
+    help readers understand the precedence for
+    :ref:`serializing HTTP messages. <serializing-http-messages>`
+
 Disambiguation of ``httpPrefixHeaders``
 ---------------------------------------
 
@@ -1134,7 +1183,7 @@ target input map as query string parameters in an HTTP request:
 
     @input
     structure ListThingsInput {
-        @httpQueryParams()
+        @httpQueryParams
         myParams: MapOfStrings
     }
 
@@ -1143,6 +1192,56 @@ target input map as query string parameters in an HTTP request:
         value: String
     }
 
+
+Given the following Smithy model that also uses the ``httpQuery`` trait:
+
+.. code-block:: smithy
+
+    @readonly
+    @http(method: "GET", uri: "/myOperation")
+    operation MyOperation {
+        input: MyOperationInput
+    }
+
+    @input
+    structure MyOperationInput {
+        @httpQueryParams
+        query: MapOfStrings
+
+        @httpQuery
+        foo: String
+    }
+
+    map MapOfStrings {
+        key: String
+        value: String
+    }
+
+And given the following input to ``MyOperation``:
+
+.. code-block:: json
+
+    {
+        "query": {
+            "foo": "not sent"
+        }
+        "foo": "resolved"
+    }
+
+An example HTTP request would be serialized as:
+
+::
+
+    GET /myOperation?foo=resolved
+    Host: <server>
+
+.. note::
+
+    If using both ``httpQueryParams`` and ``httpQuery``, placing the member
+    that uses ``httpQueryParams`` ahead of those that use ``httpQuery`` can
+    help readers understand the precedence for
+    :ref:`serializing HTTP messages. <serializing-http-messages>`
+
 Serialization rules
 -------------------
 
@@ -1378,6 +1477,7 @@ See
         output: PutSomethingOutput
     }
 
+.. _serializing-http-messages:
 
 Serializing HTTP messages
 =========================
@@ -1393,14 +1493,14 @@ parameters:
    corresponding structure member by name:
 
    1. If the member has the ``httpLabel`` trait, expand the value into the URI.
-   2. If the member has the ``httpQuery`` trait, serialize the value into the
-      HTTP request as a query string parameter.
-   3. If the member has the ``httpQueryParams`` trait, serialize the values into
+   2. If the member has the ``httpQueryParams`` trait, serialize the values into
       the HTTP request as query string parameters.
-   4. If the member has the ``httpHeader`` trait, serialize the value in an
-      HTTP header using the value of the ``httpHeader`` trait.
-   5. If the member has the ``httpPrefixHeaders`` trait and the value is a map,
+   3. If the member has the ``httpQuery`` trait, serialize the value into the
+      HTTP request as a query string parameter.
+   4. If the member has the ``httpPrefixHeaders`` trait and the value is a map,
       serialize the map key value pairs as prefixed HTTP headers.
+   5. If the member has the ``httpHeader`` trait, serialize the value in an
+      HTTP header using the value of the ``httpHeader`` trait.
    6. If the member has the ``httpPayload`` trait, serialize the value as the
       body of the request.
    7. If the member has no bindings, serialize the key-value pair as part of a
@@ -1418,10 +1518,10 @@ parameters:
 3. Iterate over all of the key-value pairs of the parameters and find the
    corresponding structure member by name:
 
-   1. If the member has the ``httpHeader`` trait, serialize the value in an
-      HTTP header using the value of the ``httpHeader`` trait.
-   2. If the member has the ``httpPrefixHeaders`` trait and the value is a map,
+   1. If the member has the ``httpPrefixHeaders`` trait and the value is a map,
       serialize the map key value pairs as prefixed HTTP headers.
+   2. If the member has the ``httpHeader`` trait, serialize the value in an
+      HTTP header using the value of the ``httpHeader`` trait.
    3. If the member has the ``httpPayload`` trait, serialize the value as the
       body of the response.
    4. If the member has no bindings, serialize the key-value pair as part of a

smithy-model/src/main/java/software/amazon/smithy/model/validation/validators/HttpPrefixHeadersTraitValidator.java

@@ -14,7 +14,9 @@
 import software.amazon.smithy.model.traits.HttpHeaderTrait;
 import software.amazon.smithy.model.traits.HttpPrefixHeadersTrait;
 import software.amazon.smithy.model.validation.AbstractValidator;
+import software.amazon.smithy.model.validation.Severity;
 import software.amazon.smithy.model.validation.ValidationEvent;
+import software.amazon.smithy.utils.StringUtils;
 
 /**
  * Validates that httpHeader traits do not case-insensitively start with an
@@ -41,23 +43,37 @@ private List<ValidationEvent> validateMember(
     ) {
         List<ValidationEvent> events = new ArrayList<>();
         String prefix = prefixTrait.getValue().toLowerCase(Locale.ENGLISH);
+        Severity severity = Severity.ERROR;
+        String detail =
+                "`httpHeader` bindings must not case-insensitively start with any `httpPrefixHeaders` bindings.";
+        if (StringUtils.isEmpty(prefix)) {
+            severity = Severity.NOTE;
+            detail = String.format(
+                    "The service will not be able to disambiguate between header parameters intended for the `%s` "
+                            + "member and those explicitly bound to the `httpHeader` members.",
+                    member.getId());
+        }
 
         // Find all structure members that case-insensitively start with the same prefix.
         for (MemberShape otherMember : structure.getAllMembers().values()) {
-            otherMember.getTrait(HttpHeaderTrait.class).ifPresent(httpHeaderTrait -> {
+            if (otherMember.hasTrait(HttpHeaderTrait.ID)) {
+                HttpHeaderTrait httpHeaderTrait = otherMember.expectTrait(HttpHeaderTrait.class);
                 String lowerCaseHeader = httpHeaderTrait.getValue().toLowerCase(Locale.ENGLISH);
+
                 if (lowerCaseHeader.startsWith(prefix)) {
-                    events.add(error(otherMember,
+                    events.add(createEvent(
+                            severity,
+                            otherMember,
                             httpHeaderTrait,
                             String.format(
                                     "`httpHeader` binding of `%s` conflicts with the `httpPrefixHeaders` binding of `%s` "
-                                            + "to `%s`. `httpHeader` bindings must not case-insensitively start with any "
-                                            + "`httpPrefixHeaders` bindings.",
+                                            + "to `%s`. %s",
                                     lowerCaseHeader,
                                     member.getId(),
-                                    prefix)));
+                                    prefix,
+                                    detail)));
                 }
-            });
+            }
         }
 
         return events;

smithy-model/src/test/resources/software/amazon/smithy/model/errorfiles/validators/http-request-response-validator.errors

@@ -21,7 +21,8 @@
 [DANGER] ns.foo#MInput$a: `Authorization` is not an allowed HTTP header binding | HttpHeaderTrait
 [ERROR] ns.foo#NInput$a: This `a` structure member is marked with the `httpLabel` trait, but no corresponding `http` URI label could be found when used as the input of the `ns.foo#N` operation. | HttpLabelTrait
 [ERROR] ns.foo#PInput$a: The `a` structure member corresponds to a greedy label when used as the input of the `ns.foo#P` operation. This member targets (integer: `ns.foo#Integer`), but greedy labels must target string shapes. | HttpLabelTrait
-[ERROR] ns.foo#RInput$b: `httpHeader` binding of `x-foo` conflicts with the `httpPrefixHeaders` binding of `ns.foo#RInput$a` to ``. `httpHeader` bindings must not case-insensitively start with any `httpPrefixHeaders` bindings. | HttpPrefixHeadersTrait
+[NOTE] ns.foo#RInput$b: `httpHeader` binding of `x-foo` conflicts with the `httpPrefixHeaders` binding of `ns.foo#RInput$a` to ``. The service will not be able to disambiguate between header parameters intended for the `ns.foo#RInput$a` member and those explicitly bound to the `httpHeader` members. | HttpPrefixHeadersTrait
+[NOTE] ns.foo#ROutput$b: `httpHeader` binding of `x-foo` conflicts with the `httpPrefixHeaders` binding of `ns.foo#ROutput$a` to ``. The service will not be able to disambiguate between header parameters intended for the `ns.foo#ROutput$a` member and those explicitly bound to the `httpHeader` members. | HttpPrefixHeadersTrait
 [ERROR] ns.foo#GInput$b: Trait `httpHeader` cannot be applied to `ns.foo#GInput$b`. This trait may only be applied to shapes that match the following selector: structure > :test(member > :test(boolean, number, string, timestamp, list > member > :test(boolean, number, string, timestamp))) | TraitTarget
 [ERROR] ns.foo#GOutput$b: Trait `httpHeader` cannot be applied to `ns.foo#GOutput$b`. This trait may only be applied to shapes that match the following selector: structure > :test(member > :test(boolean, number, string, timestamp, list > member > :test(boolean, number, string, timestamp))) | TraitTarget
 [ERROR] ns.foo#HInput$a: Trait `httpHeader` cannot be applied to `ns.foo#HInput$a`. This trait may only be applied to shapes that match the following selector: structure > :test(member > :test(boolean, number, string, timestamp, list > member > :test(boolean, number, string, timestamp))) | TraitTarget