This specification extends ServiceWorkerGlobalScope [[!service-workers]] with APIs for managing the lifecycle of an application and associated events.

Introduction

The extensions to the service worker global execution context defined in this specification allow web developers to author applications that manage the application lifecycle and react to system events. These capabilities allow application developers to create applications that integrate closely with the underlying system.

Using the APIs defined in this specification, an application is able to run application logic independently of any user interface scripts and react to:

There is only one class of product that can claim conformance to this specification: a user agent.

Implementations that use ECMAScript to implement the APIs defined in this specification MUST implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [[WEBIDL]], as this specification uses that specification and terminology.

Dependencies

This specification relies on the following specifications:

Terminology

The term JavaScript global environment refers to the global environment concept defined in [[!ECMA-262]].

The EventHandler interface represents a callback used for event handlers as defined in [[!HTML5]].

The concepts queue a task and fire a simple event are defined in [[!HTML5]].

The terms event handlers and event handler event types are defined in [[!HTML5]].

The ServiceWorkerGlobalScope interface is defined in [[!service-workers]]

The TaskScheduler interface is defined in [[!TASKSCHEDULER]].

Use Cases and Requirements

Below is a list of use cases derived from the initial input to the System Applications Working Group Charter that were not addressed by the Runtime and Security Model for Web Applications [[SYSAPPS-RUNTIME]] — a proposal the group decided to obsolete due to lack of implementers' interest. Currently, the domain initially covered by [[SYSAPPS-RUNTIME]] is split across multiple specifications and the use cases compatible with the Web security model are being addressed by a set of specifications: Application Lifecycle and Events and its normative dependencies Service Workers [[!service-workers]], Task Scheduler [[!TASKSCHEDULER]], and the Manifest for web applications [[!appmanifest]]. The set of specifications is expected to grow over time to cover more of the domain and use cases.

In the context of use cases, main document refers to a JavaScript global environment.

A Single Entry Point to the Application

The main document is the main entry point of the application to the system. When loading the main document, the runtime does not display it to the user. If the application intends to show a user interface it has to create windows or interact with the platform in other ways such as by using a notification system.

The runtime can unload the main document in certain circumstances, which results in termination of the application. When the main document is not executing any script, has no pending callbacks, and no open windows, the runtime can decide to unload the main document. In addition, the runtime unloads the main document in order to reduce resource consumption. For example, after loading the main document and no window is visible, the application can be terminated by the runtime.

Behavior Adaptation at Launch

This section is non-normative.

The runtime does not create any visible windows by itself when launching an application. This is up to the application and is handled as part of the launch event. When launched, the application will know the reason for the launch. The reason could be a scheduled wake up, a persistent event of interest or a direct launch either by the system, another application, or initiated by the user. This allows the application to act differently depending on the reason.

System Event-initiated Launch

The runtime starts the application for the purpose of delivering events from the system. For example, a system-level service might ask an email application to send an email on its behalf. To handle these cases, the runtime will listen to system events in order to launch the main document in response to them.

An application subscribes to system events either at install time or at runtime.

Wakeup-initiated Launch

This section is non-normative.

An application can schedule itself for wake-up by scheduling a task. A task will ensure that the application is running and that the launch event has been fired at the main document before resolving the the task.

Note that in order to run a task at the scheduled time, the application can be started a bit earlier.

Termination Sequence

This section is non-normative.

The runtime terminates the application if it becomes idle or in case of resource constraints.

Before actual termination, the terminate event is sent, giving the application the ability to clear up, store state and close windows. In case that the application does not terminate within a given time, the runtime can consider the application as too slow or hanging and has the ability to terminate it immediately (forced termination). The application can save its state periodically to protect against data loss, in such a case.

After the terminate event, or in case of forced termination, the runtime will progress to actual termination, which at least includes closing all remaining windows and unloading of the main document. What other resources the runtime unloads is up to the implementation.

There is an exception as the application can receive a wakeup or a system event while processing the terminate event. If this is the case, the terminate event is followed by a terminate canceled event, as actual termination will not happen.

The runtime will avoid terminating an active, focused application if at all possible. However, the runtime can terminate the application as a last resort (e.g., due to resource exhaustion or bad behavior).

The runtime prevents an application from interfering with the application's termination, e.g. event listeners or long-running scripts using APIs such as Geolocation, setTimeout, XMLHttpRequest will not block the runtime from terminating the application.

Application Events

This section is non-normative.

The runtime context associated with the main document can be launched and terminated either by the user, another application, or by the system. The system can decide to terminate an application as long as it is considered idle (no visible views or connected message ports). In the case the application received an event (or something similar, like a task was scheduled) while processing the terminate event, the terminate canceled event will be fired successively and the main document will stay active until considered idle again.

Mozilla would like the Mozilla Push API to use a [model similar to what is proposed in this spec].

When the application is launched, the launch event is fired with a reason which can be of type pending event, scheduled or other. If the application was launched in order to handle an event it subscribed to or in response to a scheduled task, the type will be pending event and scheduled respectively. This allows for the application to avoid creating any user interface not resulting from the respective event handling.

Explain how the other reason is handled by application developers.

In the case the user or another application started the application, the reason is set to other, allowing the main document to load the default user interface and potentially a “screenshot” of the application while the main user interface is being built in the background.

For handling application lifecycle, the application's main document can listen to the events.

System Events

This section is non-normative.

A system event is an event sent by the system. This event type does not originate from the DOM itself and thus lives outside of the main document's lifetime. A system event can wake up a terminated application. An implementation can also allow a system event to wake up the system from sleeping.

A typical browser-driven use case for system events is an email application that wants to show a desktop notification when a push notification is received so the user is informed that there are new emails even though the tab in which the email application was running has been closed.

System events are applicable to event types that fire at low frequency and support filtering. For example, they are not appropriate for user interaction events that require a visible user interface or fire frequently.

When an application is launched in response to a system event, its main document is loaded, a launch event is dispatched, and immediately after the launch event, the system event handler is called. If the application did not register the listener as part of the launch event, nothing happens.

To register for system events, need an event handler that is triggered when the application is first installed, the application is updated, or the runtime is updated to a new version ("oninstalled" or similar). Registration through the Manifest would be beneficial too.

Filtered Events

This section is non-normative.

Filtered events are a mechanism that allows listeners to specify a subset of events that they are interested in. A listener that makes use of a filter is not invoked for events that do not pass the filter, which makes the listening code more declarative and efficient.

To prevent an application from being woken up for no reason, filtering happens in the runtime and not in an application.

The difference between "persistent" and "regular" DOM events must be made obvious so that developers do not expect regular DOM events to behave similarly.

Event Registration

This section is non-normative.

When an application subscribes to an event, it will be subscribed to it until it is unsubscribed, the application is uninstalled, updated or terminated.

The listeners only exist in the context of the main document. Event listeners for system events need to be registered each time the main document is launched after termination.

Creating Windows

This section is non-normative.

One or more windows might be created from the main document. These windows are directly scriptable by the main document.

TODO: expand windowing use cases in a separate specification if needed.

Requirements

Below is a summary of requirements derived from the above use cases:

  1. An application (e.g. a background service) MUST be able to run without visible user interface.
  2. An application MUST be able to decide when to show the user interface, if at all. It is up to the application developer to decide when it is appropriate to show the user interface.
    • An application MUST be able to show the user interface only after it is fully constructed with the right dimensions and all the needed data has been loaded.
  3. The runtime model MUST support authoring an application (or a service without user interface) that can be terminated without user’s consent, and that is able to restore to its previous state.
  4. After being launched, an application MUST be able to execute scripts to recreate its state before recreating the actual user interface.
  5. An application MUST be able to show a different user interface given how the app was launched.
    • For example, if launched as a photo picker, the application will not show the default application window, but instead creates a special purpose user interface.
  6. The runtime MUST provide a mechanism to prevent an application from being launched unnecessarily.
    • As the system events can result in launching dormant apps, it is important that that only happens for subscribed events which support pre-filtering. For example, if an application listens to a "USB plugged" event, it can additionally ask to only listen to a specific device connected or a specific port.
  7. The application MUST be able to enumerate windows associated with it, and create new windows.
  8. The application MUST be able to create a window and have it laid out correctly with the right dimensions before being shown.
    • This allows emulating the splash screen/application screenshot at launch for any screen size, before loading any application logic, so that the screenshot is not needed to be part of the manifest.

APIs Available to Service Workers

An environment through which the interfaces defined in this specification are exposed to JavaScript is referred to as the service worker global execution context (also referred to as the global execution context of a Service Worker in [[!service-workers]]) whose global object is referred to as service worker global scope.

Extensions to the ServiceWorkerGlobalScope interface

attribute EventHandler onlaunch
attribute EventHandler onterminate
attribute EventHandler onterminatecanceled
readonly attribute TaskScheduler taskScheduler
This is a (non-exhaustive) list of features ServiceWorkerGlobalScope inherits from WorkerGlobalScope:
  • navigator object
  • location object (read-only)
  • XMLHttpRequest() method
    • If the JavaScript global environment is a worker environment, the responseType of document is not supported as per [[XHR]].
  • setTimeout()/clearTimeout() and setInterval()/clearInterval()
  • applicationCache object
  • importScripts() method
  • Worker() method (spawning web workers)
  • indexedDB object
  • ...
Communicating with the service worker is done with explicit MessagePort objects similar to shared workers. ServiceWorkerGlobalScope [[!service-workers]] has a clients attribute, which represents a list of windows or workers that match the service worker's origin and scope.
Remove features that do not have strong use cases and consider them in v2. After implementation feedback, we can add features that appear to be lacking. For example, reason in LaunchEvent, terminate and terminatecanceled are proposed to be deferred to v2 without strong use cases.

When the application is launched, the user agent MUST queue a task to launch the application.

When the application is terminated, the user agent MUST queue a task to terminate the application.

When the application termination is canceled, the user agent MUST queue a task to cancel the termination.

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

event handler event handler event type
onlaunch launch
onterminate terminate
onterminatecanceled terminatecanceled
It would be nice to have a diagram that shows when all events are fired and the order.

Launching the Application

readonly attribute DOMString reason
attribute DOMString reason

When the user agent is REQUIRED to launch the application, the user agent MUST run the following steps:

  1. Re-instantiate the pre-existing version of the service worker global execution context, if any. Otherwise, establishing a new service worker global execution context.
  2. Create a LaunchEvent object and initialize it with the given name launch.
  3. Initialize the reason attribute to a value corresponding to a launch reason as defined in the table below.
  4. Dispatch the newly created LaunchEvent object at the ServiceWorkerGlobalScope object.
reason attribute value Description Times [fired] When
pending-event The application is launched in response to a system event it is listening to. Zero or more.
scheduled The application is launched by the system at the scheduled time. Zero or more.
other Other reason. Zero or more.
The pending-event, scheduled or other event types are confusing. This should be implied by the event "class" or the event name.
Need a mechanism for passing data to the service worker from the application that launched it. Does Web Activities/Intents address the use case (in scope for Web Intents Task Force), or is this addressed by e.g. passing the data in LaunchEvent?

Terminating the Application

When the user agent is REQUIRED to terminate the application, it MUST run the following steps:

  1. Fire a simple event named terminate at the ServiceWorkerGlobalScope object.
  2. Spin the event loop for a user-agent-defined amount of time.
    This is intended to allow the application to run scripts to persist state, do clean up tasks before being terminated.
  3. Close all the windows created by the service worker script.
  4. Discard the service worker.
Need to make it clear that the service worker can be terminated only when it is idling, all Promises resolved, all indexedDB transactions completed, no Workers running etc. However, Badly behaving application that try to prevent an application for being closed can be killed by the system similarly to onunload.

Canceling the Termination

readonly attribute DOMString reason
attribute DOMString reason

When the user agent is REQUIRED to cancel the termination, the user agent MUST run the following steps:

  1. Cancel the already-running instance of the terminate the application algorithm, if any.
  2. Create an event that uses the TerminateCanceledEvent interface, with the name terminatecanceled.
  3. Initialize the reason attribute to a value corresponding to a terminate cancellation reason as defined in the table below.
  4. Dispatch the newly created TerminateCanceledEvent object at the ServiceWorkerGlobalScope object.
reason attribute value Description Times [fired] When
- - - -
- - - -

Acknowledgments

Thanks to everyone who have contributed to the Service Worker proposal that provides primitives for this specification to build atop.

Some use cases are derived from Adam Barth’s execution model proposal referenced in the System Applications Working Group Charter. Thanks to the Chrome team for their experiments with Packaged Apps. Also special thanks to Thiago Marcos P. Santos and Caio Marcelo de Oliveira Filho for their comments.

Also, big thank you to all SysApps Toronto participants who reviewed the proposal, sent feedback and participated in the task force session.

  翻译：