Microsoft pre-LCWD feedback on WebSocket API

Apologies for only sending this at the deadline. I have been collecting feedback from a number of different groups at Microsoft who have been reviewing the WebSockets API spec and only had chance to collate it today.

Feedback on Web Sockets API (draft dated 29 October 2009)

1) In the WebSocket constructor, we think it would make sense to limit the optional protocol string to a set of characters that is easier to secure. The UI never surfaces this string and having something that doesn't require processing the full set of strings into UTF-8 shouldn't be a significant restriction. We also think that specifying length constraints would be useful. For example, stipulating the minimum length that conforming implementations must be able to handle. One suggestion was to re-use the same criteria as a valid scheme name as defined in section 3.1 of RFC 3986.

2) The second comment about the protocol string is editorial. There was quite a lot of confusion about what the protocol string is used for and whether a central registry would be needed for well-known protocol strings. I don't believe this is intended or necessary but this suggests that the language could be clearer. Perhaps an informative section describing the expected use of the protocol string might be included.

3) The spec uses many terms that the HTML5 spec defines. As far as I can tell, there isn't a definitive list of these. The 2.1 dependencies section notes that many concepts come from HTML5 but not saying which ones seems insufficient for spec moving to Last Call. Most of the people who looked at this spec had never looked at HTML5 before and their feedback was simply that many terms were undefined.

4) In step 2 of the UA steps for the WebSocket() constructor, the spec calls for an exception to be thrown if the user agent chooses to block a well-known port. We think that web developers will often miss this case because it will be hard to test the error case and may be an unusual failure. We propose that the UA signal this condition in the same way as failing to connect to a service which will be much more common and more likely to be handled by web developers.

5) It is not clear precisely where the '"fail the Web Socket connection" algorithm' is defined.

6) The send() method can both throw an exception in the CONNECTING state or return an 'error' flag if in the CLOSED state. APIs that both have return values and also throw exceptions commonly cause coding errors by developers using them. For example, here web developers may fail to deal with the CONNECTING state because on their test service they get an almost immediate connection but once they deploy hitting this case becomes much more common. We recommend choosing between exceptions or return values but not both.

7) It is not clear exactly how to implement the bufferedAmount property and be interoperable. Where is the queue of bytes not yet sent? Is this at the application layer, in the networking stack, on the network card, or somewhere else? We propose removing the bufferedAmount property.

I think we will have some other feedback more related to the wire protocol than the API although changes to the protocol could potentially impact the API. I'm not sure how the working group plans to handle this interaction between the API draft and discussions elsewhere about the protocol (I understand there is a proposal to deal with the protocol in an IETF working group?).

Cheers,

Adrian.

-----Original Message-----
From: public-webapps-request@w3.org [mailto:public-webapps-request@w3.org] On Behalf Of Arthur Barstow
Sent: Wednesday, November 04, 2009 5:46 AM
To: public-webapps
Subject: Seeking pre-LCWD comments for: Server-sent Events, Web {Database, Sockets, Storage Workers}; deadline 19 November

As noted on 23 October [1], the following "HTML5 APIs" are ready or  
very close to being ready for Last Call Working Draft (LC):

1. Server-Sent Events
   http://dev.w3.org/html5/eventsource/

2. Web Database
   http://dev.w3.org/html5/webdatabase/

3. Web Sockets API
   http://dev.w3.org/html5/websockets/

4. Web Storage
   http://dev.w3.org/html5/webstorage/

5. Web Workers
   http://dev.w3.org/html5/workers/

Please submit comments about these specs by 19 November.

Note the Process Document states the following regarding the  
significance/meaning of LCWD:

[[
http://www.w3.org/2005/10/Process-20051014/tr.html#last-call
Purpose: A Working Group's Last Call announcement is a signal that:

* the Working Group believes that it has satisfied its relevant  
technical requirements (e.g., of the charter or requirements  
document) in the Working Draft;

* the Working Group believes that it has satisfied significant  
dependencies with other groups;

* other groups SHOULD review the document to confirm that these  
dependencies have been satisfied.
In general, a Last Call announcement is also a signal that the  
Working Group is planning to advance the technical report to later  
maturity levels.

]]

Additionally, a LCWD should be considered feature-complete with all  
issues resolved; that is, as Chaals noted yesterday, "Last Call means  
the Working Group considers the work to be good".

-Regards, Art Barstow

[1] http://lists.w3.org/Archives/Public/public-webapps/2009OctDec/ 
0313.html

Received on Thursday, 19 November 2009 20:57:32 UTC