Make references to h1-messaging non-normative

[mnot]

Both caching and semantics make some references to h1-messaging. They should not be normative.

We can do this by:

• Removing unnecessary references
• Turning references into examples / advisory text
• Clarifying H1 specificity where appropriate

Includes #332, #333, #311, #259, #183, #182, #118.

[mnot]

In semantics:

• chunked.trailer.section - 1 ref, is an example
• connection.management - 2 refs, one defines "connection", the other is an aside.
• differences.between.http.and.mime - 1 ref in Canonicalization and Text Defaults
• field.parsing - 1 ref, talking about leading and trailing WS being discarded
• h1.effective.request.uri - 1 ref, illustrative
• request.target - see request target is h1-specific #259, Section 5.4 (Host) in Semantics has normative 1.1 requirements #182, CONNECT, OPTIONS and request-target #340
• header.connection - 4 refs:
  • proxy forwarding headers
  • defining hop-by-hop in considerations for new fields
  • requirement for intermediary forwarding messages
  • connection: close on 408
• header.te - talking about TE: trailers. See also TE: trailers #18
• header.transfer-encoding - 1 ref, contrasting with Content-Encoding
• header.upgrade - 3 refs, definitions of 101, 426 and Via grammar
• http.message - 4 refs, definition of message. See also Define "request" and "response" independent of HTTP/1.1 #311.
• media.type.message.http - 1 ref, requirement from TRACE
• line.folding - 2 refs, talking about OWS folding - see Should Semantics assume that field values have been coalesced or just unfolded? #116
• message.body - 2 refs, talking about message body, parsing reqs.
• persistent.connections - 0 refs
• persistent.tear-down - 1 ref, Expect requirements
• request.line - 1 ref, size limits
• request.smuggling - 2 refs, field limits and GET
• transfer.codings - 3 refs: proxy transformations, contrasting with content-coding, message/http

[mnot]

@royfielding it seems like either header.upgrade needs to move into Semantics, or 101 and `426 need to move into Messaging. WDYT?

[mnot]

In Caching, there's are two references to message.body.length, in Storing Incomplete Responses (talking about what "incomplete" is; see #334), and as a 1.1-specific example.

I think once #334 is resolved, Caching should be good.

[royfielding]

@royfielding it seems like either header.upgrade needs to move into Semantics, or 101 and `426 need to move into Messaging. WDYT?

Yes, I think we will be better served by defining all of the header fields in Semantics and stating explicitly when they are only applicable to one version of HTTP (or some subset of versions).

[royfielding]

Er, I mean defining all of the fields in Semantics or Caching -- no need to move CC and Expires, etc.

[mnot]

I'm leaning the other way - moving 101 and 426 into Messaging. Each of these mechanisms is pretty clearly 1.x-specific:

• Upgrade
• Connection
• Transfer-codings

Putting them into Semantics just makes that document larger, and adds to confusion about whether they can be used in 2 or 3.

[MikeBishop]

I can see this either way. My general inclination is that status codes et al. are always generic mechanisms, but which might not be applicable/defined for certain mappings. (I kind of regret that we went with "Extended CONNECT" instead of defining that Upgrade works on a stream in H2/H3, but that's water under the bridge.)

[mnot]

Current set of anchors pointing to messaging from semantics, with those that can be considered non-normative ticked:

• chunked.trailer.section
• differences.between.http.and.mime
• field.parsing
• h1.effective.request.uri
• field.connection
• field.te
• field.transfer-encoding
• field.upgrade
• http.message
• media.type.message.http
• line.folding
• message.body
• persistent.tear-down
• request.line
• request.smuggling
• transfer.codings
• security.considerations

[mnot]

Of those remaining, I think:

• field.parsing - can be changed to "e.g., [ref] in HTTP/1.1"
• field.connection - I think we can reword this in a way to effectively move the requirement to messaging
• field.te - should be moved from Messaging to Semantics
• field.upgrade - should be moved from Messaging to Semantics
• http.message - these all seem to be references to the abstract concept of a request message, which I think can be pointed at architecture.
• media.type.message.http - I'm tempted to say that this can be considered informative, thoughts?
• persistent.tear-down - change changed to "e.g., [ref] in HTTP/1.1"
• request.line - this should not be mentioned here; it's 1.1 specific
• transfer.codings - all informative except for the mention in message.transformations, which I think can be removed or downgraded to a note that version-specific wire serialisations like transfer codings don't count

@royfielding / @reschke if this sounds about right, I'll do a PR that effects the above and moves Messaging to Informative References.

[mnot]

Dicussed; we need two PRs, one for moving, one for rewording. Connection needs to be in semantics. Messaging will remain normative.

[mnot]

Only thing left to do is #407; closing.