Return Promise from JavaScript API

[michael-oneill]

Browsers mostly are based on multiple processes and threads of execution. Many things happen in parallel i.e. asynchronously such as the different browser tabs, separate "browsing contexts" in embedded iframes, loading of resources etc. This is especially important for APIs that deal with cross-domain activities as DNT has to. The code to calculate what the DNT header should be for a particular request needs to operate asynchronously and usually is executed in an entirely different process than a particular browsing context.

JavaScript is designed to be single-threaded, there is no yield, pre-emption or need for a spin lock.

The only way to model parallel activities is to use callbacks. If a piece of code needs to run later or at intervals then there is the built-in function setInterval and setTimeout which take a call back function as an argument. When the timeout/interval elapses the callback function is queued to be called after all the code sequences in the current document has completed, there is no pre-emption.

Similarly any API that deals with delayed execution, which is necessary for example if data needs to assembled across different origins such as the web-wide or site specific "DNT exceptions" needs to be support a callback function. For example if some code registers DNT:0 for a subresource then initiates an XHR to send a request , the DNT value will probably be wrong (i.e. still set) if there is no intervening delay. This means that at the moment any call to the JavaScrpt API must be followed by a call to setTimeout to allow the exception time to be executed.

The modern way to use callbacks is Promises, many APIs now support them and the intrinsics are built in to the latest version of JavaScript.

Here is a brief description: https://spring.io/understanding/javascript-promises

As we have discussed in the past we should amend the API so all functions return a Promise to guarantee asynchronous completion at the time the Promise is resolved.

The Promise has a fulfilment value, i.e. a JavaScript object, named TrackingStatusObject .

A TrackingStatusObject (TSO) contains a DOMString Status indicating the success or failure of the call. Although all calls with valid parameters can be assumed to succeed, there needs to be a way to indicate if the parameters were wrong. We could also return other properties here but that will be the subject of another Issue, as will other additions to the API.

partial interface Navigator {
    Promise<TrackingStatusObject> 
        storeSiteSpecificTrackingException (TrackingPermission properties);
    Promise<TrackingStatusObject> 
        confirmTrackingException(TrackingPermission properties);
};
dictionary TrackingStatusObject {
    DomString Status; // string value indicating "OK" for success or any other value for failure
    DOMString Version; // a string indicating what version of the API is supported by this implementation.
                         // this is encoded as {major-version-number}.{minor-version-number}
                        // e.g. "1.0" can signify the current version.


};
dictionary StoreExceptionPropertyBag {
DOMString? domain;
DOMString? siteName;
DOMString? explanationString;
DOMString? detailURI;
DOMString? expires;
long? maxAge;
};
dictionary TrackingPermission : StoreExceptionPropertyBag {


};

[michael-oneill]

This is split from issue 6 which will eventually be closed

[michael-oneill]

Here is an html document containing the 7.4 Site-specific Exceptions section with Promises added. The promises all resolve to a void or a boolean (the confirms), with SYNTAX_ERR now the reason for a rejection.
The idea is that all this can be edited independently then plonked into the main TPE text. It is all in the file dntapiwithpromises.html in this repo.

If we want to add more complex return values we can resolve to a new object instead of a void.

https://w3c.github.io/dnt/dntapiwithpromises.html

[mschunte2]

2017-02-06: We agreed that promises are a good idea. Editors: Could you change the spec accordingly (Mike may be able to provide missing details).

[michael-oneill]

I have edited the TPE in the drafts folder https://w3c.github.io/dnt/drafts/tracking-dnt.html#exceptions-javascript-api-rqst

[royfielding]

My guess is that you were subclassing the parameter definitions for editorial reasons, so I simplified it by merging the directories.

[royfielding]

actually, the previous (purely editorial) merge was not related to issue #12

[royfielding]

I agree that promises are the right construct to use for APIs that access client-side storage. However, I don't think the new API definitions are consistent with how other specifications have defined promises. In particular, the return values and exceptions are not consistent with how we are supposed to define a promise as being fulfilled or rejected.

For better examples, see the FileSystem API, Push API, and the TAG finding on Writing Promise-Using Specifications.