This document specifies the runtime and security model of Web Applications. It is describing how an application is defined trough an application manifest, how it can be installed, updated and packaged. It is also specifying how such an application can put in background, put back in foreground or waken up.
Finaly, the document describes the security model for such applications. This includes the permission model and the different security rules that would apply.

Terminology

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

The concept of fire a simple event is defined in [[!HTML5]].

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

The DOMError interface represents an error handling object as defined in [[!DOM4]].

Application Manifest

An application manifest is a JSON file describing an installable web application. This JSON file consists of a top-level object and several properties. The JSON grammar is described in [[!RFC4627]].

      {
        "name": "MozillaBall",
        "description": "Exciting Open Web development action!",
        "launch_path": "/",
        "version": "1.0",
        "icons": {
          "16": "/img/icon_16.png",
          "48": "/img/icon_48.png",
          "128": "/img/icon_128.png"
        },
        "developer": {
          "name": "Mozilla",
          "url": "https://mozilla.org/en-US"
        },
        "appcache_path": "/cache.manifest",
        "locales": [
          "es": {
            "description": "¡Acción abierta emocionante del desarrollo del Web!",
            "developer": {
              "url": "https://mozilla.org/es-ES"
            }
          }
        ],
        "default_locale": "en",
        "screen_size": {
          "min_width": "600",
          "min_height": "300"
        },
        "required_features": [
          "touch", "geolocation", "webgl"
        ],
        "permissions": {
          "contacts": {
            "description": "Required for autocompletion in the share screen",
            "access": "read"
          }
        },
        "fullscreen": "true",
        "relNotes": {
          "1.0": "Bugs fixed. New exciting effects. Ready for an official release!"
          "0.5": "First alpha version with still some bugs but already fun!"
        }
      }
      }
      

Properties

Adding new properties to the manifest

Any new specification can add new properties to the application manifest. Those specifications MUST describe the new properties, the expected values and the expected behaviour. Implementations MUST implement the basic properties as describe below but SHOULD only implement any extented feature if they are implementing those specifications.

Basic properties

All leaf properties MUST contain a string value unless specified otherwise.

The following properties MUST be part of the application manifest: name and description. In addition, if locales is part of the application manifest, default_locale MUST be part of the application manifest. The other properties are optional.

  • name: The name of the web application in the default locale. The name SHOULD not be longer than 128 characters.
  • description: A short description of the web application. The description MUST be in the default locale. The description SHOULD not be longer than 1024 characters.
  • default_locale: The property's value MUST be the top-level name and description's locale.
  • launch_path: The property's value MUST be the path within the application's origin that is loaded when the application is launched.
  • icons: A map of icon sizes to URIs of the icons (which may be absolute, relative or data URIs). Icons MUST be square. Relative URLs MUST use the application manifest URL as base URL.
  • developer: This property describe the developer of the application and MUST contain the following properties:
    • name: The value MUST contain the name of the developer.
    • url: The value MUST contain an URL pointing to the developer's website
  • locales: The property's value MUST contain a map of locale specific overrides of strings contained in the application manifest. Each locale key is keyed on a locale tag [[!RFC4646]], and contains a sparse representation of the manifest. Any field in the locales property SHOULD override the corresponding property in a localized user interface. The UA MAY ignore some values if localizing the property doesn't appear to be legit.
    If the locales property is set, the default_locale MUST also be set.
  • appcache_path: The value MUST contain the absolute path to the application cache manifest [[!OFFLINE-WEBAPPS]].
    When an application is installed, the AppCache manifest will be fetched and parsed, and its static assets under the CACHE header MUST be cached.
  • version: The value MUST be a string that represents the version of the application. The UA SHOULD NOT interpret this value but MAY show it to the user so the auther SHOULD use human understandable versions.
  • screen_size: This object SHOULD contain the min_height and min_width properties that describe the minimum height and width (in pixels) the application needs in order to render correctly. Those values are only hint for the UA and should not be considered as mandatory restrictions.
  • required_features: This value MUST be an array containing the mandatory feature set the application needs in order to run correctly. If the property is missing or the value is an empty array or if the value is invalid, the mandatory feature set SHOULD be considered as the empty set.
    TBD: add a list of features.
  • fullscreen: This value MUST be set to either true or false to describe whether the runtime should launch the application in fullscreen mode.
  • relNotes: This property's value MUST contain a map associating an application's version with a string describing the changes between that version and the previous one.
  • permissions: This value consists of a set of permissions that the application needs. An application SHOULD list every API that is considered to require user permission in this field. Usage of an API without a corresponding entry in the manifest SHOULD fail. The field is an object, with each property name specifying a single permission, and object containing the following fields:
    • description: Contains a human readable string specifying the intent behind requesting use of this API. This property is mandatory.
    • access: Contains a a string specifying the type of access required for this permission. This field is mandatory for a certain subset of permissions, and MUST be one of read, readwrite, readcreate, or createonly.

    Each specification MUST specify the new permissions that would be required to use the feature it is defining.

The application's origin is the origin of the application manifest. [[!ORIGIN]]

Serving Manifests

An application manifest MUST be served from the same origin as the application.

When served as a static file, it is RECOMMENDED that the manifest is stored with the extension .webapp. The manifest MUST be served with a Content-Type header of application/x-web-app-manifest+json. It is RECOMMENDED that application manifests are served over SSL.

Application Management

Application interface

Web Applications are represented by the Application interface.

readonly attribute DOMString origin
The attribute MUST return the application's origin.
readonly attribute Object manifest
The attribute MUST return an object representing the parsed application manifest.
readonly attribute DOMString installOrigin
The attribute MUST return the origin of the page from which the application was installed. [[!ORIGIN]]
readonly attribute unsigned long installTime
The attribute MUST return the time in milliseconds since epoch at which the application was installed.
readonly attribute Object parameters
The attribute MUST return the parameters that were provided at install time. See install() in ApplicationRegistry.
DOMRequest launch()
This method MUST return a DOMRequest instance and then run the following steps asynchronously:
  1. If the caller isn't allowed by the UA to launch the application, the UA MUST fire an error event to the DOMRequest object with the "NotAllowedError" error code and exit those steps.
  2. If the caller is allowed to launch the application, the UA SHOULD launch the application.
  3. If the application has been successfuly launched, the UA MUST fire a success event to the DOMRequest object and set result to null.
    Otherwise, the UA MUST fire an error event to the DOMRequest object with an error code that describes the error.
DOMRequest uninstall()
This method MUST return a DOMRequest instance and then run the following steps asynchronously:
  1. If the application isn't currently installed, the UA MUST fire an error event to the DOMRequest object with the "NotInstalledError" error code and exit those steps.
  2. If the caller isn't allowed by the UA to uninstall the application, the UA MUST fire an error event to the DOMRequest object with the "NotAllowedError" error code and exit those steps.
  3. If the caller is allowed to uninstall the application, the UA SHOULD uninstall the application.
  4. If the application has been successfuly uninstalled, the UA MUST fire a success event to the DOMRequest object and set result to null.
    Otherwise, the UA MUST fire an error event to the DOMRequest object with an error code that describes the error.
readonly attribute DOMString updateState
The attribute MUST return the empty string, available, downloading, downloaded or installing, depending on the state of the application.
If the application is being updated, the attribute MUST return installing.
If the application is ready to be updated, with the updtade fully downloaded or if there is no download to proceed to the update, the attribute MUST return downloaded.
If the application's update is being downloaded, the attribute MUST return downloading.
If there is an application update available, it is not being installed, nor downloaded, nor downloading, the attribute MUST return available. Otherwise, the attribute MUST return the empty string.
readonly attribute unsigned long downloadSize
The attribute SHOULD return the size of the download that would be required to update the application in kilobytes, if any. If the application doesn't have have an available update, if the download has already been done or if the UA can't find out the size of the download required for the update, the attribute MUST return 0.
If the download is happening, the attribute MUST return 0.
If the download has been made but interupted and the UA is able to continue it, the attribute SHOULD return the remaining size to download.
DownloadRequest downloadUpdate()
The method MUST return a DownloadRequest object and asynchronously run the following steps:
  1. If the application doesn't have an available update, the UA MUST send an error message to the request object with the value InvalidState and abort these steps.
  2. If the application doesn't require a download to process the update, the UA MUST send a succes message to the request object with no value and abort these steps.
  3. If the application's update is currently being downloaded, the request MUST reflect the current state of the download. Otherwise, the request must start the download.
readonly attribute DOMString state;
The attribute MUST return running if the current application state is running. Otherwise, if the current application state is paused, it MUST return paused. Otherwise, it MUST return terminated.
void hide()
When this method is called, the UA SHOULD hide the application from the user. Hiding the application SHOULD fire visibility events as described in [[!PAGE-VISIBILITY]].
If the application was already not visible, this method MUST be a no-op.
void exit()
When this method is called, the UA MUST put the application state to terminated and fire the appropriate events.
If the application was already in the terminated state, this method MUST be a no-op.
attribute EventHandler onlaunch
attribute EventHandler onpause
attribute EventHandler onresume
attribute EventHandler onterminate

The following are the event handlers (and their corresponding event handler event types) that MUST be supported as attributes by the Application objects:

event handler event handler event type
onlaunch launch
onpause pause
onresume resume
onterminate terminate

DownloadRequest interface

void cancel()
This method MUST stops the download and asynchronously send an error message to itself with the value UserCancel.
attribute double progress
If the current state is error the attribute MUST return 0.0. Otherwise, if the current state is success, the attribute MUST return 1.0. Otherwise, the attribute SHOULD return the current progress of the download expressed between 0.0 and 1.0.
attribute EventHandler onprogress

When the caller start the download, the DownloadRequest SHOULD start downloading the resource.

If the resource fails to download, the UA MUST send an error message to the request.

If the resource succeed to download, the UA MUST send a success message to the request.

While the resource is downloading, which means as long as readyState is pending, the UA SHOULD regularly fire a simple event named progress on the object. The UA should note that sending too much events might have an impact on performance but sending too few of them might impact the user experince.

The following are the event handlers (and their corresponding event handler event types) that MUST be supported as attributes by the DOMRequest objects:

event handler event handler event type
onprogress progress

Extension to the Navigator interface

An ApplicationRegistry instance is exposed on the Navigator object trough the an app attribute.

readonly attribute ApplicationRegistry app
The attribute MUST return an ApplicationRegistry instance.

ApplicationRegistry interface

The ApplicationRegistry interface allows handling applications and query there status.

DOMRequest install(in DOMString manifestUrl, [Optional] in Object parameters)
This method MUST return a DOMRequest instance and then run the following steps asynchronously:
  1. If the caller isn't allowed by the UA to install the application, the UA MUST fire an error event to the DOMRequest object with the "NotAllowedError" error code and exit those steps.
  2. If the caller is allowed to install the application, the UA SHOULD install the application as described in the manifest at manifestUrl.
  3. If the application has been successfuly installed, the UA MUST fire a success event to the DOMRequest object and set result to null.
    Otherwise, the UA MUST fire an error event to the DOMRequest object with an error code that describes the error.

The UA SHOULD verify at any moment before installing that manifestUrl points to a valid manifest. If this is not the case, the UA MUST fire an error event to the DOMRequest object with the "InvalidArgumentError" and exit the steps.

The UA SHOULD save the parameters if some are passed so they can later be retrieved by the parameters attribute on the Application interface.

DOMRequest getSelf()
The UA SHOULD return a DOMRequest object and asynchronously get all applications that have an origin matching the caller's origin. [[!ORIGIN]]
When those applications are collected, the UA SHOULD send a success event to the DOMRequest object and populate its request attribute with an array containing the applications.
DOMRequest getInstalled()
The UA SHOULD return a DOMRequest object and asynchronously get all applications that have an origin matching the caller's origin. [[!ORIGIN]]
When those applications are collected, the UA SHOULD send a success event to the DOMRequest object and populate its request attribute with an array containing the applications.
DOMRequest checkInstalled(DOMString manifestURL)
The UA SHOULD return a DOMRequest object and asynchronously check if there is an installed application in the system with a manifest URL matching manifestURL.
After the asynchronous operation is done,, the IA SHOULD send a success event to the DOMRequest object and populate its result attribute with the boolean value true if there is an installed application fulfilling the condition, otherwise result should be set to false.
checkInstalled() could be synchronous. Seems way more convevient.
  • What's the real difference between getSelf() and getInstalled()?
  • Can an application be not installed but still in the registry? How?
attribute ApplicationManagement management
If the caller isn't allowed to manage applications, the UA MUST return null. Otherwise, it MUST return an ApplicationManagement object.
  • Permission check isn't clearly defined here. Should it be better?

ApplicationManagement interface

The ApplicationManagement interface allows access to all applications and is being informed any time an application is being installed or uninstalled. The intent of this interface is to be restricted to privileged callers.

DOMRequest getAll()
The UA SHOULD return a DOMRequest object and asynchronously get all applications currently in the application registry.
When those applications are collected, the UA SHOULD send a success event to the DOMRequest object and populate its request attribute with an array containing the applications.
[TreatNonCallableAsNull] attribute EventHandler oninstall
This value may be set to a function that will be invoked when an application is installed. The only argument to this function will be the AppObject of the application that was installed.
[TreatNonCallableAsNull] attribute EventHandler onuninstall
This value may be set to a function that will be invoked when an application is uninstalled. The only argument to this function be the AppObject of the application that was uninstalled.
DOMRequest applyUpdate(Application application)
The method MUST return a DOMRequset object and perform the following steps asynchronously:
  1. If the application doesn't have an updated or the updated isn't fully downloaded, the UA MUST send an error message to the request with the value InvalidState and abort these steps.
  2. Stop application from running if it is currently running.
  3. Replace the previous version with the new version of the application.
  4. If an error has occured during the previous steps, the UA MUST send an error message to the request with any appropriate value. Otherwise, the UA MUST send a success message to the request with an Application object representing the updated application as a value.

Events

An install event MUST be fired on all ApplicationManagement instances as soon as an application is installed.

The uninstall event MUST be fired on all ApplicationManagement instances as soon as an application is uninstalled.

The following are the event handlers (and their corresponding event handler event types) that MUST be supported as attributes by the ApplicationManagement object:

event handler event handler event type
oninstall install
onuninstall uninstall

Application Event Types

Application Events are sent when an event happen on the application level like an application being installed or uninstalled.

readonly attribute Application application
Application application

ApplicationEvent objects MUST contain a non-null application attribute representing the application on each the action happened.
The application events are always sent asynchronously, do not buble and are not cancelable.

There are currently two types of Application Events:

Packaged applications

A packaged application is an application that is self-contained in a container. All resources that are commonly used by the application SHOULD be available in the container.

A hosted application is an application that is not a packaged application

Use cases

A packaged application would be useful in a few situations, amongst them:

Package format

An application manifest for the application MUST be present at the root of the container.

The container of a packaged application MUST be a ZIP file.

URI of a packaged file

A file contained in a packaged application MUST have an URI with the following rules:

For more information about URI's, refer to [[!RFC3986]].

For example, the URI of index.html from an application can be: app://e35b8412-7451-46e7-ab29-0cee24fd486a/index.html.

The URI of a packaged file is defined such as two files from the same packaged application MUST share the same origin.
A file from a packaged application and any other resource outside of this application (an application or not, packaged or not) MUST not share the same origin. [[!ORIGIN]]

Manifest

A packaged application MUST have a copy of its application manifest outside of the package so it can be used for installation and updates purposes. As a consequence, that copy of the application manifest can be reduced to only a few properties: name, version and relNotes. In addition, a new property can be used only in the content a packaged application manifest: package that SHOULD contain an object with the following properties:

        {
          "name": "My Packaged App",
          "description": "This is my first packaged app!",
          "launch_path": "/",
          "version": "1.0",
          "developer": {
            "name": "Mozilla",
            "url": "https://mozilla.org/en-US"
          },
          "package": {
            "url": "http://example.org/mypackagedapp.zip",
            "size": "1024",
            "sha256": "6df134b0cfd88d6d4f27a99e29b9923d50eb8b2c0d5289c60012de424c7a9d97"
          }
        }
        
* Add relNotes to the properties of the manifest, like: 'relNotes': { '1.0': "This is what has been done...", '0.1': "That was so long ago..." }

Updates

An application SHOULD advertise an update by updating its application manifest.

The UA SHOULD regularly check if the application manifest of installed applications has not been updated. To know if the file has been updated, HTTP semantics apply.

For package applications, both application manifests (outside and inside the package) SHOULD be updated. However, the application manifest inside the package SHOULD always be checked to make sure the update (or the install) is genuine.

Data isolation

In the context of a running application, all usual rules for data isolation MUST apply: same-origin policy, same-domain policy, or whatever is used. However, between two applications, those rules no longer apply. Two applications MUST be fully isolated from each other in the sense that they SHOULD NOT be able to access data from each other. For example, if App1 accesses http://example.org and gets a cookie from it, App2 should not be able to see that cookie when accessing http://example.org even if the usual cookie sharing policy should allow this to happen.

This isolation SHOULD apply for all data storage like cookies, localStorage, IndexedDB, app cache and any other Web Platform mechanism that allows to store data and doesn't explicitly opts out from the application data isolation.
The isolation SHOULD also apply to UA specifics data storage. For example, any permission granted or denied to a host/origin/domain should be isolated per-application or auto-fill and autocompletion features for forms.

Navigation

Depending on the user interface around the application context, navigating outside the application's origin might lock the user out of the application. To prevent that, the UA SHOULD NOT allow navigation out of the application's origin, unless the origin is specified in the following application manifest property:

If the application tries to navigate to an unauthorized origin, the UA SHOULD open the link in a regular but distinct browsing context.

System Messages

TODO: We might want to have something describing how an application goes inactive, get killed and everything to have a better description of system messages. TODO: there is no notion of multi-page applications in this descirption of system messages. We do not handle system messages that are registered on another page.

System Messages are events sent by the system to an application which has registered for it before. Those events are different from DOM events in the sense that they are always originated by the system and that if the targeted application isn't currently running, it will be started.
In addition, un-handled messages will stay in a queue.

Use cases

Some applications might be interested in getting some events even if they are not running and want to be woken up if such events is sent while they are asleep.
In addition, when the application is being woken, it needs to know as soon as possible why it has been disturbed to be able to show the appropriate interface.
Finally, the capability of being woken should be transparent to the application.

Extension to the Navigator interface

optional Object message
The parameter message SHOULD contain an object that would be used by the handler and giving information about the system message. For example, a system message about a delivered pizza should give information about the pizzas that have been delivered. If the system message is already self-explanatory, message SHOULD be null.
void setMessageHandler(DOMString type, systemMessageCallback? callback)
The method MUST set callback as the new message handler for the type of system message type.
If callback is null, the current callback, if any, for the type of message type must be reset and no callback should no longer be set for this type.
If callback is not null and there was no message handler for the given type and there are messages in the pool of messages for the type, then the UA MUST start an asynchronous task that executes all the messages in the pool by the new handler in a FIFO basis and then remove all those messages from the pool of messages.
If the callback is not null and there is a message handler for the given type, that message handler should be replaced by callback.
boolean hasPendingMessages(DOMString type)
The method MUST returns true if there is at least one message in the pool of messages for the given type. Otherwise, it MUST return false.

Definitions

The type of system message identifies a category of system messages.
Application are be able to register and handle system messages based on their types. There is no exhaustive list of system messages type. Any specification can create a new type of system message.

Each application has a pool of messages for each type of system message. Everytime a system message is sent to an application, if there is no handler for that message's type, the UA MUST add the message to the pool of messages used for that type.
The UA MAY, for memory optimization, discard old messages if the pool becomes too big or if the messages are too old.

When a UA is required to fire a system message of a given type, it has to do one of these actions:

Permissions

Use cases

Some API might allow the application to access sensitive parts of the hardware or sensitive information. To prevent applications to access them, some APIs might require one or more permissions. For example, for an application to be allowed to access your geolocation information, it has to be granted the geolocation permission.

Permission declaration

An application SHOULD define all permissions it is going to use in the application manifest. The UA MAY automatically grant some permissions at install-time or ask the user to grant some applications. However, MAY, in addition or alternatively, ask the user to grant permissions at run-time.

The user MUST be able to revoke a granted permission or grant a denied permission at any time.

Basic Permissions

Specifications are expected to declare the permissions they will require for their feature to work. Altough, some basic permissions can't really go into a specific specification or a related to specifications that might be harder to change.

Thus, this specification is defining the following permissions:

Permission Name Permission Description Access Type
desktop-notification Allow the application to use the Desktop Notification API. N/A
geolocation Allow the application to access the Geolocation API. N/A
storage Allow localStorage and IndexedDB without size limitations. N/A
webapps-manage Allow access to the navigator.apps.management API to manage installed webapps. N/A

Trusted applications

Use cases

Any application can be compromised. It just depends on how much effort the attacker wants to provide and how much efforts the author wants to dedicate making its application more secure. With an interesting enough outcome, attackers could easily double their efforts to beat the security in place. For example, an API allowing to send SMS, if it can be manipulated by the evil persons, could be used to send premium SMS and steal money from the users.

With a simple permission system, users could be tricked to install the application and accept to grant the application the relevant permissions. These kind of attacks are proven to be efficient.

Chain of trust

An application is said to be a trusted application if the origin installing the application is trusted by the UA and the origin installing the application consider the application as trusty.

A UA SHOULD have the public key of all installation origin it is considering trusted.

Marking an application trusted

A hosted application MUST be recognized as marked trusted by the installation origin if the application manifest is signed by the installation origin's private key.

A packaged application MUST be recognized as marked trusted by the installation origin if the package is signed by the installation origin's private key.

In both cases, the application SHOULD be considered as trusted by the UA if the UA considers the installation origin as trusted, following the chain of trust mentioned above.

Security considerations

UA should keep in mind that a signed package is way more secure than a signed manifest. A correctly signed package can only be compromised if the private key has been compromised or the cryptographic algorithm. A UA should not trust an installation origin if it does not trust its ability to keep safe its private key.

On the other hands, a signed manifest only proves that the application is genuinly trusted (if the private key was not compromised nor the cryptographic algorithm). Anything else can be compromised given that it lives in the Internet. There is no need to list all possible attacks.

An important difference between a packaged application and a hosted application is the ability to review the code. Any permission granted to a packaged application will be granted to the code inside the package only. That means trusting such application is way easier after a code review, for example.

However, code review for packaged applications could be avoided if the installation origin trusts enough an application developer. Such developer could get all its packaged applications trusted without too much risk for the users.
The same thing colud be done for hosted application except that it would be recommended to make sure that the developer has strong server security or would not risk any security flaw on their servers.

CSP Policy

The following sub-section assumes that a trusted application can only be a packaged application. This needs to be updated.

The following CSP policy MUST apply to all trusted applications [[!CSP]]:

default-src *; script-src 'self'; object-src 'none'; style-src 'self'

This puts the following restrictions on web pages part of a trusted application:

  • Scripts can only be loaded from the package;
  • Scripts can not use data:-URIs;
  • Inline scripts can not be used;
  • eval() can not be used. Neither can eval-like functions like setTimeout or "new Function". setTimeout can still be used as long as the first argument is a Function object rather than a string;
  • onXXX attributes can't be used in the markup of pages. However, using the associated EventHandler is doable. For example: myElement.onXXX = someFunction;
  • <object>, <embed> and <applet> are fully disabled. In other words, plugins won't work at all. Including flash.
  • CSS can only be loaded from the package. Inline CSS is however allowed.

This does not restrict any of the following:

  • <iframe>s can still point to any URL;
  • Images can still be loaded from anywhere. Including when loaded using an <img> element, when using CSS background images or when using other types of CSS images;
  • Media (audio and video) can still be loaded from anywhere;
  • Network connections can still be opened anywhere using data-centric APIs like XMLHttpRequest or WebSocket.

There is no way for trusted applications to relax this policy.

Application life-cycle

Application states

At any time, an application MUST be in one of the following states: running, paused, terminated.

An application is running when it has been launched by the UA and has not been put in paused. A running application can transition to paused or terminated states.

If a running application transitions to a paused state, the UA MUST fire a simple event named pause on the Application object before switching its state.

If a running application transitions to a terminated state, the UA MUST fire a simple event named terminate on the Application object before shutting down the application.

An application is paused when the UA stops the execution of an application without terminating it. A paused application SHOULD have all its scripts no longer running, such as rendering, parsing, processing media files and any action that requires CPU and memory or would distract the user. A paused application can transition to running or terminated states.

If a paused application transitions to a running state, the UA MUST fire a simple event named resume on the Application object after changing its state.

An application is terminated when the application has been stopped and is no longer loaded in the system. The state of a terminated application can only be changed to running if the application is launched again.

If a terminated application transitions to a running state, the UA MUST fire a simple event named launch on the Application object after the main browsing context is created but before the load and DOMContentLoaded events are fired.

The specification currently assumes that one will save important when paused so there is no terminate event when transitionning from pause to terminate.

Do we have real use cases for launch?
Is firing before load a hard thing to do?

Consequences of visibility

While an application is running, it can be part or fully hidden. The visibility events described in [[!PAGE-VISIBILITY]] MUST be sent when the visibility status of the application changes.

In addition, when the application becomes fully hidden, the UA MAY put the application in a paused state.

DOMRequest interface

The DOMRequest interface is temporarily hosted by this specification. The Runtime and Security Model for Web Applications specificaton doesn't plan to keep that guest for ever, this is why it is currently staying in an appendix.

Use cases

Some methods want to return a value or do an action but can't do it synchronously, most of the time for performance reasons. In that case, most of those methods will use a callback mechanism to inform the caller of the success or the failure of the action.
However, this callback mechanism makes the code barely readable and there is no common pattern used by all API in the Web Platform.
DOMRequest intend to be used instead of those callbacks to make those APIs more developer-friendly and help code readability.

Definition

The DOMRequest interface is intented to be used by asynchronous methods that want to return something after performing an action or simply want to inform the caller that the action is done.
It returned request can also be used to inform that an error happened during the operation.

A DOMRequest has three state. It is whether pending, success or error.
The initial state of a DOMRequest MUST be pending.
If a DOMRequest receives a success message while in the pending state, its state MUST change to success and SHOULD NOT change afterward.
If a DOMRequest receives an error message while in the pending state, its state MUST change to error and SHOULD NOT change afterward.
If a DOMRequest receives a success message or an error message while not in the pending state, the message MUST be ignored.

A success message SHOULD be sent to the DOMRequest when the operation is successfuly terminated. The message MAY contain a value which MUST be used by the result attribute. If the message does not contain a value, null MUST be used instead.

As soon as a success message is received, readyState MUST return done, result MUST return the received value or null as explained above and the object MUST NOT change its state and MUST, therefore, ignore all following success message and error message.
Finally, the UA MUST fire a simple event named success on the object

An error message SHOULD be sent to the DOMRequest when the operation has failed. The message MAY contain a value which MUST be a DOMError object and MUST be used by the error attribute. If the message does not contain a value, the UA SHOULD find the most appropriate DOMError that represents the failure.

As soon as an error message is received, readyState MUST return done, error MUST return the received value the most appropriate error value as explained above and the object MUST NOT change its state and MUST, therefore, ignore all following success message and error message.
Finally, the UA MUST fire a simple event named error on the object.

readonly attribute DOMString readyState
The attribute MUST return pending if the current state is pending. Otherwise, it MUST return done.
readonly attribute any result
The attribute MUST return undefined if the current state is not success. Otherwise, it MUST return the value provided by the success message or null if no value was sent with the message.
readonly attribute DOMError? error
The attribute MUST return null if the current state is not error. Otherwise, it MUST return the value provided by by the error message. If there was no provided value, it SHOULD return the most appropriate DOMError that represents the failure.
[TreatNonCallableAsNull] attribute EventHandler onsuccess
[TreatNonCallableAsNull] attribute EventHandler onerror

Events

The following are the event handlers (and their corresponding event handler event types) that MUST be supported as attributes by the DOMRequest objects:

event handler event handler event type
onerror error
onsuccess success

Acknowledgments

Thanks to the Samsung team, especially 金明(Ming Jin), Janusz Majnert and 송정기(Jungkee Song) for their work on the System Application Runtime: Execution and Security Model specification.

Special thanks to Anant Narayanan for his Web Application Manifest Format and Management APIs that this specification reuse shamlesly and to Jonas Sicking for being awesome, as always.