Feature management decision (#103)

Author: mjc1283

lib/core/bucketer/index.js

@@ -56,7 +56,7 @@ module.exports = {
         throw new Error(sprintf(ERROR_MESSAGES.INVALID_GROUP_ID, MODULE_NAME, groupId));
       }
       if (group.policy === RANDOM_POLICY) {
-        var bucketedExperimentId = module.exports._bucketUserIntoExperiment(group,
+        var bucketedExperimentId = module.exports.bucketUserIntoExperiment(group,
                                                                           bucketerParams.bucketingId,
                                                                           bucketerParams.userId,
                                                                           bucketerParams.logger);
@@ -111,7 +111,7 @@ module.exports = {
    * @param {Object} logger       Logger implementation
    * @return {string} ID of experiment if user is bucketed into experiment within the group, null otherwise
    */
-  _bucketUserIntoExperiment: function(group, bucketingId, userId, logger) {
+  bucketUserIntoExperiment: function(group, bucketingId, userId, logger) {
     var bucketingKey = sprintf('%s%s', bucketingId, group.id);
     var bucketValue = module.exports._generateBucketValue(bucketingKey);
     logger.log(LOG_LEVEL.DEBUG, sprintf(LOG_MESSAGES.USER_ASSIGNED_TO_EXPERIMENT_BUCKET, MODULE_NAME, bucketValue, userId));

lib/core/decision_service/index.js

@@ -27,6 +27,7 @@ var ERROR_MESSAGES = enums.ERROR_MESSAGES;
 var LOG_LEVEL = enums.LOG_LEVEL;
 var LOG_MESSAGES = enums.LOG_MESSAGES;
 var RESERVED_ATTRIBUTE_KEY_BUCKETING_ID = '$opt_bucketing_id';
+var DECISION_SOURCES = enums.DECISION_SOURCES;
 
 
 /**
@@ -260,11 +261,184 @@ DecisionService.prototype.__saveUserProfile = function(userProfile, experiment,
   }
 };
 
+/**
+ * Given a feature, user ID, and attributes, returns an object representing a
+ * decision. If the user was bucketed into a variation for the given feature
+ * and attributes, the returned decision object will have variation and
+ * experiment properties (both objects), as well as a decisionSource property.
+ * decisionSource indicates whether the decision was due to a rollout or an
+ * experiment.
+ * @param   {Object} feature    A feature flag object from project configuration
+ * @param   {String} userId     A string identifying the user, for bucketing
+ * @param   {Object} attributes Optional user attributes
+ * @return  {Object} An object with experiment, variation, and decisionSource
+ * properties. If the user was not bucketed into a variation, the variation
+ * property is null.
+ */
+DecisionService.prototype.getVariationForFeature = function(feature, userId, attributes) {
+  var experimentDecision = this._getVariationForFeatureExperiment(feature, userId, attributes);
+  if (experimentDecision.variation !== null) {
+    this.logger.log(LOG_LEVEL.DEBUG, sprintf(LOG_MESSAGES.USER_IN_FEATURE_EXPERIMENT, MODULE_NAME, userId, experimentDecision.variation.key, experimentDecision.experiment.key, feature.key));
+    return experimentDecision;
+  }
+
+  this.logger.log(LOG_LEVEL.DEBUG, sprintf(LOG_MESSAGES.USER_NOT_IN_FEATURE_EXPERIMENT, MODULE_NAME, userId, feature.key));
+
+  var rolloutDecision = this._getVariationForRollout(feature, userId, attributes);
+  if (rolloutDecision.variation !== null) {
+    this.logger.log(LOG_LEVEL.DEBUG, sprintf(LOG_MESSAGES.USER_IN_ROLLOUT, MODULE_NAME, userId, feature.key));
+    return rolloutDecision;
+  }
+
+  this.logger.log(LOG_LEVEL.DEBUG, sprintf(LOG_MESSAGES.USER_NOT_IN_ROLLOUT, MODULE_NAME, userId, feature.key));
+
+  return {
+    experiment: null,
+    variation: null,
+    decisionSource: null,
+  };
+};
+
+DecisionService.prototype._getVariationForFeatureExperiment = function(feature, userId, attributes) {
+  var experiment = null;
+  var variationKey = null;
+
+  if (feature.hasOwnProperty('groupId')) {
+    var group = this.configObj.groupIdMap[feature.groupId];
+    if (group) {
+      experiment = this._getExperimentInGroup(group, userId);
+      if (experiment) {
+        variationKey = this.getVariation(experiment.key, userId, attributes);
+      }
+    }
+  } else if (feature.experimentIds.length > 0) {
+    // If the feature does not have a group ID, then it can only be associated
+    // with one experiment, so we look at the first experiment ID only
+    experiment = projectConfig.getExperimentFromId(this.configObj, feature.experimentIds[0], this.logger);
+    if (experiment) {
+      variationKey = this.getVariation(experiment.key, userId, attributes);
+    }
+  } else {
+    this.logger.log(LOG_LEVEL.DEBUG, sprintf(LOG_MESSAGES.FEATURE_HAS_NO_EXPERIMENTS, MODULE_NAME, feature.key));
+  }
+
+  var variation = null;
+  if (variationKey !== null && experiment !== null) {
+    variation = experiment.variationKeyMap[variationKey];
+  }
+  return {
+    experiment: experiment,
+    variation: variation,
+    decisionSource: DECISION_SOURCES.EXPERIMENT,
+  };
+};
+
+DecisionService.prototype._getExperimentInGroup = function(group, userId) {
+  var experimentId = bucketer.bucketUserIntoExperiment(group, userId, userId, this.logger);
+  if (experimentId !== null) {
+    this.logger.log(LOG_LEVEL.INFO, sprintf(LOG_MESSAGES.USER_BUCKETED_INTO_EXPERIMENT_IN_GROUP, MODULE_NAME, userId, experimentId, group.id));
+    var experiment = projectConfig.getExperimentFromId(this.configObj, experimentId, this.logger);
+    if (experiment) {
+      return experiment;
+    }
+  }
+
+  this.logger.log(LOG_LEVEL.INFO, sprintf(LOG_MESSAGES.USER_NOT_BUCKETED_INTO_ANY_EXPERIMENT_IN_GROUP, MODULE_NAME, userId, group.id));
+  return null;
+};
+
+DecisionService.prototype._getVariationForRollout = function(feature, userId, attributes) {
+  if (!feature.rolloutId) {
+    this.logger.log(LOG_LEVEL.DEBUG, sprintf(LOG_MESSAGES.NO_ROLLOUT_EXISTS, MODULE_NAME, feature.key));
+    return {
+      experiment: null,
+      variation: null,
+      decisionSource: DECISION_SOURCES.ROLLOUT,
+    };
+  }
+
+  var rollout = this.configObj.rolloutIdMap[feature.rolloutId];
+  if (!rollout) {
+    this.logger.log(LOG_LEVEL.ERROR, sprintf(ERROR_MESSAGES.INVALID_ROLLOUT_ID, MODULE_NAME, feature.rolloutId, feature.key));
+    return {
+      experiment: null,
+      variation: null,
+      decisionSource: DECISION_SOURCES.ROLLOUT,
+    };
+  }
+
+  if (rollout.experiments.length === 0) {
+    this.logger.log(LOG_LEVEL.ERROR, sprintf(LOG_MESSAGES.ROLLOUT_HAS_NO_EXPERIMENTS, MODULE_NAME, feature.rolloutId));
+    return {
+      experiment: null,
+      variation: null,
+      decisionSource: DECISION_SOURCES.ROLLOUT,
+    };
+  }
+
+  // The end index is length - 1 because the last experiment is assumed to be
+  // "everyone else", which will be evaluated separately outside this loop
+  var endIndex = rollout.experiments.length - 1;
+  var index;
+  var experiment;
+  var bucketerParams;
+  var variationId;
+  var variation;
+  for (index = 0; index < endIndex; index++) {
+    experiment = this.configObj.experimentKeyMap[rollout.experiments[index].key];
+
+    if (!this.__checkIfUserIsInAudience(experiment.key, userId, attributes)) {
+      this.logger.log(LOG_LEVEL.DEBUG, sprintf(LOG_MESSAGES.USER_DOESNT_MEET_CONDITIONS_FOR_TARGETING_RULE, MODULE_NAME, userId, index + 1));
+      continue;
+    }
+
+    this.logger.log(LOG_LEVEL.DEBUG, sprintf(LOG_MESSAGES.USER_MEETS_CONDITIONS_FOR_TARGETING_RULE, MODULE_NAME, userId, index + 1));
+    bucketerParams = this.__buildBucketerParams(experiment.key, userId, userId);
+    variationId = bucketer.bucket(bucketerParams);
+    variation = this.configObj.variationIdMap[variationId];
+    if (variation) {
+      this.logger.log(LOG_LEVEL.DEBUG, sprintf(LOG_MESSAGES.USER_BUCKETED_INTO_TARGETING_RULE, MODULE_NAME, userId, index + 1));
+      return {
+        experiment: experiment,
+        variation: variation,
+        decisionSource: DECISION_SOURCES.ROLLOUT,
+      };
+    } else {
+      this.logger.log(LOG_LEVEL.DEBUG, sprintf(LOG_MESSAGES.USER_NOT_BUCKETED_INTO_TARGETING_RULE, MODULE_NAME, userId, index + 1));
+      break;
+    }
+  }
+
+  var everyoneElseExperiment = this.configObj.experimentKeyMap[rollout.experiments[endIndex].key];
+  if (this.__checkIfUserIsInAudience(everyoneElseExperiment.key, userId, attributes)) {
+    bucketerParams = this.__buildBucketerParams(everyoneElseExperiment.key, userId, userId);
+    variationId = bucketer.bucket(bucketerParams);
+    variation = this.configObj.variationIdMap[variationId];
+    if (variation) {
+      this.logger.log(LOG_LEVEL.DEBUG, sprintf(LOG_MESSAGES.USER_BUCKETED_INTO_EVERYONE_TARGETING_RULE, MODULE_NAME, userId));
+      return {
+        experiment: everyoneElseExperiment,
+        variation: variation,
+        decisionSource: DECISION_SOURCES.ROLLOUT,
+      };
+    } else {
+      this.logger.log(LOG_LEVEL.DEBUG, sprintf(LOG_MESSAGES.USER_NOT_BUCKETED_INTO_EVERYONE_TARGETING_RULE, MODULE_NAME, userId));
+    }
+  }
+
+  return {
+    experiment: null,
+    variation: null,
+    decisionSource: DECISION_SOURCES.ROLLOUT,
+  };
+};
+
 module.exports = {
   /**
    * Creates an instance of the DecisionService.
    * @param  {Object} options               Configuration options
-   * @param  {Object} options.projectConfig
+   * @param  {Object} options.configObj
+   * @param  {Object} options.userProfileService
    * @param  {Object} options.logger
    * @return {Object} An instance of the DecisionService
    */