Subject: Re: [hybi] Feedback on thewebsocketprotocol

From: Graham Klyne <[email-masked]>
Date: Sat, 03 Oct 2009 12:44:31 +0100

[Resending via a different SMTP relay - my previous attempts all sank without 
trace. #g]

Ian Hickson wrote:
> On Sun, 6 Sep 2009, Graham Klyne wrote:
>> I still find the abstract a bit obscure.
> 
> Could you elaborate on this? I just tried writing a new abstract and I 
> basically ended up with almost exactly what the spec already has.

If I knew enough about the proposal to elaborate, I'd have tried to suggest some
words.

The new introduction is a vast improvement, and I think I maybe now see enough
to make the attempt.

Currently, from http://tools.ietf.org/html/draft-hixie-thewebsocketprotocol-41
[[
    This protocol enables two-way communication between a user agent
    running untrusted code running in a controlled environment to a
    remote host that understands the protocol.  It is intended to fail to
    communicate with servers of pre-existing protocols like SMTP or HTTP,
    while allowing HTTP servers to opt-in to supporting this protocol if
    desired.  It is designed to be easy to implement on the server side.
]]

Suggested:
[[
The websockets protocol enables two-way communication between a user agent
running untrusted code running in a controlled environment to a remote host.  It
allows a session that starts as a normal HTTP connection to be upgraded to a
bidirectional message-oriented exchange, while gracefully failing to make this
transition when communicating with HTTP servers that do not support this
protocol.  Consisting of the initial handshake and basic message-framing, the
protocol is a minimal layer over TCP, designed to be easy to implement for
servers and clients.

The goal of the webssockets protocol is to support browser-based interactive Web
applications without having to rely on <iframe> and long-polled XMLHTTPRequest
abuses that are needed to implement them in current browsers.
]]

(I assume here that ease of implementation for the client is also a goal - as
originally phrased, there's a possible implication of trading ease of
server-side implementation for possible client complexity.  I use the term
message-oriented to explain the role of framing.)

> On Tue, 8 Sep 2009, Graham Klyne wrote:
>>>> Also, along the way, it might be worth mentioning efforts like 
>>>> cometd/bayeux and BOSH and saying how this proposal is similar 
>>>> and/or different.
>>> I'm not really sure what I would say here.
>> I think that an informative reference to 
>> http://www.ietf.org/id/draft-loreto-http-bidirectional-00.txt and a 
>> high-level comparison with the long-poll and streaming approaches 
>> described there would do it.  And mention why you are not just using 
>> COMET/BAYEUX or BOSH which are mentioned there.  You might even consider 
>> contributing a section describing your approach to the authors of that 
>> document.
> 
> I really don't feel comfortable having a specification compare itself to 
> other specifications. I always feel like this is rather presumptuous, and 
> would rather readers draw their own conclusions. (HTML5 had a number of 
> such sections a few years ago, and since then they've all been removed, 
> one by one, as various people either took offence, or asked what the point 
> was, or said they disagreed with it, etc.)
> 
> I'd rather the spec just stayed focus on what it is rather than on what it 
> is not or what else exists.

Well, if you don't feel comfortable making the comparison, an attempt to
describe and explain the protocol in high-level terms that allow others to make
the comparison would be reasonable to do.  I think your new introduction
substantially achieves this.

As for explanatory material in specs, I've been there too, and it can be hard to
get the level right.  I understand there are different viewpoints about this:  I
happen to feel that non-normative explanation really does help.  If a
specification is like the answer to some question, it really helps to also know
what that question may be:  this is the role of the explanatory and/or
compatative material.  In this, I think your new introduction works pretty well,
modulo minor nits.

>>>> 6. Provide a protocol state diagram or similar overview.
>>> I'm not sure I understand what that would look like for this protocol.
>>>
>>> Do you mean something like this?:
>>>
>>>    HANDSHAKE --> FRAME TYPE <-------------------------.
>>>                       |                               |
>>>                       +---0x00---> DATA --> 0x00 --->-+
>>>                       |                               |
>>>                       `---0x80---> LENGTH -> DATA -->-'
>> Maybe that:  if it's really that simple, then a diagram like this helps to
>> emphasize that point.  See also the state diagrams in RFC821.
> 
> Ok, I've added a diagram to the intro. Hopefully it'll help someone.

I'm not seeing that yet, so I can't comment in detail.  But I think the state
diagram should also show how the initial HTTP-like handshake transitions to the
bidirectional stream.

> On Tue, 8 Sep 2009, Graham Klyne wrote:
>> In this message, I'm going to stand back from the immediate discussion 
>> of my review, and try and present some broader points, in decreasing 
>> order of metaphysicality...
>>
>> 1. Why are we here?
>>
>> 2. Provide context for evaluation
>>
>> 3. Declarative vs procedural definitions
>>
>> ...
>>
>> 1. Why are we here?
>>
>> What I really mean is:  why are you bringing this proposal to a 
>> standards body, specifically the IETF?
> 
> Lisa asked me to. This technology was originally part of the WHATWG HTML5 
> draft, and when the W3C published it, the IETF asked the W3C if it could 
> be an RFC instead, since apparently the W3C and the IETF have some 
> agreement that they won't step on each other's toes.

This assumes you want to create a standard, which is pretty much implied if you
want browser (and server) implementers to support it.  The IETF is then the
logical place.  My point (not really made as such) was that creating a standard
is a consensus-building process, which needs considerable effort to help people
understand as well laying down the technical details.

What I'm now seeing looks like good movement in this direction.  :)

> My goal is to have browser vendors implement this (which some are already 
> doing) so that it can be used to write interactive Web apps without having 
> to rely on <iframe> and XHR hacks like today.

OK - that sounds like someting to be worked into the abstract.   I'll go back
and edit my proposal... done.

>> 2. Provide context for evaluation
>>
> 
> Yeah, the draft was lacking in introductory material and consisted 
> primarily of the implementation requirements for a while. Hopefully this 
> is significantly improved now.

Did I mention, it's much better? :)

>> Related to this is making as much use as possible of well-known base 
>> specifications (hence my comments about RFC3986 vs [WEBADDRESSES]).
> 
> [WEBADDRESSES] is pretty well known in the expected implementation circles 
> (in that it describes what is implemented by most UAs already, unlike the 
> URI specs).

Hmmm... if this works, bank on it being picked up outside "the expected
implementation circles"

>> 3. Declarative vs procedural definitions
> 
> I like using declarative approaches where possible. Unfortunately I find 
> that such an approach becomes unwieldly very fast. I don't really see to 
> make the Web Socket protocol spec more declarative at this point. If you 
> have any concrete ideas along these lines, I'm more than happy to examine 
> them.

Now that I have a clearer idea of what the protocol actually does, I think a
state diagram supported by explanatory text would work well.

(One can argue whether that's actually declarative, but that's less of an issue.
  A state diagram *can* be expressed in a matrix of events vs states, with
actions in the relevant cell elements.  Or simply as a diagram.)

Given this, I think the details in your text would be much easier to follow.

But mainly, understanding that the protocol consists of an initial connection,
an upgrade request followed by a simple framed message exchange covers most of
it.  The rest is detail(!).

#g

---

From: Ian Hickson <[email-masked]>
Date: Tue, 13 Oct 2009 12:15:36 +0000 (UTC)

On Thu, 17 Sep 2009, SM wrote:
> At 03:36 17-09-2009, Ian Hickson wrote:
> > That is part of what it is about. Could you elaborate on why that sentence
> > isn't useful? What else should the abstract say, if not that?
> 
>   "The Abstract section should provide a concise and comprehensive
>    overview of the purpose and contents of the entire document, to give
>    a technically knowledgeable reader a general overview of the function
>    of the document."
> 
> You are telling me what the specification is not intended to do instead of
> what the document is supposed to be about.

Fair enough. I've changed where the bit about the security model is given.

> > Is this a rhetorical question? Is the paragraph not clear?
> 
> It is not clear as I do not know what you mean by "constraints of the Web".

I think explaining the constraints of defining protocols compatible with 
the Web's legacy environment is somewhat out of scope of an RFC like this 
one. I mean, one could go on for pages and pages about this topic.

> > Could you elaborate?
> 
> I assume that you have already settled on the structure and main content as
> the latest version is draft-hixie-thewebsocketprotocol-41.  You are asking the
> community to put in time and effort to comment on your proposal.  The numerous
> iterations do not encourage that.  In my opinion, the draft is not ready for
> community review.  I suggest that you read Graham Klyne's message [1] again.
> There's also a message from Julian Reschke [2].

I always welcome community review. This text has been getting review since 
about 2004, and has gone through hundreds of iterations in this time, and 
will likely go through many more in the future. I'm a firm believer in the 
"release early, release often" philosophy, and welcome anyone who wants to 
participate in this technology's development. However, if you do not think 
it is yet ready, you are welcome to wait for a later version to review.

Cheers,
-- 
Ian Hickson               U+1047E                )\._.,--....,'``.    fL
http://ln.hixie.ch/       U+263A                /,   _.. \   _\  ;`._ ,.
Things that are impossible just take longer.   `._.-(,_..'--(,_..'`-.;.'

---

From: Ian Hickson <[email-masked]>
Date: Tue, 13 Oct 2009 23:31:30 +0000 (UTC)

On Sat, 19 Sep 2009, Graham Klyne wrote:
> If I knew enough about the proposal to elaborate, I'd have tried to 
> suggest some words.
> 
> The new introduction is a vast improvement, and I think I maybe now see 
> enough to make the attempt.
> 
> running untrusted code running in a controlled environment to a remote host.
> It allows a session that starts as a normal HTTP connection to be upgraded to
> a bidirectional message-oriented exchange, while gracefully failing to make
> this transition when communicating with HTTP servers that do not support this
> The goal of the webssockets protocol is to support browser-based interactive
> Web applications without having to rely on <iframe> and long-polled
> XMLHTTPRequest abuses that are needed to implement them in current browsers.
> ]]

To summarise the proposed changes and how I applied them:

 * Change "This protocol" to "The websockets protocol". Done.

 * Remove the caveat that it only allows communications to a server that 
   understands Web Sockets. I haven't made this change, though I have 
   clarified the text a little.

 * Remove this:

   > It is intended to fail to communicate with servers of
   > pre-existing protocols like SMTP or HTTP, while allowing HTTP
   > servers to opt-in to supporting this protocol if desired.

   I removed this yesterday in response to other feedback.

 * Add this:

   > It allows a session that starts as a normal HTTP connection to be
   > upgraded to a bidirectional message-oriented exchange, while
   > gracefully failing to make this transition when communicating
   > with HTTP servers that do not support this protocol.

   I haven't bothered to include this detail, as the HTTP upgrade needs 
   more caveats than I'd like to mention in the abstract (e.g. it's not 
   just any HTTP session; you can't upgrade from a pipelined connection).

 * Add a vague description of the protocol and its relationship to TCP.
   Done.

 * Add that it's intended for ease of implementation on clients. I've 
   removed the mention of who it's easy to be implemented by. Implementors 
   can work out for themselves if it's easy. :-)

 * Mention the reason for the protocol compared to XHR or similar techniques.
   I've added something along these lines.

I hope you like the new text.

> I assume here that ease of implementation for the client is also a goal 
> - as originally phrased, there's a possible implication of trading ease 
> of server-side implementation for possible client complexity.

Ease of client implementation wasn't particularly a goal, no (there are 
far fewer clients expected than servers).

> > > Maybe that:  if it's really that simple, then a diagram like this 
> > > helps to emphasize that point.  See also the state diagrams in 
> > > RFC821.
> > 
> I'm not seeing that yet, so I can't comment in detail.  But I think the 
> state diagram should also show how the initial HTTP-like handshake 
> transitions to the bidirectional stream.

I'm not sure what you mean. Could you show an example?

The diagram is in "Protocol overview" section of the spec, for what it's 
worth.

> > primarily of the implementation requirements for a while. Hopefully 
> > this is significantly improved now.
> 

Excellent. :-)

> > [WEBADDRESSES] is pretty well known in the expected implementation 
> > circles (in that it describes what is implemented by most UAs already, 
> > unlike the URI specs).
> 

It's just a temporary reference until Larry updates the IRI specs.

---

From: SM <[email-masked]>
Date: Thu, 15 Oct 2009 10:53:18 -0700

>Fair enough. I've changed where the bit about the security model is given.

I took a quick look.  That's much better.

>one. I mean, one could go on for pages and pages about this topic.

You don't have to explain the constraints in your I-D.  You could 
provide a reference.

Regards,
-sm

---

From: Ian Hickson <[email-masked]>
Date: Thu, 15 Oct 2009 21:25:26 +0000 (UTC)

On Thu, 15 Oct 2009, SM wrote:
> You don't have to explain the constraints in your I-D.  You could provide a
> reference.

I don't know of one, unfortunately. If anyone has any suggestions, I'd be 
more than happy to include such a reference.