IE Team's Feedback on the XHR Draft

We've taken a look at the latest editor's draft and our suggestions and comments are below. The spec does have granularity to allow UA's to make consistent implementations and reduces the scope for confusion. I'm on a thread with Hallvord and he's mentioned the compliance tests will be more stable once the spec becomes less of a moving target. We'd love to know where the spec and IE differs as soon as that's ready so we can explore where we want to go for each case. Hope the feedback helps!


·        Mentioning the target audience would improve readability.

o   This spec is very different from existing HTML/CSS/DOM spec where the functionality/API specification is the focus.  This spec talks about interface specification as well as a lot of details that appear to be internal implementation issues that cannot be verified by Web developers.  Having internal implementation recommendation for UA's is nice, however we can improve the readability by calling out implementation detail sections or having a separate section for this detail .  What we've love is to have the spec clearly state what is external API specification, and what is internal implementation details. This way a web developer can read this without reading the whole spec and take away the key points.

§  I remember Anne mentioning that the spec's target audience is only UA's however that is not clear from the spec. Here's an instance from the spec (Send method) that highlights this. Note the use of the word 'Authors' meaning web authors so this validates the importance of marking the internal implementation issues so that it's clearly distinguishable for the authors. We tend to use a functional specification and an internal design specification here to separate the two aspects.  Perhaps this specification is intended to be only the internal design spec; if so, perhaps we should pull out a copy of the API definition and explanations, and make a "web developers' guide to XHR"?

·        Authors are encouraged to ensure that they have specified the Content-Type header via setRequestHeader()<http://dev.w3.org/2006/webapi/XMLHttpRequest/#setrequestheader> before invoking send()<http://dev.w3.org/2006/webapi/XMLHttpRequest/#send> with a non-null data argument.

o   Here's the internal UA specific detail that should be called out separately.

§  When the XMLHttpRequest() constructor is invoked a persistent pointer to the associated Window object must be stored on the newly created object. This is the Window pointer. The associated Window object is the one of which the XMLHttpRequest() constructor was invoked. This pointer<http://www.w3.org/TR/XMLHttpRequest/#window-pointer> must persist even if the browsing context in which the Window is located is destroyed (by removing it from a parent browsing context, for instance).

§  The DONE state has an associated error flag which can be either "true" or "false". The initial value of the error flag is "false".

§  <For open call> If the password argument was not omitted and is null remove stored password.

§  <For open call> Switch the object to the OPENED<http://dev.w3.org/2006/webapi/XMLHttpRequest/#opened-state> state, set the send() flag<http://dev.w3.org/2006/webapi/XMLHttpRequest/#send-flag> to "false" and then synchronously dispatch a readystatechange<http://dev.w3.org/2006/webapi/XMLHttpRequest/#readystatechange> event on the object and return the method call.

§  <For send call> If async is true set the send() flag<http://dev.w3.org/2006/webapi/XMLHttpRequest/#send-flag> to "true".

§  <For send call> Make a request to stored url, using HTTP method stored method, user stored user (if provided) and password stored password (if provided), taking into account the entity body, list of request headers and the rules listed directly after this set of steps. Synchronously dispatch a readystatechange<http://dev.w3.org/2006/webapi/XMLHttpRequest/#readystatechange> event on the object.

§  <For HTTP Redirects>

1.      Set the response entity body<http://dev.w3.org/2006/webapi/XMLHttpRequest/#response-entity-body> to "null", the error flag<http://dev.w3.org/2006/webapi/XMLHttpRequest/#error-flag> to "true" and reset the list of request headers.

2.      Synchronously switch the state to DONE<http://dev.w3.org/2006/webapi/XMLHttpRequest/#done-state>.

3.      If async is set to false raise a NETWORK_ERR<http://dev.w3.org/2006/webapi/XMLHttpRequest/#network-err> exception and terminate the overall algorithm.

4.      Synchronously dispatch a readystatechange<http://dev.w3.org/2006/webapi/XMLHttpRequest/#readystatechange> event on the object.

5.      Terminate the overall algorithm.

§  <For user Canceling download>

1.      Set the response entity body<http://dev.w3.org/2006/webapi/XMLHttpRequest/#response-entity-body> to "null", the error flag<http://dev.w3.org/2006/webapi/XMLHttpRequest/#error-flag> to "true" and reset the list of request headers.

2.      Synchronously switch the state to DONE<http://dev.w3.org/2006/webapi/XMLHttpRequest/#done-state>.

3.      If async is set to false raise an ABORT_ERR<http://dev.w3.org/2006/webapi/XMLHttpRequest/#abort-err> exception and terminate the overall algorithm.

4.      Synchronously dispatch a readystatechange<http://dev.w3.org/2006/webapi/XMLHttpRequest/#readystatechange> event on the object.

5.      Terminate the overall algorithm.


·        Please link conformance test suite to an appendix/bottom of specification.

o   The spec is very detailed and the tests are difficult to correlate to exact sections of the spec. I think that's understandable at this stage since the spec is in flux. We think the official test suite deserves to be called out; linking the tests to the spec will ensure that this is the official test.

o   As per our agreement in the tech plenary the spec will conform to IE's implementation of XHR (with the exception of constants) and will be changed accordingly. The tests are important for us and other UAs as it's the guarantor of that.

§  If there is no Content-Type header or there is a Content-Type header which contains a MIME type that is text/xml, application/xml or ends in +xml (ignoring any parameters) use the rules set forth in the XML specifications to determine the character encoding. Let charset be the determined character encoding.

·        Other observations from the spec

o   Is this included due to security concerns?

§  Scripts in the resulting document tree will not be executed, resources referenced will not be loaded and no associated XSLT will be applied.

·        It's not clear what the end result is we're trying to achieve with the following is. Can we clarify?



§  The associated Document object is the one returned by the document attribute from the object on which the XMLHttpRequest() constructor was invoked (a Window object).

o   Is it:

§  When invoking a new XHR object, tie new object to the window its associated with?

§  User agents should persist document pointers to the newly created XHR object?

·        Why is this in the open method section of the specification? I recommend the spec does not mention this; if it does, we should talk about "the future" in a separate section.

o   A future version or extension of this specification will most likely define a way of doing cross-site requests.

o   It is likely that a future version of the XMLHttpRequest<http://dev.w3.org/2006/webapi/XMLHttpRequest/#xmlhttprequest-object> object will dispatch an error event here as well

o   It is likely that a future version of the XMLHttpRequest<http://dev.w3.org/2006/webapi/XMLHttpRequest/#xmlhttprequest-object> object will dispatch an abort event here as well.




--
Sunava Dutta
Program Manager (AJAX) - Developer Experience Team, Internet Explorer
One Microsoft Way, Redmond WA 98052
TEL# (425) 705-1418
FAX# (425) 936-7329