Bug 1252215 - [webext] Add Embedded Extensions helper to LegacyExtensionsUtils. r=aswan,kmag

This patch introduces helper for the embedding of a webextension (and new related tests).

The new exported helpers are going to be integrated in the XPIProvider
to provide the Embedded WebExtension to the Legacy Extensions which
have enabled it in their install.rdf

MozReview-Commit-ID: 7M1DRkXjGat

--HG--
extra : rebase_source : 3226a83652b97601d9d4d34693761cfc720735a0

toolkit/components/extensions/Extension.jsm

@@ -1514,6 +1514,11 @@ this.Extension = class extends ExtensionData {
 
       GlobalManager.init(this);
 
+      // The "startup" Management event sent on the extension instance itself
+      // is emitted just before the Management "startup" event,
+      // and it is used to run code that needs to be executed before
+      // any of the "startup" listeners.
+      this.emit("startup", this);
       Management.emit("startup", this);
 
       return this.runManifest(this.manifest);

toolkit/components/extensions/LegacyExtensionsUtils.jsm

@@ -101,4 +101,158 @@ var LegacyExtensionContext = class extends ExtensionContext {
   }
 };
 
-this.LegacyExtensionsUtils = {};
+var EmbeddedExtensionManager;
+
+/**
+ * Instances of this class are used internally by the exported EmbeddedWebExtensionsUtils
+ * to manage the embedded webextension instance and the related LegacyExtensionContext
+ * instance used to exchange messages with it.
+ */
+class EmbeddedExtension {
+  /**
+   * Create a new EmbeddedExtension given the add-on id and the base resource URI of the
+   * container add-on (the webextension resources will be loaded from the "webextension/"
+   * subdir of the base resource URI for the legacy extension add-on).
+   *
+   * @param {Object} containerAddonParams
+   *   An object with the following properties:
+   * @param {string} containerAddonParams.id
+   *   The Add-on id of the Legacy Extension which will contain the embedded webextension.
+   * @param {nsIURI} containerAddonParams.resourceURI
+   *   The nsIURI of the Legacy Extension container add-on.
+   */
+  constructor({id, resourceURI}) {
+    this.addonId = id;
+    this.resourceURI = resourceURI;
+
+    // Setup status flag.
+    this.started = false;
+  }
+
+  /**
+   * Start the embedded webextension.
+   *
+   * @returns {Promise<LegacyContextAPI>} A promise which resolve to the API exposed to the
+   *   legacy context.
+   */
+  startup() {
+    if (this.started) {
+      return Promise.reject(new Error("This embedded extension has already been started"));
+    }
+
+    // Setup the startup promise.
+    this.startupPromise = new Promise((resolve, reject) => {
+      let embeddedExtensionURI = Services.io.newURI("webextension/", null, this.resourceURI);
+
+      // This is the instance of the WebExtension embedded in the hybrid add-on.
+      this.extension = new Extension({
+        id: this.addonId,
+        resourceURI: embeddedExtensionURI,
+      });
+
+      // This callback is register to the "startup" event, emitted by the Extension instance
+      // after the extension manifest.json has been loaded without any errors, but before
+      // starting any of the defined contexts (which give the legacy part a chance to subscribe
+      // runtime.onMessage/onConnect listener before the background page has been loaded).
+      const onBeforeStarted = () => {
+        this.extension.off("startup", onBeforeStarted);
+
+        // Resolve the startup promise and reset the startupError.
+        this.started = true;
+        this.startupPromise = null;
+
+        // Create the legacy extension context, the legacy container addon
+        // needs to use it before the embedded webextension startup,
+        // because it is supposed to be used during the legacy container startup
+        // to subscribe its message listeners (which are supposed to be able to
+        // receive any message that the embedded part can try to send to it
+        // during its startup).
+        this.context = new LegacyExtensionContext(this.extension, {
+          url: this.resourceURI.resolve("/"),
+        });
+
+        // Destroy the LegacyExtensionContext cloneScope when
+        // the embedded webextensions is unloaded.
+        this.extension.callOnClose({
+          close: () => {
+            this.context.unload();
+          },
+        });
+
+        // resolve startupPromise to execute any pending shutdown that has been
+        // chained to it.
+        resolve(this.context.api);
+      };
+
+      this.extension.on("startup", onBeforeStarted);
+
+      // Run ambedded extension startup and catch any error during embedded extension
+      // startup.
+      this.extension.startup().catch((err) => {
+        this.started = false;
+        this.startupPromise = null;
+        this.extension.off("startup", onBeforeStarted);
+
+        reject(err);
+      });
+    });
+
+    return this.startupPromise;
+  }
+
+  /**
+   * Shuts down the embedded webextension.
+   *
+   * @returns {Promise<void>} a promise that is resolved when the shutdown has been done
+   */
+  shutdown() {
+    EmbeddedExtensionManager.untrackEmbeddedExtension(this);
+
+    // If there is a pending startup,  wait to be completed and then shutdown.
+    if (this.startupPromise) {
+      return this.startupPromise.then(() => {
+        this.extension.shutdown();
+      });
+    }
+
+    // Run shutdown now if the embedded webextension has been correctly started
+    if (this.extension && this.started && !this.extension.hasShutdown) {
+      this.extension.shutdown();
+    }
+
+    return Promise.resolve();
+  }
+}
+
+// Keep track on the created EmbeddedExtension instances and destroy
+// them when their container addon is going to be disabled or uninstalled.
+EmbeddedExtensionManager = {
+  // Map of the existent EmbeddedExtensions instances by addon id.
+  embeddedExtensionsByAddonId: new Map(),
+
+  untrackEmbeddedExtension(embeddedExtensionInstance) {
+    // Remove this instance from the tracked embedded extensions
+    let id = embeddedExtensionInstance.addonId;
+    if (this.embeddedExtensionsByAddonId.get(id) == embeddedExtensionInstance) {
+      this.embeddedExtensionsByAddonId.delete(id);
+    }
+  },
+
+  getEmbeddedExtensionFor({id, resourceURI}) {
+    let embeddedExtension = this.embeddedExtensionsByAddonId.get(id);
+
+    if (!embeddedExtension) {
+      embeddedExtension = new EmbeddedExtension({id, resourceURI});
+      // Keep track of the embedded extension instance.
+      this.embeddedExtensionsByAddonId.set(id, embeddedExtension);
+    }
+
+    return embeddedExtension;
+  },
+};
+
+this.LegacyExtensionsUtils = {
+  getEmbeddedExtensionFor: (addon) => {
+    return EmbeddedExtensionManager.getEmbeddedExtensionFor(addon);
+  },
+};

toolkit/components/extensions/test/xpcshell/test_ext_legacy_extension_embedding.js

@@ -0,0 +1,188 @@
+"use strict";
+
+/* globals browser */
+
+Cu.import("resource://gre/modules/LegacyExtensionsUtils.jsm");
+
+// Import EmbeddedExtensionManager to be able to check that the
+// tacked instances are cleared after the embedded extension shutdown.
+const {
+  EmbeddedExtensionManager,
+} = Cu.import("resource://gre/modules/LegacyExtensionsUtils.jsm", {});
+
+/**
+ * This test case ensures that the LegacyExtensionsUtils.EmbeddedExtension:
+ *  - load the embedded webextension resources from a "/webextension/" dir
+ *    inside the XPI.
+ *  - EmbeddedExtension.prototype.api returns an API object which exposes
+ *    a working `runtime.onConnect` event object (e.g. the API can receive a port
+ *    when the embedded webextension is started  and it can exchange messages
+ *    with the background page).
+ *  - EmbeddedExtension.prototype.startup/shutdown methods manage the embedded
+ *    webextension lifecycle as expected.
+ */
+add_task(function* test_embedded_webextension_utils() {
+  function backgroundScript() {
+    let port = browser.runtime.connect();
+
+    port.onMessage.addListener((msg) => {
+      if (msg == "legacy_extension -> webextension") {
+        port.postMessage("webextension -> legacy_extension");
+        port.disconnect();
+      }
+    });
+  }
+
+  const id = "@test.embedded.web.extension";
+
+  // Extensions.generateXPI is used here (and in the other hybrid addons tests in this same
+  // test dir) to be able to generate an xpi with the directory layout that we expect from
+  // an hybrid legacy+webextension addon (where all the embedded webextension resources are
+  // loaded from a 'webextension/' directory).
+  let fakeHybridAddonFile = Extension.generateZipFile({
+    "webextension/manifest.json": {
+      applications: {gecko: {id}},
+      name: "embedded webextension name",
+      manifest_version: 2,
+      version: "1.0",
+      background: {
+        scripts: ["bg.js"],
+      },
+    },
+    "webextension/bg.js": `new ${backgroundScript}`,
+  });
+
+  // Remove the generated xpi file and flush the its jar cache
+  // on cleanup.
+  do_register_cleanup(() => {
+    Services.obs.notifyObservers(fakeHybridAddonFile, "flush-cache-entry", null);
+    fakeHybridAddonFile.remove(false);
+  });
+
+  let fileURI = Services.io.newFileURI(fakeHybridAddonFile);
+  let resourceURI = Services.io.newURI(`jar:${fileURI.spec}!/`, null, null);
+
+  let embeddedExtension = LegacyExtensionsUtils.getEmbeddedExtensionFor({
+    id, resourceURI,
+  });
+
+  ok(embeddedExtension, "Got the embeddedExtension object");
+
+  equal(EmbeddedExtensionManager.embeddedExtensionsByAddonId.size, 1,
+        "Got the expected number of tracked embedded extension instances");
+
+  do_print("waiting embeddedExtension.startup");
+  let embeddedExtensionAPI = yield embeddedExtension.startup();
+  ok(embeddedExtensionAPI, "Got the embeddedExtensionAPI object");
+
+  let waitConnectPort = new Promise(resolve => {
+    let {browser} = embeddedExtensionAPI;
+    browser.runtime.onConnect.addListener(port => {
+      resolve(port);
+    });
+  });
+
+  let port = yield waitConnectPort;
+
+  ok(port, "Got the Port API object");
+
+  let waitPortMessage = new Promise(resolve => {
+    port.onMessage.addListener((msg) => {
+      resolve(msg);
+    });
+  });
+
+  port.postMessage("legacy_extension -> webextension");
+
+  let msg = yield waitPortMessage;
+
+  equal(msg, "webextension -> legacy_extension",
+     "LegacyExtensionContext received the expected message from the webextension");
+
+  let waitForDisconnect = new Promise(resolve => {
+    port.onDisconnect.addListener(resolve);
+  });
+
+  do_print("Wait for the disconnect port event");
+  yield waitForDisconnect;
+  do_print("Got the disconnect port event");
+
+  yield embeddedExtension.shutdown();
+
+  equal(EmbeddedExtensionManager.embeddedExtensionsByAddonId.size, 0,
+        "EmbeddedExtension instances has been untracked from the EmbeddedExtensionManager");
+});
+
+function* createManifestErrorTestCase(id, xpi, expectedError) {
+  // Remove the generated xpi file and flush the its jar cache
+  // on cleanup.
+  do_register_cleanup(() => {
+    Services.obs.notifyObservers(xpi, "flush-cache-entry", null);
+    xpi.remove(false);
+  });
+
+  let fileURI = Services.io.newFileURI(xpi);
+  let resourceURI = Services.io.newURI(`jar:${fileURI.spec}!/`, null, null);
+
+  let embeddedExtension = LegacyExtensionsUtils.getEmbeddedExtensionFor({
+    id, resourceURI,
+  });
+
+  yield Assert.rejects(embeddedExtension.startup(), expectedError,
+                       "embedded extension startup rejected");
+
+  // Shutdown a "never-started" addon with an embedded webextension should not
+  // raise any exception, and if it does this test will fail.
+  yield embeddedExtension.shutdown();
+}
+
+add_task(function* test_startup_error_empty_manifest() {
+  const id = "empty-manifest@test.embedded.web.extension";
+  const files = {
+    "webextension/manifest.json": ``,
+  };
+  const expectedError = "(NS_BASE_STREAM_CLOSED)";
+
+  let fakeHybridAddonFile = Extension.generateZipFile(files);
+
+  yield createManifestErrorTestCase(id, fakeHybridAddonFile, expectedError);
+});
+
+add_task(function* test_startup_error_invalid_json_manifest() {
+  const id = "invalid-json-manifest@test.embedded.web.extension";
+  const files = {
+    "webextension/manifest.json": `{ "name": }`,
+  };
+  const expectedError = "JSON.parse:";
+
+  let fakeHybridAddonFile = Extension.generateZipFile(files);
+
+  yield createManifestErrorTestCase(id, fakeHybridAddonFile, expectedError);
+});
+
+add_task(function* test_startup_error_blocking_validation_errors() {
+  const id = "blocking-manifest-validation-error@test.embedded.web.extension";
+  const files = {
+    "webextension/manifest.json": {
+      name: "embedded webextension name",
+      manifest_version: 2,
+      version: "1.0",
+      background: {
+        scripts: {},
+      },
+    },
+  };
+
+  function expectedError(actual) {
+    if (actual.errors && actual.errors.length == 1 &&
+        actual.errors[0].startsWith("Reading manifest:")) {
+      return true;
+    }
+
+    return false;
+  }
+
+  let fakeHybridAddonFile = Extension.generateZipFile(files);
+
+  yield createManifestErrorTestCase(id, fakeHybridAddonFile, expectedError);
+});

toolkit/components/extensions/test/xpcshell/xpcshell.ini

@@ -55,6 +55,7 @@ skip-if = release_build
 [test_ext_storage.js]
 [test_getAPILevelForWindow.js]
 [test_ext_legacy_extension_context.js]
+[test_ext_legacy_extension_embedding.js]
 [test_locale_converter.js]
 [test_locale_data.js]
 [test_native_messaging.js]