Bug 12510 - Specs split off from HTML5 (like WebSockets) need to have xrefs linked, otherwise they're ambiguous
Summary: Specs split off from HTML5 (like WebSockets) need to have xrefs linked, other...
Status: NEW
Alias: None
Product: WebAppsWG
Classification: Unclassified
Component: WebSocket API (editor: Ian Hickson) (show other bugs)
Version: unspecified
Hardware: All All
: P2 normal
Target Milestone: ---
Assignee: Glenn Adams
QA Contact: public-webapps-bugzilla
URL:
Whiteboard: xref
Keywords:
: 13280 (view as bug list)
Depends on:
Blocks:
 
Reported: 2011-04-16 02:11 UTC by Glenn Adams
Modified: 2012-10-29 21:50 UTC (History)
8 users (show)

See Also:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Glenn Adams 2011-04-16 02:11:08 UTC
As presently defined, WebSocket may establish a connection before onopen is set. Using the example found in Section 4:

var socket = new WebSocket('ws://game.example.com:12010/updates');
socket.onopen = function () {
  setInterval(function() {
    if (socket.bufferedAmount == 0)
      socket.send(getUpdateData());
  }, 50);
};

In this case, the new websocket may transition to OPEN state prior to execution of the statement that sets the onopen property. For instance, this may occur when stepping through this JS code in a JS debugger, or when GC occurs between the constructor and the following statement.

The WS API should be modified to separate construction from opening, e..g., following a paradigm similar to XHR in which case the above example would become:

var socket = new WebSocket();
socket.onopen = function () {
  setInterval(function() {
    if (socket.bufferedAmount == 0)
      socket.send(getUpdateData());
  }, 50);
};
socket.open('ws://game.example.com:12010/updates');

Regards,
Glenn Adams
Comment 1 Simon Pieters 2011-04-29 14:23:08 UTC
There's no race condition. The spec queues a task to fire 'open', so even if the connection is established before the script has finished running, the event isn't fired until the event loop spins.

Adding .open() doesn't help since we'd still want there to be no race condition if open() is called before setting the listener (since authors are going to do that).
Comment 2 Olli Pettay 2011-05-24 19:14:02 UTC
Yeah, this is invalid, as far as I see.
Comment 3 Glenn Adams 2011-05-24 20:09:39 UTC
(In reply to comment #2)
> Yeah, this is invalid, as far as I see.

I disagree.

Notwithstanding the statement in 2.1 that "Many fundamental concepts from HTML are used by this specification. [HTML]", the current WebSocket spec does not normatively reference the task, task queue, or task dispatch semantics defined by HTML5. If the constraints on task semantics that are defined by HTML5 are required to prevent deadlocks in WebSocket, then WebSocket must normatively reference the definitions of task, task queue, and task dispatching semantics defined in HTML5.

Otherwise, WebSocket is underspecified and an arbitrary implementation (that does not happen to employ the HTML5 constraints) may indeed be deadlocked.

Regards,
Glenn
Comment 4 Ian 'Hixie' Hickson 2011-05-24 23:43:50 UTC
The sentence you quote is that normative reference.

You're better off reading the spec in its full form where those terms are just part of the spec, anyway; the W3C copy is just an extract of the full spec. The full spec is here:

   http://www.whatwg.org/specs/web-apps/current-work/complete/network.html#network
Comment 5 Glenn Adams 2011-05-25 04:22:17 UTC
(In reply to comment #4)
> The sentence you quote is that normative reference.
> 
> You're better off reading the spec in its full form where those terms are just
> part of the spec, anyway; the W3C copy is just an extract of the full spec. The
> full spec is here:
> 
>   
> http://www.whatwg.org/specs/web-apps/current-work/complete/network.html#network

I'm sorry, but I do not recognize the role of WhatWG in terms of defining normative W3C specifications. The sentence I quoted is insufficient since it does not cite which normative definitions of HTML5 apply. At present, this results in WebSocket being "not-well-defined".

Regards,
Glenn
Comment 6 Aryeh Gregor 2011-05-25 22:42:42 UTC
It looks like the script that splits up the spec doesn't make cross-spec references into links.  This seems like a bug in the spec-splitter, which could be confusing, since the writing style of HTML5 relies heavily on xrefs to make its meaning clear.  Specs like DOM Range do cross-spec xrefs just fine, so no reason HTML5-related specs shouldn't.
Comment 7 Aryeh Gregor 2011-05-27 17:13:05 UTC
Changed summary to make it clear this is a question of bugs in the spec-splitter, not a bug in the original source text.  In this specific case, the terms used are pretty distinctive, and if you know they're defined in HTML5 (which this spec normatively references) you'll be able to find them, so it's not really very ambiguous in the end.  But it could be confusing to someone who's not so familiar with HTML5.
Comment 8 Glenn Adams 2011-05-27 17:40:44 UTC
(In reply to comment #7)
> Changed summary to make it clear this is a question of bugs in the
> spec-splitter, not a bug in the original source text.  In this specific case,
> the terms used are pretty distinctive, and if you know they're defined in HTML5
> (which this spec normatively references) you'll be able to find them, so it's
> not really very ambiguous in the end.  But it could be confusing to someone
> who's not so familiar with HTML5.

Please note also that there is a circular reference between HTML5 and WebSockets, since the former normatively references the latter and the latter normatively references the former.

This is rather unsatisfactory in formal spec writing. It is best to have a non-circular dependency graph.
Comment 9 Aryeh Gregor 2011-05-27 17:49:55 UTC
If you think that's an issue, you should probably file a separate bug.  As far as I'm aware, it's allowed by W3C Process: they'd just have to progress to PR at the same time.
Comment 10 Aryeh Gregor 2011-07-17 14:29:22 UTC
*** Bug 13280 has been marked as a duplicate of this bug. ***
Comment 11 Ian 'Hixie' Hickson 2011-10-31 22:47:58 UTC
I have no intention of adding cross-spec cross-references to the WebSocket spec. If someone is interested in providing patches to the spec splitter to do this, please contact me directly.
Comment 12 Glenn Adams 2011-11-09 02:12:32 UTC
(In reply to comment #11)
> I have no intention of adding cross-spec cross-references to the WebSocket
> spec. If someone is interested in providing patches to the spec splitter to do
> this, please contact me directly.

How you create your spec products for use in the W3C is your business, not mine. I am asking that each reference or use of a "fundamental concept" as described in 2.1:

"Many fundamental concepts from HTML are used by this specification. [HTML]"

be made explicit by using a link (anchor) to the relevant defining clause/section in [HTML].

For example, the following phrases should link to the defining sections of [HTML]:

1. "queue a task" => http://dev.w3.org/html5/spec/Overview.html#queue-a-task
2. "dispatch [an] event" => http://dev.w3.org/html5/spec/Overview.html#concept-event-dispatch
3. "task source" => http://dev.w3.org/html5/spec/Overview.html#task-source
4. "event loop" => http://dev.w3.org/html5/spec/Overview.html#event-loop
5. "task" (otherwise unqualified) => http://dev.w3.org/html5/spec/Overview.html#concept-task

If these (and any other "concepts from HTML" I don't list above) are used normatively, then it should be made clear that the HTML definition applies (and not some other random implied definition). I don't care if it is done by links at each usage, or by listing the concepts in one place (e.g., under dependencies) and placing the links there.
Comment 13 Ian 'Hixie' Hickson 2011-12-02 16:48:33 UTC
I understand what you're asking for. I'm saying that if you want it any time soon, you need to provide the script to set it up. Failing that, it'll have to wait until I get around to it, which may not be for some time as I don't really have a good idea for how to do it.
Comment 14 Julian Reschke 2011-12-02 17:19:16 UTC
This is indeed a problem. The W3C version is incomplete/underspecified without these terms being properly linked (note that a similar issue has been raised by me with respect to "URL" parsing during WGLC).
Comment 15 Ian 'Hixie' Hickson 2011-12-03 02:54:27 UTC
If you want the hyperlinks, use the WHATWG version. It's the same text.

Hyperlinks cannot possibly be required for the content to make sense, by the way, otherwise we'd never be able to print the spec. That just makes no sense.
Comment 16 Julian Reschke 2011-12-03 09:28:05 UTC
(In reply to comment #15)
> If you want the hyperlinks, use the WHATWG version. It's the same text.

This bug isn't about the WHATWG spec.

The *published* W3C spec needs to be complete and well-defined. Somebody will have to take care of this. (And yes, it's your right to not care, in which the W3C should assign somebody else to fix it).
 
> Hyperlinks cannot possibly be required for the content to make sense, by the
> way, otherwise we'd never be able to print the spec. That just makes no sense.

What's essential is that's clear what certain text means. Hyperlinking it is one way for HTML. For a print version, external links could be inlined as visibile text. Also, with respect to printing, internal links have the same problem.
Comment 17 Ian 'Hixie' Hickson 2012-07-10 22:36:31 UTC
If the W3C does "assign somebody else to fix it", I'd be happy to work with them. So if anyone wants to do that, drop me a private e-mail and I'll set you up with the right files to edit, etc.
Comment 18 Julian Reschke 2012-07-12 05:35:10 UTC
See <http://lists.w3.org/Archives/Public/public-webapps/2012JulSep/0104.html> for a patch applicable to the W3C version of the spec.
Comment 19 Ian 'Hixie' Hickson 2012-10-26 23:35:42 UTC
That patch is unhelpful since it is to a dynamically generated file. Hence my comment 17.

I'm marking this WONTFIX, since I view the WHATWG version as canonical and don't really think it's a problem for people to use the WHATWG version. The W3C version is only useful for the patent policy, and thus doesn't need the hyperlinks.

However, I wouldn't object to someone finding a solution to this. If anyone does want to actually work with me to fix this, please reopen the bug, assign it to yourself, and e-mail me, as per comment 17. Thanks.
Comment 20 Glenn Adams 2012-10-27 05:18:33 UTC
I'm unable to accept this resolution, in part because this is a W3C venue and, as a consequence, the W3C version of HTML5 is canonical, not WHATWG. It is the responsibility of the spec writer to define or referenced external definition of formal terms, and that responsibility applies here.
Comment 21 Ian 'Hixie' Hickson 2012-10-29 21:50:49 UTC
I'm not going to be doing it, if you want to do it you are welcome to work with Art to do so. Reassigning it to you to get it off my radar. The W3C versions of these specs are not their canonical versions, whether for Web Sockets or for HTML, as far as I am concerned.