proposed clarifications regarding the state machine (editorial)

*Section 5.1*

If you are trying to understand the state machine based on the diagram in text in Section 5.1, you will likely go away thinking that you can only send DATA frames in the "open" state.  Section 6.1 does clarify this point, but I think it would be good to call it out explicitly here in 5.1.

As a reader, it would also be convenient if there was a reference to Sections 8.1 and 8.2 for examples of the state flow for an entire request/response (not sure where it best fits though).



If an endpoint receives additional frames for a stream that is in this state, other than WINDOW_UPDATE, PRIORITY or RST_STREAM, it MUST respond with a stream error (Section 5.4.2) of type STREAM_CLOSED.

>>>

A stream in the "half closed (remote)" state may still be used by the endpoint to send frames of any type. In this state, the endpoint continues to observe advertised stream level flow control limits (Section 5.2).

<<<

A stream can transition from this state to "closed" by sending a frame that contains an END_STREAM flag, or when either peer sends a RST_STREAM frame.



<<<

An example of the state transitions for an HTTP request/response can be found in Section 8.1.  An example for a server push request/response can be found in Sections 8.2.1 and 8.2.2.

>>>



*Section 8.1*

I think the final paragraph would be a more useful example of the typical state machine flow if it clarified the half closed states because (if I understand correctly) the client and server diverge at that point.



An HTTP request/response exchange fully consumes a single stream. A request starts with the HEADERS frame that puts the stream into an "open" state and ends with a frame bearing END_STREAM, which causes the stream to become

<<<

"half closed (local)" for the client and "half closed (remote)" for the server.

>>>

A response starts with a HEADERS frame and ends with a frame bearing END_STREAM, optionally followed by CONTINUATION frames, which places the stream in the "closed" state.





*Section 8.2.1*

I found the text in this paragraph a bit confusing.  It currently says "PUSH_PROMISE frames can be sent by the server on any stream...". If I understand correctly, PUSH_PROMISE frames are _associated_ with a stream, but aren't sent _on_ that stream.  They get their own promised stream id right?  I suggest something like "in response to" instead of "on".

Also, section 8.1 includes text about the state transitions.  I propose a sentence about the state transitions at the end of Section...



PUSH_PROMISE frames MUST NOT be sent by the client. PUSH_PROMISE frames can be sent by the server in response to any stream that was opened by the client, however the stream MUST be in either the "open" or "half closed (remote)" state with respect to the server. PUSH_PROMISE frames are interspersed with the frames that comprise a response, though they cannot be interspersed with HEADERS and CONTINUATION frames that comprise a single header block.

<<<

Sending a PUSH_PROMISE frame creates a new stream and puts the stream into the "reserved (local)" state for the server and the "reserved (remote)" state for the client.

>>>



*Section 8.2.2*

...and two sentences about the state transitions at the end of this Section.



<<<

The response for a PUSH_PROMISE stream begins with a HEADERS frame, which immediately puts the stream into the "half closed (remote)" state for the server and "half closed (local)" state for the client, and ends with a frame bearing END_STREAM, optionally followed by CONTINUATION frames, which places the stream in the "closed" state.



NOTE: The client never sends a frame with the END_STREAM flag for a server push.

>>>



This email message is intended only for the use of the named recipient. Information contained in this email message and its attachments may be privileged, confidential and protected from disclosure. If you are not the intended recipient, please do not read, copy, use or disclose this communication to others. Also please notify the sender by replying to this message and then delete it from your system.