Service Workers

This specification describes a method that enables applications to take advantage of persistent background processing, including hooks to enable bootstrapping of web applications while offline.

The core of this system is an event-driven Web Worker, which responds to events dispatched from documents and other sources. A system for managing installation, versions, and upgrades is provided.

The service worker is a generic entry point for event-driven background processing in the Web Platform that is extensible by other specifications.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

Document Context

Example: Bootstrapping with a ServiceWorker

// scope defaults to "/"
navigator.serviceWorker.register("/assets/v1/serviceworker.js").then(
  function(registration) {
    console.log("success!");
    if (registration.installing) {
      registration.installing.postMessage("Howdy from your installing page.");
    }
  },
  function(why) {
    console.error("Installing the worker failed!:", why);
  });

3.1

`ServiceWorker`

[Exposed=(Window,ServiceWorker)]
interface ServiceWorker : Worker {
  readonly attribute USVString scriptURL;
  readonly attribute ServiceWorkerState state;

  // event
  attribute EventHandler onstatechange;

  // terminate() method inherited from Worker should not be accessible.
};

enum ServiceWorkerState {
  "installing",
  "installed",
  "activating",
  "activated",
  "redundant"
};

A ServiceWorker object represents a service worker. Each ServiceWorker object is associated with a service worker. Multiple separate objects implementing the ServiceWorker interface across document environments and service worker environments can all be associated with the same service worker simultaneously.

A ServiceWorker object has an associated ServiceWorkerState object which is itself associated with service worker's state.

The terminate() method inherited from Worker, when called on the context object, should throw an "InvalidAccessError" exception.

The postMessage(message, transfer) method inherited from Worker, when called on the context object, should throw an "InvalidStateError" exception if the state attribute of the context object is "redundant". Otherwise, it must run as defined on the Worker interface.

3.1.1

`scriptURL`

The scriptURL attribute must return service worker's serialized script url.

For example, consider a document created by a navigation to https://example.com/app.html which matches via the following registration call which has been previously executed:

// Script on the page https://example.com/app.html
navigator.serviceWorker.register("/service_worker.js", { scope: "/" });

The value of navigator.serviceWorker.controller.scriptURL will be "https://example.com/service_worker.js".

3.1.2

`state`

The state attribute must return the value (in ServiceWorkerState enumeration) corresponding to the first matching statement, switching on service worker's state:

installing: "installing"
The service worker in this state is considered an installing worker. During this state, event.waitUntil(f) can be called inside the oninstall event handler to extend the life of the installing worker until the passed promise resolves successfully. This is primarily used to ensure that the service worker is not active until all of the core caches are populated.
installed: "installed"
The service worker in this state is considered a waiting worker.
activating: "activating"
The service worker in this state is considered an active worker. During this state, event.waitUntil(f) can be called inside the onactivate event handler to extend the life of the active worker until the passed promise resolves successfully. No functional events are dispatched until the state becomes activated.
activated: "activated"
The service worker in this state is considered an active worker ready to handle functional events.
redundant: "redundant"
A new service worker is replacing the current service worker, or the current service worker is being discarded due to an install failure.

3.1.3

Event handler

The following is the event handler (and its corresponding event handler event type) that must be supported, as event handler IDL attributes, by all objects implementing ServiceWorker interface:

event handler	event handler event type
`onstatechange`	`statechange`

3.2

`ServiceWorkerRegistration`

[Exposed=Window]
interface ServiceWorkerRegistration : EventTarget {
  [Unforgeable] readonly attribute ServiceWorker? installing;
  [Unforgeable] readonly attribute ServiceWorker? waiting;
  [Unforgeable] readonly attribute ServiceWorker? active;

  readonly attribute USVString scope;

  Promise<boolean> unregister();

  // event
  attribute EventHandler onupdatefound;
};

A ServiceWorkerRegistration object represents a service worker registration. Each ServiceWorkerRegistration object is associated with a service worker registration. Multiple separate objects implementing the ServiceWorkerRegistration interface across document environments can all be associated with the same service worker registration simultaneously.

3.2.1

`installing`

installing attribute must return a ServiceWorker object that represents the installing worker.

3.2.2

`waiting`

waiting attribute must return a ServiceWorker object that represents the waiting worker.

3.2.3

`active`

active attribute must return a ServiceWorker object that represents the active worker.

3.2.4

`scope`

The scope attribute must return service worker registration's serialized scope url.

In the example in section 3.1.1, the value of registration.scope, obtained from navigator.serviceWorker.ready.then(function(registration) { console.log(registration.scope); }) for example, will be "https://example.com/".

3.2.5

`unregister()`

The unregister() method unregisters the service worker registration. It is important to note that the currently controlled service worker client's service worker registration is effective until all the service worker clients (including itself) using this service worker registration unload. That is, unregister() method only affects subsequent navigations.

unregister() method must return the result of running the Unregister algorithm, or their equivalent, passing document, the context object's associated document, and scope, the scope url of the service worker registration, as the arguments.

3.2.6

Event handler

The following is the event handler (and its corresponding event handler event type) that must be supported, as event handler IDL attributes, by all objects implementing ServiceWorkerRegistration interface:

event handler	event handler event type
`onupdatefound`	`updatefound`

3.3

`navigator.serviceWorker`

partial interface Navigator {
  readonly attribute ServiceWorkerContainer serviceWorker;
};

The serviceWorker attribute of the Navigator interface must return a ServiceWorkerContainer object, which provides access to registration, removal, upgrade, and communication with service workers for the associated document.

Communication with these workers is provided via standard HTML5 messaging APIs, and messaging occurs as per usual with Web Workers.

3.4

`ServiceWorkerContainer`

[Exposed=Window]
interface ServiceWorkerContainer : EventTarget {
  [Unforgeable] readonly attribute ServiceWorker? controller;
  readonly attribute Promise<ServiceWorkerRegistration> ready;

  Promise<ServiceWorkerRegistration> register(USVString scriptURL, optional RegistrationOptions options);

  Promise<ServiceWorkerRegistration> getRegistration(optional USVString documentURL = "");
  Promise<sequence<ServiceWorkerRegistration>?> getRegistrations();


  // events
  attribute EventHandler oncontrollerchange;
  attribute EventHandler onerror;
};

dictionary RegistrationOptions {
  USVString scope = "/";
};

A ServiceWorkerContainer's associated Window is the associated Window of the Navigator object that the ServiceWorkerContainer is retrieved from. A ServiceWorkerContainer's associated Document is the newest Document object of its associated Window.

A ServiceWorkerContainer object has an associated ready promise (a promise). It is initially set to null.

3.4.1

`controller`

controller attribute must return a ServiceWorker object that represents the active worker for the context object's associated document.

navigator.serviceWorker.controller returns null if the request is a force refresh (shift+refresh).

3.4.2

`ready`

ready attribute must return the result of running these steps or their equivalent:

If the context object's ready promise is null, then:
1. Set the context object's ready promise to a new promise.
If the context object's ready promise is settled, then:
1. Return the context object's ready promise.
Let registration be null.
Let documentURL be the result of running the URL serializer on the context object's associated document's URL.
Run the following substeps in parallel:
1. CheckRegistration: If the result of running Match Scope algorithm, or its equivalent, with documentURL as its argument is not null, then:
  1. Set registration to the result value.
2. Else:
  1. Wait until [[ScopeToRegistrationMap]] has a new entry.
  2. Jump to the step labeled CheckRegistration.
3. If registration's active worker is null, then:
  1. Wait until registration acquires an active worker.
  Implementers should consider this condition is met when the corresponding registration request gets to the step 1.8 of Activate algorithm.
4. Resolve context object's ready promise with registration.
Return context object's ready promise.

The ready attribute is designed in a way that the returned promise will never reject. Instead, it waits until the promise resolves with a service worker registration that has an active worker.

3.4.3

`register(scriptURL, options)`

The register(scriptURL, options) method creates or updates a service worker registration for the given scope url. If successful, a service worker registration ties the provided script url to a scope url, which is subsequently used for navigation matching.

register(scriptURL, options) method must return the result of running these steps or their equivalent:

Let p be the result of running the Register algorithm, or their equivalent, passing the context object's associated document document, scriptURL, options.scope, and entry settings object's API base URL as the arguments.
Return p.

3.4.4

`getRegistration(documentURL)`

getRegistration(documentURL) method must run these steps or their equivalent:

Let promise be a new promise.
Let documentURL be the result of running the URL parser on documentURL with entry settings object's API base URL.
Set documentURL to the result of running the URL serializer on documentURL.
Run the following substeps in parallel:
1. If the origin of documentURL does not match the document's origin, then:
  1. Reject promise with a "SecurityError" exception.
  2. Abort these steps.
2. Let registration be the result of running Match Scope algorithm, or its equivalent, with documentURL as its argument.
3. If registration is not null, then:
  1. Resolve promise with a ServiceWorkerRegistration object that represents registration.
4. Else:
  1. Resolve promise with undefined.
Return promise.

3.4.5

`getRegistrations()`

getRegistrations() method must run these steps or their equivalent:

Let promise be a new promise.
Run the following substeps in parallel:
1. Let array be an empty array.
2. Let origin be the unicode serialization of the context object's associated document's origin.
3. For each Record {[[key]], [[value]]} entry of its [[ScopeToRegistrationMap]]:
  1. If the origin of entry.[[key]] matches origin, then:
    1. Add a ServiceWorkerRegistration object associated with entry.[[value]] to the array.
4. Resolve promise with array.
Return promise.

3.4.6

Event handlers

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

event handler	event handler event type
`oncontrollerchange`	`controllerchange`
`onerror`	`error`

3.5

Events

The following events are dispatched on ServiceWorker object:

Event name	Interface	Dispatched when…
`statechange`	`Event`	The `state` attribute of the `ServiceWorker` object is changed.

The following events are dispatched on ServiceWorkerContainer object:

Event name	Interface	Dispatched when…
`updatefound`	`Event`	A service worker registration acquires a new installing worker (See step 4.6 of the Install algorithm).
`controllerchange`	`Event`	The document's associated service worker registration acquires a new active worker. (See step 1.9 of the Activate algorithm. The skip waiting flag of a service worker causes activation of the service worker registration to occur while clients are using the service worker registration, `navigator.serviceWorker.controller` immediately reflects the active worker as the service worker that controls the document.)
`error`	`ErrorEvent`	Any error occurred from the associated service workers.

Execution Context

Example: Serving Cached Resources

// caching.js
this.addEventListener("install", function(e) {
  e.waitUntil(
    // Create a cache of resources.
    caches.create("shell-v1").then(function(cache) {
      // Begins the process of fetching them.
      // The coast is only clear when all the resources are ready.
      return cache.addAll([
        "/app.html",
        "/assets/v1/base.css",
        "/assets/v1/app.js",
        "/assets/v1/logo.png",
        "/assets/v1/intro_video.webm"
      ])
    })
  );
});

this.addEventListener("fetch", function(e) {
  // No "fetch" events are dispatched to the ServiceWorker until it
  // successfully installs.

  // All operations on caches are async, including matching URLs, so we use
  // promises heavily. e.respondWith() even takes promises to enable this:
  e.respondWith(
    caches.match(e.request).then(function(response) {
      return response || e.default();
    }).catch(function() {
      return caches.match("/fallback.html");
    })
  );
});

4.1

`ServiceWorkerGlobalScope`

[Global=(Worker,ServiceWorker), Exposed=ServiceWorker]
interface ServiceWorkerGlobalScope : WorkerGlobalScope {
  readonly attribute Cache scriptCache;
  readonly attribute CacheStorage caches;

  // A container for a list of ServiceWorkerClient objects that correspond to
  // browsing contexts (or shared workers) that are on the origin of this SW
  readonly attribute ServiceWorkerClients clients;
  [Unforgeable] readonly attribute USVString scope;

  void update();
  Promise<boolean> unregister();
  Promise<void> skipWaiting();

  attribute EventHandler oninstall;
  attribute EventHandler onactivate;
  attribute EventHandler onfetch;
  attribute EventHandler onbeforeevicted;
  attribute EventHandler onevicted;

  // The event.source of these MessageEvents are instances of ServiceWorkerClient
  attribute EventHandler onmessage;

  // close() method inherited from WorkerGlobalScope should not be accessible.
};

A ServiceWorkerGlobalScope object represents the global execution context of a service worker.

ServiceWorkerGlobalScope object provides generic, event-driven, time-limited script execution contexts that run at an origin. Once successfully registered, a service worker is started, kept alive and killed by their relationship to events, not service worker clients. Any type of synchronous requests must not be initiated inside of a service worker.

The close() method inherited from WorkerGlobalScope, when called on the context object, should throw an "InvalidAccessError" exception.

4.1.1

`scriptCache`

scriptCache must return a Cache object that represents the storage for scripts that are cached as part of the service worker installation.

4.1.2

`caches`

caches attribute must return the CacheStorage object that is the global asynchronous map object for the ServiceWorkerGlobalScope execution context containing the Cache objects keyed by the name of the Cache objects. Cache objects are always enumerable via self.caches in insertion order (per ECMAScript 6 Map objects.)

4.1.3

`clients`

clients attribute must return the ServiceWorkerClients object.

4.1.4

`scope`

The scope attribute must return the serialized scope url of the service worker's associated service worker registration.

4.1.5

`update()`

update() pings the server for an updated version of this script without consulting caches. This is conceptually the same operation that UA does maximum once per every 24 hours.

update() method must run these steps or their equivalent:

Let scope be the scope url of the service worker's associated service worker registration.
Let registration be the result of running Get Registration algorithm passing scope as the argument.
Invoke Soft Update algorithm, or its equivalent, passing registration as the argument.

4.1.6

`unregister()`

The unregister() method unregisters its containing service worker registration. It is important to note that this service worker registration is effective until all the documents (including itself) using this service worker registration unload. That is, unregister() method only affects subsequent navigations.

unregister() method must run these steps or their equivalent:

Let scope be the scope url of the service worker's containing service worker registration.
Return the result of running Unregister algorithm, or its equivalent, passing document, the context object's associated document, and scope as the argument.

4.1.7

`skipWaiting()`

The skipWaiting() method allows this service worker to progress from the registration's waiting position to active even while clients are using the registration.

skipWaiting() method must run these steps or their equivalent:

Let promise be a new promise.
Run the following substeps in parallel:
1. Set service worker's skip waiting flag
2. If service worker's state is installed, then:
  1. Run Activate algorithm, or its equivalent, passing service worker's registration as the argument.
3. Resolve promise with undefined.
Return promise.

4.1.8

Event handlers

event handler	event handler event type
`oninstall`	`install`
`onactivate`	`activate`
`onfetch`	`fetch`
`onbeforeevicted`	`beforeevicted`
`onevicted`	`evicted`
`onmessage`	`message`

For onmessage event handler,ServiceWorkerGlobalScope objects act as if they had an implicit MessagePort associated with them. This port is part of a channel that is set up when the worker is created, but it is not exposed. This object must never be garbage collected before the ServiceWorkerGlobalScope object. All messages received by that port must immediately be retargeted at the ServiceWorkerGlobalScope object. That is, an event named message using the MessageEvent interface is dispatched on ServiceWorkerGlobalScope object. The event.source of these MessageEvents are instances of ServiceWorkerClient.

4.2

`ServiceWorkerClient`

[Constructor(USVString url), Exposed=ServiceWorker]
interface ServiceWorkerClient {
  readonly attribute Promise ready;
  readonly attribute boolean hidden;
  readonly attribute boolean focused;
  readonly attribute USVString url;
  readonly attribute ContextFrameType frameType;
  void postMessage(any message, optional sequence<Transferable> transfer);
  Promise focus();
};

The ServiceWorkerClient object has an associated service worker client (a service worker client).

This section will be updated as per SW #414, SW #423.

4.3

`ServiceWorkerClients`

[Exposed=ServiceWorker]
interface ServiceWorkerClients {
  // The objects returned will be new instances every time
  Promise<sequence<ServiceWorkerClient>?> getAll(optional ServiceWorkerClientQueryOptions options);
};

dictionary ServiceWorkerClientQueryOptions {
  boolean includeUncontrolled = false;
};

The ServiceWorkerClients interface represents a container for a list of ServiceWorkerClient objects.

4.3.1

`getAll(options)`

The getAll(options) method must run these steps or their equivalent:

Let promise be a new promise.
Run these steps in parallel:
1. Let clients be an empty array.
2. If the optional argument options is present and options.includeUncontrolled is true, then:
  1. For each service worker client client whose origin is the same as the associated service worker's origin:
    1. Add a ServiceWorkerClient object that represent client to clients.
  2. Resolve promise with clients.
3. Else:
  1. For each service worker client client which are controlled by the associated service worker:
    1. Add a ServiceWorkerClient object that represent client to clients.
  2. Resolve promise with clients.
Return promise.

This section will be updated as per SW #414.

4.4

Caches

To allow authors to fully manage their content caches for offline use, the ServiceWorkerGlobalScope execution context provides the caching methods largely conforming to ECMAScript 6 Map objects with additional convenience methods. A domain can have multiple, named Cache objects, whose contents are entirely under the control of scripts. Caches are not shared across domains, and they are completely isolated from the browser's HTTP cache.

4.4.1

Understanding Cache Lifetimes

The Cache instances are not part of the browser's HTTP cache. The Cache objects are exactly what authors have to manage themselves. The Cache objects do not get updated unless authors explicitly request them to be. The Cache objects do not expire unless authors delete the entries. The Cache objects do not disappear just because the service worker script is updated. That is, caches are not updated automatically. Updates must be manually managed. This implies that authors should version their caches by name and make sure to use the caches only from the version of the ServiceWorker that can safely operate on.

4.4.2

`Cache`


[Exposed=ServiceWorker]
interface Cache {
  Promise<Response> match(RequestInfo request, optional CacheQueryOptions options);
  Promise<sequence<Response>> matchAll(optional RequestInfo request, optional CacheQueryOptions options);
  Promise<void> add(RequestInfo request);
  Promise<void> addAll(sequence<RequestInfo> requests);
  Promise<void> put(RequestInfo request, Response response);
  Promise<boolean> delete(RequestInfo request, optional CacheQueryOptions options);
  Promise<sequence<Request>> keys(optional RequestInfo request, optional CacheQueryOptions options);
};

dictionary CacheQueryOptions {
  boolean ignoreSearch = false;
  boolean ignoreMethod = false;
  boolean ignoreVary = false;
  boolean prefixMatch = false;
  DOMString cacheName;
};

dictionary CacheBatchOperation {
  DOMString type;
  Request request;
  Response response;
  CacheQueryOptions options;
};

The Cache interface represents the storage for the pairs of a Request object and a Response object that are cached as part of the service worker installation. A Cache object has a [[RequestToResponseMap]] object.

Each Cache object is associated with a [[RequestToResponseMap]]. Multiple separate objects implementing the Cache interface across service worker environments can all be associated with the same [[RequestToResponseMap]] simultaneously.

4.4.2.1

`match(request, options)`

match(request, options) method must run these steps or their equivalent:

Let promise be a new promise.
Run these steps in parallel:
1. Let p be the result of running the algorithm specified in matchAll(request, options) method with request and options as the arguments.
2. Wait until p settles.
3. If p rejects with an exception, then:
  1. Reject promise with that exception.
4. Else if p resolves with an array, responseArray, then:
  1. If responseArray is an empty array, then:
    1. Resolve promise with undefined.
  2. Else:
    1. Resolve promise with the first element of responseArray.
Return promise.

4.4.2.2

`matchAll(request, options)`

matchAll(request, options) method must run these steps or their equivalent:

Let promise be a new promise.
Run these steps in parallel:
1. Let responseArray be an empty array.
2. If the optional argument request is omitted, then:
  1. For each Record {[[key]], [[value]]} entry of its [[RequestToResponseMap]], in key insertion order:
    1. Add entry.[[value]] to responseArray.
  2. Resolve promise with responseArray.
  3. Abort these steps.
3. Else:
  1. Let r be null.
  2. If request is a USVString, then:
    1. Set r to the associated request of the result of invoking the initial value of Request as constructor with request as its argument. If this throws an exception, return a promise rejected with that exception.
  3. Else:
    1. Set r to request's associated request.
  4. Set r's url's fragment to null.
  5. Let entries be the result of running Query Cache algorithm passing a Request object that represents r and options as the arguments.
  6. For each entry of entries:
    1. Add entry[1] to responseArray.
  7. Resolve promise with responseArray.
Return promise.

4.4.2.3

`add(request)`

add(request) method must run these steps or their equivalent:

Let requests be an array containing only request.
Set responseArrayPromise to the result of running the algorithm specified in addAll(requests) passing requests as the argument.
Let p be transforming responseArrayPromise with onFulfilled.
Upon fulfillment of p with value responseArray, perform the following substeps, onFulfilled, in parallel:
1. Resolve p with undefined.
Return p.

4.4.2.4

`addAll(requests)`

addAll(requests) method must run these steps or their equivalent:

Let responsePromiseArray be an empty array.
Let requestArray be an empty array.
For each request in requests:
1. Let r be null.
2. If request is a USVString, then:
  1. Set r to the associated request of the result of invoking the initial value of Request as constructor with request as its argument. If this throws an exception, return a promise rejected with that exception.
3. Else:
  1. Set r to request's associated request.
4. Set r's url's fragment to null.
5. Add a Request object that represents r to requestArray.
6. If r's url's scheme is not one of "http" and "https", then:
  1. Add a promise rejected with a "NetworkError" exception to responsePromiseArray.
  2. Continue to the next iteration of the loop.
7. Run the algorithm specified in fetch(input, init) with r and add the returned value to responsePromiseArray.
Let p be waiting for all of responsePromiseArray.
Let q be transforming p with onFulfilled.
Upon fulfillment of p with value responseArray, perform the following substeps, onFulfilled, in parallel:
1. Let operations be an empty array.
2. For each response in responseArray with the index index:
  1. Let o be an empty object representing a CacheBatchOperation dictionary.
  2. Set the type dictionary member of o to "put".
  3. Set the request dictionary member of o to requestArray[index].
  4. Set the response dictionary member of o to response.
  5. Add o to operations.
3. Let resultPromise to the result of running Batch Cache Operations algorithm passing operations as the argument.
4. Resolve q with undefined.
Return q.

4.4.2.5

`put(request, response)`

put(request, response) method must run these steps or their equivalent:

Let r be null.
If request is a USVString, then:
1. Set r to the associated request of the result of invoking the initial value of Request as constructor with request as its argument. If this throws an exception, return a promise rejected with that exception.
Else:
1. Set r to request's associated request.
Set r's url's fragment to null.
Let operations be an empty array.
Let o be an empty object representing a CacheBatchOperation dictionary.
Set the type dictionary member of o to "put".
Set the request dictionary member of o to a Request object that represents r.
Set the response dictionary member of o to response.
Add o to operations.
Let resultPromise to the result of running Batch Cache Operations passing operations as the argument.
Let p be transforming resultPromise with onFulfilled.
Upon fulfillment of p with responseArray, perform the following substeps, onFulfilled, in parallel:
1. Resolve p with undefined.
Return p.

4.4.2.6

`delete(request, options)`

delete(request, options) method must run these steps or their equivalent:

Let r be null.
If request is a USVString, then:
1. Set r to the associated request of the result of invoking the initial value of Request as constructor with request as its argument. If this throws an exception, return a promise rejected with that exception.
Else:
1. Set r to request's associated request.
Set r's url's fragment to null.
Let operations be an empty array.
Let o be an empty object representing a CacheBatchOperation dictionary.
Set the type dictionary member of o to "delete".
Set the request dictionary member of o to a Request object that represents r.
Set the options dictionary member of o to options.
Add o to operations.
Let resultPromise to the result of running Batch Cache Operations passing operations as the argument.
Let p be transforming resultPromise with onFulfilled.
Upon fulfillment of p with responseArray, perform the following substeps, onFulfilled, in parallel:
1. If responseArray is not null, then:
  1. Resolve p with true.
2. Else:
  1. Resolve p with false.
Return p.

4.4.2.7

`keys(request, options)`

keys(request, options) method must run these steps or their equivalent:

Let promise be a new promise.
Run these steps in parallel:
1. Let resultArray be an empty array.
2. If the optional argument request is omitted, then:
  1. For each Record {[[key]], [[value]]} entry of its [[RequestToResponseMap]], in key insertion order:
    1. Add entry.[[key]] to resultArray.
3. Else:
  1. Let r be null.
  2. If request is a USVString, then:
    1. Set r to the associated request of the result of invoking the initial value of Request as constructor with request as its argument. If this throws an exception, return a promise rejected with that exception.
  3. Else:
    1. Set r to request's associated request.
  4. Set r's url's fragment to null.
  5. Let requestResponseArray be the result of running Query Cache algorithm passing a Request object that represents r and options as the arguments.
  6. For each requestResponse in requestResponseArray:
    1. Add requestResponse[0] to resultArray.
4. Resolve promise with resultArray.
Return promise.

4.4.3

`CacheStorage`


[Exposed=ServiceWorker]
interface CacheStorage {
  Promise<Response> match(RequestInfo request, optional CacheQueryOptions options);
  Promise<boolean> has(DOMString cacheName);
  Promise<Cache> open(DOMString cacheName);
  Promise<boolean> delete(DOMString cacheName);
  Promise<sequence<DOMString>> keys();
};

CacheStorage interface is designed to largely conform to ECMAScript 6 Map objects but entirely async, and with additional convenience methods. The methods, clear, forEach, entries and values, are intentionally excluded from the scope of the first version resorting to the ongoing discussion about the async iteration by TC39.

The CacheStorage interface represents the storage for Cache objects. A CacheStorage object has a [[NameToCacheMap]] object.

4.4.3.1

`match(request, options)`

match(request, options) method must run these steps or their equivalent:

Let cacheName be null.
If the optional argument options is not omitted, then:
1. Set cacheName to options.cacheName.
If cacheName is not null, then:
1. Return a promise, p, resolved with the result of running the following substeps:
  1. For each Record {[[key]], [[value]]} entry of its [[NameToCacheMap]], in key insertion order:
    1. If cacheName matches entry.[[key]], then:
      1. Resolve p with the result of running the algorithm specified in match(request, options) method of Cache interface with request and options as the arguments (providing entry.[[value]] as thisArgument to the [[Call]] internal method of match(request, options).)
      2. Abort these steps.
  2. Reject p with an "NotFoundError" exception.
Else:
1. Set p to transforming the result of running the algorithm specified in keys() method, with onFulfilled.
2. Upon fulfillment of p with value keys, perform the following substeps, onFulfilled, in parallel:
  1. For each key in keys:
    1. Let q be the result of running the algorithm specified in match(request, options) method of Cache interface with request and options as the arguments (providing key as thisArgument to the [[Call]] internal method of match(request, options).)
    2. Upon fulfillment of q with value matchedResponse:
      1. If matchedResponse is not undefined, then:
        
        Resolve p with matchedResponse.
        
        Abort these steps.
    3. Upon rejection of q with value err:
      1. Reject p with err.
      2. Abort these steps.
  2. Resolve p with undefined.
3. Return p.

4.4.3.2

`has(cacheName)`

has(cacheName) method must run these steps or their equivalent:

Return a promise, p, resolved with the result of running the following substeps:
1. For each Record {[[key]], [[value]]} entry of its [[NameToCacheMap]], in key insertion order:
  1. If cacheName matches entry.[[key]], then:
    1. Return true.
2. Return false.

4.4.3.3

`open(cacheName)`

open(cacheName) method must run these steps or their equivalent:

Return a promise, p, resolved with the result of running the following substeps:
1. For each Record {[[key]], [[value]]} entry of its [[NameToCacheMap]], in key insertion order:
  1. If cacheName matches entry.[[key]], then:
    1. Return a new Cache object which is a copy of entry.[[value]].
    2. Abort these steps.
2. Let cache be a new Cache object.
3. Set a newly-created Record {[[key]]: cacheName, [[value]]: cache} to [[NameToCacheMap]].
4. Return cache.

4.4.3.4

`delete(cacheName)`

delete(cacheName) method must run these steps or their equivalent:

Let p be the result of running the algorithm specified in has(cacheName) method with cacheName as the argument.
Let q be transforming p with onFulfilled.
Upon fulfillment of p with value cacheExists, perform the following substeps, onFulfilled, in parallel:
1. If cacheExists is true, then:
  1. Delete a Record {[[key]], [[value]]} entry of its [[NameToCacheMap]] where cacheName matches entry.[[key]].
  2. Resolve q with true.
  3. Abort these steps.
2. Else:
  1. Resolve q with flase.
Return q.

4.4.3.5

`keys()`

keys() method must run these steps or their equivalent:

The promise returned from this method resolves with the sequence of keys, cache names in DOMString, in insertion order.

Let resultArray be an empty array.
Return a promise, p, resolved with the result of running the following substeps:
1. For each Record {[[key]], [[value]]} entry of its [[NameToCacheMap]], in key insertion order:
  1. Add entry.[[key]] to resultArray.
2. Return resultArray.

4.5

`ExtendableEvent`


[Constructor(DOMString type, optional ExtendableEventInit eventInitDict), Exposed=ServiceWorker]
interface ExtendableEvent : Event {
  void waitUntil(Promise<any> f);
};

dictionary ExtendableEventInit : EventInit {
  // Defined for the forward compatibility across the derived events
};

Service workers have two lifecycle events, install and activate. Service workers use the ExtendableEvent interface for activate event and the InstallEvent interface, which inherits from the ExtendableEvent interface, for install event. Service worker extensions that define event handlers may also use the ExtendableEvent interface.

Each event using ExtendableEvent interface or a derived interface has the following associated flags that are all initially unset:

extend lifetime flag
wait-until reject flag

4.5.1

`event.waitUntil(f)`

waitUntil(f) method, extends the lifetime of the event. When called in oninstall, it delays treating the installing worker as installed (i.e. a waiting worker) until the passed promise resolves successfully. This is primarily used to ensure that a service worker is not considered installed (i.e. a waiting worker) until all of the core caches it depends on are populated. When called in onactivate, it delays treating the active worker as activated until the passed promise resolves successfully. This is primarily used to ensure that any functional events are not dispatched to the ServiceWorkerGlobalScope object that represents the service worker until it upgrades database schemas and deletes the outdated cache entries. Service worker extensions that define event handlers will define their own behaviours, allowing the extend lifetime flag to suggest operation length, and the wait-until reject flag to suggest operation failure.

waitUntil(f) method must run these steps or their equivalent:

Set the extend lifetime flag.
Run the following substeps in parallel:
1. Wait until f settles.
2. If f rejected, then:
  1. Set the wait-until reject flag.
3. Else if f resolved with a value, then:
  1. Do nothing.
4. Unset the extend lifetime flag.

4.6

`InstallEvent`


[Constructor(DOMString type, optional InstallEventInit eventInitDict), Exposed=ServiceWorker]
interface InstallEvent : ExtendableEvent {
  readonly attribute ServiceWorker? activeWorker;
};

dictionary InstallEventInit : EventInit {
  ServiceWorker activeWorker;
};

4.7

`FetchEvent`


[Constructor(DOMString type, optional FetchEventInit eventInitDict), Exposed=ServiceWorker]
interface FetchEvent : Event {
  readonly attribute Request request;
  readonly attribute ServiceWorkerClient client;
  readonly attribute boolean isReload;

  void respondWith((Response or Promise<Response>) r);
  Promise<Response> forwardTo(USVString url);
  Promise<Response> default();
};

dictionary FetchEventInit : EventInit {
  Request request;
  ServiceWorkerClient client;
  boolean isReload;
};

Each event using FetchEvent interface has the following associated flag that is initially unset:

wait to respond flag
respond-with entered flag
respond-with error flag

4.7.1

`event.respondWith(r)`

When event.respondWith(r) method is invoked, the argument, r, must resolve with a Response, else a network error is returned to Fetch. If the request is a top-level navigation and the return value is a Response whose type attribute is "opaque" (i.e., an opaque response body), a network error is returned to Fetch. The final URL of all successful (non network-error) responses is the requested URL. Renderer-side security checks about tainting for cross-origin content are tied to the transparency (or opacity) of the Response body, not URLs.

respondWith(r) method must run these steps or their equivalent:

If the respond-with entered flag is set, then:
1. Throw an "InvalidStateError" exception.
2. Abort these steps.
Set the respond-with entered flag.
Set the wait to respond flag.
Run the following substeps in parallel:
1. Wait until r settles.
2. If r rejected, then:
  1. Set the respond-with error flag.
3. If r resolved with response, then:
  1. If response is an instance of Response interface, then:
    1. Let request be the value that the context object's request attribute's getter returns
    2. If response.type is "opaque", and request's associated request's context is one of frame, hyperlink, iframe, location, and sharedworker, then:
      1. Set the respond-with error flag.
  2. Else:
    1. Set the respond-with error flag.
    If the respond-with error flag is set, a network error is returned to Fetch through Handle Fetch algorithm. (See the step 25.1.) Otherwise, the value response is returned to Fetch through Handle Fetch algorithm. (See the step 26.1.)
4. Unset the wait to respond flag.

4.7.2

`event.default()`

The invocation of event.default() method performs a fetch using event.request. event.request represents the original request from the controlled service worker client. During the execution, the original request is not altered (except the skip service worker flag), and thus event.default() fetches the original request through the UA's HTTP stack. event.default() returns a promise, which resolves with a Response object, that can be an argument to the event.respondWith(r) method.

default() method must run these steps or their equivalent:

If event's dispatch flag is unset, then:
1. Return a promise rejected with a "InvalidStateError" exception.
Let promise be a new promise.
Run the following substeps in parallel:
1. Let r be the value that the context object's request attribute's getter returns.
2. Let request be r's associated request.
3. Set request's skip service worker flag and request's synchronous flag.
4. Let response be the result of running fetch with request as its argument.
5. If response is a network error, then:
  1. Reject promise with a TypeError.
6. Else:
  1. Resolve promise with a new Response object associated with response.
Return promise.

4.7.3

`event.isReload`

isReload attribute must return true if event was dispatched with the user's intention for the page reload, and false otherwise. Pressing the refresh button should be considered a reload while clicking a link and pressing the back button should not. The behavior of the Ctrl+l enter is left to the implementations of the user agents.

4.8

Events

The following events are dispatched on ServiceWorkerGlobalScope object:

Event name	Interface	Dispatched when…
`install`	`InstallEvent`	[Lifecycle event] A service worker registration acquires a new installing worker. (See step 4.7.3 of the Install algorithm.)
`activate`	`ExtendableEvent`	[Lifecycle event] A service worker registration acquires a new active worker. (See step 1.10.3 of the Activate algorithm.)
`fetch`	`FetchEvent`	[Functional event] Fetch invokes Handle Fetch with `request`. As a result of performing Handle Fetch, the Service Woker returns a response to Fetch. The response, represented by a `Response` object, can be retrieved from a Cache object or directly from network using `self.fetch(input, init)` method or `event.default()` method. (A custom `Response` object can be another option.)

Custom event types for beforeevicted and evicted should be added.

Appendix A: Algorithms

The double square bracket notation ([[name of method or name of property]]) is used throughout the specification to indicate user agent's internal data structures.

[[ScopeToRegistrationMap]] represents an internal map structure that stores the entries of the Record {[[key]], [[value]]} where [[key]] is a string that represents a scope url and [[value]] is a service worker registration.

[[RequestToResponseMap]] represents an internal map structure that stores the entries of the Record {[[key]], [[value]]} where [[key]] is a Request and [[value]] is a Response.

[[NameToCacheMap]] represents an internal map structure that stores the entries of the Record {[[key]], [[value]]} where [[key]] is a string that represents a name of the Cache object and [[value]] is a Cache object.

An algorithm thread queue is a thread safe queue used to synchronize the set of concurrent entries of algorithm steps. The queue contains timestamps (with the assumptions), gained by algorithms, as its elements. The queue should satisfy the general properties of FIFO queue.

[[RegistrationQueue]] is an algorithm thread queue for synchronizing the set of concurrent registration requests. The user agent must maintain a separate queue for each service worker registration keyed by its scope url. The queue is initially empty.

[[InstallationQueue]] is an algorithm thread queue for synchronizing the set of concurrent installation jobs. The user agent must maintain a separate queue for each service worker registration keyed by its scope url. The queue is initially empty.

[[InstallationResultHandleQueue]] is an algorithm thread queue for synchronizing the set of concurrent installation jobs. The user agent must maintain a separate queue for each service worker registration keyed by its scope url. The queue is initially empty.

8.1

Register

Input: document, a Document; scriptURL, a string that represents the URL of the script; scope, a relative URL that represents a path prefix of a scope url; base, a base URL, optional
Output: promise, a promise

Let scope be the result of running the URL parser on scope with base.
Set scope to the result of running the URL serializer on scope with the exclude fragment flag set.
Let scriptURL be the result of running the URL parser on scriptURL with base.
If the result of running Is origin authenticated origin with the origin of scriptURL as the argument is unauthenticated, then:
1. Return a promise rejected with a "SecurityError" exception.
If the origin of scriptURL does not match document's origin, then:
1. Return a promise rejected with a "SecurityError" exception.
If the origin of scope does not match document's origin, then:
1. Return a promise rejected with a "SecurityError" exception.
Run the following substeps atomically:
1. Let registration be the result of running the Get Registration algorithm passing scope as the argument.
2. If registration is not null, then:
  1. Let newestWorker be the result of running the Get Newest Worker algorithm passing registration as the argument.
  2. If newestWorker is not null, scriptURL is equal to newestWorker's script url, and scriptURL is equal to registration's registering script url, then:
    1. If newestWorker is an active worker, then:
      1. If registration's uninstalling flag is set, unset it.
      2. Return a promise resolved with a ServiceWorkerRegistration object that represents registration.
3. Else:
  1. Set registration to the result of running Set Registration algorithm passing scope as its argument.
4. Set registration's registering script url to scriptURL.
5. Return the result of running the Update algorithm, or its equivalent, passing registration as the argument.

8.2

Update

The algorithm uses [[RegistrationQueue]] to synchronize the set of multiple registration requests. Implementers may use it or other synchronization primitives and methods to satisfy this requirement.

Input: registration, a service worker registration
Output: promise, a promise

Let p be a new promise.
Generate a timestamp and let timeStamp be the result value.
Push timeStamp to [[RegistrationQueue]], [[InstallationQueue]], and [[InstallationResultHandleQueue]].
Run the following substeps in parallel:
1. CheckPriority: If the value of the top element of [[RegistrationQueue]] matches timeStamp, then:
  1. Pop the top element from [[RegistrationQueue]].
2. Else:
  1. Wait until the top element of [[RegistrationQueue]] is popped.
  2. Jump to the step labeled CheckProirity.
  Wait is a blocking wait. Implementers may use a condition variable or its equivalent synchronization primitive.
3. Run the following substeps atomically:
  1. If registration's installing worker is not null, then:
    1. Terminate registration's installing worker.
    2. Run the Update State algorithm passing registration's installing worker and redundant as the arguments.
    3. Set registration's installing worker to null.
    4. The user agent may abort in-flight requests triggered by registration's installing worker.
  2. Let r be the associated request of the result of invoking the initial value of Request as constructor with registration's registering script url. If this throws an exception, then:
    1. Reject p with the exception.
    2. Pop the top element from [[InstallationQueue]] and [[InstallationResultHandleQueue]].
    3. If the result of running Get Newest Worker algorithm is null, then:
      1. Invoke Clear Registration algorithm passing registration as its argument.
    4. Abort these steps.
  3. Set r's context to serviceworker.
  4. Append `Service-Worker`/`script` to r's header list.
  5. Set r's skip service worker flag and r's synchronous flag.
  6. Let response be the result of running fetch using r, forcing a network fetch if cached entry is greater than 1 day old.
  7. If response is a network error, then:
    1. If r's redirect count is not zero, then:
      1. Reject p with a "SecurityError" exception.
      2. Pop the top element from [[InstallationQueue]] and [[InstallationResultHandleQueue]].
      3. If the result of running Get Newest Worker algorithm is null, then:
        
        Invoke Clear Registration algorithm passing registration as its argument.
      4. Abort these steps.
    2. Else:
      1. Reject p with a "NetworkError" exception.
      2. Pop the top element from [[InstallationQueue]] and [[InstallationResultHandleQueue]].
      3. If the result of running Get Newest Worker algorithm is null, then:
        
        Invoke Clear Registration algorithm passing registration as its argument.
      4. Abort these steps.
  8. Extract a MIME type from the response's header list. If this MIME type (ignoring parameters) is not one of text/javascript, application/x-javascript, or application/javascript, then:
    1. Reject p with a "SecurityError" exception.
    2. Pop the top element from [[InstallationQueue]] and [[InstallationResultHandleQueue]].
    3. If the result of running Get Newest Worker algorithm is null, then:
      1. Invoke Clear Registration algorithm passing registration as its argument.
    4. Abort these steps.
  9. Let newestWorker be the result of running the Get Newest Worker algorithm passing registration as the argument.
  10. If newestWorker is not null, and newestWorker's script url is equal to registration's registering script url and response is a byte-for-byte match with the script of newestWorker, then:
    1. Resolve p with registration.
    2. Abort these steps.
  11. Else:
    1. Let worker be a new service worker for the script with registration's registering script url.
    2. If worker fails to start up, due to parse errors or uncaught errors, then:
      1. Reject p with the error.
      2. Pop the top element from [[InstallationQueue]] and [[InstallationResultHandleQueue]].
      3. If the result of running Get Newest Worker algorithm is null, then:
        
        Invoke Clear Registration algorithm passing registration as its argument.
      4. Abort these steps.
4. Invoke Install algorithm, or its equivalent, with registration, worker, p, and timeStamp as its arguments.
Return p.

8.3

Soft Update

The user agent may call this as often as it likes to check for updates.

Input: registration, a service worker registration
Output: None

If registration's uninstalling flag is set, then:
1. Abort these steps.
If registration's installing worker is not null, then:
1. Abort these steps.
Invoke Update algorithm, or its equivalent, with registration as its argument.

Inspect whether the promise returned from Update algorithm should be returned to the caller (either UA internal context or self.update()).

8.4

Install

The algorithm uses [[InstallationQueue]] to synchronize the set of multiple installation jobs. Implementers may use it or other synchronization primitives and methods to satisfy this requirement.

Input: registration, a service worker registration; worker, a service worker; registrationPromise, a promise; timeStamp, a timestamp
Output: none

Let installFailed be false.
CheckPriority: If the value of the top element of [[InstallationQueue]] matches timeStamp, then:
1. Pop the top element from [[InstallationQueue]].
Else:
1. Wait until the top element of [[InstallationQueue]] is popped.
2. Jump to the step labeled CheckProirity.
Wait is a blocking wait. Implementers may use a condition variable or its equivalent synchronization primitive.
Run the following substeps atomically:
1. If registration's installing worker is not null, then:
  1. Terminate registration's installing worker.
  2. Run the Update State algorithm passing registration's installing worker and redundant as the arguments.
  3. The user agent may abort any in-flight requests triggered by registration's installing worker.
2. Set registration's installing worker to worker.
3. Run the Update State algorithm passing registration's installing worker and installing as the arguments.
4. Assert: registrationPromise is not null.
5. Resolve registrationPromise with registration.
6. Queue a task to fire a simple event named updatefound at all the ServiceWorkerRegistration objects associated with registration for all the service worker clients which use registration.
7. Queue a task to run the following substeps:
  1. Let installingWorker be registration's installing worker.
  2. Run a worker, if not running, for a script with installingWorker's script url and installingWorker's environment settings object.
  3. Fire an event named install using InstallEvent interface at installingWorker's environment settings object's global object.
  4. For each event listener invoked:
    1. If any uncaught runtime script error occurs, then:
      1. Report the error for the script per the runtime script errors handling.
      2. Run the Update State algorithm passing registration's installing worker and redundant as the arguments.
      3. Set registration's installing worker to null.
      4. Pop the top element from [[InstallationResultHandleQueue]].
      5. If the result of running Get Newest Worker algorithm is null, then:
        
        Invoke Clear Registration algorithm passing registration as its argument.
      6. Abort these steps.
    2. Let event be the event for which this event listener was invoked.
    3. If event's extend lifetime flag is set, then:
      1. Wait until event's extend lifetime flag is unset.
      2. If event's wait-until reject flag is set, then:
        
        Set installFailed to true.
CheckResultHandlePriority: If the value of the top element of [[InstallationResultHandleQueue]] matches timeStamp, then:
1. Pop the top element from [[InstallationResultHandleQueue]].
Else:
1. Wait until the top element of [[InstallationResultHandleQueue]] is popped.
2. Jump to the step labeled CheckResultHandlePriority.
Wait is a blocking wait. Implementers may use a condition variable or its equivalent synchronization primitive.
Run the following substeps atomically:
1. Wait for the task queued by the step 4.7 to have executed.
2. If registration's installing worker is null, then:
  1. Abort these steps.
3. If installFailed is true, then:
  1. Run the Update State algorithm passing registration's installing worker and redundant as the arguments.
  2. Set registration's installing worker to null.
  3. If the result of running Get Newest Worker algorithm is null, then:
    1. Invoke Clear Registration algorithm passing registration as its argument.
  4. Abort these steps.
4. If registration's waiting worker is not null, then:
  1. Terminate registration's waiting worker.
  2. Run the Update State algorithm passing registration's waiting worker and redundant as the arguments.
  3. The user agent may abort in-flight requests triggered by registration's waiting worker.
5. Set registration's waiting worker to registration's installing worker.
6. Set registration's installing worker to null.
7. Run the Update State algorithm passing registration's waiting worker and installed as the arguments.
8. If registration's uninstalling flag is set before timeStamp, then:
  1. Wait until a Record {[[key]], [[value]]} entry of its [[ScopeToRegistrationMap]] where registration's scope url matches entry.[[key]] is deleted.
  2. Set a newly-created Record {[[key]]: registration's scope url, [[value]]: registration} to [[ScopeToRegistrationMap]].
  3. Unset registration's uninstalling flag.
9. If registration's waiting worker's skip waiting flag is set, then:
  1. For each service worker client client whose client url matches registration's scope url:
    1. Let exitingWorker be the active worker that controls client.
    2. If exitingWorker is not null, then:
      1. Wait for exitingWorker to finish handling any in-progress requests.
      2. Terminate exitingWorker.
      3. Run the Update State algorithm passing exitingWorker and redundant as the arguments.
  2. Run Activate algorithm, or its equivalent, passing registration as the argument.
  3. Abort these steps.
Wait until no service worker client is using registration as their service worker registration.
Invoke Activate algorithm, or its equivalent, with registration as its argument.

8.5

Activate

Input: registration, a service worker registration
Output: None

Run the following substeps atomically:
1. Let activateFailed be false.
2. Let activatingWorker be registration's waiting worker.
3. Let exitingWorker be registration's active worker.
4. If activatingWorker is null, then:
  1. Abort these steps.
5. If exitingWorker is not null, then:
  1. Wait for exitingWorker to finish handling any in-progress requests.
  2. Terminate exitingWorker.
  3. Run the Update State algorithm passing exitingWorker and redundant as the arguments.
6. Set registration's active worker to activatingWorker.
7. Set registration's waiting worker to null.
8. Run the Update State algorithm passing registration's active worker and activating as the arguments.
9. Queue a task to fire a simple event named controllerchange at all the ServiceWorkerContainer objects for all the service worker clients which use registration.
10. Queue a task to run the following substeps:
  1. Let activeWorker be registration's active worker.
  2. Run a worker, if not running, for a script with activeWorker's script url and activeWorker's environment settings object.
  3. Fire an event named activate using ExtendableEvent interface at activeWorker's environment settings object's global object.
  4. For each event listener invoked:
    1. If any uncaught runtime script error occurs, then:
      1. Report the error for the script per the runtime script errors handling.
      2. Run the Update State algorithm passing registration's active worker and redundant as the arguments.
      3. Set registration's active worker to null.
      4. Abort these steps.
    2. Let event be the event for which this event listener was invoked.
    3. If event's extend lifetime flag is set, then:
      1. Wait until event's extend lifetime flag is unset.
      2. If event's wait-until reject flag is set, then:
        
        Set activateFailed to true.
11. Wait for the task queued by the previous step to have executed.
12. If activateFailed is true, then:
  1. Run the Update State algorithm passing registration's active worker and redundant as the arguments.
  2. Set registration's active worker to null.
  3. Abort these steps.
13. Run the Update State algorithm passing registration's active worker and activated as the arguments.

8.6

Handle Fetch

The Handle Fetch algorithm is the entry point for the fetch handling handed to the service worker context.

Input: request, a request
Output: response, a response

Let handleFetchFailed be false.
Let respondWithEntered be false.
Let r be a new Request object associated with request.
Let headersObject be r's headers attribute value.
Set headersObject's guard to immutable.
Let response be null.
Let registration be null.
Let client be null.
Assert: request's client's global object is either a Window object or a SharedWorkerGlobalScope object.
If request's client's global object is a Window object, then:
1. Set client to the associated document of request's client's global object.
Else if request's client's global object is a SharedWorkerGlobalScope object, then:
1. Set client to the shared worker represented by request's client's global object.
Assert: request's context is not serviceworker.
If request's context is either embed or object, then:
1. Return null.
Else if request's context is one of frame, hyperlink, iframe, location, and sharedworker, then:
1. If the navigation triggering request was initiated with a shift+reload or equivalent, then:
  1. Return null.
2. Set registration to the result of running Match Scope algorithm, or its equivalent, passing r.url as the argument.
Else:
1. If client is a service worker client, then:
  1. Set registration to client's service worker registration.
If registration is null, then:
1. Return null.
If registration's active worker is null, then:
1. Return null.
Let matchedWorker be registration's active worker.
Assert: request's context is not serviceworker, embed, or object.
If request's context is one of frame, hyperlink, iframe, location, and sharedworker, then:
1. Let client use registration as its service worker registration.
If matchedWorker's state is activating, then:
1. Wait for matchedWorker's state to become activated.
2. If matchedWorker's activation fails, then:
  1. Return null.
Queue a task to run the following substeps:
1. Let activeWorker be registration's active worker.
2. Run a worker, if not running, for a script with activeWorker's script url and activeWorker's environment settings object.
3. Fire an event named fetch, using FetchEvent interface, with request attribute initialized to r, client attribute initialized to client of the request, in the form of ServiceWorkerClient object, and isReload initialized to true if event was dispatched with the user's intention for the page reload, and false otherwise, at activeWorker's environment settings object's global object.
4. For each event listener invoked:
  1. If any uncaught runtime script error occurs, then:
    1. Report the error for the script per the runtime script errors handling.
    2. Abort these steps.
  2. Let event be the event for which this event listener was invoked.
  3. If event's respond-with entered flag is set, then:
    1. Set respondWithEntered to true.
  4. If event's wait to respond flag is set, then:
    1. Wait until event's wait to respond flag is unset.
    2. If event's respond-with error flag is set, then:
      1. Set handleFetchFailed to true.
    3. Else:
      1. Set response to the value, which the argument passed into the event's respondWith(r) method resolved with.
Wait for the task queued by the previous step to have executed.
If respondWithEntered is false, then:
1. Return null and run the following substeps in parallel.
2. If request's context is one of frame, hyperlink, iframe, location, and sharedworker, then:
  1. Invoke Soft Update algorithm, or its equivalent, with registration.
3. Abort these steps.
If handleFetchFailed is true, then:
1. Return a network error and run the following substeps in parallel.
2. If request's context is one of frame, hyperlink, iframe, location, and sharedworker, then:
  1. Invoke Soft Update algorithm, or its equivalent, with registration.
Else:
1. Return a response represented by response and run the following substeps in parallel.
2. If request's context is one of frame, hyperlink, iframe, location, and sharedworker, then:
  1. Invoke Soft Update algorithm, or its equivalent, with registration.

8.7

Handle Functional Event

Input: registration, a service worker registration; callbackSteps, an algorithm
Output: None

Queue a task to run Handle Functional Event On Scheduled Task algorithm with registration and callbackSteps.

Event loop and task queuing model for this algorithm will be specified.

8.8

Handle Functional Event On Scheduled Task

Input: registration, a service worker registration; callbackSteps, an algorithm
Output: None

Assert: a Record with the [[value]] equals to registration is contained in [[ScopeToRegistrationMap]].
Assert: registration's active worker is not null.
Let activeWorker be registration's active worker.
Run a worker, if not running, for a script with activeWorker's script url and activeWorker's environment settings object.
Invoke callbackSteps, defined by the caller of the algorithm which queued this task, with activeWorker's environment settings object's global object as its argument.
Return.

8.9

Handle Document Unload

The user agent must run these steps, or their equivalent, when it unloads a document.

Input: document, a document using the service worker registration
Output: None

Run the following steps atomically.
Let registration be the service worker registration used by document.
If registration is null, then:
1. Abort these steps.
If any other document is using registration as their service worker registration, then:
1. Abort these steps.
If registration's uninstalling flag is true, then:
1. Invoke Clear Registration algorithm passing registration as its argument.
2. Abort these steps.
If registration.waiting is not null:
1. Run Activate algorithm, or its equivalent, with registration at the argument.

8.10

Unregister

Input: document, a Document; scope, a scope url
Output: promise, a promise

Let promise be a new promise.
Let scope to the result of running the URL serializer on scope with the exclude fragment flag set.
Run the following substeps in parallel:
1. If the origin of scope does not match document's origin, then:
  1. Reject promise with a "SecurityError" exception.
  2. Abort these steps.
2. Let registration be the result of running Get Registration algorithm passing scope as the argument.
3. If registration is null, then:
  1. Resolve promise with false.
  2. Abort these steps.
4. Set registration's uninstalling flag.
5. Resolve promise with true.
6. If no document is using registration as their service worker registration, then:
  1. If registration's uninstalling flag is unset, then:
    1. Abort these steps.
  2. Invoke Clear Registration algorithm passing registration as its argument.
Return promise.

8.11

Set Registration

Input: scope, a scope url
Output: registration, a service worker registration

Run the following steps atomically.
Let registration be a new service worker registration whose scope url is set to scope.
Set a newly-created Record {[[key]]: scope, [[value]]: registration} to [[ScopeToRegistrationMap]].
Return registration.

8.12

Clear Registration

Input: registration, a service worker registration
Output: None

Run the following steps atomically.
If registration's installing worker is not null, then:
1. Terminate registration's installing worker.
2. Run the Update State algorithm passing registration's installing worker and redundant as the arguments.
3. Set registration's installing worker to null.
4. The user agent may abort in-flight requests triggered by registration's installing worker.
If registration's waiting worker is not null, then:
1. Terminate registration's waiting worker.
2. Run the Update State algorithm passing registration's waiting worker and redundant as the arguments.
3. Set registration's waiting worker to null.
4. The user agent may abort in-flight requests triggered by registration's waiting worker.
If registration's active worker is not null, then:
1. Terminate registration's active worker.
2. Run the Update State algorithm passing registration's active worker and redundant as the arguments.
3. Set registration's active worker to null.
4. The user agent may abort in-flight requests triggered by registration's active worker.
Delete a Record {[[key]], [[value]]} entry of its [[ScopeToRegistrationMap]] where registration's scope url matches entry.[[key]].

8.13

Update State

Input: worker, a service worker; state, a service worker's state
Output: None

Set worker's state to state.
Let serviceWorkers be an array containing all the ServiceWorker objects associated with worker for all the browsing contexts' Document objects and the ServiceWorkerGlobalScope object represented by worker.
For each serviceWorker in serviceWorkers:
1. Queue a task to fire a simple event named statechange at serviceWorker.

8.14

Match Scope

Input: scope, a scope url
Output: registration, a service worker registration

Run the following steps atomically.
Let matchingScope be the longest [[key]] in [[ScopeToRegistrationMap]] starting with the value of scope.
Let registration be the result of running Get Registration algorithm passing matchingScope as the argument.
If registration is not null and registration's uninstalling flag is set, then:
1. Return null.
Return registration.

8.15

Get Registration

Input: scope, a scope url
Output: registration, a service worker registration

Run the following steps atomically.
Let registration be null.
For each Record {[[key]], [[value]]} entry of its [[ScopeToRegistrationMap]]:
1. If scope matches entry.[[key]], then:
  1. Set registration to entry.[[value]].
Return registration.

8.16

Get Newest Worker

Input: registration, a service worker registration
Output: worker, a service worker

Run the following steps atomically.
Let newestWorker be null.
If registration's installing worker is not null, then:
1. Set newestWorker to registration's installing worker.
Else if registration's waiting worker is not null, then:
1. Set newestWorker to registration's waiting worker.
Else if registration's active worker is not null, then:
1. Set newestWorker to registration's active worker.
Return newestWorker.

8.17

Query Cache

Input: request, a Request object; options, a CacheQueryOptions object, optional; targetStorage, an array that has [Request, Response] pairs as its elements, optional
Output: resultArray, an array that has [Request, Response] pairs as its elements

Let requestArray be an empty array.
Let responseArray be an empty array.
Let resultArray be an empty array.
If options.ignoreMethod is false and request.method is neither "GET" nor "HEAD", then:
1. Return resultArray.
Let cachedURL and requestURL be null.
Let serializedCachedURL and serializedRequestURL be null.
If the optional argument targetStorage is omitted, then:
1. For each Record {[[key]], [[value]]} entry of its [[RequestToResponseMap]], in key insertion order:
  1. Set cachedURL to entry.[[key]]'s associated request's url.
  2. Set requestURL to request's associated request's url.
  3. If options.ignoreSearch is true, then:
    1. Set cachedURL's query to the empty string.
    2. Set requestURL's query to the empty string.
  4. Set serializedCachedURL to serialized cachedURL.
  5. Set serializedRequestURL to serialized requestURL.
  6. If options.prefixMatch is true, then:
    1. Set serializedCachedURL to the substring of itself from the start, with the length of serializedRequestURL.
  7. If serializedCachedURL matches serializedRequestURL, then:
    1. Add entry.[[key]] to requestArray.
    2. Add entry.[[value]] to responseArray.
Else:
1. For each record in targetStorage:
  1. Set cachedURL to record[0]'s associated request's url.
  2. Set requestURL to request's associated request's url.
  3. If options.ignoreSearch is true, then:
    1. Set cachedURL's query to the empty string.
    2. Set requestURL's query to the empty string.
  4. Set serializedCachedURL to serialized cachedURL.
  5. Set serializedRequestURL to serialized requestURL.
  6. If options.prefixMatch is true, then:
    1. Set serializedCachedURL to the substring of itself from the start, with the length of serializedRequestURL.
  7. If serializedCachedURL matches serializedRequestURL, then:
    1. Add record[0] to requestArray.
    2. Add record[1] to responseArray.
For each cachedResponse in responseArray with the index index:
1. Let cachedRequest be the indexth element in requestArray.
2. If the result of running cachedResponse.headers object's has(name) method with "Vary" as the argument is false, or options.ignoreVary is true, then:
  1. Add an array [cachedRequest, cachedResponse] to resultArray.
  2. Continue to the next iteration of the loop.
3. Let varyHeaders be the array containing the elements corresponding to the field-values of the Vary header.
4. Let matchFailed be false.
5. For each f in varyHeaders:
  1. If f matches "*", then:
    1. Continue to the next iteration of the loop.
  2. If the result of running cachedRequest.headers object's get(name) method with f as the argument does not match the result of running request.headers object's get(name) method with f as the argument, then:
    1. Set matchFailed to true.
    2. Break the loop.
6. If matchFailed is false, then:
  1. Add an array [cachedRequest, cachedResponse] to resultArray.
Return resultArray.

8.18

Batch Cache Operations

Input: operations, an array of CacheBatchOperation dictionary objects
Output: q, a promise resolves with an array of Response objects.

Let p be a promise resolved with no value.
Let q be transforming p with onFulfilled.
Upon fulfillment of p with value v, perform the following substeps, onFulfilled, in parallel:
1. Let itemsCopy be a new [[RequestToResponseMap]] object that is a copy of its context object's [[RequestToResponseMap]] object.
2. Let addedRecords be an empty array.
3. Try running the following substeps atomically:
  1. Let resultArray be an empty array.
  2. For each operation in operations with the index index:
    1. If operation.type matches neither "delete" nor "put", then:
      1. Throw a TypeError.
    2. If operation.type matches "delete" and operation.response is not null, then:
      1. Throw a TypeError.
    3. Let requestResponseArray be the result of running Query Cache algorithm passing operation.request and operation.options as the arguments.
    4. For each requestResponse in requestResponseArray:
      1. If the result of running Query Cache algorithm passing requestResponse[0], operation.options, and addedRecords as the arguments is not an empty array, then:
        
        Throw an "InvalidStateError" exception.
      2. For each Record {[[key]], [[value]]} entry of its [[RequestToResponseMap]], in key insertion order:
        
        If the result of running Query Cache algorithm passing requestResponse[0] and operation.options is equal to the result of running Query Cache algorithm passing entry.[[key]] and operation.options, then:
        
        Delete entry.
    5. If operation.type matches "put", then:
      1. If operation.response is null, then:
        
        Throw a TypeError.
      2. Let r be operation.request's associated request.
      3. If r's url's scheme is not one of "http" and "https", then:
        
        Throw a TypeError.
      4. If r's method is not `GET`, then:
        
        Throw a TypeError.
      5. If operation.options is not null, then:
        
        Throw a TypeError.
      6. Set a newly-created Record {[[key]]: operation.request, [[value]]: operation.response} to [[RequestToResponseMap]].
      7. Add an array [operation.request, operation.response] to addedRecords.
    6. Add operation.response to resultArray.
  3. Resolve q with resultArray.
4. And then, if an exception was thrown, then:
  1. Set the context object's [[RequestToResponseMap]] to itemsCopy.
  2. Reject q with the exception
Return q.

Service Workers

W3C Working Draft 18 November 2014

Abstract

Status of This Document