Testing Viewer Upgrades

Viewers listed in the Third Party Viewer Directory may use the Linden Lab Viewer Version Management system to manage user upgrades.

Before actually posting a version where your users will get it, you should test whether or not upgrading to that version from an earlier version of your viewer works, and whether or not upgrading from that new version to some successor version will work.

Infrastructure

The upgrade query is just an HTTP GET request, and the responses are just XML-encoded LLSD. You can create your own test infrastructure by creating a web service that returns the responses you want for each test. This can be as simple as putting hard-coded responses into the content of a normal HTTP server that returns files, or you could build a CGI or other program to return the responses your test needs.

Update Query Requests

An update query request URL looks like:

https://update.secondlife.com/update/v1.1/Second%20Life%20Release/3.5.1.271395/mac/10.7.5/testok/5a94bdc9a55607a7edc1e26f2cf58b31

or, generically:

https://update.example.org/prefix/v1.1/Viewer+Channel+Name/version-number/platform/platform-version/test-flag/system-unique-id

where:

Viewer Channel Name: your viewer channel name
version-number: the four part version number of the requesting viewer
platform: the platform identifier (in the official viewer, one of: win, mac, lnx)
platform-version: a three part version number for the platform
test-flag: either testok or testno to indicate the value of the WillingToTest setting
system-unique-id: an MD5 hash value constructed to be specific to the requesting system

The easiest way to get the values your viewer will send from any given system is to look in the log file for the request it generates; you can then configure the responses that will be returned for those queries.

Update Query Responses

An update query might get any of three sorts of responses:

HTTP Errors: Any HTTP error response should result in the update query being treated as complete with no update needed, and then retried after a number of seconds specified by the setting UpdaterServiceCheckPeriod.

No Update: A 200 Ok response containing an empty LLSD map means that there is no update available:

<?xml version="1.0"?><llsd><map/></llsd>

Update Available: A 200 Ok response for an update has a map with contents as shown here:

<?xml version="1.0"?>
<llsd>
  <map>
   <key>url</key>
   <string>http://example.org/path-to-installer</string>
   <key>required</key>
   <boolean>0|1</boolean>                <!-- 1 == required, 0 == optional -->
   <key>version</key>
   <string>3.5.1.271402</string>         <!-- new version number -->
   <key>channel</key>
   <string>Viewer Channel Name</string>  <!-- channel name for your new viewer -->
   <key>more_info</key>
   <string>https://example.org/path-to-release-notes</string>
   <key>size</key>
   <integer>size of the installer download in bytes</integer>
   <key>hash</key>
   <string>32 character hex MD5 checksum of installer download</string>
  </map>
</llsd>

Critical Cases To Test

From a previous version, does a required update response result in downloading and installing the new version (or at least offering it, depending on the users upgrade preference)
From the new version, does an HTTP error response result in a retry after UpdaterServiceCheckPeriod seconds
From the new version, does a no-update response result in a retry after UpdaterServiceCheckPeriod seconds
From the new version, does a required update response result in downloading and installing the new version (or at least offering it, depending on the users upgrade preference)

Helpful Settings and Switches

Any setting can be overridden by using the --set setting-name setting-value command line switch.

UpdaterServiceCheckPeriod: defaults to 3600 (an hour) - shortening this makes retry testing much quicker
UpdaterMaximumBandwidth: limits the download speed of the request for the installer. The default is deliberately very slow (so as to prevent a background download from interfering with Second Life performance). When testing, setting this to 10000000 makes downloads go quickly.

Overriding the update service location

At and after version 3.6.4-release, use the command line option:

--update-service https://your-host/your-prefix

where

your-prefix is any path that precedes the v1.1 in the request query URL

Prior to version 3.6.4-release, override the location using the two settings:

UpdaterServiceURL: set to http://hostname for your service
UpdateServicePath: any path elements between the host name and the v1.1 (defaults to /update/)