summaryrefslogtreecommitdiffstats
path: root/toolkit/mozapps/webextensions/docs/SystemAddons.rst
diff options
context:
space:
mode:
authorMatt A. Tobin <email@mattatobin.com>2018-06-26 16:09:08 -0400
committerMatt A. Tobin <email@mattatobin.com>2018-06-26 16:09:08 -0400
commiteda567b364a06e9e63efb865a6b1c73f1cb5232e (patch)
tree912ab15d877f733318e2c0394713bca33b830547 /toolkit/mozapps/webextensions/docs/SystemAddons.rst
parent80eb356d57fc310cdf812cae63de30d6e56c1788 (diff)
downloadUXP-eda567b364a06e9e63efb865a6b1c73f1cb5232e.tar
UXP-eda567b364a06e9e63efb865a6b1c73f1cb5232e.tar.gz
UXP-eda567b364a06e9e63efb865a6b1c73f1cb5232e.tar.lz
UXP-eda567b364a06e9e63efb865a6b1c73f1cb5232e.tar.xz
UXP-eda567b364a06e9e63efb865a6b1c73f1cb5232e.zip
[AllAM] Remove Mozilla Tests
Diffstat (limited to 'toolkit/mozapps/webextensions/docs/SystemAddons.rst')
-rw-r--r--toolkit/mozapps/webextensions/docs/SystemAddons.rst224
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.