This specification defines a model and a document format to allow a user agent to locate and replace a widget package with a new or different version of a widget package. The updates model is designed to allow user agents to update widget packages over HTTP. Updates for from non-HTTP sources (e.g., directly from a device's memory card or hard disk) are beyond the scope of this specifications.

Implementers should be aware that this document is not stable. 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 defines conformance criteria that apply to a single product: user agents.

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.

Precondition for Updating a Widget Package

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.

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.

1. Let widget be an installed widget.

2. 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 ca 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:

1. Referencing an update description document on the Web.
2. 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.

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.

  <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&amp;version=1.0"/>

  </widget>
        

Processing update-description elements in the Configuration Document

A user agent MUST add the following to the Table of Configuration Defaults [[!WIDGETS]] as part of Step 7.

If this is not the first update-description element, then the user agent MUST ignore this element and its descendants.

If this is the first update-description element and the href attribute is used, and it is a valid uri, then let update href be the value of the href attribute.

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.

          <update-info xmlns="http://www.w3.org/ns/widgets"
                       src="http://evil-fruit-company.com/sins/unoriginal-patent.wgt"
                       version="1.1">
            <details>
              This update tries to make 2010 a little bit more like "1984".
            </details>
          </update-info>
        

UDD Acquisition

A user agent MUST support the capability to acquire a UDD over [HTTP] and over [HTTPS].

Aquisition of a UDD

Response Codes

UDD Processing

@@ TBW @@

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.