Adding upstream version 115.7.0esr.upstream/115.7.0esrupstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 294 insertions, 0 deletions

diff --git a/toolkit/components/featuregates/FeatureGateImplementation.sys.mjs b/toolkit/components/featuregates/FeatureGateImplementation.sys.mjs
new file mode 100644
index 0000000000..e54ac139cb
--- /dev/null
+++ b/toolkit/components/featuregates/FeatureGateImplementation.sys.mjs
@@ -0,0 +1,294 @@
+/* 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/. */
+
+const lazy = {};
+ChromeUtils.defineESModuleGetters(lazy, {
+  FeatureGate: "resource://featuregates/FeatureGate.sys.mjs",
+});
+
+/** An individual feature gate that can be re-used for more advanced usage. */
+export class FeatureGateImplementation {
+  // Note that the following comment is *not* a jsdoc. Making it a jsdoc would
+  // makes sphinx-js expose it to users. This feature shouldn't be used by
+  // users, and so should not be in the docs. Sphinx-js does not respect the
+  // @private marker on a constructor (https://github.com/erikrose/sphinx-js/issues/71).
+  /*
+   * This constructor should only be used directly in tests.
+   * ``FeatureGate.fromId`` should be used instead for most cases.
+   *
+   * @private
+   *
+   * @param {object} definition Description of the feature gate.
+   * @param {string} definition.id
+   * @param {string} definition.title
+   * @param {string} definition.description
+   * @param {string} definition.descriptionLinks
+   * @param {boolean} definition.restartRequired
+   * @param {string} definition.type
+   * @param {string} definition.preference
+   * @param {string} definition.defaultValue
+   * @param {object} definition.isPublic
+   * @param {object} definition.bugNumbers
+   */
+  constructor(definition) {
+    this._definition = definition;
+    this._observers = new Set();
+  }
+
+  // The below are all getters instead of direct access to make it easy to provide JSDocs.
+
+  /**
+   * A short string used to refer to this feature in code.
+   * @type string
+   */
+  get id() {
+    return this._definition.id;
+  }
+
+  /**
+   * A Fluent string ID that will resolve to some text to identify this feature to users.
+   * @type string
+   */
+  get title() {
+    return this._definition.title;
+  }
+
+  /**
+   * A Fluent string ID that will resolve to a longer string to show to users that explains the feature.
+   * @type string
+   */
+  get description() {
+    return this._definition.description;
+  }
+
+  get descriptionLinks() {
+    return this._definition.descriptionLinks;
+  }
+
+  /**
+   * Whether this feature requires a browser restart to take effect after toggling.
+   * @type boolean
+   */
+  get restartRequired() {
+    return this._definition.restartRequired;
+  }
+
+  /**
+   * The type of feature. Currently only booleans are supported. This may be
+   * richer than JS types in the future, such as enum values.
+   * @type string
+   */
+  get type() {
+    return this._definition.type;
+  }
+
+  /**
+   * The name of the preference that stores the value of this feature.
+   *
+   * This preference should not be read directly, but instead its values should
+   * be accessed via FeatureGate#addObserver or FeatureGate#getValue. This
+   * property is provided for backwards compatibility.
+   *
+   * @type string
+   */
+  get preference() {
+    return this._definition.preference;
+  }
+
+  /**
+   * The default value for the feature gate for this update channel.
+   * @type boolean
+   */
+  get defaultValue() {
+    return this._definition.defaultValue;
+  }
+
+  /** The default value before any targeting evaluation. */
+  get defaultValueOriginalValue() {
+    // This will probably be overwritten by the loader, but if not provide a default.
+    return (
+      this._definition.defaultValueOriginalValue || {
+        default: this._definition.defaultValue,
+      }
+    );
+  }
+
+  /**
+   * Check what the default value of this feature gate would be on another
+   * browser with different facts, such as on another platform.
+   *
+   * @param {Map} extraFacts
+   *   A `Map` of hypothetical facts to consider, such as {'windows': true} to
+   *   check what the value of this feature would be on Windows.
+   */
+  defaultValueWith(extraFacts) {
+    return lazy.FeatureGate.evaluateTargetedValue(
+      this.defaultValueOriginalValue,
+      extraFacts,
+      { mergeFactsWithDefault: true }
+    );
+  }
+
+  /**
+   * If this feature should be exposed to users in an advanced settings panel
+   * for this build of Firefox.
+   *
+   * @type boolean
+   */
+  get isPublic() {
+    return this._definition.isPublic;
+  }
+
+  /** The isPublic before any targeting evaluation. */
+  get isPublicOriginalValue() {
+    // This will probably be overwritten by the loader, but if not provide a default.
+    return (
+      this._definition.isPublicOriginalValue || {
+        default: this._definition.isPublic,
+      }
+    );
+  }
+
+  /**
+   * Check if this feature is available on another browser with different
+   * facts, such as on another platform.
+   *
+   * @param {Map} extraFacts
+   *   A `Map` of hypothetical facts to consider, such as {'windows': true} to
+   *   check if this feature would be available on Windows.
+   */
+  isPublicWith(extraFacts) {
+    return lazy.FeatureGate.evaluateTargetedValue(
+      this.isPublicOriginalValue,
+      extraFacts,
+      { mergeFactsWithDefault: true }
+    );
+  }
+
+  /**
+   * Bug numbers associated with this feature.
+   * @type Array<number>
+   */
+  get bugNumbers() {
+    return this._definition.bugNumbers;
+  }
+
+  /**
+   * Get the current value of this feature gate. Implementors should avoid
+   * storing the result to avoid missing changes to the feature's value.
+   * Consider using :func:`addObserver` if it is necessary to store the value
+   * of the feature.
+   *
+   * @async
+   * @returns {Promise<boolean>} A promise for the value associated with this feature.
+   */
+  // Note that this is async for potential future use of a storage backend besides preferences.
+  async getValue() {
+    return Services.prefs.getBoolPref(this.preference, this.defaultValue);
+  }
+
+  /**
+   * An alias of `getValue` for boolean typed feature gates.
+   *
+   * @async
+   * @returns {Promise<boolean>} A promise for the value associated with this feature.
+   * @throws {Error} If the feature is not a boolean.
+   */
+  // Note that this is async for potential future use of a storage backend besides preferences.
+  async isEnabled() {
+    if (this.type !== "boolean") {
+      throw new Error(
+        `Tried to call isEnabled when type is not boolean (it is ${this.type})`
+      );
+    }
+    return this.getValue();
+  }
+
+  /**
+   * Add an observer for changes to this feature. When the observer is added,
+   * `onChange` will asynchronously be called with the current value of the
+   * preference. If the feature is of type boolean and currently enabled,
+   * `onEnable` will additionally be called.
+   *
+   * @param {object} observer Functions to be called when the feature changes.
+   *        All observer functions are optional.
+   * @param {Function()} [observer.onEnable] Called when the feature becomes enabled.
+   * @param {Function()} [observer.onDisable] Called when the feature becomes disabled.
+   * @param {Function(newValue: boolean)} [observer.onChange] Called when the
+   *        feature's state changes to any value. The new value will be passed to the
+   *        function.
+   * @returns {Promise<boolean>} The current value of the feature.
+   */
+  async addObserver(observer) {
+    if (this._observers.size === 0) {
+      Services.prefs.addObserver(this.preference, this);
+    }
+
+    this._observers.add(observer);
+
+    if (this.type === "boolean" && (await this.isEnabled())) {
+      this._callObserverMethod(observer, "onEnable");
+    }
+    // onDisable should not be called, because features should be assumed
+    // disabled until onEnabled is called for the first time.
+
+    return this.getValue();
+  }
+
+  /**
+   * Remove an observer of changes from this feature
+   * @param observer The observer that was passed to addObserver to remove.
+   */
+  removeObserver(observer) {
+    this._observers.delete(observer);
+    if (this._observers.size === 0) {
+      Services.prefs.removeObserver(this.preference, this);
+    }
+  }
+
+  /**
+   * Removes all observers from this instance of the feature gate.
+   */
+  removeAllObservers() {
+    if (this._observers.size > 0) {
+      this._observers.clear();
+      Services.prefs.removeObserver(this.preference, this);
+    }
+  }
+
+  _callObserverMethod(observer, method, ...args) {
+    if (method in observer) {
+      try {
+        observer[method](...args);
+      } catch (err) {
+        console.error(err);
+      }
+    }
+  }
+
+  /**
+   * Observes changes to the preference storing the enabled state of the
+   * feature. The observer is dynamically added only when observer have been
+   * added.
+   * @private
+   */
+  async observe(aSubject, aTopic, aData) {
+    if (aTopic === "nsPref:changed" && aData === this.preference) {
+      const value = await this.getValue();
+      for (const observer of this._observers) {
+        this._callObserverMethod(observer, "onChange", value);
+
+        if (value) {
+          this._callObserverMethod(observer, "onEnable");
+        } else {
+          this._callObserverMethod(observer, "onDisable");
+        }
+      }
+    } else {
+      console.error(
+        new Error(`Unexpected event observed: ${aSubject}, ${aTopic}, ${aData}`)
+      );
+    }
+  }
+}