HTTP/2 editorial problems <draft-ietf-httpbis-http2-17>

HTTP/2 editor & co-authors,

As I said, treat this as a late review from a clueful but fresh pair 
of eyes. So my misunderstandings might match those of a typical 
reader, as opposed to someone who has read many previous drafts.

==Comprehensibility / Ambiguity==

<https://tools.ietf.org/html/draft-ietf-httpbis-http2-17#section-5>5. 
Streams and Multiplexing
Definition of "stream":
It is not at all clear that the stream ID is the same in both 
directions. I think the authors assume that readers will extrapolate 
the definition of a stream /ID/ from the definition of a /stream/. 
But I read it as the endpoints each hold stream state which 
associates two different stream IDs in each direction (one odd and 
one even) to comprise a stream.

Also, what is a "bi-directional sequence of frames"? If this means 
anything, it means that the frames in both directions can be placed 
in a single ordered sequence. I don't think this is the intended 
meaning, because the two directions surely overlap.

<https://tools.ietf.org/html/draft-ietf-httpbis-http2-16#section-5.1>
Describing the process of starting to close a stream as half-closing 
the stream leads to imprecision. It would be more precise to talk 
instead of closing one of the half-streams (C-S or S-C). Then, 
because HTTP/2 sits over the ordered delivery of TCP, the spec can 
very precisely define when each half-stream closes, from the 
perspective of each end:

The ES flag (or an end-stream implied by a HEADERS frame) could be 
precisely defined as an end-half-stream (EHS) message, as follows:
* On the A-B half-stream, the sender can send no more messages on the 
half-stream after it sends an EHS message, and the receiver can 
expect not to receive any data on that half-stream after it receives 
the EHS message.
* Then, on the B-A half-stream, B can still send data on the 
half-stream until it responds with an EHS message. And A can expect 
to continue to receive B-A half-stream data until it receives the EHS message.

The RST_STREAM frame would be easy to define precisely too (except in 
the one case identified):
* On the A-B half-stream, the sender can send no more messages on the 
half-stream after it sends a RST_STREAM frame, and the receiver can 
expect not to receive any data on that half-stream after it receives 
the RST_STREAM frame.
* On the B-A half-stream, B cannot send data on the half-stream as 
soon as it receives the RST_STREAM frame. The imprecise part is how A 
knows when it can expect to stop receiving more data from B. If A 
could see the ACK of its RST_Stream at the TCP layer, it would know; 
but it can't.

<https://tools.ietf.org/html/draft-ietf-httpbis-http2-17#section-5.1>5.1. 
Stream States
"  open: [...]
      Either endpoint can send a RST_STREAM frame from this state,
       causing it to transition immediately to "closed".
"
'it' is ambiguous. I think an endpoint transitions to closed 
immediately it sends RST_STREAM, and immediately it receives RST_STREAM.



==Nits==


<https://tools.ietf.org/html/draft-ietf-httpbis-http2-17#section-2.2>2.2. 
Conventions and Terminology
definition of frame:
s/header/frame header/ (disambiguates from HTTP header).

<https://tools.ietf.org/html/draft-ietf-httpbis-http2-17#section-3.2>3.2. 
Starting HTTP/2 for "http" URIs
I suggest the following section order would be clearer after 3.1:
3.2. Starting HTTP/2 for "http" URIs
3.2.1. Starting HTTP/2 for "http" URIs without prior knowledge
        Text of current 3.2.
3.2.1.1. HTTP2-Settings Header Field
          Text of current 3.2.1.
3.2.2. Starting HTTP/2 for "http" URIs with prior knowledge
        Text of current 3.4.
3.2.2.1. HTTP/2 Connection Preface
          Text of current 3.5.
3.3. Starting HTTP/2 for "https" URIs
        Text of current 3.3.

Even better: start with HTTP/2 for https URIs then for http URIs

<https://tools.ietf.org/html/draft-ietf-httpbis-http2-17#section-3.2>3.2. 
Starting HTTP/2 for "http" URIs
s/an payload/
  /a payload/

<https://tools.ietf.org/html/draft-ietf-httpbis-http2-17#section-3.3>3.3. 
Starting HTTP/2 for "https" URIs
s/a client/such a client/ (2nd para)
s/a server/a TLS server/

<https://tools.ietf.org/html/draft-ietf-httpbis-http2-17#section-4>4. 
HTTP Frames
"Once the HTTP/2 connection is established"
The term 'established' is not defined. It seems it means after the 
first settings frame after the preface. Or does it mean after the 
first settings frame is acknowledged (requiring a round of delay)?

<https://tools.ietf.org/html/draft-ietf-httpbis-http2-17#section-4.1>4.1. 
Frame Format
s/Length: The length of the frame/
  /Length: The length in octets of the frame/

<https://tools.ietf.org/html/draft-ietf-httpbis-http2-17#section-5>5. 
Streams and Multiplexing
s/Recipients process frames in the order they are received./
  /Recipients process frames in the order TCP delivers them to the 
HTTP receiver./

"  Endpoints do not
    coordinate the creation of streams; they are created unilaterally by
    either endpoint.  The negative consequences of a mismatch in states
    are limited to the "closed" state after sending RST_STREAM, where
    frames might be received for some time after closing.
"
The second sentence presumes the reader has made a few conceptual 
leaps triggered by the first sentence, without stating those leaps.

"      Therefore, a
       RST_STREAM is needed to close an unwanted promised stream.
"
s/a RST_STREAM/
  /another RST_STREAM/

<https://tools.ietf.org/html/draft-ietf-httpbis-http2-17#section-5.3>5.3. 
Stream priority
s/prefer its peer allocate resources/
  /prefer its peer to allocate resources/

<https://tools.ietf.org/html/draft-ietf-httpbis-http2-17#section-6.3>6.3. 
PRIORITY
"The PRIORITY frame always identifies a stream."

This amended text is even less clear than it was in draft-16. The 
solution is to delete this sentence completely. I think this means a 
priority frame has a value in the Stream ID field of its frame 
header, which cannot be untrue anyway.

<https://tools.ietf.org/html/draft-ietf-httpbis-http2-17#section-6.5>6.5. 
SETTINGS
s/Parameters are processed in the order in which they appear,/
  /Parameters are processed in the order in which TCP delivers them,/

<https://tools.ietf.org/html/draft-ietf-httpbis-http2-17#section-8.3>8.3. 
The CONNECT Method
"  Frame types other than DATA
    or stream management frames (RST_STREAM, WINDOW_UPDATE, and PRIORITY)
    MUST NOT be sent on a connected stream
"
Two paras later, this is contradicted for the case of RST_STREAM:
"  A TCP connection error is signaled with RST_STREAM.
"

<https://tools.ietf.org/html/draft-ietf-httpbis-http2-17#section-9.2.2>9.2.2. 
TLS 1.2 Cipher Suites
s/if one of the cipher suites from the black list are negotiated/
  /if one of the cipher suites from the black list is negotiated/

<https://tools.ietf.org/html/draft-ietf-httpbis-http2-17#section-10.5.2>10.5.2. 
CONNECT Issues
s/an proxy/
  /a proxy/


HTH


Bob

________________________________________________________________
Bob Briscoe,                                                  BT