gecko-dev/toolkit/components/nimbus/lib/PrefFlipsFeature.sys.mjs

/* 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, {
  NimbusFeatures: "resource://nimbus/ExperimentAPI.sys.mjs",
  PrefUtils: "resource://normandy/lib/PrefUtils.sys.mjs",
});

const FEATURE_ID = "prefFlips";
export const REASON_PREFFLIPS_FAILED = "prefFlips-failed";

export class PrefFlipsFeature {
  #initialized;
  #updating;

  static get FEATURE_ID() {
    return FEATURE_ID;
  }

  constructor({ manager }) {
    this.manager = manager;
    this._prefs = new Map();

    this.#initialized = false;
    this.#updating = false;
  }

  onFeatureUpdate() {
    if (this.#updating) {
      return;
    }

    this.#updating = true;

    const activeEnrollment =
      this.manager.store.getExperimentForFeature(PrefFlipsFeature.FEATURE_ID) ??
      this.manager.store.getRolloutForFeature(PrefFlipsFeature.FEATURE_ID);

    const prefs = lazy.NimbusFeatures[FEATURE_ID].getVariable("prefs") ?? {};

    try {
      for (const [pref, details] of this._prefs.entries()) {
        if (Object.hasOwn(prefs, pref)) {
          // The pref may have changed.
          const newDetails = prefs[pref];

          if (
            newDetails.branch !== details.branch ||
            newDetails.value !== details.value
          ) {
            this._updatePref({
              pref,
              branch: newDetails.branch,
              value: newDetails.value,
              slug: activeEnrollment.slug,
            });
          }
        } else {
          // The pref is no longer controlled by us.
          this._unregisterPref(pref);
        }
      }
    } catch (e) {
      if (e instanceof PrefFlipsFailedError) {
        this.#updating = false;

        this._unenrollForFailure(activeEnrollment, e.pref);
        return;
      }
    }

    try {
      for (const [pref, { branch, value }] of Object.entries(prefs)) {
        const known = this._prefs.get(pref);
        if (known) {
          // We have already processed this pref.
          continue;
        }

        const setPref = this.manager._prefs.get(pref);
        if (setPref) {
          const toUnenroll = Array.from(setPref.slugs.values()).map(slug =>
            this.manager.store.get(slug)
          );

          if (toUnenroll.length === 2 && !toUnenroll[0].isRollout) {
            toUnenroll.reverse();
          }

          for (const enrollment of toUnenroll) {
            this.manager._unenroll(enrollment, {
              reason: "prefFlips-conflict",
              conflictingSlug: activeEnrollment.slug,
            });
          }
        }

        this._registerPref({
          pref,
          branch,
          value,
          originalValue: lazy.PrefUtils.getPref(pref, { branch }),
          slug: activeEnrollment.slug,
        });
      }
    } catch (e) {
      this.#updating = false;

      this._unenrollForFailure(activeEnrollment, e.pref);
      return;
    }

    if (activeEnrollment) {
      // If this is new enrollment, we need to cache the original values of prefs
      // so they can be restored.
      if (!Object.hasOwn(activeEnrollment, "prefFlips")) {
        activeEnrollment.prefFlips = {};
      }

      activeEnrollment.prefFlips.originalValues = Object.fromEntries(
        Array.from(this._prefs.entries(), ([pref, { originalValue }]) => [
          pref,
          originalValue,
        ])
      );
    }

    this.#updating = false;
  }

  /**
   * Intialize the prefFlips feature.
   *
   * This will re-hydrate `this._prefs` from the active enrollment (if any) and
   * register any necessary pref observers.
   *
   * onFeatureUpdate will be called for any future feature changes.
   */
  init() {
    if (this.#initialized) {
      return;
    }

    const activeEnrollment =
      this.manager.store.getExperimentForFeature(FEATURE_ID) ??
      this.manager.store.getRolloutForFeature(FEATURE_ID);

    if (activeEnrollment?.prefFlips?.originalValues) {
      const featureValue = activeEnrollment.branch.features.find(
        fc => fc.featureId === FEATURE_ID
      ).value;
      try {
        for (const [pref, { branch, value }] of Object.entries(
          featureValue.prefs
        )) {
          this._registerPref({
            pref,
            branch,
            value,
            originalValue: activeEnrollment.prefFlips.originalValues[pref],
            slug: activeEnrollment.slug,
          });
        }
      } catch (e) {
        if (e instanceof PrefFlipsFailedError) {
          this._unenrollForFailure(activeEnrollment, e.pref);
          return;
        }
      }
    }

    lazy.NimbusFeatures.prefFlips.onUpdate((...args) =>
      this.onFeatureUpdate(...args)
    );

    this.#initialized = true;
  }

  _registerPref({ pref, branch, value, originalValue, slug }) {
    const observer = (_aSubject, _aTopic, aData) => {
      // This observer will be called for changes to `name` as well as any
      // other pref that begins with `name.`, so we have to filter to
      // exactly the pref we care about.
      if (aData === pref) {
        this._onPrefChanged(pref);
      }
    };

    // If we *just* unenrolled a setPref experiment for this pref on the default
    // branch, the pref will only be correctly restored if the pref had a value
    // on the default branch. Otherwise, it will be left as-is until restart.
    // This may result in us computing an incorrect originalValue, but (a) we
    // couldn't correct the problem even if we recorded the correct (i.e., null)
    // value and (b) the issue will resolve itself at next startup. This is
    // consistent with how setPref experiments work.
    const entry = {
      branch,
      originalValue,
      value: value ?? null,
      observer,
      slug,
    };

    try {
      lazy.PrefUtils.setPref(pref, value ?? null, { branch });
    } catch (e) {
      throw new PrefFlipsFailedError(pref);
    }

    Services.prefs.addObserver(pref, observer);
    this._prefs.set(pref, entry);
  }

  _updatePref({ pref, branch, value, slug }) {
    const entry = this._prefs.get(pref);
    if (!entry) {
      return;
    }

    Services.prefs.removeObserver(pref, entry.observer);

    let originalValue = entry.originalValue;
    if (entry.branch !== branch) {
      // Restore the value on the previous branch.
      //
      // Because we were able to set the pref, it must have the same type as the
      // originalValue, so this will also succeed.
      lazy.PrefUtils.setPref(pref, entry.originalValue, {
        branch: entry.branch,
      });

      originalValue = lazy.PrefUtils.getPref(pref, { branch });
    }

    Object.assign(entry, {
      branch,
      value,
      originalValue,
      slug,
    });

    try {
      lazy.PrefUtils.setPref(pref, value, { branch });
    } catch (e) {
      throw new PrefFlipsFailedError(pref);
    }
    Services.prefs.addObserver(pref, entry.observer);
  }

  _unregisterPref(pref) {
    const entry = this._prefs.get(pref);
    if (!entry) {
      return;
    }

    this._prefs.delete(pref);
    Services.prefs.removeObserver(pref, entry.observer);

    const { originalValue, branch } = entry;
    lazy.PrefUtils.setPref(pref, originalValue, { branch });
  }

  _onPrefChanged(pref) {
    if (this.#updating) {
      return;
    }

    if (this.manager._prefs.get(pref)?.enrollmentChanging) {
      return;
    }

    this.#updating = true;

    const entry = this._prefs.get(pref);
    if (!entry) {
      return;
    }

    this._prefs.delete(pref);
    Services.prefs.removeObserver(pref, entry.observer);

    const changedPref = {
      name: pref,
      branch: PrefFlipsFeature.determinePrefChangeBranch(
        pref,
        entry.branch,
        entry.value
      ),
    };

    // If there is both an experiment and a rollout that would both control the
    // same pref, we unenroll both because if we only unenrolled the experiment,
    // the rollout would clobber the pref change that just happened.
    const toUnenroll = this.manager.store.getAll().filter(enrollment => {
      if (!enrollment.active || !enrollment.featureIds.includes(FEATURE_ID)) {
        return false;
      }

      const featureValue = enrollment.branch.features.find(
        featureConfig => featureConfig.featureId === FEATURE_ID
      ).value;
      return Object.hasOwn(featureValue.prefs, pref);
    });

    // We have to restore every *other* pref controlled by these enrollments.
    const toRestore = new Set(
      toUnenroll.flatMap(enrollment =>
        Object.keys(
          enrollment.branch.features.find(
            featureConfig => featureConfig.featureId === FEATURE_ID
          ).value.prefs
        )
      )
    );
    toRestore.delete(pref);

    for (const prefToRestore of toRestore) {
      this._unregisterPref(prefToRestore);
    }

    // Unenrollment doesn't matter here like it does in ExperimentManager's
    // managed prefs because we've already restored prefs before unenrollment.
    for (const enrollment of toUnenroll) {
      this.manager._unenroll(enrollment, {
        reason: "changed-pref",
        changedPref,
      });
    }

    this.#updating = false;

    // If we've caused unenrollments, we need to recompute state.
    this.onFeatureUpdate();
  }

  static determinePrefChangeBranch(pref, expectedBranch, expectedValue) {
    // We want to know what branch was changed so we can know if we should
    // restore prefs (.e.,g if we have a pref set on the user branch and the
    // user branch changed, we do not want to then overwrite the user's choice).

    // This is not complicated if a pref simply changed. However, we must also
    // detect `nsIPrefBranch::clearUserPref()`, which wipes out the user branch
    // and leaves the default branch untouched. That is where this gets
    // complicated.

    if (Services.prefs.prefHasUserValue(pref)) {
      // If there is a user branch value, then the user branch changed, because
      // a change to the default branch wouldn't have triggered the observer.
      return "user";
    } else if (!Services.prefs.prefHasDefaultValue(pref)) {
      // If there is no user branch value *or* default branch avlue, then the
      // user branch must have been cleared because you cannot clear the default
      // branch.
      return "user";
    } else if (expectedBranch === "default") {
      const value = lazy.PrefUtils.getPref(pref, { branch: "default" });
      if (value === expectedValue) {
        // The pref we control was set on the default branch and still matches
        // the expected value. Therefore, the user branch must have been
        // cleared.
        return "user";
      }
      // The default value branch does not match the value we expect, so it
      // must have just changed.
      return "default";
    }
    return "user";
  }

  _unenrollForFailure(enrollment, pref) {
    const rawType = Services.prefs.getPrefType(pref);
    let prefType = "invalid";

    switch (rawType) {
      case Ci.nsIPrefBranch.PREF_BOOL:
        prefType = "bool";
        break;

      case Ci.nsIPrefBranch.PREF_STRING:
        prefType = "string";
        break;

      case Ci.nsIPrefBranch.PREF_INT:
        prefType = "int";
        break;
    }

    this.manager._unenroll(enrollment, {
      reason: REASON_PREFFLIPS_FAILED,
      prefName: pref,
      prefType,
    });
  }
}

/**
 * Thrown when the prefFlips feature fails to set a pref.
 */
class PrefFlipsFailedError extends Error {
  constructor(pref, value) {
    super(`The Nimbus prefFlips feature failed to set ${pref}=${value}`);
    this.pref = pref;
  }
}