Programmable HTTP Caching and Serving

4.2.1 Starting a transaction

When the user agent is required to create a cache transaction given an application cache group and an off-line flag, the user agent must run the following steps:

1. Let cache group be the application cache group passed to these steps.
2. If cache group is marked obsolete, then set an error and abort these steps.
3. Pick the appropriate steps:

   If the off-line flag passed to these steps is set.

   1. Create a new application cache, called cache, in cache group.
   2. Set the dynamic completeness flag of cache to incomplete.
   3. Create a new cache transaction called transaction and set cache to be its application cache.
   4. Mark transaction as off-line transaction.
   5. Return transaction.

   If the off-line flag passed to these steps is not set.

   1. Atomically, so as to avoid race conditions, perform the following sub-steps
      1. If the dynamic update status of cache group is updating, then set an error and abort these steps, as a cache transaction is already open on this application cache group.
      2. Set the dynamic update status of cache group to updating.
   2. Create a new application cache, called cache, in cache group which holds all the same resources as the relevant application cache of cache group.
   3. Set the dynamic completeness flag of cache to incomplete.
   4. Create a new cache transaction called transaction and set cache to be its application cache.
   5. Mark transaction as not off-line.

4. Set transaction's commit status to pending.
5. Return transaction.

4.2.2 Capturing resources

When the user agent is required to add a resource to be captured, given the URI of the resource to capture, a cache transaction, optionally a list of dynamic methods, optionally content to serve as the static representation of that resource, and optionally content type for that representation, the user agent must perform the following steps:

1. Let transaction be the cache transaction passed to these steps.
2. If transaction's commit status is not pending, then set an error and abort these steps.
3. Pick the appropriate sub-steps:

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

   Let origin be the origin of the cache host passed to these steps.

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

   Let origin be the origin of the scripts in the worker for the cache host passed to these steps.

4. Resolve the URI passed to these steps relative to base URI.
5. If the resulting absolute URI has a different <scheme> component than the base URI (compared in an ASCII case-insensitive manner), then set an error and abort these steps.
6. If the resulting absolute URI does not have the same origin as base URI, then set an error and abort these steps.
7. Drop the <fragment> component of the resulting absolute URI, if it has one.
8. Let cache be transaction's application cache.
9. If the resulting absolute URI identifies an explicit entry or master entry or the manifest of cache, then set an error and abort these steps.
10. If the resulting absolute URI identifies a managed resource that is already in cache, then remove that managed resource from cache.
11. Pick the appropriate sub-steps:

    If transaction is not marked as off-line

    1. If the list of dynamic methods passed to these steps includes the method GET, then skip the remaining sub-steps and store in cache a managed resource comprising the resulting absolute URI and the list of dynamic methods passed to these steps.
    2. Fetch the representation of the resource identified by the absolute URI. Use the transaction's application cache as an HTTP cache, and honor HTTP caching semantics (such as expiration, ETags, and so forth) with respect to that cache. User agents may also have other caches in place that are also honored.

       If the resource in question is already being fetched for other reasons, then the existing download process can sometimes be used for the purposes of this step.

    3. If the previous step fails (e.g. the server returns a 4xx or 5xx response or equivalent, or there is a DNS error, or the connection times out, or the user cancels the download), or if the server returned a redirect, then run the capture failure steps with the status code of the previous step and terminate these steps.

       Redirects are fatal because they are either indicative of a network problem (e.g. a captive portal); or would allow resources to be added to the cache under URIs that differ from any URI that the networking model will allow access to, leaving orphan entries; or would allow resources to be stored under URIs different than their true URIs. All of these situations are bad.

    4. Otherwise, the fetching succeeded. Store in cache a managed resource comprising the resulting absolute URI, its fetched representation, and the list of dynamic methods passed to these steps.

    If transaction is marked as off-line.

    1. If the list of dynamic methods passed to these steps includes the method GET, then skip the remaining sub-steps and store in cache a managed resource comprising the resulting absolute URI and the list of dynamic methods passed to these steps.
    2. Let representation be the content passed to these steps.
    3. Let type be the content type passed to these steps.
    4. If type is empty or null, set it to text/plain.
    5. Store in cache a managed resource comprising the resulting absolute URI, representation, and the list of dynamic methods passed to these steps.

12. Queue a task to fire an event at transaction for the URI passed to these steps with the name captured, which does not bubble, is not cancelable, and which uses the CacheEvent interface.

The capture failure steps are performed with a status code as follows:

1. Discard cache.
2. Set cache group's dynamic update status to idle.
3. Pick the appropriate sub-steps:

   If the status code was not 404 or 410 or equivalent, then

   Skip this resource and release it from application cache.

   Otherwise

   Set the error code to the status code passed to these steps.

4. Mark transaction's commit status as aborted.

Attempts to fetch resources as part of the steps to add a resource to be captured may be done with cache-defeating semantics, to avoid problems with stale or inconsistent intermediary caches.

4.2.3 Releasing resources

When the user agent is required to add a resource to be released, given the URI of the resource to release, and a cache transaction, the user agent must perform the following steps:

1. Let transaction be the cache transaction passed to these steps.
2. If transaction's commit status is not pending, then set an error and abort these steps.
3. Pick the appropriate sub-steps:

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

   Let origin be the origin of the cache host passed to these steps.

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

   Let origin be the origin of the scripts in the worker for the cache host passed to these steps.

4. Resolve the URI passed to these steps relative to base URI.
5. If the resulting absolute URI has a different <scheme> component than the base URI (compared in an ASCII case-insensitive manner), then set an error and abort these steps.
6. If the resulting absolute URI does not have the same origin as base URI, then set an error and abort these steps.
7. Drop the <fragment> component of the resulting absolute URI, if it has one.
8. Let cache be transaction's application cache.
9. If the resulting absolute URI does not identify a managed resource that is already in cache, then set an error and abort these steps.
10. Remove the managed resource for the resulting absolute URI from cache.
11. Queue a task to fire an event at transaction for the URI passed to these steps with the name released, which does not bubble, is not cancelable, and which uses the CacheEvent interface.

4.2.4 Commiting a transaction

When the user agent is required to commit a cache transaction, given a cache transaction, it means that the user agent must run the following steps:

1. Let transaction be the cache transaction passed to these steps.
2. If transaction's commit status is not pending, then set an error and abort these steps.
3. Let cache be transaction's application cache.
4. Let cache group be the application cache group containing cache.
5. Atomically, so as to avoid race conditions, perform the following sub-steps:
   1. Let cache group version be the version of the relevant application cache of cache group.
   2. Set cache's version to be higher than cache group version.
   3. Set the cache's dynamic completeness flag to complete.
   4. Obtain the storage mutex.
   5. If the host sets cookies in response to such a request, the user agent should update its cookie store accordingly.
   6. Release the storage mutex.
6. Pick the appropriate sub-steps:

   If transaction is marked as off-line, then

   1. Make cache the effective application cache for cache group to the cache host passed to these steps.

   If transaction is not marked as off-line, then

   1. Set the dynamic update status of cache group to idle.

7. Queue a task to fire an event at transaction with the name ready, which does not bubble, is not cancelable, and which uses the Event interface.
8. Set transaction's commit status as committed.

4.2.5 Aborting a transaction

When the user agent is required to abort a cache transaction, given a cache transaction, it means that the user agent must run the following steps:

1. Let transaction be the cache transaction passed to these steps.
2. If transaction's commit status is not pending, then set an error and abort these steps.
3. Discard transaction's application cache.
4. Set transaction's commit status as aborted.

4.2.6 The API Entry Point

var cache = self.applicationCache;

var cache = window.applicationCache;

[Supplemental]
interface CacheUtil {
    attribute ApplicationCache2Request applicationCache;
};

Window implements CacheUtil;

WorkerGlobalScope implements CacheUtil;

4.2.7 Asynchronous requests

Events are fired during asynchronous access as managed resources are accessed and manipulated. As requests are made for managed resources, the user agent processes them and saves or retrieves data from the network or storage, and when the required data is available, it alerts the application through the firing of events. The events are as follows:

interface AppCacheRequest {
    void abort ();
    const unsigned short INITIAL = 0;
    const unsigned short LOADING = 1;
    const unsigned short DONE = 2;
    readonly attribute unsigned short readyState;
    readonly attribute any            error;
    readonly attribute any            result;
             attribute Function       onsuccess;
             attribute Function       onerror;
};

4.2.8 Extending the ApplicationCache interface

Additional metadata is available about an application cache through the ApplicationCache2.

interface ApplicationCache2 : ApplicationCache {
    readonly attribute unsigned long      version;
    readonly attribute unsigned long long size;
    readonly attribute long long          lastRefresh;
    readonly attribute unsigned long      pendingUpdates;
    readonly attribute DOMString          outbox;
};

interface ApplicationCache2Request : ApplicationCache2 {
    AppCacheRequest    setOutbox (in DOMString uri);
    AppCacheRequest    immediate (in DOMString uri, in optional DOMString dynamicMethods);
    AppCacheRequest    offline (in DOMString uri, in DOMString body, in optional DOMString contentType, in optional DOMString dynamicMethods);
    AppCacheRequest    transaction (in optional boolean restart);
    AppCacheRequest    offlineTransaction ();
    CacheCursorRequest openModifiedItemCursor (in long version) raises (DOMException);
};

When the user agent is required to create a cache cursor, given the application cache and the low watermark version, the user agent must return a new CacheCursorRequest object, called result 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 application cache passed to these steps.
3. For each application cache belonging to cache's application cache group, starting from cache's version down to low watermark version, perform the following sub-steps:
   1. Let old cache be the application cache.
   2. Let old version be old cache's version.
   3. For the entity entity of 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. Prepare a list of items by appending removals to additions and set that list as cursor's item list.
5. Set cursor's current position to the first item in item list.
6. Set result's result to the item at cursor's current position in item list.
7. Queue a task to fire an event at result with the name success, which does not bubble, is not cancelable, and which uses the Event interface.

interface CacheCursorRequest : AppCacheRequest {
    void continue ();
};

interface CacheTransactionRequest {
    attribute Function oncaptured;
    attribute Function onreleased;
    attribute Function onready;
    void            resetPendingUpdates ();
    void            incrementPendingUpdates ();
    void            decrementPendingUpdates ();
    AppCacheRequest getItem (in DOMString uri);
    AppCacheRequest release (in DOMString uri);
    AppCacheRequest abort ();
    AppCacheRequest commit ();
};

interface OnlineTransactionRequest : CacheTransactionRequest {
    AppCacheRequest capture (in DOMString uri, in optional DOMString dynamicMethods);
};

interface OfflineTransactionRequest : CacheTransactionRequest {
    AppCacheRequest capture (in DOMString uri, in DOMString body, in optional DOMString contentType, in optional DOMString dynamicMethods);
};

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 Blob           body;
    readonly attribute DOMStringList  dynamicMethods;
    readonly attribute any            headers;
};

4.2.9 The CacheEvent Interface

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

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

The following are the event handlers (and their corresponding event handler event types) that must be supported, as IDL attributes, by objects implementing the CacheTransaction interface and CacheTransactionRequest interface:

4.3.1 Local Server Interfaces

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

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 {
    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 delay ();
    void send ();
};

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

4.3.2 Changes to the networking model

When a cache host is associated with an application cache whose dynamic completeness flag is complete, any and all loads for resources related to that cache host other than those for child browsing contexts must go through the following steps prior to the the networking model for application caches defined in [HTML5].

1. Let request be the resource request for fetching the resource.
2. If request includes the HTTP header Cache-Control with the value no-cache, then fetch the resource normally, and abort these steps.
3. Let cache be the application cache for the cache host.
4. Let resource be the resource to be fetched.
5. If resource is not managed in cache, then fetch a representation of resource normally and abort these steps.
6. 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 cache (instead of fetching it), and abort these steps.
7. 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 cache (instead of fetching it), and abort these steps.
8. 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.
9. Perform the steps to select an embedded local server server.
10. If server is not set, then fetch a representation of resource normally and abort these steps.
11. Pick the appropriate steps:

    If the user agent is off-line

    1. Create a new response object to hold the dynamic response to request.
    2. Call the interceptor function of server passing as arguments request and response.
    3. Wait for the interceptor function to dispatch the dynamic response until the typical network timeout.
    4. If the dynamic response times out, then raise a time out error and abort these steps.
    5. Handle response as the dynamic response, and abort these steps.

    If the user agent is online

    1. If the reviewer function of server is not set, then abort these steps and perform the steps for the case when the user agent is off-line.
    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.