This specification defines a process and a document format to allow a user agent to update an installed widget package with a different version of a widget package. A widget cannot automatically update itself; instead, a widget relies on the user agent to manage the update process.
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/.
User agents that wish to extend this specification in any way are encouraged to discuss their extensions on a public forum, such as public-webapps so their extensions can be considered for standardization.
This specification is part of the Widgets Family of Specifications.
To exit the Candidate Recommendation (CR) stage, the following criteria must have been met:
There will be at least two interoperable implementations passing all approved test cases in the test suite for this specification. An implementation is to be available (i.e. for download), shipping (i.e. not private), and not experimental (i.e. intended for a wide audience). The working group will decide when the test suite is of sufficient quality to test interoperability and will produce an implementation report (hosted together with the test suite).
A minimum of three months of the CR stage will have elapsed (i.e. not until after 24 August 2012). This is to ensure that enough time is given for any remaining major errors to be caught. The CR period will be extended if implementations are slow to appear.
This document was published by the Web Applications Working Group as a Candidate Recommendation. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to firstname.lastname@example.org (subscribe, archives). W3C publishes a Candidate Recommendation to indicate that the document is believed to be stable and to encourage implementation by the developer community. This Candidate Recommendation is expected to advance to Proposed Recommendation no earlier than 24 June 2012. All feedback is welcome.
Publication as a Candidate Recommendation 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.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This section is non-normative.
There are a multitude of reasons why an author of might want to update an application including:
Sometimes an author may even want to revert back to a previous version of an application, if it is found that a newly deployed version of a application contains issues or vulnerabilities.
To facilitate the process of updating widgets, this specification introduces an XML element, called an update description source, that is included as an Extension to the Configuration Document of a widget package. This specification also introduces a new XML vocabulary, called an update description document. The update description source provides an author with a means to point to an update description document.
An update description document is metadata about a widget update including:
a means to describe the purpose of the update.
a link to where the potential update widget package can be retrieved from.
If a user agent determines, after Acquiring an Update Description Document and during Processing an Update Description Document, that two widget packages are not the same version, and if the user consents, the user agent will attempt to replace the currently installed widget with the potential update. Updates are designed to retain any locally stored data, so to protect end-users from losing data that a widget may have stored at runtime.
This specification also discusses the Security Considerations that are left up to the discretion of implementers.
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words must, must not, required, should, should not, recommended, may, and optional in this specification are to be interpreted as described in [RFC2119].
This specification defines conformance requirements for a single class of product: user agents.
The concepts of a widget package, a configuration document, a valid IRI, a version attribute, user agent locales, global attributes and the definition that one element is allowed per language are defined in the [WIDGETS] specification.
A user agent is an implementation of this specification that also implements the [WIDGETS] specification and its dependencies.
An update description source is the URI pointing to the location of an update description document.
A potential update is a resource acquired via HTTP (from an update source) or from local media.
Note: This specification does not define the means or format of a failure notification, which is left up to implementers.
update-description element is in the
http://www.w3.org/ns/widgets namespace as defined in
widgetelement defined in the [WIDGETS] specification.
This example shows the expected usage of the
<widget xmlns ="http://www.w3.org/ns/widgets" id ="http://example.com/my-widget" version="1.0"> <update-description href="http//example.com/update?widget=my-widget&version=1.0"/> </widget>
update-descriptionelements in the Configuration Document
The user agent must process a configuration document [WIDGETS] containing an
update-description element according
to the rule for processing the update-description element.
The rule for processing the update-description element is defined as follows.
|Variable||Type||Default Value||Overridden in||Description|
The URI for where the widget's update description document can be downloaded, corresponding to the
update-descriptionelement, then the user agent must ignore this element and its descendants.
update-descriptionelement and the href attribute is used, and it is a valid IRI [WIDGETS], then let update href be the value of the href attribute. Otherwise, this element is in error and the user agent must ignore this element.
Within an update description document an author declares, amongst other things, what's new or different in the potential update, the version that the widget will be updated to, and the update source from where the user agent can retrieve the potential update.
In order for a user agent to retrieve and process an update description document, an author will initially declare a
valid IRI [WIDGETS] for the
update-description element in the installed configuration document (e.g.
<update-description href="https://example.com/myWidget/updates"/>), as defined in the Update Extensions to Widget Configuration Documents section.
Below is an example of a typical update description document.
<update-info xmlns = "http://www.w3.org/ns/widgets" src = "https://w.example.com/2.1/RC/app.wgt" version = "RC2.1"> <details xml:lang="en-us"> Now supporting X, Y and Z features! </details> <details xml:lang="ar" dir="rtl"> دعم الآن سين وصاد وعين ملامح </details> <details xml:lang="pt"> Agora com suporte a X, Y e Z recursos! </details> </update-info>
update-info element is intended to provide metadata about the potential update. In addition, it serves as
a container for the other elements.
The example below shows how the
update-info element can be used.
<update-info xmlns="http://www.w3.org/ns/widgets" src="http://sometld/somewidget_0_3_BETA.wgt" version="BETA 0.3"> </update-info>
details element represents a human-readable description of what differentiates this potential update from
The example below shows how the
details element can be used.
<update-info xmlns="http://www.w3.org/ns/widgets" src="http://foo.com/widget.wgt" version="1.3.1"> <details> This update tries to make 2010 a little bit less like 1984. </details> <details xml:lang="pt"> Esta atualização tenta fazer de 2010 um pouco menos parecido com 1984. </details> <details xml:lang="ar" dir="rtl"> يحاول هذا التحديث لجعل 2010 أقل قليلا مثل 1984. </details> </update-info>
It is expected that user agents will perform a widget update process asynchronously and periodically check for any available updates. The timing of any widget update process is an implementation detail left to the discretion of the implementer (e.g. once a day or once a week).
The user agent must send the last known ETag response value, if available, in an If-None-Match header.
The user agent must send an Accept-Language header representing the widget's locale.
As data is received, the user agent will then act as follows.
The user agent must ignore any Cache-Control or Pragma header with a value of
On receiving HTTP response codes in the 2xx range, other than HTTP 200 OK, the user agent must terminate the widget update. They are, however, likely to indicate an error has occurred somewhere and may cause the user agent to emit a warning.
On receiving HTTP 301 Moved Permanently, 302 Found, 303 See Other, and 307 Temporary Redirect responses, the user agent must reconnect using the new server specified URL instead of the previously specified URL.
The user agent should treated HTTP 305 Use Proxy, 401 Unauthorized, and 407 Proxy Authentication Required responses transparently as for any other subresource.
Any other HTTP response code not listed here, and any network error that prevents the HTTP connection from being established in the first place (e.g. DNS errors), must cause the user agent to terminate the widget update.
A user agent must process an update description document according to the rule for processing an update description document.
The following processing model is written with more concern for clarity over efficiency. As such, a user agent can optimize the processing model so long as the end result is indistinguishable from the result that would be obtained by following the specification.
The term in error, typically used on an element or attribute, means that the element, attribute, or other construct does not conform to the rules of this specification. Rules for exactly how a user agent needs to treat the erroneous construct are always given when the term is used.
The rule for processing an update description document is defined as follows:
Documentusing a [XML-NAMES]-aware parser. If the document is not well-formed [XML10], then treat this as an invalid update description document.
update-infoelement in the widget namespace, then treat this update description document as an invalid update description document.
versionattribute was used, and it is a valid version attribute [WIDGETS], then let version-tag be the value of
versionattribute was used, or the value was in error, treat this as an invalid update description document.
detailselement, in document order, that matches a language range in the user agent locales; or, if no
detailselement in the document matches the user agent locales and this is not the first element; then the element is in error and must be ignored.
When a user agent is to remove the installed widget it is to disable the current incumbent widget, if it exists. The user agent may also physically remove the incumbent widget from the device. The user agent may emit a notification warning that the incumbent widget is being removed.
When a user agent is to terminate the widget update it is to terminate the current widget update process. The user agent may emit a failure notification warning that the widget update has been terminated.
The rule for verifying a widget update enables a user agent to match and verify a potential update - acquired via HTTP or from local media - with an installed widget package [WIDGETS] and is defined as follows:
Because an update description document is not self-contained, it is conceivable that the update model could be subject to a man-in-the-middle attack, as with any unencrypted requests performed over [HTTP11]. For this reason, it is recommended that, for widgets that have not been digitally signed, updates are always performed over [HTTP-TLS].
Another means of protection is for authors to always digitally sign their widget resources. During an update, the user agent will then validate the signature before installation, ensuring that a widget resource's identity and integrity was maintained over the network.
Without the availability of a digitally signed installed widget, it is extremely easy to overwrite a widget resource with another (potentially malicious) widget resource. Therefore it is recommended that a user agent only allow updates to a signed installed widget or to a non-signed installed widget only from a potential update obtained via its authoritative update URI.
This section is non-normative.
The editors would like to thank the following contributors (in alphabetical order): Art Barstow, Raine Hillebrand, Hari G Kumar, Scott Wilson.
Special thanks to Robin Berjon for co-editing an early version of this specification.
Thanks to the W3C WebApps WG, and to participants on the email@example.com listserv.