[hybi] List of (mostly) editorial changes for draft-01

[Patrick McManus <[e-mail]>]

Ian, 

Thanks for the new draft! I think it is great that we all have a
document to focus on moving forward; this is a big help. 

Websockets Group,

I've read through the document and I wanted to provide a list of mostly
editorial-style updates to the portions that deal with framing. They are
generally not meant to change the substance of the document but rather
to improve clarity and help us focus on the real issues. Very much a
refinement of what Ian achieved with -01. 

However, some of the changes do go beyond syntax changes (see control
messages) in order to address  some basic problems. But any really
significant changes in meaning will go into separate email threads.

There is good material in section 1 and especially 4 and my goal is to
especially strengthen the normative material in section 4 and get it at
least a little closer to ietf-standards speak. 

Like your revision, I have limited myself to the framing considerations.
Basically that's section 4 and parts of section 1. The other stuff
obviously still needs to be addressed.

Each of my proposed changes is described below, broken apart by
subsection. I've also attached copies of the draft with my edits
included and a diff between that and -01, so people can easily review
them.

-Patrick (proposed changes below)

Section 1.2 - Protocol Overview. There is good normative content here
that is too detailed for the overview and that should be in section 4
instead (as it is wasted in the non-normative section 1).

  * Change the text "On the network layer, a message may be represented
as one or more frames." to be "The websocket message does not
necessarily correspond to any network layer framing.".. This is more
correct as the network layer may coalesce as well as fragment.
  
  * strike the paragraph beginning "to close" as it too low level of a
detail to be considered part of the overview and is redundant to the
normative text.

  * For similar reasons, strike the paragraph "the protocol is designed"
but add the more summary oriented sentence "This version of the protocol
defines six frame types and leaves ten reserved for future use." to the
end of the section 1.2 paragraph that begins "Data is sent". The
original sentence doesn't reflect the current allocation of op codes.

  * move the ABNF portion to normative section 4.2.

Section 4.1 - normative Data Framing Overview

  * strike the sentence "The base framing protocol is deliberately kept
simple so that simple implementations may ignore advanced features."
There is no definition of simple implementations, no definition of
advanced features, and no definition of what ignore might mean in this
context. What is an implementor to do with it? :)..  I personally don't
think we need the text at all, but if we want it move it to a
non-normative section.

  * update the remainder of 4.1 to standards-speak: "In the absence of
extensions negotiated during the opening handshake (Section 5), all
reserved bits MUST be 0 and reserved opcode values MUST NOT be used."..
actually this probably belongs somewhere other than the overview.

  * Add to that 4.1 paragraph the text "A data frame MAY be transmitted
by either the client or the server at any time after handshake
completion and before that host has generated a close message." That
probably means we need a normative definition of client and server
somewhere - but I think this is an important thing to say in a place
other than section 1.

Section 4.2 - 

  * as noted the ABNF from 1.2 is moved here

  * Payload length - before "The payload length is" .. insert the
sentence "Multibyte length quantities are expressed in network byte
order." - that's an impt omission.

  * I had trouble understanding where the extension data length came
from. I now (think) I understand that it is part of the extension
definiton or negotiation itself. I changed the Extension Data definition
to reflect this requirement more clearly:

      "The extension data is 0 bytes unless there is a reserved op-code
      or reserved bit present in the frame which indicates an
      extension. Any extension MUST specify the length of the
      extension data and its use MUST be negotiated during the
      handshake."


Section 4.3 - Fragmentation

 * Change the paragraph that begins "a sender MAY arbitrarily fragment a
single message (which allows generation of dynamic content without
having to buffer the data in order to count it)." to read more simply "A
sender MAY create fragments of any size for non control messages." If we
need to explain why fragments are important, which I don't think we need
to do, that can live outside of normative section 4.

  * Change the paragraph "A receiver MUST be prepared to accept
arbitrarily fragmented messages, even if the sender sent the message in
a single frame." to the more direct "A receiver MUST support receipt of
fragmented messages.". .. I assume the text about "sender sent .. in
single frame" is referring to intermediaries, but it can't really happen
like that - the intermediary is a sender too. To express the concept we
would have to define something like origin-server/user-agent which are
subsets of senders.. but I really don't see why this paragraph needs the
concept at all.

  * Change the paragraph "An intermediary MAY fragment .." to read "An
intermediary MAY change the fragmentation of a message if the message
uses an opcode and reserved bit values known to the intermediary."  This
change allows coalescing as well as fragmentation, and using the "if"
keeps us out of the awkward "may.. except must not" language the text
was using, and it restricts the section 4.3 requirement to only deal
with fragmentation.

Section 4.4 - Control Frames

I've done some more significant cleanups here that go a bit beyond the
editorial. Specifically I want to include some of James Graham's
concerns.

As drafted a ping and pong are meant to be paired together via their
content.. but the pong is allowed to truncate the content but isn't
given any mechanism to indicate that it has done so.. in light of that
how can the pinger determine if there is a match? If those truncated
bytes aren't relevant to the match, why did it send them in the first
place? My answer to that is to disallow truncation but limit the message
size to the tiny 125 byte frame size. If people want to argue for a
larger but still reasonable constant I don't have a problem with that.
Furthermore the draft made responding to the ping optional (SHOULD
level) which really makes it kind of useless as a keep-alive.. so I
changed that to MUST respond, but SHOULD do it soonish. (see text).

We've been calling them control frames, not control messages, so I
assume that means they shouldn't be fragmented and I made that a
requirement. The alternative is to try and consistently call them
control messages. Personally, I don't see a reason to let them be
fragmented into multiple frames.

With that being said - this is the proposed replacement for section 4.4:

=============

4.4.  Control Frames

   Control frames have opcodes of 0x01, 0x02, or 0x03. They are used
   to communicate state about the websocket.

   All control frames MUST be 125 bytes or less in length and MUST NOT
   be fragmented.

4.4.1 Close

   The Close message contains an opcode of 0x01.

   The application MUST NOT send any more data messages after
   sending a close message.

   A recevied close message is deemed to be an acknowledgement if the
   message body matches the body of a close message previously sent by
   the receiver. Otherwise the close message is a close initiated by
   the sender.

   Upon receipt of an initiated close the endpoint MUST send a close
   acknowledgment. It should do so as soon as is practical.

   The websocket is considered fully closed when an endpoint has either
   received a close acknowledgment or sent a close acknowledgment.


4.4.2 Ping

   The Ping message contains an opcode of 0x02.

   Upon receipt of a Ping message, an endpoint MUST send a Pong
   message in response. It SHOULD do so as soon as is practical. The
   message bodies of the Ping and Pong MUST be the same.

4.4.3 Pong

   The Pong message contains an opcode of 0x03.

   Upon receipt of a Ping message, an endpoint MUST send a Pong
   message in response. It SHOULD do so as soon as is practical. The
   message bodies of the Ping and Pong MUST be the same.

======================

Section 4.5 Data Frames

  * replace "not listed above" with "not listed in Section 4.4"
  
  * strike the paragraph "Additional data frame types" .. its just not
necessary for this part of the normative document and is redundant with
the overview section which describes future use.

Section 4.7 Extensibility

With respect to section 4 framing there isn't a lot to say about
extensibility. I replaced the existing section 4.7 text with this:

"   The endpoints MUST negotiate the use of any extensions during the
   handshake. This specification provides opcodes 0x6 through 0xF, the
   extension data field, and the frame-rsv1, frame-rsv2,
   frame-rsv3, and frame-rsv4 bits of the frame	header for use by
   extensions.   "