[Wiki syntax updated by **jumar** - **Gil**, if you've a bit of free time, have a look at the [[wiki:syntax]] page and train yourself on the [[wiki:playground]]...]

====== Updater Overview ======
he WinLibre updater project compliments of Goggle's summer of code and WinLibre. The proposal is an initial proposal. It is not completely compatible with my current thinking and comments from Pierre-Jean

===== Proposal =====
Summer of Code Proposal


Name: Gil Tal
Univercity: UC Davis, California
email: giltalgiltal@hotmail.com 
Sponsor: WinLibre
Project: WinLibre Updater

Requirements: See
http://www.winlibre.com/wiki/doku.php?id=winlibre_dev:proposals_for_the_google_summer_of_code_program 

===== Overview =====


The WinLibre updater should allow reliable and painless update of exisitng
installations. This is a big project with multiple components. The goal is
to provide a useful and functional system that can be integrated as is into 
WinLibre and improved later. I expect the requirements to be refined by
WinLibre as we go along. The architecture and the design emphasize
simplicity, but should not limit future enhancements and extensions. I will 
describre system specification, the flow of the update process, the update
info XML format, the architecture and various components, special concerns
like performance and security and introduce a tentative roadmap. 

=====System Specification (Initial)=====

Client-Server system with a single update server that provides update 
information to clients and multiple download servers. The update server will
handle dependency trees and will be the brain of the server-side. The
download server will be plain HTTP servers that allow access to the 
software. The client will check periodically with the update serve for
updates and notify the user about available updates and allow him to
initiate an update. The server administration tool will allow a WinLibre 
administrator to deploy a new release.

The Update server could be mirrored. 

==== Main Flow ====

  * Admin prepares new release on local machine
  * Admin uploads the release to all download servers 
  * Admin updates the update info file on the update server
  * Client performs periodic check and gets the new update file
  * User sees update notification in system tray
  * User clicks tray icon and launches the update client GUI 
  * Client GUI displays update information (in user's language)
  * User selects some packages and clicks install
  * Update downloads all necessary packages
  * Installer kicks and installs/uninstalls packages.
  * Dependencies must be installed before the packages that depend on them. 
  * Client updates a file with all installed packages to reflect the new state


=== Possible Errors and handling ===
== Bad Update Info file (malformed xml, wrong version numbers, wrong dependencies) ==
   * Check Private/Public Key for ehenced security.
   *  Client should detect and behave as if no update is available
   * Admin should detect and fix 
== Update Server is down ==
   * Check first a known mirror list.
   * Client should detect and behave as if no update is available
   * Admin should detect and fix 
== Download server is down ==
  * Client will try another download server
  * If all servers are down client will abort the update (revert to previous
state?)
== Client-side crash at any stage ==
  * Client will make best effort to continue where it stopped 
  * Client will keep the update process state in a file
== Installation problems ==
  * Client will make best effort depending on policy (uninstall, uninstall
dependencies, reinstall, restart and reinstall etc) 
== Out of disk space (either during download or installation) ==
Check this first  before  download stage : at the selection stage.
  * Client will issue a proper error message and request the user to make some
room 
== Conflict with a program installed outside WinLibre updater ==
  * Try first to detect installed version with known registry keys. 
  * Client will make best effort to detect the problem and alert the user


====Update Info XML Format ====

There is a pair of XML stanzas that the client and the server exchange. The
client sends to the server its current state in regard to installed WinLibre
software. Here is a sample stanza: 
<code xml>
<?xml version="1.0" encoding="UTF-8"?>
<UpdateInfoRequest language="en">
        <Package name="WinLibre.UpdateClient" version="2.1.1" />
        <Package name="P1" version="1.1.1" />
        <Package name="P2" version="1.3.1" />
        <Package name="P3" version="5.1.1" /> 
        <Package name="P4" version="2.1.0" />
</UpdateInfoRequest>
</code>

As you can see it is extremely simple. it is just a list of name and version
of each installed package. The language attribute is important so the server
can send a proper response to the client in its own language.

The response is a little more complicated it contains a list of download 
servers and for each package its path as well as its dependencies. The
client is responsible to install dependencies before installing package that
depends on them.
<code xml>
<?xml version="1.0" encoding="UTF-8"?> 
<UpdateInfoResponse language="en">
        <Servers>
                <Server url="http://www.winlibre.com" />
                <Server url="http://mirror1.winlibre.com" />
                <Server url="http://mirror2.winlibre.com" />
        </Servers>
        <Packages>
                <Package name="WinLibre_UpdateClient" version="0.3.2"
path="/files/WinLibre_UpdateClient_0.3.1_En_.exe">
                        <Dependencies>
                                <Package name="Python" version="2.4.1" path="..." />
                                <Package name="Python" version="2.6.1.0" path="..." />
                        </Dependencies>
                </Package>
                <Package name="P1" version="2.0.0" path="..." >
                        <Dependencies>
                                <Package name="P5" version="1.0.0"  path="..." />
                        </Dependencies>
                </Package>
                <Package name="P1" version="2.0.0" path="..." >
                        <Dependencies>
                                <Package name="newPackage" version="2.0.0"  path="..." />
                        </Dependencies>
                </Package>
        </Packages>
</UpdateInfoResponse> 
</code>
We can take a look at RDF and RSS. 

==== Components ====


== Update Server ==

The update server will handle the incoming requests for update info and
prepare appropriate response for each client depending on its current
software configuration and its language.

== Download Servers ==

Plain web servers that serve the packages. Clients will hit them randomly or
in round robin fashion to provide ad hoc load balancing. Also if a server
goes down the other servers will cover up providing availability. 


== Update Client ==

The update client will have two parts. One part will always run in the 
background and probe the server periodically for updates. When an update is
available it will trigger a flashing tray icon in the system tray. The other
part will be a GUI application that will be launched when the user clicks 
the tray icon. The user will also be able to to launch the update client
manually in order to install/uninstall packages from the current set of
packages. The UpdateClient GUI should probably at some point be integrated 
into the WinLibre control center. There is no point in maitaining multiple
client-side programs

== Installer ==

The installer is an important piece and it will have to integrate with or
extend the existing WinLibre installer that invokes the installers of the 
specific packages. I need more information about the operation of the
existing installer.

Some questions:

1. How does the installer know what program to invoke when installing a
package (setup.exe, install.exe, PackageName_Setup_1.0.0.exe etc)

Should be written in the XML file.



2. How does the installer handle packages that require reboot to complete
their installation. I expect the WinLibre installer to register in the Run 
or RunOnce in the registry, but the installed package will register itself
independently and then   the WinLibre installer will not know when the
installed package is done installing.

The WinLibre installer should wait for every setup to complete : just wait for it's process to die.



== Server Administration Tools ==

These tools should allow the administrator to edit prepare releases, specify 
dependencies and upload packages and metadata to the download servers and
the update server.

==== Performance/Scalability ====

== Update traffic ==

The actual traffic should be measured and/or estimated. I don't predict any 
bottleneck that can't be solved by adding download servers. The load on the
update server shouldn't be too severe. In the remote possibility that it
does turn out to be a bottle neck, it should be easy to cluster it also and 
provide multiple access points to the client (we can always update the
client, remember? :-), plus replicate new releases to multiple update
servers.

== Automatic notification ==

The automatic notification might be an issue if many users are online. 
imagine what happens if all client check for updates at 3:00AM. They will
all get the  notification at the same time and many will start to download
the new  updates. This will create a peak load on the download servers. 
There are several solutions to mitigate this risk such as random delays in
turning the tray notification or random low frequency check for updates
(e.g. no more that once a day at a random hour).


== Client-side performance ==

Since WinLibre potentially installs a large number of packages it may be 
nice to do it in the background in a low priority thread. However, it can't
be completely automatic since most packages require the user to accept their
license.

We probably can preprocess user acceptation and lauch setups silently. 

 ===== Security ====

Security should be taken into account. One scenario is that WinLibre 
suddenly discovers that they inadvertantly released a package with a
security valnerability.
It is crucial to resolve the issue as soon as possible. One way to handle it
is to release a regular update that solves the problem, but since the users 
control the actual installation it may not guarantee the safety of the
users. This is a policy call of course, but here are two technical
solutions:

=== Automatic updates ===

automatic update simply solves the issue ( e.g. installs a patch, or
uninstalls a malicious component)  without user intervention and simply
notifies the user about the action that was taken and why. There are issues
if the rouge program is running and keeping its files open. 

=== Forced updates and or uninstalls ===

The update client will be launched automatically and will require the user
to update or uninstall rouge packages. There are problems here also if the
user doesn't cooperate 

=== Server Authentication ===

Server authentication may be necessary, so the client can verify that it is
really talking to a WinLibre server and no one hijacked it and try to
install some malware on their systems. 


=== Client Authentication ===

Client authentication may be required, so the server can reduce denial of 
service attack by fake clients.

===== Roadmap =====


The roadmap is divided into two phases. Phase 1 is a must have and contains
essential features. Every feature in phase 1 must be completed in order to 
perform the most rudimentary update. Phase 2 contain features that are still
important for solid updater, but can be added later as part of an update.
That's the nice thing about an updater - once it works you can always update 
everything

=== Phase 1===

  * Fully Operational Update Server
  * Manual Update client (No automatic notification)

=== Phase 2===

  * Tray Notification
  * Administration tools
  * Selected features from the security section 

=====  Current Plan =====
===== Schedule =====
None. We'll see how it goes in a true agile programming fashion