Conflicts between Smithy semantics and HTTP specification

[hlbarber]

What should happen in situations where the semantics of Smithy conflict with the HTTP spec?

Consider the following example:

@http(method: "PUT", uri: "/", code: 204)
operation Put {
    output: Output
}

@output
structure Output {
    someValue: String
}

The HTTP spec forbids a 204 response to have a message-body. https://httpwg.org/specs/rfc7231.html#status.204

A 204 response is terminated by the first empty line after the header fields because it cannot contain a message body.

Should the semantics of this operation yield to the HTTP spec? i.e. should the payload get removed to be in compliance?

In the case of smithy-rs we are backed by hyper.

It will not provide Content-Length headers in accordance with https://httpwg.org/specs/rfc7230.html#header.content-length

A server MUST NOT send a Content-Length header field in any response with a status code of 1xx (Informational) or 204 (No Content). A server MUST NOT send a Content-Length header field in any 2xx (Successful) response to a CONNECT request.

See hyperium/hyper#2216.

It will also do a variety of checks in relation to the spec.

A further example of such a collision is with https://awslabs.github.io/smithy/1.0/spec/core/http-traits.html#httpheader-trait, although @httpHeader("Content-Length") is marked as "highly discouraged", hyper would also cause problems honoring this for 1xx, 204, and 304 responses.

Some clarification on these issues would be appreciated.

[mtdowling]

We could add a note in the spec that says to be aware of HTTP limitations, call out specifically 204 as an example, and call out that violating the HTTP spec in a Smithy model is undefined behavior with no expectation of working across languages or implementations. I think that's a better approach than trying to cover every edge case of HTTP in Smithy specification. We could also add validation for 204 responses to Smithy to emit a DANGER event when detected. As other things come up, they can be accounted for in our validation too.