Abstract
This specification defines a process and a document format to allow a user agent to update an installed
widget package with different version of a widget package. A widget cannot update itself; instead, a widget relies on the user agent to manage the update process. A user agent can perform an update over HTTP and from non-HTTP sources (e.g., directly from a device's memory card or hard disk).
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/.
Implementers should be aware that this document is not stable and should not be implemented.
Implementers who are not taking part in the discussions are likely to find the specification
changing out from under them in incompatible ways. Vendors interested in implementing this
document before it eventually reaches the Candidate Recommendation stage should join the
group's public mailing list and take part in the discussions.
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.
This Specification takes into account the recommendations from the Widget
Updates Patent Advisory Group and considering the large set of prior art the PAG found.
This document was published by the Web Applications WG as a Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to [email protected] (subscribe, archives). All feedback is welcome.
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.
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.
3. Definitions
The concepts of a widget package and a configuration document 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 installed widget is a widget package that has been correctly installed
on a user agent. Not every installed widget classifies as an updatable widget (see rule for determining if a widget can be updated).
An updatable widget is an installed widget that meets all the preconditions
defined in this specification that would allow it to be updated.
An update source is the URI referenced by the src attribute of
a update-info element of an update description document.
A potential update is a resource acquired by downloading the update source (i.e., the resource addressed
by the src attribute of a update-info element).
The update process is a multi-step process whereby a user agent compares the
version of a currently installed widget package to the version of a resource available
either on the Web or on local storage.
The version of an installed widget is determined by the version
attribute of the widget element declared by an author in a widget package's configuration
document.
An installed widget is said to be up-to-date if
a user agent determines, via the update-checking strategies, that an installed widget does not need updating.
In order to verify that an installed widget meets the preconditions which deem it an updatable widget, a user agent must apply the rule for determining if a widget can be updated.
The rule for determining if an installed widget can be updated is given by the following algorithm. This rule makes use of values derived in the configuration defaults table (CDT)established in the [WIDGETS] specification.
-
Let widget be an installed widget.
-
In the CDT, if the widget identifier is not null and update href is not null, return true. Otherwise, return false.
Update-Checking Strategies
This document defines two update-checking strategies that a user agent can use to
check if a widget package is up-to-date, as well as the rules that define how user agents
are expected to behave when performing each . The strategies are
as follows:
- Referencing an update description document on the Web.
- Updating from local media.
Update-checking strategy 1 is performed by acquiring and processing an update description document
(UDD) from a URI. An UDD is an XML document in which 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
URI from where the user agent can retrieve the potential update (the update source). It is
expected that user agents will perform updates asynchronously by periodically checking for
changes in either the HTTP response codes for the UDD (e.g. a changed [HTTP11] Etag header or using If-Modified-Since) and by processing the UDD itself.
The timing of periodic checks is an implementation detail left to the discretion of the implementer
(e.g. once a day or once a week).
A push mechanism could be applied as well that pushes a UDD to the user agent as soon as an
update is available.
In the case of update-checking strategy 2, updating from local media, this specification works in
conjunction with the Widget Packaging and Configuration specification [WIDGETS]
to define the rules for how to verify and install a potential update.
4. The update-description Element
The update-description element points, via the href attribute, to an
update description document.
The update-description element is in the http://www.w3.org/ns/widgets namespace
as defined in [WIDGETS].
- Context in which this element may be used:
- As a child of the
widget element defined in the [WIDGETS] specification.
- Content model:
- Empty.
- Occurrences:
- Zero or one.
- Expected children:
- none.
- Localizable via
xml:lang:
- No.
4.1 Attributes
href-
A URI attribute that points to the location of an update description document.
4.2 Usage example
This example shows the expected usage of the update-description element.
<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>
6. Update Description Document (UDD)
An update description document (UDD) is an [XML10] document that has a
update-info element at its root.
The purpose of the UDD is to provide the details about a potential update, including a pointer to HTTP resource that will act as the potential update.
6.3 The update-info Element
The update-info element is intended to provide metadata about the potential update.
In addition, it serves as a container for the other elements; as such, it must be used.
- Context in which this element may be used:
- The root element of an UDD document.
- Content model:
- Zero or more
details elements.
- Occurrences:
- One.
- Expected children:
details.- Localizable via
xml:lang:
- No.
6.3.1 Attributes
version-
A valid version tag that denotes the version number of the potential update.
src-
A valid URI that references a potential update. Over the wire, the potential
update must be labeled with a correct widget media type (i.e.
application/widget).
6.4 The details Element
The details element represents a human-readable description of
what differentiates this potential update from other versions.
- Context in which this element can be used:
- Inside a
update-info element.
- Content model:
- Anything.
- Occurrences:
- Zero or more.
- Expected children:
- Anything.
- Localizable via
xml:lang:
- Yes.
7. UDD Acquisition
A user agent must support the capability to acquire a UDD over [HTTP] and over [HTTPS].
Response Codes
8. UDD Processing
@@ TBW @@
A user agent must assume the following defaults prior to processing a UDD:
Update Defaults
| Variable |
Type |
Default value |
Description |
| update-source |
URI |
null |
|
| version-tag |
DOMString |
null |
|
| details |
DOMString |
null |
|
8.1 Processing model
The term in error, typically used of 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. Typically this will involve ignoring
the erroneous nodes, meaning the UA must, for the purposes of processing, act as if those
nodes were absent from the UDD.
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 the following the specification.
TBW: need to integrate i18n model.
-
Let doc be the result of parsing the acquired UDD as a [DOM-LEVEL-3-CORE]
Document using a [XML-NAMES]-aware parser. If the document is not well-formed [XML10],
then threat this as an invalid UDD.
-
Let root element be the documentElement of doc.
-
If the root element is not a
update-info element in the widget namespace,
then treat this UDD as an invalid.
-
If the root element is a
update-info element:
-
If the
version attribute was used, and it is a valid version-tag,
then let version-tag be the value of version.
- If no
version attribute was used, or the value was in error, treat this as an invalid UDD.
-
If the
src attribute was used, and it is a valid URI, then let
update-source be the value of src.
- If no
src attribute was used, or the value was in error, treat this as an invalid UDD.
- For any child element of the root element:
-
-
If the child element is a
details element:
-
If this is not the first
details element, then the element is in error
and must be ignored.
- TBW: Need to extract the text content ignoring any invalid nodes not defined in this document.
- Otherwise it must be ignored.
8.2 Dealing with invalid Update Description Documents
TBW
8.3 Potential update verification and installation process
@@ TBW @@
9. Security concerns
It is conceivable that an UDD 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.
TBW: downgrade attacks.
A. Acknowledgements
The editors would like to think the following contributors (in no particular order):
Raine Hillebrand.