DataCache API

4.1.1. Examples

An application can use a data cache to capture the representation of a resource, i.e., cache an off-line representation in the data cache.

var uri = ...
var cache = window.openDataCache();
document.body.addEventListener('onready', function(event) {
  event.cache.swapCache();
  ... // take advantage of the new stuff in the cache
});

cache.transaction(function(txn) {
  txn.capture(uri);
  txn.finish();  
});

var req = new XMLHttpRequest;
req.open('GET', uri);
...
req.send();

A dynamic representation is produced by using an embedded local server in conjunction with the data cache. An interceptor processes an HTTP request locally in an embedded local server without changing the network APIs used by applications. Thus even if a host is unreachable, applications can successfully make HTTP requests to managed resources.

var uri = ...
var cache = window.openDataCache();
var local = function(request, response) {
  response.statusCode = 200;
  response.statusLine = 'HTTP/1.1 OK';
  response.bodyText = ...
  response.send();
};

window.navigator.registerOfflineHandler(uri, local);

var txn = cache.offlineTransaction(function(txn) {
  txn.capture(uri, '', null, ['GET']);
  txn.commit();
});

var req = new XMLHttpRequest;
req.open('GET', uri);
...
req.send();

Applications can also locally intercept requests that modify data, e.g., unsafe HTTP requests such as PUT in an off-line handler. Requests to resources that are managed in a data cache can be intercepted and served by an interceptor, when the user agent is off-line or by the server, when the user agent is online with a reviewer analyzing the result of the online request. A user agent can switch between these two behaviors automatically based on system conditions.

var uri = ...
var cache = self.openDataCacheSync();
var txn = cache.transactionSync();
txn.capture(uri, ['PUT']);
txn.commit();

cache = window.openDataCache();
var intercept = function(request, response) {
  if (...) {
    // validation fails
    response.setStatus(400, 'HTTP/1.1 Bad Request');
    response.send();
    return;
  } 
  cache.offlineTransaction(function(txn) {
    txn.oncommitted = function() {
      response.bodyText = request.bodyText;
      response.headers['Content-Type'] = type;
      response.statusCode = 200;
      response.statusLine = 'HTTP/1.1 OK';
      response.send();
    });
    txn.capture(request.targetURL, request.bodyText, request.headers['Content-Type']);
    txn.commit();    
  });
};
  
var review = function(request, response) {
  cache.offlineTransaction(function(txn) {
    txn.capture(request.targetURL, response.bodyText, response.headers['Content-Type']); 
    txn.commit();
  });
};

window.navigator.registerOfflineHandler(uri, intercept, review);

var req = new XMLHttpRequest;
req.open('PUT', uri);
...
req.send(...);

var req = new XMLHttpRequest;
  req.open('GET', uri);
  ...
  req.send();

4.1.2. Event summary

Application scripts may modify the managed resources of a data cache. The user agent will fetch the representations of newly added and modified managed resources and add the representations to the data cache.

A number of events are fired to keep the application updated as to the state of the cache, so that the user can be notified appropriately. The events are as follows:

4.2.1. Opening a cache

When the user agent is required to open a data cache, given a cache host, optionally the name of an authorization cookie the user agent must perform the following steps:

1. Let cookie name be the name of an authorization cookie passed to these steps.
2. Pick the appropriate substeps:

   If the cache host passed to these steps is a Window object

   Let origin be the origin of the active document of the browsing context of that Window object.

   If the cache host passed to these steps is a WorkerUtils object

   Let origin be the origin of the scripts in the worker.

3. Atomically, so as to avoid race conditions, perform the following substeps

   If cookie name is empty, then perform the following steps:

   1. If there is an unsecure data cache group for origin origin, let data cache group be that existing data cache group.
   2. If data cache group does not exist, the perform the following substeps:
      1. Create a new data cache, called data cache, in a new unsecure data cache group for origin origin called data cache group.
      2. Set the completeness flag of data cache to incomplete.
      3. Set the update status of data cache group to idle.

   If cookie name is not empty, then perform the following steps:

   1. Let data cache group be an existing secure data cache group for origin origin, the name of whose authorization cookie case-insensitively matches cookie name.
   2. Obtain the storage mutex.
   3. Let cookie be the cookie in the current browsing context, whose name case-insensitively matches cookie name.
   4. If data cache group is defined and has an authorization cookie whose value doesn't match cookie's value then perform the following substeps:
      1. Mark data cache group obsolete.
      2. Create a new data cache, called data cache, in a new secure data cache group for origin origin called data cache group with its authorization cookie set to cookie.
      3. Set the completeness flag of data cache to incomplete.
      4. Set the update status of data cache group to idle.
   5. Release the storage mutex.

4. Return data cache.

4.2.2. Constructing and modifying data caches

Application scripts identify the resources managed by a data cache during a cache transaction, when applications may either capture or release its resources.

Each cache transaction has a data cache group and a data cache.

A cache transaction can be marked as off-line.

Each cache transaction has a status, which can be either of pending, committed, or aborted.

When a cache transaction is started, the user agent must run the cache transaction creation process. When a resource is added to a transaction's list of captured resources, the user agent must run the resource capturing process. When a resource is added to a transaction's list of released resources, the user agent must run the resource release process. When the transaction is finished, the user agent must run the cache transaction finish process.

4.2.3. Expiring data caches

As a general rule, user agents should not expire data caches, except on request from the user, or after having been left unused for an extended period of time.

Implementors are encouraged to expose data caches in a manner related to HTTP cookies, allowing caches to be expired together with cookies and other origin-specific data. Data caches and cookies have similar implications with respect to privacy (e.g. if the site can identify the user when providing the cache, it can store data in the cache that can be used for cookie resurrection).

4.2.4. The API

[Supplemental] 
  interface CacheUtil {
    DataCache openDataCache([optional in] DOMString cookieName);
  };
    
  Window implements CacheUtil;
  
  [Supplemental]
  interface CacheUtilSync {
    DataCacheSync openDataCacheSync([optional in] DOMString cookieName);
  };
    
  WorkerUtils implements CacheUtilSync;

window.openDataCache()

(In a window) Returns a DataCache object that represents the data cache obtained from cache opening steps using window as the cache host and cookieName as the name of an authorization cookie.

self.openDataCacheSync()

(In a shared worker) Returns a DataCacheSync object that represents the data cache obtained from cache opening steps using worker as the cache host and cookieName as the name of an authorization cookie.

var cache = self.openDataCacheSync();

var cache = window.openDataCache('SSID');

4.2.5. Asynchronous Data Cache API

interface DataCache { 
  const unsigned short IDLE = 0;
  const unsigned short READY = 1;
  const unsigned short OBSOLETE = 2;
  readonly attribute unsigned short status;
  readonly attribute DOMString requiredCookie;
  readonly attribute long version;
  
  // updates
  void transaction(in TransactionCallback callback,
                   [optional in] VoidCallback errorCallback);
  void offlineTransaction(in TransactionCallback callback,
                          [optional in] VoidCallback errorCallback);
  void swapCache();
  void eachModificationSince(in long version, 
                             in ItemCallback callback,
                             [optional in] VoidCallback successCallback);
};

[Callback=FunctionOnly, NoInterfaceObject]
interface TransactionCallback {
  void callback(in CacheTransaction txn);
};

[Callback=FunctionOnly, NoInterfaceObject]
interface VoidCallback {
  void callback();
};

transaction() and offlineTransaction()

Both methods take one or two arguments - a transaction callback and optionally an error callback. When called, this method must immediately return and asynchronously perform the following steps:

1. Set off-line to false if offlineTransaction() was called, and true otherwise.
2. Execute the steps to create a cache transaction with the first argument being the data cache group of this DataCache object and the second argument being off-line.
3. Let result be a new CacheTransaction object for the transaction returned from the previous step.
4. If transaction callback is not null, queue a task to invoke the transaction callback with the aforementioned CacheTransaction object as its only argument, and wait for that task to be run.
5. If transaction callback raised an exception, jump to the last step.
6. End these steps. The next step is only used when something goes wrong.
7. Queue a task to invoke the error callback, if it is not null.

swapCache()

Perform the steps to activate updates with the data cache group of this DataCache object.

eachModificationSince()

This method takes one to three parameters - low watermark version and item callback, and an optional success callback. When called, this method must immediately return and asynchronously perform the following steps:

1. Let additions be a list of entities with their URIs and let removals be a list of URIs.
2. Let cache be the data cache represented by this DataCache object.
3. For each data cache belonging to cache's data cache group, starting from cache's version down to low watermark version, perform the following substeps:
   1. Let old cache be the data cache.
   2. Let old version be old cache's version.
   3. For the entity entityof each managed resource of old cache that was added in the old version, perform the following steps:
      1. Let id be the URI of the managed resource.
      2. If neither additions nor removals already includes id, then add id with entity to additions.
   4. For each managed resource of old cache that was removed in the old version, perform the following steps:
      1. Let id be the URI of the managed resource.
      2. If neither additions nor removals already includes id, then add id to removals.
4. If item callback is not null, then for each item item in additions, perform the following steps:
   1. For each item item in additions, queue a task to invoke the item callback with item.
   2. For each item item in removals, queue a task to invoke the item callback with item.
5. If success callback is not null, then queue a task to invoke the success callback

version

This attribute, on getting, must return the version of the data cache of this DataCache object.

requiredCookie

This attribute, on getting, must return the name of the authorization cookie of the data cache group of this DataCache object.

status

This attribute, on getting, must return the current state of the data cache of this DataCache object. This must be the appropriate value from the following list:

IDLE

This DataCache object's cache host is aassociated with a data cache whose data cache group's update status is idle and that data cache is the newest cache in its data cache group, and the data cache group is not marked obsolete.

READY

This DataCache object's cache host is aassociated with a data cache whose data cache group's update status is idle, and whose data cache group is not marked as obsolete, but that data cache is not the newest cache in its data cache group.

OBSOLETE

This DataCache object's cache host is aassociated with a data cache whose data cache group is marked as obsolete.

4.2.6. Synchronous Data Cache API

interface DataCacheSync : DataCache {
  OnlineTransaction transactionSync();
};

The transactionSync method must perform the following steps:

1. Execute the steps to create a cache transaction with the first argument being the data cache group of this DataCache object and the second argument being false.
2. Let result be a new CacheTransaction object for the transaction returned from the previous step.
3. Return result.

4.2.7. Transaction API

interface CacheTransaction {
  void getItem(in DOMString uri, ItemCallback callback);
  void release(in DOMString uri);
  void commit();
  
  // events
           attribute Function oncommitted;
};

interface OnlineTransaction : CacheTransaction {
  void capture(in DOMString uri, [optional in] DOMStringList dynamicMethods);
  void abort();
};

interface OfflineTransaction : CacheTransaction {
  void capture(in DOMString uri, 
               in DOMString body, 
               [optional in] DOMString contentType, 
               [optional in] DOMStringList dynamicMethods);
};

[Callback=FunctionOnly, NoInterfaceObject]
interface ItemCallback {
  void callback(in CacheItem item);
};

interface CacheItem {
  const unsigned short UNCACHED = 0;
  const unsigned short FETCHING = 1;
  const unsigned short CACHED = 2;
  const unsigned short GONE = 3;
  
  readonly attribute unsigned short readyState;
  readonly attribute FileData body;
  readonly attribute DOMStringList dynamicMethods; 
  readonly attribute any headers;
};

capture()

This method takes one or two arguments - a uri of the resource to capture and an optional list of dynamic methods. When called, this method must immediately return and asynchronously perform the steps in the resource capturing process with the first argument being uri, second being the current window or worker object, the third being this CacheTransaction object's associated cache transaction, the fourth being dynamic methods.

capture()

This method takes two to four arguments - a uri of the resource to capture, an entity body, optionally a content type, and an optional list of dynamic methods. When called, this method must immediately return and asynchronously perform the steps in the resource capturing process with the first argument being uri, second being the current window or worker object, the third being this CacheTransaction object's associated cache transaction, the fourth being dynamic methods, the fifth being entity body, and the sixth being content type.

release()

This method takes one argument - uri of the resource to release. When called, this method must immediately return and asynchronously perform the steps in the resource releasing process with the first argument being uri, second being the current window or worker object, and the third being this CacheTransaction object's associated cache transaction.

abort()

When called, this method must immediately return and asynchronously perform the steps in the cache transaction abort process with the first argument being this CacheTransaction object's associated cache transaction, and the second being the window or worker object.

commit()

When called, this method must immediately return and asynchronously perform the following steps:

1. Execute the cache transaction commit process with the first argument being this CacheTransaction object's associated cache transaction, and the second being the current window or worker object.
2. If oncommitted attribute on this CacheTransaction object is not null, queue a task to invoke the function identified by oncommitted .

getItem()

This method takes two arguments - a uri and an item callback. When called, this method must immediately return and asynchronously perform the following steps:

1. If the resource identified by uri does not exist in this CacheTransaction object's associated data cache, then the method must raise data cache object, then the method must raise the NOT_FOUND_ERR exception and terminate these steps.
2. Let item be the entity in this CacheTransaction object's associated data cache.
3. Create object, a new CacheItem object with the associated item.
4. Queue a task to invoke item callback with the aforementioned CacheItem object as its only argument.

oncommitted

This attribute, on getting, must return the function to be invoked when this CacheTransaction object has been committed.

This attribute, on setting, must store the function to be invoked when this CacheTransaction object has been committed.

body

This attribute, on getting, must return the entity body, if any, as a FileData object [FileAPI], of the managed resource associated with this CacheItem object.

dynamicMethods

This attribute, on getting, must return the list of protocol methods, if any, of the managed resource associated with this CacheItem object.

headers

This attribute, on getting, must return the headers as a native ordered dictionary data type from the managed resource associated with this CacheItem object. In the JavaScript binding, this must be Object. Each header must have one property (or dictionary entry), with those properties enumerating in the order that the headers were recorded in the managed resource. Each property must have the name of the header and its value as recorded in the managed resource.

readyState

This attribute, on getting, must return the current state of the managed resource. This must be the appropriate value from the following list:

UNCACHED

This CacheItem object is associated with a managed resource which has been added for capturing but has not yet been cached. There is no value available in body or headers.

FETCHING

This CacheItem object is associated with a managed resource which is currently being fetched. There is no value available in body or headers.

CACHED

This CacheItem object is associated with a managed resource which has been cached.

GONE

This CacheItem object is associated with a managed resource which has been released. There is no value available in body, headers, or dynamicMethods.

For both capture() methods, dynamic methods is a comma separated list of protocol methods that can be intercepted for local processing. An empty string is allowed for this parameter.

4.2.8. The CacheEvent

The task source for this task is the networking task source.

If the event being fired is fetching, captured, or released, then the event must have its uri attribute set to the URI of the affected managed resource.

Otherwise, if the event being fired is off-line-updating, updating, error, obsolete, or ready, then the event must have its uri attribute set to null.

interface CacheEvent : Event {
  readonly attribute DataCache cache;
  readonly attribute DOMString uri;
  
  void initCacheEvent(DataCache cache,
                      in DOMString uri);  
  void initCacheEventNS(in DOMString namespaceURI,
                        DataCache cache,
                        in DOMString uri);
};            
            

cache

This attribute, on getting, must return a DataCache object representing the data cache on which this event is fired.

uri

This attribute, on getting, must return the URI of the managed resource for which this event is fired.

initCacheEvent and initCacheEventNS

These methods must initialize the event in a manner analogous to the similarly named methods in the DOM Events interfaces. [DOM3Events]

4.3.1. Local Server API

[Supplemental, NoInterfaceObject]
interface NavigatorLocalServer {
  void registerOfflineHandler(in DOMString namespace, 
                       InterceptHandler intercept, 
                       ReviewHandler review);
};

Navigator implements NavigatorLocalServer;

[Callback=FunctionOnly, NoInterfaceObject]
interface InterceptHandler {
  void callback(in HttpRequest request,
                in MutableHttpResponse response);
};

[Callback=FunctionOnly, NoInterfaceObject]
interface ReviewHandler {
  void callback(in HttpRequest request,
                in HttpResponse response);
};

interface HttpRequest {
  // properties
  readonly attribute DOMString method;
  readonly attribute DOMString target;
  readonly attribute DOMString bodyText;
  readonly attribute any headers;
};

interface MutableHttpResponse {
  void setStatus(in unsigned short code, in DOMString message);
  void setResponseText(in DOMString text);
  void setResponseHeader(in DOMString name, in DOMString value);
  void send();
};

interface HttpResponse {
  // properties
  readonly attribute unsigned short statusCode;
  readonly attribute DOMString statusMessage;
  readonly attribute DOMString bodyText;
  readonly attribute any headers;
};

The navigator.registerOfflineHandler() method takes two or three arguments - a uri for identifying the namespace of resources that are to be intercepted, an intercept handler function, and an optional review handler function. This method allows applications to register themselves as possible handlers for particular URI namespaces. Upon being invoked, this method should create a new embedded local server called server with its interceptor function set to intercept handler and its reviewer function set to review handler and add server to the cache host.

The user agent must invoke the InterceptHandler, with an HttpRequest object request based on the application's resource request and an MutableHttpResponse object response. When the send() method is invoked on response, the user agent must respond to request with the headers, body, and status specified in response.

The user agent must invoke the ReviewHandler, with an HttpRequest object request based on the application's resource request and an HttpResponse object response based on the host's response to that request.

The following attributes are available on the HttpRequest object:

method

This attribute, on getting, must return the HTTP method, in upper-case characters, present on this HttpRequest object.

target

This attribute, on getting, must return the URI of this HttpRequest object.

bodyText

This attribute, on getting, must return the entity body of this HttpRequest object, if the body has a Content-Type of either text/* or application/xml.

headers

This attribute, on getting, must return the headers as a native ordered dictionary data type from this HttpRequest object. In the JavaScript binding, this must be Object. Each header must have one property (or dictionary entry), with those properties enumerating in the order that the headers were present in the request. Each property must have the name of the header and its value as present in the request.

The following methods are available on the MutableHttpResponse object:

setResponseHeader()

This method takes two arguments - name and value of a response header. Upon calling, this method must store the header with name and value in this MutableHttpResponse object. If a value is already associated with this header, then this method must append value to it.

setStatus()

This method takes two arguments - code and message of the response status. Upon calling, this method must store the status with code and message in this MutableHttpResponse object, replacing any previous values for both.

setResponseText()

This method takes a single arguments - body of the response entity. Upon calling, this method must store the entity body in this MutableHttpResponse object, replacing any previous value.

send()

Upon calling, this method must dispatch this MutableHttpResponse object. No further changes must be allowed to it.

The following attributes are available on the HttpResponse object:

statusCode

This attribute, on getting, must return the status code of this HttpResponse object.

statusMessage

This attribute, on getting, must return the status message of this HttpResponse object.

bodyText

This attribute, on getting, must return the entity body of this HttpResponse object, if the body has a Content-Type of either text/* or application/xml.

headers

This attribute, on getting, must return the headers as a native ordered dictionary data type from this HttpResponse object. In the JavaScript binding, this must be Object. Each header must have one property (or dictionary entry), with those properties enumerating in the order that the headers were present in the response. Each property must have the name of the header and its value as present in the response.

4.3.2. Changes to the networking model

When a cache host is associated with one or more effective data caches, any and all loads for resources related to that cache host other than those for child browsing contexts must go through the following steps instead of immediately invoking the mechanisms appropriate to that resource's scheme:

1. Let request be the resource request for fetching the resource.
2. If request includes the HTTP header X-Bypass-DataCache and the value of that header is true, then fetch the resource normally, and abort these steps.
3. Let caches be the set of all effective data caches for the cache host.
4. Let resource be the resource to be fetched.
5. If resource is not managed in caches, then fetch a representation of resource normally and abort these steps.
6. Select a data cache cache from caches.
7. If request is using the HTTP GET mechanism and resource is not defined in cache with a dynamic GET method, then get the entity for resource from the cache (instead of fetching it), and abort these steps.
8. If request is using the HTTP HEAD mechanism and resource is not defined in cache with a dynamic HEAD method, then get the entity headers for resource from the cache (instead of fetching it), and abort these steps.
9. If resource is not defined in cache with the dynamic method that request is using, then fetch a representation of resource normally and abort these steps.
10. Pick the appropriate steps:

    If the user agent is off-line

    1. Select an embedded server server to produce an off-line response.
    2. Create a new response object to hold the dynamic response to request.
    3. Call the interception function of server passing as arguments request and response.
    4. Wait for the interception function to dispatch the dynamic response.
    5. Handle response as the dynamic response, and abort these steps.

    If the user agent is online

    1. Select an embedded server server to review the online response.
    2. Fetch a representation of resource normally and call it response.
    3. Call the reviewer function of server passing as arguments request and response.
    4. Handle response as the dynamic response, and abort these steps.

11. Fail the resource load.