path: root/toolkit/modules/Integration.jsm

/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

/*
 * Implements low-overhead integration between components of the application.
 * This may have different uses depending on the component, including:
 *
 * - Providing product-specific implementations registered at startup.
 * - Using alternative implementations during unit tests.
 * - Allowing add-ons to change specific behaviors.
 *
 * Components may define one or more integration points, each defined by a
 * root integration object whose properties and methods are the public interface
 * and default implementation of the integration point. For example:
 *
 *   const DownloadIntegration = {
 *     getTemporaryDirectory() {
 *       return "/tmp/";
 *     },
 *
 *     getTemporaryFile(name) {
 *       return this.getTemporaryDirectory() + name;
 *     },
 *   };
 *
 * Other parts of the application may register overrides for some or all of the
 * defined properties and methods. The component defining the integration point
 * does not have to be loaded at this stage, because the name of the integration
 * point is the only information required. For example, if the integration point
 * is called "downloads":
 *
 *   Integration.downloads.register(base => ({
 *     getTemporaryDirectory() {
 *       return base.getTemporaryDirectory.call(this) + "subdir/";
 *     },
 *   }));
 *
 * When the component defining the integration point needs to call a method on
 * the integration object, instead of using it directly the component would use
 * the "getCombined" method to retrieve an object that includes all overrides.
 * For example:
 *
 *   let combined = Integration.downloads.getCombined(DownloadIntegration);
 *   Assert.is(combined.getTemporaryFile("file"), "/tmp/subdir/file");
 *
 * Overrides can be registered at startup or at any later time, so each call to
 * "getCombined" may return a different object. The simplest way to create a
 * reference to the combined object that stays updated to the latest version is
 * to define the root object in a JSM and use the "defineModuleGetter" method.
 *
 * *** Registration ***
 *
 * Since the interface is not declared formally, the registrations can happen
 * at startup without loading the component, so they do not affect performance.
 *
 * Hovever, this module does not provide a startup registry, this means that the
 * code that registers and implements the override must be loaded at startup.
 *
 * If performance for the override code is a concern, you can take advantage of
 * the fact that the function used to create the override is called lazily, and
 * include only a stub loader for the final code in an existing startup module.
 *
 * The registration of overrides should be repeated for each process where the
 * relevant integration methods will be called.
 *
 * *** Accessing base methods and properties ***
 *
 * Overrides are included in the prototype chain of the combined object in the
 * same order they were registered, where the first is closest to the root.
 *
 * When defining overrides, you do not need to set the "__proto__" property of
 * the objects you create, because their properties and methods are moved to a
 * new object with the correct prototype. If you do, however, you can call base
 * properties and methods using the "super" keyword. For example:
 *
 *   Integration.downloads.register(base => ({
 *     __proto__: base,
 *     getTemporaryDirectory() {
 *       return super.getTemporaryDirectory() + "subdir/";
 *     },
 *   }));
 *
 * *** State handling ***
 *
 * Storing state directly on the combined integration object using the "this"
 * reference is not recommended. When a new integration is registered, own
 * properties stored on the old combined object are copied to the new combined
 * object using a shallow copy, but the "this" reference for new invocations
 * of the methods will be different.
 *
 * If the root object defines a property that always points to the same object,
 * for example a "state" property, you can safely use it across registrations.
 *
 * Integration overrides provided by restartless add-ons should not use the
 * "this" reference to store state, to avoid conflicts with other add-ons.
 *
 * *** Interaction with XPCOM ***
 *
 * Providing the combined object as an argument to any XPCOM method will
 * generate a console error message, and will throw an exception where possible.
 * For example, you cannot register observers directly on the combined object.
 * This helps preventing mistakes due to the fact that the combined object
 * reference changes when new integration overrides are registered.
 */

"use strict";

this.EXPORTED_SYMBOLS = [
  "Integration",
];

const { classes: Cc, interfaces: Ci, utils: Cu, results: Cr } = Components;

Cu.import("resource://gre/modules/XPCOMUtils.jsm");

/**
 * Maps integration point names to IntegrationPoint objects.
 */
const gIntegrationPoints = new Map();

/**
 * This Proxy object creates IntegrationPoint objects using their name as key.
 * The objects will be the same for the duration of the process. For example:
 *
 *   Integration.downloads.register(...);
 *   Integration["addon-provided-integration"].register(...);
 */
this.Integration = new Proxy({}, {
  get(target, name) {
    let integrationPoint = gIntegrationPoints.get(name);
    if (!integrationPoint) {
      integrationPoint = new IntegrationPoint();
      gIntegrationPoints.set(name, integrationPoint);
    }
    return integrationPoint;
  },
});

/**
 * Individual integration point for which overrides can be registered.
 */
this.IntegrationPoint = function () {
  this._overrideFns = new Set();
  this._combined = {
    QueryInterface: function() {
      let ex = new Components.Exception(
                   "Integration objects should not be used with XPCOM because" +
                   " they change when new overrides are registered.",
                   Cr.NS_ERROR_NO_INTERFACE);
      Cu.reportError(ex);
      throw ex;
    },
  };
}

this.IntegrationPoint.prototype = {
  /**
   * Ordered set of registered functions defining integration overrides.
   */
  _overrideFns: null,

  /**
   * Combined integration object. When this reference changes, properties
   * defined directly on this object are copied to the new object.
   *
   * Initially, the only property of this object is a "QueryInterface" method
   * that throws an exception, to prevent misuse as a permanent XPCOM listener.
   */
  _combined: null,

  /**
   * Indicates whether the integration object is current based on the list of
   * registered integration overrides.
   */
  _combinedIsCurrent: false,

  /**
   * Registers new overrides for the integration methods. For example:
   *
   *   Integration.nameOfIntegrationPoint.register(base => ({
   *     asyncMethod: Task.async(function* () {
   *       return yield base.asyncMethod.apply(this, arguments);
   *     }),
   *   }));
   *
   * @param overrideFn
   *        Function returning an object defining the methods that should be
   *        overridden. Its only parameter is an object that contains the base
   *        implementation of all the available methods.
   *
   * @note The override function is called every time the list of registered
   *       override functions changes. Thus, it should not have any side
   *       effects or do any other initialization.
   */
  register(overrideFn) {
    this._overrideFns.add(overrideFn);
    this._combinedIsCurrent = false;
  },

  /**
   * Removes a previously registered integration override.
   *
   * Overrides don't usually need to be unregistered, unless they are added by a
   * restartless add-on, in which case they should be unregistered when the
   * add-on is disabled or uninstalled.
   *
   * @param overrideFn
   *        This must be the same function object passed to "register".
   */
  unregister(overrideFn) {
    this._overrideFns.delete(overrideFn);
    this._combinedIsCurrent = false;
  },

  /**
   * Retrieves the dynamically generated object implementing the integration
   * methods. Platform-specific code and add-ons can override methods of this
   * object using the "register" method.
   */
  getCombined(root) {
    if (this._combinedIsCurrent) {
      return this._combined;
    }

    // In addition to enumerating all the registered integration overrides in
    // order, we want to keep any state that was previously stored in the
    // combined object using the "this" reference in integration methods.
    let overrideFnArray = [...this._overrideFns, () => this._combined];

    let combined = root;
    for (let overrideFn of overrideFnArray) {
      try {
        // Obtain a new set of methods from the next override function in the
        // list, specifying the current combined object as the base argument.
        let override = overrideFn.call(null, combined);

        // Retrieve a list of property descriptors from the returned object, and
        // use them to build a new combined object whose prototype points to the
        // previous combined object.
        let descriptors = {};
        for (let name of Object.getOwnPropertyNames(override)) {
          descriptors[name] = Object.getOwnPropertyDescriptor(override, name);
        }
        combined = Object.create(combined, descriptors);
      } catch (ex) {
        // Any error will result in the current override being skipped.
        Cu.reportError(ex);
      }
    }

    this._combinedIsCurrent = true;
    return this._combined = combined;
  },

  /**
   * Defines a getter to retrieve the dynamically generated object implementing
   * the integration methods, loading the root implementation lazily from the
   * specified JSM module. For example:
   *
   *   Integration.test.defineModuleGetter(this, "TestIntegration",
   *                    "resource://testing-common/TestIntegration.jsm");
   *
   * @param targetObject
   *        The object on which the lazy getter will be defined.
   * @param name
   *        The name of the getter to define.
   * @param moduleUrl
   *        The URL used to obtain the module.
   * @param symbol [optional]
   *        The name of the symbol exported by the module. This can be omitted
   *        if the name of the exported symbol is equal to the getter name.
   */
  defineModuleGetter(targetObject, name, moduleUrl, symbol) {
    let moduleHolder = {};
    XPCOMUtils.defineLazyModuleGetter(moduleHolder, name, moduleUrl, symbol);
    Object.defineProperty(targetObject, name, {
      get: () => this.getCombined(moduleHolder[name]),
      configurable: true,
      enumerable: true,
    });
  },
};