Source code
Revision control
Copy as Markdown
Other Tools
/* 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
import { AppConstants } from "resource://gre/modules/AppConstants.sys.mjs";
const lazy = {};
ChromeUtils.defineESModuleGetters(lazy, {
// This is an unfortunate exception where we depend on ASRouter because
// Nimbus has this dependency.
// This implementation is written in a way where it will avoid requiring
// this module if it's not available.
ASRouterTargeting:
// eslint-disable-next-line mozilla/no-browser-refs-in-toolkit
"resource:///modules/asrouter/ASRouterTargeting.sys.mjs",
FeatureGateImplementation:
"resource://featuregates/FeatureGateImplementation.sys.mjs",
ExperimentManager: "resource://nimbus/lib/ExperimentManager.sys.mjs",
TargetingContext: "resource://messaging-system/targeting/Targeting.sys.mjs",
});
ChromeUtils.defineLazyGetter(lazy, "gFeatureDefinitionsPromise", async () => {
const url = "resource://featuregates/feature_definitions.json";
return fetchFeatureDefinitions(url);
});
const kCustomTargeting = {
// For default values, although something like `channel == 'nightly'` kinda
// works, local builds don't have that update channel set in that way so it
// doesn't, and then tests fail because the defaults for the FeatureGate
// do not match the default value in the prefs code.
// We may in future want other things from AppConstants here, too.
nightly_build: AppConstants.NIGHTLY_BUILD,
thunderbird: AppConstants.MOZ_APP_NAME == "thunderbird",
};
ChromeUtils.defineLazyGetter(lazy, "defaultContexts", () => {
let ASRouterEnv = {};
try {
ASRouterEnv = lazy.ASRouterTargeting.Environment;
} catch (ex) {
// No ASRouter; just keep going.
}
return [
kCustomTargeting,
lazy.ExperimentManager.createTargetingContext(),
ASRouterEnv,
];
});
function getCombinedContext(...contexts) {
let combined = lazy.TargetingContext.combineContexts(
...lazy.defaultContexts,
...contexts
);
return new lazy.TargetingContext(combined, {
source: "featuregate",
});
}
async function fetchFeatureDefinitions(url) {
const res = await fetch(url);
let definitionsJson = await res.json();
return new Map(Object.entries(definitionsJson));
}
async function buildFeatureGateImplementation(definition) {
const targetValueKeys = ["defaultValue", "isPublic"];
for (const key of targetValueKeys) {
definition[key] = await FeatureGate.evaluateJexlValue(
definition[key + "Jexl"]
);
}
return new lazy.FeatureGateImplementation(definition);
}
let featureGatePrefObserver = {
onChange() {
FeatureGate.annotateCrashReporter();
},
// Ignore onEnable and onDisable since onChange is called in both cases.
onEnable() {},
onDisable() {},
};
const kFeatureGateCache = new Map();
/** A high level control for turning features on and off. */
export class FeatureGate {
/*
* This is structured as a class with static methods to that sphinx-js can
* easily document it. This constructor is required for sphinx-js to detect
* this class for documentation.
*/
constructor() {}
/**
* Constructs a feature gate object that is defined in ``Features.toml``.
* This is the primary way to create a ``FeatureGate``.
*
* @param {string} id The ID of the feature's definition in `Features.toml`.
* @param {string} testDefinitionsUrl A URL from which definitions can be fetched. Only use this in tests.
* @throws If the ``id`` passed is not defined in ``Features.toml``.
*/
static async fromId(id, testDefinitionsUrl = undefined) {
let featureDefinitions;
if (testDefinitionsUrl) {
featureDefinitions = await fetchFeatureDefinitions(testDefinitionsUrl);
} else {
featureDefinitions = await lazy.gFeatureDefinitionsPromise;
}
if (!featureDefinitions.has(id)) {
throw new Error(
`Unknown feature id ${id}. Features must be defined in toolkit/components/featuregates/Features.toml`
);
}
// Make a copy of the definition, since we are about to modify it
return buildFeatureGateImplementation({ ...featureDefinitions.get(id) });
}
/**
* Constructs feature gate objects for each of the definitions in ``Features.toml``.
* @param {string} testDefinitionsUrl A URL from which definitions can be fetched. Only use this in tests.
*/
static async all(testDefinitionsUrl = undefined) {
let featureDefinitions;
if (testDefinitionsUrl) {
featureDefinitions = await fetchFeatureDefinitions(testDefinitionsUrl);
} else {
featureDefinitions = await lazy.gFeatureDefinitionsPromise;
}
let definitions = [];
for (let definition of featureDefinitions.values()) {
// Make a copy of the definition, since we are about to modify it
definitions[definitions.length] = await buildFeatureGateImplementation(
Object.assign({}, definition)
);
}
return definitions;
}
static async observePrefChangesForCrashReportAnnotation(
testDefinitionsUrl = undefined
) {
let featureDefinitions = await FeatureGate.all(testDefinitionsUrl);
for (let definition of featureDefinitions.values()) {
FeatureGate.addObserver(
definition.id,
featureGatePrefObserver,
testDefinitionsUrl
);
}
}
static async annotateCrashReporter() {
if (!Services.appinfo.crashReporterEnabled) {
return;
}
let features = await FeatureGate.all();
let enabledFeatures = [];
for (let feature of features) {
if (await feature.getValue()) {
enabledFeatures.push(feature.preference);
}
}
Services.appinfo.annotateCrashReport(
"ExperimentalFeatures",
enabledFeatures.join(",")
);
}
/**
* Add an observer for a feature gate by ID. If the feature is of type
* boolean and currently enabled, `onEnable` will be called.
*
* The underlying feature gate instance will be shared with all other callers
* of this function, and share an observer.
*
* @param {string} id The ID of the feature's definition in `Features.toml`.
* @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)} [observer.onChange] Called when the
* feature's state changes to any value. The new value will be passed to the
* function.
* @param {string} testDefinitionsUrl A URL from which definitions can be fetched. Only use this in tests.
* @returns {Promise<boolean>} The current value of the feature.
*/
static async addObserver(id, observer, testDefinitionsUrl = undefined) {
if (!kFeatureGateCache.has(id)) {
kFeatureGateCache.set(
id,
await FeatureGate.fromId(id, testDefinitionsUrl)
);
}
const feature = kFeatureGateCache.get(id);
return feature.addObserver(observer);
}
/**
* Remove an observer of changes from this feature
* @param {string} id The ID of the feature's definition in `Features.toml`.
* @param observer Then observer that was passed to addObserver to remove.
*/
static async removeObserver(id, observer) {
let feature = kFeatureGateCache.get(id);
if (!feature) {
return;
}
feature.removeObserver(observer);
if (feature._observers.size === 0) {
kFeatureGateCache.delete(id);
}
}
/**
* 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
* @param {string} id The ID of the feature's definition in `Features.toml`.
* @returns {Promise<boolean>} A promise for the value associated with this feature.
*/
static async getValue(id, testDefinitionsUrl = undefined) {
let feature = kFeatureGateCache.get(id);
if (!feature) {
feature = await FeatureGate.fromId(id, testDefinitionsUrl);
}
return feature.getValue();
}
/**
* An alias of `getValue` for boolean typed feature gates.
*
* @async
* @param {string} id The ID of the feature's definition in `Features.toml`.
* @returns {Promise<boolean>} A promise for the value associated with this feature.
* @throws {Error} If the feature is not a boolean.
*/
static async isEnabled(id, testDefinitionsUrl = undefined) {
let feature = kFeatureGateCache.get(id);
if (!feature) {
feature = await FeatureGate.fromId(id, testDefinitionsUrl);
}
return feature.isEnabled();
}
/**
* Take a jexl expression and evaluate it against the standard Nimbus
* context, extended with some additional properties defined in
* kCustomTargeting.
*
* @param {String} jexlExpression The expression to evaluate.
* @param {Object[]?} additionalContexts Any additional context properties
* that should be taken into account.
*
* @returns {Promise<boolean>} Resolves to either true or false if successful,
* or null if there was some problem with the jexl expression (which
* will also log an error to the console).
*/
static async evaluateJexlValue(jexlExpression, ...additionalContexts) {
let result = null;
let context = getCombinedContext(...additionalContexts);
try {
result = !!(await context.evalWithDefault(jexlExpression));
} catch (ex) {
console.error(ex);
}
return result;
}
}