diff options
Diffstat (limited to 'toolkit/mozapps/webextensions/docs/SystemAddons.rst')
| -rw-r--r-- | toolkit/mozapps/webextensions/docs/SystemAddons.rst | 224 |
1 files changed, 0 insertions, 224 deletions
diff --git a/toolkit/mozapps/webextensions/docs/SystemAddons.rst b/toolkit/mozapps/webextensions/docs/SystemAddons.rst deleted file mode 100644 index 5f724e9ef..000000000 --- a/toolkit/mozapps/webextensions/docs/SystemAddons.rst +++ /dev/null @@ -1,224 +0,0 @@ -Firefox System Add-on Update Protocol -===================================== -This document describes the protocol that Firefox uses when retrieving updates -for System Add-ons from the automatic update service (AUS, currently `Balrog`_), -and the expected behavior of Firefox based on the updater service's response. - -.. _Balrog: https://wiki.mozilla.org/Balrog - -System Add-ons --------------- -System add-ons: - -* Are add-ons that ship with Firefox, are hidden from the UI, and cannot be - disabled -* Can be updated by Firefox depending on the AUS response to Firefox's update - request -* Are stored in two locations: - - * The **default** set ships with Firefox and is stored in the application - directory. - * The **update** set is stored in the user’s profile directory. If an add-on - is both in the update and default set, the update version gets precedence. - -Update Request --------------- -To determine what updates to install, Firefox makes an HTTP **GET** request to -AUS once a day via a URL of the form:: - - https://aus5.mozilla.org/update/3/SystemAddons/%VERSION%/%BUILD_ID%/%BUILD_TARGET%/%LOCALE%/%CHANNEL%/%OS_VERSION%/%DISTRIBUTION%/%DISTRIBUTION_VERSION%/update.xml - -The path segments surrounded by ``%`` symbols are variable fields that Firefox -fills in with information about itself and the environment it's running in: - -``VERSION`` - Firefox version number -``BUILD_ID`` - Build ID -``BUILD_TARGET`` - Build target -``LOCALE`` - Build locale -``CHANNEL`` - Update channel -``OS_VERSION`` - OS Version -``DISTRIBUTION`` - Firefox Distribution -``DISTRIBUTION_VERSION`` - Firefox Distribution version - -Update Response ---------------- -AUS should respond with an XML document that looks something like this: - -.. code-block:: xml - - <?xml version="1.0"?> - <updates> - <addons> - <addon id="flyweb@mozilla.org" URL="https://ftp.mozilla.org/pub/system-addons/flyweb/flyweb@mozilla.org-1.0.xpi" hashFunction="sha512" hashValue="abcdef123" size="1234" version="1.0"/> - <addon id="pocket@mozilla.org" URL="https://ftp.mozilla.org/pub/system-addons/pocket/pocket@mozilla.org-1.0.xpi" hashFunction="sha512" hashValue="abcdef123" size="1234" version="1.0"/> - </addons> - </updates> - -* The root element is ``<updates>``, used for all updater responses. -* The only child of ``<updates>`` is ``<addons>``, which represents a list of - system add-ons to update. -* Within ``<addons>`` are several ``<addon>`` tags, each one corresponding to a - system add-on to update. - -``<addon>`` tags **must** have the following attributes: - -``id`` - The extension ID -``URL`` - URL to a signed XPI of the specified add-on version to download -``hashFunction`` - Identifier of the hash function used to generate the hashValue attribute. -``hashValue`` - Hash of the XPI file linked from the URL attribute, calculated using the function specified in the hashValue attribute. -``size`` - Size (in bytes) of the XPI file linked from the URL attribute. -``version`` - Version number of the add-on - -Update Behavior ---------------- -After receiving the update response, Firefox modifies the **update** add-ons -according to the following algorithm: - -1. If the ``<addons>`` tag is empty (``<addons></addons>``) in the response, - **remove all system add-on updates**. -2. If no add-ons were specified in the response (i.e. the ``<addons>`` tag - is not present), do nothing and finish. -3. If the **update** add-on set is equal to the set of add-ons specified in the - update response, do nothing and finish. -4. If the set of **default** add-ons is equal to the set of add-ons specified in - the update response, remove all the **update** add-ons and finish. -5. Download each add-on specified in the update response and store them in the - "downloaded add-on set". A failed download **must** abort the entire system - add-on update. -6. Validate the downloaded add-ons. The following **must** be true for all - downloaded add-ons, or the update process is aborted: - - a. The ID and version of the downloaded add-on must match the specified ID or - version in the update response. - b. The hash provided in the update response must match the downloaded add-on - file. - c. The downloaded add-on file size must match the size given in the update - response. - d. The add-on must be compatible with Firefox (i.e. it must not be for a - different application, such as Thunderbird). - e. The add-on must be packed (i.e. be an XPI file). - f. The add-on must be restartless. - g. The add-on must be signed by the system add-on root certificate. - -6. Once all downloaded add-ons are validated, install them into the profile - directory as part of the **update** set. - -Notes on the update process: - -* Add-ons are considered "equal" if they have the same ID and version number. - -Examples --------- -The follow section describes common situations that we have or expect to run -into and how the protocol described above handles them. - -For simplicity, unless otherwise specified, all examples assume that there are -two system add-ons in existence: **FlyWeb** and **Pocket**. - -Basic -~~~~~ -A user has Firefox 45, which shipped with FlyWeb 1.0 and Pocket 1.0. We want to -update users to FlyWeb 2.0. AUS sends out the following update response: - -.. code-block:: xml - - <updates> - <addons> - <addon id="flyweb@mozilla.org" URL="https://ftp.mozilla.org/pub/system-addons/flyweb/flyweb@mozilla.org-2.0.xpi" hashFunction="sha512" hashValue="abcdef123" size="1234" version="2.0"/> - <addon id="pocket@mozilla.org" URL="https://ftp.mozilla.org/pub/system-addons/pocket/pocket@mozilla.org-1.0.xpi" hashFunction="sha512" hashValue="abcdef123" size="1234" version="1.0"/> - </addons> - </updates> - -Firefox will download FlyWeb 2.0 and Pocket 1.0 and store them in the profile directory. - -Missing Add-on -~~~~~~~~~~~~~~ -A user has Firefox 45, which shipped with FlyWeb 1.0 and Pocket 1.0. We want to -update users to FlyWeb 2.0, but accidentally forget to specify Pocket in the -update response. AUS sends out the following: - -.. code-block:: xml - - <updates> - <addons> - <addon id="flyweb@mozilla.org" URL="https://ftp.mozilla.org/pub/system-addons/flyweb/flyweb@mozilla.org-2.0.xpi" hashFunction="sha512" hashValue="abcdef123" size="1234" version="2.0"/> - </addons> - </updates> - -Firefox will download FlyWeb 2.0 and store it in the profile directory. Pocket -1.0 from the **default** location will be used. - -Remove all system add-on updates -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -A response from AUS with an empty add-on set will *remove all system add-on -updates*: - -.. code-block:: xml - - <updates> - <addons></addons> - </updates> - -Rollout -~~~~~~~ -A user has Firefox 45, which shipped with FlyWeb 1.0 and Pocket 1.0. We want to -rollout FlyWeb 2.0 at a 10% sample rate. 10% of the time, AUS sends out: - -.. code-block:: xml - - <updates> - <addons> - <addon id="flyweb@mozilla.org" URL="https://ftp.mozilla.org/pub/system-addons/flyweb/flyweb@mozilla.org-2.0.xpi" hashFunction="sha512" hashValue="abcdef123" size="1234" version="2.0"/> - <addon id="pocket@mozilla.org" URL="https://ftp.mozilla.org/pub/system-addons/pocket/pocket@mozilla.org-1.0.xpi" hashFunction="sha512" hashValue="abcdef123" size="1234" version="1.0"/> - </addons> - </updates> - -With this response, Firefox will download Pocket 1.0 and FlyWeb 2.0 and install -them into the profile directory. - -The other 90% of the time, AUS sends out an empty response: - -.. code-block:: xml - - <updates></updates> - -With the empty response, Firefox will not make any changes. This means users who -haven’t seen the 10% update response will stay on FlyWeb 1.0, and users who have -seen it will stay on FlyWeb 2.0. - -Once we’re happy with the rollout and want to switch to 100%, AUS will send the -10% update response to 100% of users, upgrading everyone to FlyWeb 2.0. - -Rollback -~~~~~~~~ -This example continues from the “Rollout” example. If, during the 10% rollout, -we find a major issue with FlyWeb 2.0, we want to roll all users back to FlyWeb 1.0. -AUS sends out the following: - -.. code-block:: xml - - <updates> - <addons> - <addon id="flyweb@mozilla.org" URL="https://ftp.mozilla.org/pub/system-addons/flyweb/flyweb@mozilla.org-1.0.xpi" hashFunction="sha512" hashValue="abcdef123" size="1234" version="1.0"/> - <addon id="pocket@mozilla.org" URL="https://ftp.mozilla.org/pub/system-addons/pocket/pocket@mozilla.org-1.0.xpi" hashFunction="sha512" hashValue="abcdef123" size="1234" version="1.0"/> - </addons> - </updates> - -For users who have updated, Firefox will download FlyWeb 1.0 and Pocket 1.0 and -install them into the profile directory. For users that haven’t yet updated, -Firefox will see that the **default** add-on set matches the set in the update -ping and clear the **update** add-on set. |