diff options
Diffstat (limited to 'toolkit/components/nimbus/lib/ExperimentManager.sys.mjs')
| -rw-r--r-- | toolkit/components/nimbus/lib/ExperimentManager.sys.mjs | 1344 |
1 files changed, 1344 insertions, 0 deletions
diff --git a/toolkit/components/nimbus/lib/ExperimentManager.sys.mjs b/toolkit/components/nimbus/lib/ExperimentManager.sys.mjs new file mode 100644 index 0000000000..cd34f5ad03 --- /dev/null +++ b/toolkit/components/nimbus/lib/ExperimentManager.sys.mjs @@ -0,0 +1,1344 @@ +/* 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/. */ + +import { XPCOMUtils } from "resource://gre/modules/XPCOMUtils.sys.mjs"; + +const lazy = {}; + +ChromeUtils.defineESModuleGetters(lazy, { + ClientEnvironment: "resource://normandy/lib/ClientEnvironment.sys.mjs", + ExperimentStore: "resource://nimbus/lib/ExperimentStore.sys.mjs", + FirstStartup: "resource://gre/modules/FirstStartup.sys.mjs", + NimbusFeatures: "resource://nimbus/ExperimentAPI.sys.mjs", + NormandyUtils: "resource://normandy/lib/NormandyUtils.sys.mjs", + PrefUtils: "resource://normandy/lib/PrefUtils.sys.mjs", + Sampling: "resource://gre/modules/components-utils/Sampling.sys.mjs", + TelemetryEnvironment: "resource://gre/modules/TelemetryEnvironment.sys.mjs", + TelemetryEvents: "resource://normandy/lib/TelemetryEvents.sys.mjs", +}); + +XPCOMUtils.defineLazyGetter(lazy, "log", () => { + const { Logger } = ChromeUtils.importESModule( + "resource://messaging-system/lib/Logger.sys.mjs" + ); + return new Logger("ExperimentManager"); +}); + +const TELEMETRY_EVENT_OBJECT = "nimbus_experiment"; +const TELEMETRY_EXPERIMENT_ACTIVE_PREFIX = "nimbus-"; +const TELEMETRY_DEFAULT_EXPERIMENT_TYPE = "nimbus"; + +const UPLOAD_ENABLED_PREF = "datareporting.healthreport.uploadEnabled"; +const STUDIES_OPT_OUT_PREF = "app.shield.optoutstudies.enabled"; + +const STUDIES_ENABLED_CHANGED = "nimbus:studies-enabled-changed"; + +function featuresCompat(branch) { + if (!branch || (!branch.feature && !branch.features)) { + return []; + } + let { features } = branch; + // In <=v1.5.0 of the Nimbus API, experiments had single feature + if (!features) { + features = [branch.feature]; + } + + return features; +} + +function getFeatureFromBranch(branch, featureId) { + return featuresCompat(branch).find( + featureConfig => featureConfig.featureId === featureId + ); +} + +/** + * A module for processes Experiment recipes, choosing and storing enrollment state, + * and sending experiment-related Telemetry. + */ +export class _ExperimentManager { + constructor({ id = "experimentmanager", store } = {}) { + this.id = id; + this.store = store || new lazy.ExperimentStore(); + this.sessions = new Map(); + // By default, no extra context. + this.extraContext = {}; + Services.prefs.addObserver(UPLOAD_ENABLED_PREF, this); + Services.prefs.addObserver(STUDIES_OPT_OUT_PREF, this); + + // A Map from pref names to pref observers and metadata. See + // `_updatePrefObservers` for the full structure. + this._prefs = new Map(); + // A Map from enrollment slugs to a Set of prefs that enrollment is setting + // or would set (e.g., if the enrollment is a rollout and there wasn't an + // active experiment already setting it). + this._prefsBySlug = new Map(); + } + + get studiesEnabled() { + return ( + Services.prefs.getBoolPref(UPLOAD_ENABLED_PREF) && + Services.prefs.getBoolPref(STUDIES_OPT_OUT_PREF) + ); + } + + /** + * Creates a targeting context with following filters: + * + * * `activeExperiments`: an array of slugs of all the active experiments + * * `isFirstStartup`: a boolean indicating whether or not the current enrollment + * is performed during the first startup + * + * @returns {Object} A context object + * @memberof _ExperimentManager + */ + createTargetingContext() { + let context = { + isFirstStartup: lazy.FirstStartup.state === lazy.FirstStartup.IN_PROGRESS, + ...this.extraContext, + }; + Object.defineProperty(context, "activeExperiments", { + get: async () => { + await this.store.ready(); + return this.store.getAllActiveExperiments().map(exp => exp.slug); + }, + }); + Object.defineProperty(context, "activeRollouts", { + get: async () => { + await this.store.ready(); + return this.store.getAllActiveRollouts().map(rollout => rollout.slug); + }, + }); + return context; + } + + /** + * Runs on startup, including before first run. + * + * @param {object} extraContext extra targeting context provided by the + * ambient environment. + */ + async onStartup(extraContext = {}) { + await this.store.init(); + this.extraContext = extraContext; + + const restoredExperiments = this.store.getAllActiveExperiments(); + const restoredRollouts = this.store.getAllActiveRollouts(); + + for (const experiment of restoredExperiments) { + this.setExperimentActive(experiment); + if (this._restoreEnrollmentPrefs(experiment)) { + this._updatePrefObservers(experiment); + } + } + for (const rollout of restoredRollouts) { + this.setExperimentActive(rollout); + if (this._restoreEnrollmentPrefs(rollout)) { + this._updatePrefObservers(rollout); + } + } + + this.observe(); + } + + /** + * Runs every time a Recipe is updated or seen for the first time. + * @param {RecipeArgs} recipe + * @param {string} source + */ + async onRecipe(recipe, source) { + const { slug, isEnrollmentPaused } = recipe; + + if (!source) { + throw new Error("When calling onRecipe, you must specify a source."); + } + + if (!this.sessions.has(source)) { + this.sessions.set(source, new Set()); + } + this.sessions.get(source).add(slug); + + if (this.store.has(slug)) { + await this.updateEnrollment(recipe, source); + } else if (isEnrollmentPaused) { + lazy.log.debug(`Enrollment is paused for "${slug}"`); + } else if (!(await this.isInBucketAllocation(recipe.bucketConfig))) { + lazy.log.debug("Client was not enrolled because of the bucket sampling"); + } else { + await this.enroll(recipe, source); + } + } + + _checkUnseenEnrollments( + enrollments, + sourceToCheck, + recipeMismatches, + invalidRecipes, + invalidBranches, + invalidFeatures, + missingLocale, + missingL10nIds + ) { + for (const enrollment of enrollments) { + const { slug, source } = enrollment; + if (sourceToCheck !== source) { + continue; + } + if (!this.sessions.get(source)?.has(slug)) { + lazy.log.debug(`Stopping study for recipe ${slug}`); + try { + let reason; + if (recipeMismatches.includes(slug)) { + reason = "targeting-mismatch"; + } else if (invalidRecipes.includes(slug)) { + reason = "invalid-recipe"; + } else if (invalidBranches.has(slug) || invalidFeatures.has(slug)) { + reason = "invalid-branch"; + } else if (missingLocale.includes(slug)) { + reason = "l10n-missing-locale"; + } else if (missingL10nIds.has(slug)) { + reason = "l10n-missing-entry"; + } else { + reason = "recipe-not-seen"; + } + this.unenroll(slug, reason); + } catch (err) { + console.error(err); + } + } + } + } + + /** + * Removes stored enrollments that were not seen after syncing with Remote Settings + * Runs when the all recipes been processed during an update, including at first run. + * @param {string} sourceToCheck + * @param {object} options Extra context used in telemetry reporting + * @param {string[]} options.recipeMismatches + * The list of experiments that do not match targeting. + * @param {string[]} options.invalidRecipes + * The list of recipes that do not match + * @param {Map<string, string[]>} options.invalidBranches + * A mapping of experiment slugs to a list of branches that failed + * feature validation. + * @param {Map<string, string[]>} options.invalidFeatures + * The mapping of experiment slugs to a list of invalid feature IDs. + * @param {string[]} options.missingLocale + * The list of experiment slugs missing an entry in the localization + * table for the current locale. + * @param {Map<string, string[]>} options.missingL10nIds + * The mapping of experiment slugs to the IDs of localization entries + * missing from the current locale. + * @param {string | null} options.locale + * The current locale. + * @param {boolean} options.validationEnabled + * Whether or not schema validation was enabled. + */ + onFinalize( + sourceToCheck, + { + recipeMismatches = [], + invalidRecipes = [], + invalidBranches = new Map(), + invalidFeatures = new Map(), + missingLocale = [], + missingL10nIds = new Map(), + locale = null, + validationEnabled = true, + } = {} + ) { + if (!sourceToCheck) { + throw new Error("When calling onFinalize, you must specify a source."); + } + const activeExperiments = this.store.getAllActiveExperiments(); + const activeRollouts = this.store.getAllActiveRollouts(); + this._checkUnseenEnrollments( + activeExperiments, + sourceToCheck, + recipeMismatches, + invalidRecipes, + invalidBranches, + invalidFeatures, + missingLocale, + missingL10nIds + ); + this._checkUnseenEnrollments( + activeRollouts, + sourceToCheck, + recipeMismatches, + invalidRecipes, + invalidBranches, + invalidFeatures, + missingLocale, + missingL10nIds + ); + + // If schema validation is disabled, then we will never send these + // validation failed telemetry events + if (validationEnabled) { + for (const slug of invalidRecipes) { + this.sendValidationFailedTelemetry(slug, "invalid-recipe"); + } + for (const [slug, branches] of invalidBranches.entries()) { + for (const branch of branches) { + this.sendValidationFailedTelemetry(slug, "invalid-branch", { + branch, + }); + } + } + for (const [slug, featureIds] of invalidFeatures.entries()) { + for (const featureId of featureIds) { + this.sendValidationFailedTelemetry(slug, "invalid-feature", { + feature: featureId, + }); + } + } + } + + if (locale) { + for (const slug of missingLocale.values()) { + this.sendValidationFailedTelemetry(slug, "l10n-missing-locale", { + locale, + }); + } + + for (const [slug, ids] of missingL10nIds.entries()) { + this.sendValidationFailedTelemetry(slug, "l10n-missing-entry", { + l10n_ids: ids.join(","), + locale, + }); + } + } + + this.sessions.delete(sourceToCheck); + } + + /** + * Bucket configuration specifies a specific percentage of clients that can + * be enrolled. + * @param {BucketConfig} bucketConfig + * @returns {Promise<boolean>} + */ + isInBucketAllocation(bucketConfig) { + if (!bucketConfig) { + lazy.log.debug("Cannot enroll if recipe bucketConfig is not set."); + return false; + } + + let id; + if (bucketConfig.randomizationUnit === "normandy_id") { + id = lazy.ClientEnvironment.userId; + } else { + // Others not currently supported. + lazy.log.debug( + `Invalid randomizationUnit: ${bucketConfig.randomizationUnit}` + ); + return false; + } + + return lazy.Sampling.bucketSample( + [id, bucketConfig.namespace], + bucketConfig.start, + bucketConfig.count, + bucketConfig.total + ); + } + + /** + * Start a new experiment by enrolling the users + * + * @param {RecipeArgs} recipe + * @param {string} source + * @param {object} options + * @param {boolean} options.reenroll - Allow re-enrollment. Only allowed for rollouts. + * @returns {Promise<Enrollment>} The experiment object stored in the data store + * @rejects {Error} + * @memberof _ExperimentManager + */ + async enroll(recipe, source, { reenroll = false } = {}) { + let { slug, branches } = recipe; + + const enrollment = this.store.get(slug); + + if ( + enrollment && + (enrollment.isActive || !enrollment.isRollout || !reenroll) + ) { + this.sendFailureTelemetry("enrollFailed", slug, "name-conflict"); + throw new Error(`An experiment with the slug "${slug}" already exists.`); + } + + let storeLookupByFeature = recipe.isRollout + ? this.store.getRolloutForFeature.bind(this.store) + : this.store.hasExperimentForFeature.bind(this.store); + const branch = await this.chooseBranch(slug, branches); + const features = featuresCompat(branch); + for (let feature of features) { + if (storeLookupByFeature(feature?.featureId)) { + lazy.log.debug( + `Skipping enrollment for "${slug}" because there is an existing ${ + recipe.isRollout ? "rollout" : "experiment" + } for this feature.` + ); + this.sendFailureTelemetry("enrollFailed", slug, "feature-conflict"); + + return null; + } + } + + return this._enroll(recipe, branch, source); + } + + _enroll( + { + slug, + experimentType = TELEMETRY_DEFAULT_EXPERIMENT_TYPE, + userFacingName, + userFacingDescription, + featureIds, + isRollout, + localizations, + }, + branch, + source, + options = {} + ) { + const { prefs, prefsToSet } = this._getPrefsForBranch(branch, isRollout); + + /** @type {Enrollment} */ + const experiment = { + slug, + branch, + active: true, + enrollmentId: lazy.NormandyUtils.generateUuid(), + experimentType, + source, + userFacingName, + userFacingDescription, + lastSeen: new Date().toJSON(), + featureIds, + prefs, + }; + + if (localizations) { + experiment.localizations = localizations; + } + + if (typeof isRollout !== "undefined") { + experiment.isRollout = isRollout; + } + + // Tag this as a forced enrollment. This prevents all unenrolling unless + // manually triggered from about:studies + if (options.force) { + experiment.force = true; + } + + if (isRollout) { + experiment.experimentType = "rollout"; + this.store.addEnrollment(experiment); + this.setExperimentActive(experiment); + } else { + this.store.addEnrollment(experiment); + this.setExperimentActive(experiment); + } + this.sendEnrollmentTelemetry(experiment); + + this._setEnrollmentPrefs(prefsToSet); + this._updatePrefObservers(experiment); + + lazy.log.debug( + `New ${isRollout ? "rollout" : "experiment"} started: ${slug}, ${ + branch.slug + }` + ); + + return experiment; + } + + forceEnroll(recipe, branch, source = "force-enrollment") { + /** + * If we happen to be enrolled in an experiment for the same feature + * we need to unenroll from that experiment. + * If the experiment has the same slug after unenrollment adding it to the + * store will overwrite the initial experiment. + */ + const features = featuresCompat(branch); + for (let feature of features) { + const isRollout = recipe.isRollout ?? false; + let enrollment = isRollout + ? this.store.getRolloutForFeature(feature?.featureId) + : this.store.getExperimentForFeature(feature?.featureId); + if (enrollment) { + lazy.log.debug( + `Existing ${ + isRollout ? "rollout" : "experiment" + } found for the same feature ${feature.featureId}, unenrolling.` + ); + + this.unenroll(enrollment.slug, source); + } + } + + recipe.userFacingName = `${recipe.userFacingName} - Forced enrollment`; + + const slug = `optin-${recipe.slug}`; + const enrollment = this._enroll( + { + ...recipe, + slug, + }, + branch, + source, + { force: true } + ); + + Services.obs.notifyObservers(null, "nimbus:enrollments-updated", slug); + + return enrollment; + } + + /** + * Update an enrollment that was already set + * + * @param {RecipeArgs} recipe + * @returns {boolean} whether the enrollment is still active + */ + async updateEnrollment(recipe, source) { + /** @type Enrollment */ + const enrollment = this.store.get(recipe.slug); + + // Don't update experiments that were already unenrolled. + if (enrollment.active === false && !recipe.isRollout) { + lazy.log.debug(`Enrollment ${recipe.slug} has expired, aborting.`); + return false; + } + + if (recipe.isRollout) { + if (!(await this.isInBucketAllocation(recipe.bucketConfig))) { + lazy.log.debug( + `No longer meet bucketing for "${recipe.slug}"; unenrolling...` + ); + this.unenroll(recipe.slug, "bucketing"); + return false; + } else if ( + !enrollment.active && + enrollment.unenrollReason !== "individual-opt-out" + ) { + lazy.log.debug(`Re-enrolling in rollout "${recipe.slug}`); + return !!(await this.enroll(recipe, source, { reenroll: true })); + } + } + + // Stay in the same branch, don't re-sample every time. + const branch = recipe.branches.find( + branch => branch.slug === enrollment.branch.slug + ); + + if (!branch) { + // Our branch has been removed. Unenroll. + this.unenroll(recipe.slug, "branch-removed"); + return false; + } + + return true; + } + + /** + * Stop an enrollment that is currently active + * + * @param {string} slug + * The slug of the enrollment to stop. + * @param {string} reason + * An optional reason for the unenrollment. + * + * This will be reported in telemetry. + */ + unenroll(slug, reason = "unknown") { + const enrollment = this.store.get(slug); + if (!enrollment) { + this.sendFailureTelemetry("unenrollFailed", slug, "does-not-exist"); + throw new Error(`Could not find an experiment with the slug "${slug}"`); + } + + this._unenroll(enrollment, { reason }); + } + + /** + * Stop an enrollment that is currently active. + * + * @param {Enrollment} enrollment + * The enrollment to end. + * + * @param {object} options + * @param {string} options.reason + * An optional reason for the unenrollment. + * + * This will be reported in telemetry. + * + * @param {object?} options.changedPref + * If the unenrollment was due to pref change, this will contain the + * information about the pref that changed. + * + * @param {string} options.changedPref.name + * The name of the pref that caused the unenrollment. + * + * @param {string} options.changedPref.branch + * The branch that was changed ("user" or "default"). + */ + _unenroll( + enrollment, + { reason = "unknown", changedPref = undefined, duringRestore = false } = {} + ) { + const { slug } = enrollment; + + if (!enrollment.active) { + this.sendFailureTelemetry("unenrollFailed", slug, "already-unenrolled"); + throw new Error( + `Cannot stop experiment "${slug}" because it is already expired` + ); + } + + lazy.TelemetryEnvironment.setExperimentInactive(slug); + // We also need to set the experiment inactive in the Glean Experiment API + Services.fog.setExperimentInactive(slug); + this.store.updateExperiment(slug, { + active: false, + unenrollReason: reason, + }); + + lazy.TelemetryEvents.sendEvent("unenroll", TELEMETRY_EVENT_OBJECT, slug, { + reason, + branch: enrollment.branch.slug, + enrollmentId: + enrollment.enrollmentId || lazy.TelemetryEvents.NO_ENROLLMENT_ID_MARKER, + }); + // Sent Glean event equivalent + Glean.nimbusEvents.unenrollment.record({ + experiment: slug, + branch: enrollment.branch.slug, + enrollment_id: + enrollment.enrollmentId || lazy.TelemetryEvents.NO_ENROLLMENT_ID_MARKER, + reason, + }); + + this._unsetEnrollmentPrefs(enrollment, { changedPref, duringRestore }); + + lazy.log.debug(`Recipe unenrolled: ${slug}`); + } + + /** + * Unenroll from all active studies if user opts out. + */ + observe(aSubject, aTopic, aPrefName) { + if (!this.studiesEnabled) { + for (const { slug } of this.store.getAllActiveExperiments()) { + this.unenroll(slug, "studies-opt-out"); + } + for (const { slug } of this.store.getAllActiveRollouts()) { + this.unenroll(slug, "studies-opt-out"); + } + } + + Services.obs.notifyObservers(null, STUDIES_ENABLED_CHANGED); + } + + /** + * Send Telemetry for undesired event + * + * @param {string} eventName + * @param {string} slug + * @param {string} reason + */ + sendFailureTelemetry(eventName, slug, reason) { + lazy.TelemetryEvents.sendEvent(eventName, TELEMETRY_EVENT_OBJECT, slug, { + reason, + }); + if (eventName == "enrollFailed") { + Glean.nimbusEvents.enrollFailed.record({ + experiment: slug, + reason, + }); + } else if (eventName == "unenrollFailed") { + Glean.nimbusEvents.unenrollFailed.record({ + experiment: slug, + reason, + }); + } + } + + sendValidationFailedTelemetry(slug, reason, extra) { + lazy.TelemetryEvents.sendEvent( + "validationFailed", + TELEMETRY_EVENT_OBJECT, + slug, + { + reason, + ...extra, + } + ); + Glean.nimbusEvents.validationFailed.record({ + experiment: slug, + reason, + ...extra, + }); + } + + /** + * + * @param {Enrollment} experiment + */ + sendEnrollmentTelemetry({ slug, branch, experimentType, enrollmentId }) { + lazy.TelemetryEvents.sendEvent("enroll", TELEMETRY_EVENT_OBJECT, slug, { + experimentType, + branch: branch.slug, + enrollmentId: + enrollmentId || lazy.TelemetryEvents.NO_ENROLLMENT_ID_MARKER, + }); + Glean.nimbusEvents.enrollment.record({ + experiment: slug, + branch: branch.slug, + enrollment_id: + enrollmentId || lazy.TelemetryEvents.NO_ENROLLMENT_ID_MARKER, + experiment_type: experimentType, + }); + } + + /** + * Sets Telemetry when activating an experiment. + * + * @param {Enrollment} experiment + */ + setExperimentActive(experiment) { + lazy.TelemetryEnvironment.setExperimentActive( + experiment.slug, + experiment.branch.slug, + { + type: `${TELEMETRY_EXPERIMENT_ACTIVE_PREFIX}${experiment.experimentType}`, + enrollmentId: + experiment.enrollmentId || + lazy.TelemetryEvents.NO_ENROLLMENT_ID_MARKER, + } + ); + // Report the experiment to the Glean Experiment API + Services.fog.setExperimentActive(experiment.slug, experiment.branch.slug, { + type: `${TELEMETRY_EXPERIMENT_ACTIVE_PREFIX}${experiment.experimentType}`, + enrollmentId: + experiment.enrollmentId || lazy.TelemetryEvents.NO_ENROLLMENT_ID_MARKER, + }); + } + + /** + * Generate Normandy UserId respective to a branch + * for a given experiment. + * + * @param {string} slug + * @param {Array<{slug: string; ratio: number}>} branches + * @param {string} namespace + * @param {number} start + * @param {number} count + * @param {number} total + * @returns {Promise<{[branchName: string]: string}>} An object where + * the keys are branch names and the values are user IDs that will enroll + * a user for that particular branch. Also includes a `notInExperiment` value + * that will not enroll the user in the experiment if not 100% enrollment. + */ + async generateTestIds(recipe) { + // Older recipe structure had bucket config values at the top level while + // newer recipes group them into a bucketConfig object + const { slug, branches, namespace, start, count, total } = { + ...recipe, + ...recipe.bucketConfig, + }; + const branchValues = {}; + const includeNot = count < total; + + if (!slug || !namespace) { + throw new Error(`slug, namespace not in expected format`); + } + + if (!(start < total && count <= total)) { + throw new Error("Must include start, count, and total as integers"); + } + + if ( + !Array.isArray(branches) || + branches.filter(branch => branch.slug && branch.ratio).length !== + branches.length + ) { + throw new Error("branches parameter not in expected format"); + } + + while (Object.keys(branchValues).length < branches.length + includeNot) { + const id = lazy.NormandyUtils.generateUuid(); + const enrolls = await lazy.Sampling.bucketSample( + [id, namespace], + start, + count, + total + ); + // Does this id enroll the user in the experiment + if (enrolls) { + // Choose a random branch + const { slug: pickedBranch } = await this.chooseBranch( + slug, + branches, + id + ); + + if (!Object.keys(branchValues).includes(pickedBranch)) { + branchValues[pickedBranch] = id; + lazy.log.debug(`Found a value for "${pickedBranch}"`); + } + } else if (!branchValues.notInExperiment) { + branchValues.notInExperiment = id; + } + } + return branchValues; + } + + /** + * Choose a branch randomly. + * + * @param {string} slug + * @param {Branch[]} branches + * @returns {Promise<Branch>} + * @memberof _ExperimentManager + */ + async chooseBranch(slug, branches, userId = lazy.ClientEnvironment.userId) { + const ratios = branches.map(({ ratio = 1 }) => ratio); + + // It's important that the input be: + // - Unique per-user (no one is bucketed alike) + // - Unique per-experiment (bucketing differs across multiple experiments) + // - Differs from the input used for sampling the recipe (otherwise only + // branches that contain the same buckets as the recipe sampling will + // receive users) + const input = `${this.id}-${userId}-${slug}-branch`; + + const index = await lazy.Sampling.ratioSample(input, ratios); + return branches[index]; + } + + /** + * Generate the list of prefs a recipe will set. + * + * @params {object} branch The recipe branch that will be enrolled. + * @params {boolean} isRollout Whether or not this recipe is a rollout. + * + * @returns {object} An object with the following keys: + * + * `prefs`: + * The full list of prefs that this recipe would set, + * if there are no conflicts. This will include prefs + * that, for example, will not be set because this + * enrollment is a rollout and there is an active + * experiment that set the same pref. + * + * `prefsToSet`: + * Prefs that should be set once enrollment is + * complete. + */ + _getPrefsForBranch(branch, isRollout = false) { + const prefs = []; + const prefsToSet = []; + + const getConflictingEnrollment = this._makeEnrollmentCache(isRollout); + + for (const { featureId, value: featureValue } of featuresCompat(branch)) { + const feature = lazy.NimbusFeatures[featureId]; + + if (!feature) { + continue; + } + + // It is possible to enroll in both an experiment and a rollout, so we + // need to check if we have another enrollment for the same feature. + const conflictingEnrollment = getConflictingEnrollment(featureId); + + const prefBranch = + feature.manifest.isEarlyStartup ?? false ? "user" : "default"; + + for (const [variable, value] of Object.entries(featureValue)) { + const prefName = feature.getSetPrefName(variable); + + if (prefName) { + let originalValue; + const conflictingPref = conflictingEnrollment?.prefs?.find( + p => p.name === prefName + ); + + if (conflictingPref) { + // If there is another enrollment that has already set the pref we + // care about, we use its stored originalValue. + originalValue = conflictingPref.originalValue; + } else if ( + prefBranch === "user" && + !Services.prefs.prefHasUserValue(prefName) + ) { + // If there is a default value set, then attempting to read the user + // branch would result in returning the default branch value. + originalValue = null; + } else { + originalValue = lazy.PrefUtils.getPref(prefName, { + branch: prefBranch, + }); + } + + prefs.push({ + name: prefName, + branch: prefBranch, + featureId, + variable, + originalValue, + }); + + // An experiment takes precedence if there is already a pref set. + if (!isRollout || !conflictingPref) { + prefsToSet.push({ name: prefName, value, prefBranch }); + } + } + } + } + + return { prefs, prefsToSet }; + } + + /** + * Set a list of prefs from enrolling in an experiment or rollout. + * + * The ExperimentManager's pref observers will be disabled while setting each + * pref so as not to accidentally unenroll an existing rollout that an + * experiment would override. + * + * @param {object[]} prefsToSet + * A list of objects containing the prefs to set. + * + * Each object has the following properties: + * + * * `name`: The name of the pref. + * * `value`: The value of the pref. + * * `prefBranch`: The branch to set the pref on (either "user" or "default"). + */ + _setEnrollmentPrefs(prefsToSet) { + for (const { name, value, prefBranch } of prefsToSet) { + const entry = this._prefs.get(name); + + // If another enrollment exists that has set this pref, temporarily + // disable the pref observer so as not to cause unenrollment. + if (entry) { + entry.enrollmentChanging = true; + } + + lazy.PrefUtils.setPref(name, value, { branch: prefBranch }); + + if (entry) { + entry.enrollmentChanging = false; + } + } + } + + /** + * Unset prefs set during this enrollment. + * + * If this enrollment is an experiment and there is an existing rollout that + * would set a pref that was covered by this enrollment, the pref will be + * updated to that rollout's value. + * + * Otherwise, it will be set to the original value from before the enrollment + * began. + * + * @param {Enrollment} enrollment + * The enrollment that has ended. + * + * @param {object} options + * + * @param {object?} options.changedPref + * If provided, a changed pref that caused the unenrollment that + * triggered unsetting these prefs. This is provided as to not + * overwrite a changed pref with an original value. + * + * @param {string} options.changedPref.name + * The name of the changed pref. + * + * @param {string} options.changedPref.branch + * The branch that was changed ("user" or "default"). + * + * @param {boolean} options.duringRestore + * The unenrollment was caused during restore. + */ + _unsetEnrollmentPrefs(enrollment, { changedPref, duringRestore } = {}) { + if (!enrollment.prefs?.length) { + return; + } + + const getConflictingEnrollment = this._makeEnrollmentCache( + enrollment.isRollout + ); + + for (const pref of enrollment.prefs) { + this._removePrefObserver(pref.name, enrollment.slug); + + if ( + changedPref?.name == pref.name && + changedPref.branch === pref.branch + ) { + // Resetting the original value would overwite the pref the user just + // set. Skip it. + continue; + } + + let newValue = pref.originalValue; + + // If we are unenrolling from an experiment during a restore, we must + // ignore any potential conflicting rollout in the store, because its + // hasn't gone through `_restoreEnrollmentPrefs`, which might also cause + // it to unenroll. + // + // Both enrollments will have the same `originalValue` stored, so it will + // always be restored. + if (!duringRestore || enrollment.isRollout) { + const conflictingEnrollment = getConflictingEnrollment(pref.featureId); + const conflictingPref = conflictingEnrollment?.prefs?.find( + p => p.name === pref.name + ); + + if (conflictingPref) { + if (enrollment.isRollout) { + // If we are unenrolling from a rollout, we have an experiment that + // has set the pref. Since experiments take priority, we do not unset + // it. + continue; + } else { + // If we are an unenrolling from an experiment, we have a rollout that would + // set the same pref, so we update the pref to that value instead of + // the original value. + newValue = getFeatureFromBranch( + conflictingEnrollment.branch, + pref.featureId + ).value[pref.variable]; + } + } + } + + // If another enrollment exists that has set this pref, temporarily + // disable the pref observer so as not to cause unenrollment when we + // update the pref to its value. + const entry = this._prefs.get(pref.name); + if (entry) { + entry.enrollmentChanging = true; + } + + lazy.PrefUtils.setPref(pref.name, newValue, { + branch: pref.branch, + }); + + if (entry) { + entry.enrollmentChanging = false; + } + } + } + + /** + * Restore the prefs set by an enrollment. + * + * @param {object} enrollment The enrollment. + * @param {object} enrollment.branch The branch that was enrolled. + * @param {object[]} enrollment.prefs The prefs that are set by the enrollment. + * @param {object[]} enrollment.isRollout The prefs that are set by the enrollment. + * + * @returns {boolean} Whether the restore was successful. If false, the + * enrollment has ended. + */ + _restoreEnrollmentPrefs(enrollment) { + const { branch, prefs = [], isRollout } = enrollment; + + if (!prefs?.length) { + return false; + } + + const featuresById = Object.assign( + ...featuresCompat(branch).map(f => ({ [f.featureId]: f })) + ); + + for (const { name, featureId, variable } of prefs) { + // If the feature no longer exists, unenroll. + if (!Object.hasOwn(lazy.NimbusFeatures, featureId)) { + this._unenroll(enrollment, { + reason: "invalid-feature", + duringRestore: true, + }); + return false; + } + + const variables = lazy.NimbusFeatures[featureId].manifest.variables; + + // If the feature is missing a variable that set a pref, unenroll. + if (!Object.hasOwn(variables, variable)) { + this._unenroll(enrollment, { + reason: "pref-variable-missing", + duringRestore: true, + }); + return false; + } + + const variableDef = variables[variable]; + + // If the variable is no longer a pref-setting variable, unenroll. + if (!Object.hasOwn(variableDef, "setPref")) { + this._unenroll(enrollment, { + reason: "pref-variable-no-longer", + duringRestore: true, + }); + return false; + } + + // If the variable is setting a different preference, unenroll. + if (variableDef.setPref !== name) { + this._unenroll(enrollment, { + reason: "pref-variable-changed", + duringRestore: true, + }); + return false; + } + } + + for (const { name, branch: prefBranch, featureId, variable } of prefs) { + // User prefs are already persisted. + if (prefBranch === "user") { + continue; + } + + // If we are a rollout, we need to check for an existing experiment that + // has set the same pref. If so, we do not need to set the pref because + // experiments take priority. + if (isRollout) { + const conflictingEnrollment = + this.store.getExperimentForFeature(featureId); + const conflictingPref = conflictingEnrollment?.prefs?.find( + p => p.name === name + ); + + if (conflictingPref) { + continue; + } + } + + const value = featuresById[featureId].value[variable]; + + if (prefBranch !== "user") { + lazy.PrefUtils.setPref(name, value, { branch: prefBranch }); + } + } + + return true; + } + + /** + * Make a cache to look up enrollments of the oppposite kind by feature ID. + * + * @param {boolean} isRollout Whether or not the current enrollment is a + * rollout. If true, the cache will return + * experiments. If false, the cache will return + * rollouts. + * + * @returns {function} The cache, as a callable function. + */ + _makeEnrollmentCache(isRollout) { + const getOtherEnrollment = ( + isRollout + ? this.store.getExperimentForFeature + : this.store.getRolloutForFeature + ).bind(this.store); + + const conflictingEnrollments = {}; + return featureId => { + if (!Object.hasOwn(conflictingEnrollments, featureId)) { + conflictingEnrollments[featureId] = getOtherEnrollment(featureId); + } + + return conflictingEnrollments[featureId]; + }; + } + + /** + * Update the set of observers with prefs set by the given enrollment. + * + * @param {Enrollment} enrollment + * The enrollment that is setting prefs. + */ + _updatePrefObservers({ slug, prefs }) { + if (!prefs?.length) { + return; + } + + for (const pref of prefs) { + const { name } = pref; + + if (!this._prefs.has(name)) { + const observer = () => this._onExperimentPrefChanged(pref); + const entry = { + slugs: new Set([slug]), + enrollmentChanging: false, + observer, + }; + + Services.prefs.addObserver(name, observer); + + this._prefs.set(name, entry); + } else { + this._prefs.get(name).slugs.add(slug); + } + + if (!this._prefsBySlug.has(slug)) { + this._prefsBySlug.set(slug, new Set([name])); + } else { + this._prefsBySlug.get(slug).add(name); + } + } + } + + /** + * Remove an entry for the pref observer for the given pref and slug. + * + * If there are no more enrollments listening to a pref, the observer will be removed. + * + * This is called when an enrollment is ending. + * + * @param {string} name The name of the pref. + * @param {string} slug The slug of the enrollment that is being unenrolled. + */ + _removePrefObserver(name, slug) { + // Update the pref observer that the current enrollment is no longer + // involved in the pref. + // + // If no enrollments have a variable setting the pref, then we can remove + // the observers. + const entry = this._prefs.get(name); + + // If this is happening due to a pref change, the observers will already be removed. + if (entry) { + entry.slugs.delete(slug); + if (entry.slugs.size == 0) { + Services.prefs.removeObserver(name, entry.observer); + this._prefs.delete(name); + } + } + + const bySlug = this._prefsBySlug.get(slug); + if (bySlug) { + bySlug.delete(name); + if (bySlug.size == 0) { + this._prefsBySlug.delete(slug); + } + } + } + + /** + * Handle a change to a pref set by enrollments by ending those enrollments. + * + * @param {object} pref + * Information about the pref that was changed. + * + * @param {string} pref.name + * The name of the pref that was changed. + * + * @param {string} pref.branch + * The branch enrollments set the pref on. + * + * @param {string} pref.featureId + * The feature ID of the feature containing the variable that set the + * pref. + * + * @param {string} pref.variable + * The variable in the given feature whose value determined the pref's + * value. + */ + _onExperimentPrefChanged(pref) { + const entry = this._prefs.get(pref.name); + // If this was triggered while we are enrolling or unenrolling from an + // experiment, then we don't want to unenroll from the rollout because the + // experiment's value is taking precendence. + // + // Otherwise, all enrollments that set the variable corresponding to this + // pref must be unenrolled. + if (entry.enrollmentChanging) { + return; + } + + // Copy the `Set` into an `Array` because we modify the set later in + // `_removePrefObserver` and we need to iterate over it multiple times. + const slugs = Array.from(entry.slugs); + + // Remove all pref observers set by enrollments. We are potentially about + // to set these prefs during unenrollment, so we don't want to trigger + // them and cause nested unenrollments. + for (const slug of slugs) { + const toRemove = Array.from(this._prefsBySlug.get(slug) ?? []); + for (const name of toRemove) { + this._removePrefObserver(name, slug); + } + } + + // Unenroll from the rollout first to save calls to setPref. + const enrollments = Array.from(slugs).map(slug => this.store.get(slug)); + + // There is a maximum of two enrollments (one experiment and one rollout). + if (enrollments.length == 2) { + // Order enrollments so that we unenroll from the rollout first. + if (!enrollments[0].isRollout) { + enrollments.reverse(); + } + } + + // 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 also must + // detect `nsIPrefBranch::clearUserPref()`, which wipes out the user branch + // and leaves the default branch untouched. That is where this gets + // complicated: + + let branch; + if (Services.prefs.prefHasUserValue(pref.name)) { + // If there is a user branch value, then the user branch changed. + branch = "user"; + } else if (!Services.prefs.prefHasDefaultValue(pref.name)) { + // If there is not default branch value, then the user branch must have + // been cleared becuase you cannot clear the default branch. + branch = "user"; + } else if (pref.branch === "default") { + const feature = getFeatureFromBranch( + enrollments.at(-1).branch, + pref.featureId + ); + const expectedValue = feature.value[pref.variable]; + const value = lazy.PrefUtils.getPref(pref.name, { branch: pref.branch }); + + if (value === expectedValue) { + // If the pref was set on the default branch and still matches the + // expected value, then the user branch must have been cleared. + branch = "user"; + } else { + branch = "default"; + } + } else { + // If the pref was set on the user branch and we don't have a user branch + // value, then the user branch must have been cleared. + branch = "user"; + } + + const changedPref = { + name: pref.name, + branch, + }; + + for (const enrollment of enrollments) { + this._unenroll(enrollment, { reason: "changed-pref", changedPref }); + } + } +} + +export const ExperimentManager = new _ExperimentManager(); |