Bug 1509003 - Document advanced Remote Settings options r=glasserc
authorMathieu Leplatre <mathieu@mozilla.com>
Mon, 26 Nov 2018 21:39:24 +0000
changeset 504566 03ab2d6df92839d1f27014742ea7bab26b7778ed
parent 504565 d3b46f3a0306aaf4dda9f47fb4f02bc66f3ba562
child 504567 7c145e1dbd4d482a066e4b199db7e167737475e8
push id10290
push userffxbld-merge
push dateMon, 03 Dec 2018 16:23:23 +0000
treeherdermozilla-beta@700bed2445e6 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersglasserc
bugs1509003
milestone65.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 1509003 - Document advanced Remote Settings options r=glasserc Documents options that will be used by the Normandy client Differential Revision: https://phabricator.services.mozilla.com/D12631
services/common/docs/RemoteSettings.rst
services/settings/remote-settings.js
--- a/services/common/docs/RemoteSettings.rst
+++ b/services/common/docs/RemoteSettings.rst
@@ -79,16 +79,17 @@ When an entry has a file attached to it,
 
 .. code-block:: js
 
     const data = await RemoteSettings("a-key").get();
 
     data.filter(d => d.attachment)
         .forEach(async ({ attachment: { url, filename, size } }) => {
           if (size < OS.freeDiskSpace) {
+            // Planned feature, see Bug 1501214
             await downloadLocally(url, filename);
           }
         });
 
 Initial data
 ------------
 
 For newly created user profiles, the list of entries returned by the ``.get()`` method will be empty until the first synchronization happens.
@@ -119,31 +120,49 @@ Uptake Telemetry
 Some :ref:`uptake telemetry <telemetry/collection/uptake>` is collected in order to monitor how remote settings are propagated.
 
 It is submitted to a single :ref:`keyed histogram <histogram-type-keyed>` whose id is ``UPTAKE_REMOTE_CONTENT_RESULT_1`` and the keys are prefixed with ``main/`` (eg. ``main/a-key`` in the above example).
 
 
 Create new remote settings
 ==========================
 
-Staff members can create new kinds of remote settings, following `this documentation <https://mana.mozilla.org/wiki/pages/viewpage.action?pageId=66655528>`_.
+Staff members can create new kinds of remote settings, following `this documentation <https://remote-settings.readthedocs.io/en/latest/getting-started.html>`_.
 
 It basically consists in:
 
 #. Choosing a key (eg. ``search-providers``)
 #. Assigning collaborators to editors and reviewers groups
 #. (*optional*) Define a JSONSchema to validate entries
 #. (*optional*) Allow attachments on entries
 
 And once done:
 
 #. Create, modify or delete entries and let reviewers approve the changes
 #. Wait for Firefox to pick-up the changes for your settings key
 
 
+Advanced Options
+================
+
+``filterFunc``: custom filtering function
+-----------------------------------------
+
+By default, the entries returned by ``.get()`` are filtered based on the JEXL expression result from the ``filter_expression`` field. The ``filterFunc`` option allows to execute a custom filter (async) function, that should return the record (modified or not) if kept or a falsy value if filtered out.
+
+.. code-block:: javascript
+
+    RemoteSettings("a-collection", {
+      filterFunc: (record, environment) => {
+        const { enabled, ...entry } = record;
+        return enabled ? entry : null;
+      }
+    });
+
+
 Debugging and testing
 =====================
 
 Trigger a synchronization manually
 ----------------------------------
 
 The synchronization of every known remote settings clients can be triggered manually with ``pollChanges()``:
 
@@ -197,29 +216,25 @@ The local data can be flushed with ``cle
     await collection.clear()
 
 For further documentation in collection API, checkout the `kinto.js library <https://kintojs.readthedocs.io/>`_, which is in charge of the IndexedDB interactions behind-the-scenes.
 
 
 Inspect local data
 ------------------
 
-The internal IndexedDBs of remote settings can be accessed via the Storage Inspector in the `browser toolbox <https://developer.mozilla.org/en-US/docs/Tools/Browser_Toolbox>`_.
+The internal IndexedDB of Remote Settings can be accessed via the Storage Inspector in the `browser toolbox <https://developer.mozilla.org/en-US/docs/Tools/Browser_Toolbox>`_.
 
-For example, the local data of the ``"key"`` collection can be accessed in the ``main/key`` IndexedDB store at *Browser Toolbox* > *Storage* > *IndexedDB* > *chrome* > *main/key*.
+For example, the local data of the ``"key"`` collection can be accessed in the ``remote-settings`` database at *Browser Toolbox* > *Storage* > *IndexedDB* > *chrome*, in the ``records`` store.
 
 
-\about:remotesettings
----------------------
+Remote Settings Dev Tools
+-------------------------
 
-The ``about:remotesettings`` extension provides some tooling to inspect synchronization statuses, to change the remote server or to switch to *preview* mode in order to sign-off pending changes. `More information on the dedicated repository <https://github.com/leplatrem/aboutremotesettings>`_.
-
-.. note::
-
-    With `Bug 1406036 <https://bugzilla.mozilla.org/show_bug.cgi?id=1406036>`_, about:remotesettings will be available natively.
+The Remote Settings Dev Tools extension provides some tooling to inspect synchronization statuses, to change the remote server or to switch to *preview* mode in order to sign-off pending changes. `More information on the dedicated repository <https://github.com/mozilla/remote-settings-devtools>`_.
 
 
 About blocklists
 ----------------
 
 Addons, certificates, plugins, and GFX blocklists were the first use-cases of remote settings, and thus have some specificities.
 
 For example, they leverage advanced customization options (bucket, content-signature certificate, target filtering etc.), and in order to be able to inspect and manipulate their data, the client instances must first be explicitly initialized.
--- a/services/settings/remote-settings.js
+++ b/services/settings/remote-settings.js
@@ -41,16 +41,19 @@ const PREF_SETTINGS_DEFAULT_SIGNER     =
 const PREF_SETTINGS_VERIFY_SIGNATURE   = "verify_signature";
 const PREF_SETTINGS_SERVER_BACKOFF     = "server.backoff";
 const PREF_SETTINGS_CHANGES_PATH       = "changes.path";
 const PREF_SETTINGS_LAST_UPDATE        = "last_update_seconds";
 const PREF_SETTINGS_LAST_ETAG          = "last_etag";
 const PREF_SETTINGS_CLOCK_SKEW_SECONDS = "clock_skew_seconds";
 const PREF_SETTINGS_LOAD_DUMP          = "load_dump";
 
+// IndexedDB name.
+const DB_NAME = "remote-settings";
+
 // Telemetry update source identifier.
 const TELEMETRY_HISTOGRAM_KEY = "settings-changes-monitoring";
 
 const INVALID_SIGNATURE = "Invalid content signature";
 const MISSING_SIGNATURE = "Missing signature";
 
 XPCOMUtils.defineLazyGetter(this, "gPrefs", () => {
   return Services.prefs.getBranch(PREF_SETTINGS_BRANCH);
@@ -277,17 +280,17 @@ class RemoteSettingsClient {
    * Open the underlying Kinto collection, using the appropriate adapter and
    * options.
    */
   async openCollection() {
     if (!this._kinto) {
       this._kinto = new Kinto({
         bucket: this.bucketName,
         adapter: Kinto.adapters.IDB,
-        adapterOptions: { dbName: "remote-settings", migrateOldData: false },
+        adapterOptions: { dbName: DB_NAME, migrateOldData: false },
       });
     }
     const options = {
       localFields: this.localFields,
       bucket: this.bucketName,
     };
     return this._kinto.collection(this.collectionName, options);
   }