toolkit/modules/Integration.sys.mjs

   1 /* This Source Code Form is subject to the terms of the Mozilla Public
   2  * License, v. 2.0. If a copy of the MPL was not distributed with this
   3  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   4
   5 /*
   6  * Implements low-overhead integration between components of the application.
   7  * This may have different uses depending on the component, including:
   8  *
   9  * - Providing product-specific implementations registered at startup.
  10  * - Using alternative implementations during unit tests.
  11  * - Allowing add-ons to change specific behaviors.
  12  *
  13  * Components may define one or more integration points, each defined by a
  14  * root integration object whose properties and methods are the public interface
  15  * and default implementation of the integration point. For example:
  16  *
  17  *   const DownloadIntegration = {
  18  *     getTemporaryDirectory() {
  19  *       return "/tmp/";
  20  *     },
  21  *
  22  *     getTemporaryFile(name) {
  23  *       return this.getTemporaryDirectory() + name;
  24  *     },
  25  *   };
  26  *
  27  * Other parts of the application may register overrides for some or all of the
  28  * defined properties and methods. The component defining the integration point
  29  * does not have to be loaded at this stage, because the name of the integration
  30  * point is the only information required. For example, if the integration point
  31  * is called "downloads":
  32  *
  33  *   Integration.downloads.register(base => ({
  34  *     getTemporaryDirectory() {
  35  *       return base.getTemporaryDirectory.call(this) + "subdir/";
  36  *     },
  37  *   }));
  38  *
  39  * When the component defining the integration point needs to call a method on
  40  * the integration object, instead of using it directly the component would use
  41  * the "getCombined" method to retrieve an object that includes all overrides.
  42  * For example:
  43  *
  44  *   let combined = Integration.downloads.getCombined(DownloadIntegration);
  45  *   Assert.is(combined.getTemporaryFile("file"), "/tmp/subdir/file");
  46  *
  47  * Overrides can be registered at startup or at any later time, so each call to
  48  * "getCombined" may return a different object. The simplest way to create a
  49  * reference to the combined object that stays updated to the latest version is
  50  * to define the root object in a JSM and use the "defineModuleGetter" method.
  51  *
  52  * *** Registration ***
  53  *
  54  * Since the interface is not declared formally, the registrations can happen
  55  * at startup without loading the component, so they do not affect performance.
  56  *
  57  * Hovever, this module does not provide a startup registry, this means that the
  58  * code that registers and implements the override must be loaded at startup.
  59  *
  60  * If performance for the override code is a concern, you can take advantage of
  61  * the fact that the function used to create the override is called lazily, and
  62  * include only a stub loader for the final code in an existing startup module.
  63  *
  64  * The registration of overrides should be repeated for each process where the
  65  * relevant integration methods will be called.
  66  *
  67  * *** Accessing base methods and properties ***
  68  *
  69  * Overrides are included in the prototype chain of the combined object in the
  70  * same order they were registered, where the first is closest to the root.
  71  *
  72  * When defining overrides, you do not need to manipulate the prototype chain of
  73  * the objects you create, because their properties and methods are moved to a
  74  * new object with the correct prototype. If you do, however, you can call base
  75  * properties and methods using the "super" keyword. For example:
  76  *
  77  *   Integration.downloads.register(base => {
  78  *     let newObject = {
  79  *       getTemporaryDirectory() {
  80  *         return super.getTemporaryDirectory() + "subdir/";
  81  *       },
  82  *     };
  83  *     Object.setPrototypeOf(newObject, base);
  84  *     return newObject;
  85  *   });
  86  *
  87  * *** State handling ***
  88  *
  89  * Storing state directly on the combined integration object using the "this"
  90  * reference is not recommended. When a new integration is registered, own
  91  * properties stored on the old combined object are copied to the new combined
  92  * object using a shallow copy, but the "this" reference for new invocations
  93  * of the methods will be different.
  94  *
  95  * If the root object defines a property that always points to the same object,
  96  * for example a "state" property, you can safely use it across registrations.
  97  *
  98  * Integration overrides provided by restartless add-ons should not use the
  99  * "this" reference to store state, to avoid conflicts with other add-ons.
 100  *
 101  * *** Interaction with XPCOM ***
 102  *
 103  * Providing the combined object as an argument to any XPCOM method will
 104  * generate a console error message, and will throw an exception where possible.
 105  * For example, you cannot register observers directly on the combined object.
 106  * This helps preventing mistakes due to the fact that the combined object
 107  * reference changes when new integration overrides are registered.
 108  */
 109
 110 /**
 111  * Maps integration point names to IntegrationPoint objects.
 112  */
 113 const gIntegrationPoints = new Map();
 114
 115 /**
 116  * This Proxy object creates IntegrationPoint objects using their name as key.
 117  * The objects will be the same for the duration of the process. For example:
 118  *
 119  *   Integration.downloads.register(...);
 120  *   Integration["addon-provided-integration"].register(...);
 121  */
 122 export var Integration = new Proxy(
 123   {},
 124   {
 125     get(target, name) {
 126       let integrationPoint = gIntegrationPoints.get(name);
 127       if (!integrationPoint) {
 128         integrationPoint = new IntegrationPoint();
 129         gIntegrationPoints.set(name, integrationPoint);
 130       }
 131       return integrationPoint;
 132     },
 133   }
 134 );
 135
 136 /**
 137  * Individual integration point for which overrides can be registered.
 138  */
 139 var IntegrationPoint = function () {
 140   this._overrideFns = new Set();
 141   this._combined = {
 142     // eslint-disable-next-line mozilla/use-chromeutils-generateqi
 143     QueryInterface() {
 144       let ex = new Components.Exception(
 145         "Integration objects should not be used with XPCOM because" +
 146           " they change when new overrides are registered.",
 147         Cr.NS_ERROR_NO_INTERFACE
 148       );
 149       console.error(ex);
 150       throw ex;
 151     },
 152   };
 153 };
 154
 155 IntegrationPoint.prototype = {
 156   /**
 157    * Ordered set of registered functions defining integration overrides.
 158    */
 159   _overrideFns: null,
 160
 161   /**
 162    * Combined integration object. When this reference changes, properties
 163    * defined directly on this object are copied to the new object.
 164    *
 165    * Initially, the only property of this object is a "QueryInterface" method
 166    * that throws an exception, to prevent misuse as a permanent XPCOM listener.
 167    */
 168   _combined: null,
 169
 170   /**
 171    * Indicates whether the integration object is current based on the list of
 172    * registered integration overrides.
 173    */
 174   _combinedIsCurrent: false,
 175
 176   /**
 177    * Registers new overrides for the integration methods. For example:
 178    *
 179    *   Integration.nameOfIntegrationPoint.register(base => ({
 180    *     asyncMethod: Task.async(function* () {
 181    *       return yield base.asyncMethod.apply(this, arguments);
 182    *     }),
 183    *   }));
 184    *
 185    * @param overrideFn
 186    *        Function returning an object defining the methods that should be
 187    *        overridden. Its only parameter is an object that contains the base
 188    *        implementation of all the available methods.
 189    *
 190    * @note The override function is called every time the list of registered
 191    *       override functions changes. Thus, it should not have any side
 192    *       effects or do any other initialization.
 193    */
 194   register(overrideFn) {
 195     this._overrideFns.add(overrideFn);
 196     this._combinedIsCurrent = false;
 197   },
 198
 199   /**
 200    * Removes a previously registered integration override.
 201    *
 202    * Overrides don't usually need to be unregistered, unless they are added by a
 203    * restartless add-on, in which case they should be unregistered when the
 204    * add-on is disabled or uninstalled.
 205    *
 206    * @param overrideFn
 207    *        This must be the same function object passed to "register".
 208    */
 209   unregister(overrideFn) {
 210     this._overrideFns.delete(overrideFn);
 211     this._combinedIsCurrent = false;
 212   },
 213
 214   /**
 215    * Retrieves the dynamically generated object implementing the integration
 216    * methods. Platform-specific code and add-ons can override methods of this
 217    * object using the "register" method.
 218    */
 219   getCombined(root) {
 220     if (this._combinedIsCurrent) {
 221       return this._combined;
 222     }
 223
 224     // In addition to enumerating all the registered integration overrides in
 225     // order, we want to keep any state that was previously stored in the
 226     // combined object using the "this" reference in integration methods.
 227     let overrideFnArray = [...this._overrideFns, () => this._combined];
 228
 229     let combined = root;
 230     for (let overrideFn of overrideFnArray) {
 231       try {
 232         // Obtain a new set of methods from the next override function in the
 233         // list, specifying the current combined object as the base argument.
 234         let override = overrideFn(combined);
 235
 236         // Retrieve a list of property descriptors from the returned object, and
 237         // use them to build a new combined object whose prototype points to the
 238         // previous combined object.
 239         let descriptors = {};
 240         for (let name of Object.getOwnPropertyNames(override)) {
 241           descriptors[name] = Object.getOwnPropertyDescriptor(override, name);
 242         }
 243         combined = Object.create(combined, descriptors);
 244       } catch (ex) {
 245         // Any error will result in the current override being skipped.
 246         console.error(ex);
 247       }
 248     }
 249
 250     this._combinedIsCurrent = true;
 251     return (this._combined = combined);
 252   },
 253
 254   /**
 255    * Defines a getter to retrieve the dynamically generated object implementing
 256    * the integration methods, loading the root implementation lazily from the
 257    * specified sys.mjs module. For example:
 258    *
 259    *   Integration.test.defineModuleGetter(this, "TestIntegration",
 260    *                    "resource://testing-common/TestIntegration.sys.mjs");
 261    *
 262    * @param targetObject
 263    *        The object on which the lazy getter will be defined.
 264    * @param name
 265    *        The name of the getter to define.
 266    * @param moduleUrl
 267    *        The URL used to obtain the module.
 268    */
 269   defineESModuleGetter(targetObject, name, moduleUrl) {
 270     let moduleHolder = {};
 271     // eslint-disable-next-line mozilla/lazy-getter-object-name
 272     ChromeUtils.defineESModuleGetters(moduleHolder, {
 273       [name]: moduleUrl,
 274     });
 275     Object.defineProperty(targetObject, name, {
 276       get: () => this.getCombined(moduleHolder[name]),
 277       configurable: true,
 278       enumerable: true,
 279     });
 280   },
 281 };