Add support for user profiles (#48)

* Stub out user profile service

* Implement user profile service interface and add tests

* Docstrings

* Stub user profile service

* Check that variation ID in user profile exists

* Add test case for error in user profile lookup, tighten assertions

* Logging assertions

* Symbolize UserProfile hash keys

* Add log message for variation IDs not in datafile

Author: delikat

lib/optimizely.rb

@@ -37,20 +37,22 @@ class Project
     attr_reader :event_dispatcher
     attr_reader :logger
 
-    def initialize(datafile, event_dispatcher = nil, logger = nil, error_handler = nil, skip_json_validation = false)
+    def initialize(datafile, event_dispatcher = nil, logger = nil, error_handler = nil, skip_json_validation = false, user_profile_service = nil)
       # Constructor for Projects.
       #
       # datafile - JSON string representing the project.
       # event_dispatcher - Provides a dispatch_event method which if given a URL and params sends a request to it.
-      # logger - Optional param which provides a log method to log messages. By default nothing would be logged.
-      # error_handler - Optional param which provides a handle_error method to handle exceptions.
+      # logger - Optional component which provides a log method to log messages. By default nothing would be logged.
+      # error_handler - Optional component which provides a handle_error method to handle exceptions.
       #                 By default all exceptions will be suppressed.
+      # user_profile_service - Optional component which provides methods to store and retreive user profiles.
       # skip_json_validation - Optional boolean param to skip JSON schema validation of the provided datafile.
 
       @is_valid = true
       @logger = logger || NoOpLogger.new
       @error_handler = error_handler || NoOpErrorHandler.new
       @event_dispatcher = event_dispatcher || EventDispatcher.new
+      @user_profile_service = user_profile_service
 
       begin
         validate_instantiation_options(datafile, skip_json_validation)
@@ -77,7 +79,7 @@ def initialize(datafile, event_dispatcher = nil, logger = nil, error_handler = n
         return
       end
 
-      @decision_service = DecisionService.new(@config)
+      @decision_service = DecisionService.new(@config, @user_profile_service)
       @event_builder = EventBuilderV2.new(@config)
     end
 

lib/optimizely/decision_service.rb

@@ -24,14 +24,16 @@ class DecisionService
     #
     # 1. Checking experiment status
     # 2. Checking whitelisting
+    # 3. Checking user profile service for past bucketing decisions (sticky bucketing)
     # 3. Checking audience targeting
     # 4. Using Murmurhash3 to bucket the user
 
     attr_reader :bucketer
     attr_reader :config
 
-    def initialize(config)
+    def initialize(config, user_profile_service = nil)
       @config = config
+      @user_profile_service = user_profile_service
       @bucketer = Bucketer.new(@config)
     end
 
@@ -50,21 +52,37 @@ def get_variation(experiment_key, user_id, attributes = nil)
         return nil
       end
 
+      experiment_id = @config.get_experiment_id(experiment_key)
+
       # Check if user is in a forced variation
-      variation_id = get_forced_variation_id(experiment_key, user_id)
-
-      if variation_id.nil?
-        unless Audience.user_in_experiment?(@config, experiment_key, attributes)
-          @config.logger.log(
-            Logger::INFO,
-            "User '#{user_id}' does not meet the conditions to be in experiment '#{experiment_key}'."
-          )
-          return nil
-        end
-
-        variation_id = @bucketer.bucket(experiment_key, user_id)
+      forced_variation_id = get_forced_variation_id(experiment_key, user_id)
+      return forced_variation_id if forced_variation_id
+
+      # Check for saved bucketing decisions
+      user_profile = get_user_profile(user_id)
+      saved_variation_id = get_saved_variation_id(experiment_id, user_profile)
+      if saved_variation_id
+        @config.logger.log(
+          Logger::INFO,
+          "Returning previously activated variation ID #{saved_variation_id} of experiment '#{experiment_key}' for user '#{user_id}' from user profile."
+        )
+        return saved_variation_id
+      end
+
+      # Check audience conditions
+      unless Audience.user_in_experiment?(@config, experiment_key, attributes)
+        @config.logger.log(
+          Logger::INFO,
+          "User '#{user_id}' does not meet the conditions to be in experiment '#{experiment_key}'."
+        )
+        return nil
       end
 
+      # Bucket normally
+      variation_id = @bucketer.bucket(experiment_key, user_id)
+
+      # Persist bucketing decision
+      save_user_profile(user_profile, experiment_id, variation_id)
       variation_id
     end
 
@@ -102,5 +120,71 @@ def get_forced_variation_id(experiment_key, user_id)
       )
       forced_variation_id
     end
+
+    def get_saved_variation_id(experiment_id, user_profile)
+      # Retrieve variation ID of stored bucketing decision for a given experiment from a given user profile
+      #
+      # experiment_id - String experiment ID
+      # user_profile - Hash user profile
+      #
+      # Returns string variation ID (nil if no decision is found)
+      return nil unless user_profile[:experiment_bucket_map]
+
+      decision = user_profile[:experiment_bucket_map][experiment_id]
+      return nil unless decision
+      variation_id = decision[:variation_id]
+      return variation_id if @config.variation_id_exists?(experiment_id, variation_id)
+
+      @config.logger.log(
+        Logger::INFO,
+        "User '#{user_profile['user_id']}' was previously bucketed into variation ID '#{variation_id}' for experiment '#{experiment_id}', but no matching variation was found. Re-bucketing user."
+      )
+      nil
+    end
+
+    def get_user_profile(user_id)
+      # Determine if a user is forced into a variation for the given experiment and return the ID of that variation
+      #
+      # user_id - String ID for the user
+      #
+      # Returns Hash stored user profile (or a default one if lookup fails or user profile service not provided) 
+
+      user_profile = {
+        :user_id => user_id,
+        :experiment_bucket_map => {}
+      }
+
+      return user_profile unless @user_profile_service
+
+      begin
+        user_profile = @user_profile_service.lookup(user_id) || user_profile
+      rescue => e
+        @config.logger.log(Logger::ERROR, "Error while looking up user profile for user ID '#{user_id}': #{e}.")
+      end
+
+      user_profile
+    end
+
+
+    def save_user_profile(user_profile, experiment_id, variation_id)
+      # Save a given bucketing decision to a given user profile
+      #
+      # user_profile - Hash user profile
+      # experiment_id - String experiment ID
+      # variation_id - String variation ID
+
+      return unless @user_profile_service
+
+      user_id = user_profile[:user_id]
+      begin
+        user_profile[:experiment_bucket_map][experiment_id] = {
+          :variation_id => variation_id
+        }
+        @user_profile_service.save(user_profile)
+        @config.logger.log(Logger::INFO, "Saved variation ID #{variation_id} of experiment ID #{experiment_id} for user '#{user_id}'.")
+      rescue => e
+        @config.logger.log(Logger::ERROR, "Error while saving user profile for user ID '#{user_id}': #{e}.")
+      end
+    end
   end
 end

lib/optimizely/project_config.rb

@@ -294,6 +294,29 @@ def parsing_succeeded?
       @parsing_succeeded
     end
 
+    def variation_id_exists?(experiment_id, variation_id)
+      # Determines if a given experiment ID / variation ID pair exists in the datafile
+      #
+      # experiment_id - String experiment ID
+      # variation_id - String variation ID
+      #
+      # Returns true if variation is in datafile
+
+      experiment_key = get_experiment_key(experiment_id)
+      variation_id_map = @variation_id_map[experiment_key]
+      if variation_id_map
+        variation = variation_id_map[variation_id]
+        return true if variation
+        @logger.log Logger::ERROR, "Variation ID '#{variation_id}' is not in datafile."
+        @error_handler.handle_error InvalidVariationError
+        return false
+      end
+
+      @logger.log Logger::ERROR, "Experiment ID '#{experiment_id}' is not in datafile."
+      @error_handler.handle_error InvalidExperimentError
+      false
+    end
+
     private
 
     def generate_key_map(array, key)

lib/optimizely/user_profile_service.rb

@@ -0,0 +1,36 @@
+#
+#    Copyright 2017, Optimizely and contributors
+#
+#    Licensed under the Apache License, Version 2.0 (the "License");
+#    you may not use this file except in compliance with the License.
+#    You may obtain a copy of the License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS,
+#    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#    See the License for the specific language governing permissions and
+#    limitations under the License.
+#
+
+module Optimizely
+  class BaseUserProfileService
+    # Class encapsulating user profile service functionality.
+    # Override with your own implementation for storing and retrieving user profiles.
+
+    def lookup(user_id)
+      # Retrieve the Hash user profile associated with a given user ID.
+      #
+      # user_id - String user ID
+      #
+      # Returns Hash user profile.
+    end
+
+    def save(user_profile)
+      # Saves a given user profile.
+      #
+      # user_profile - Hash user profile.
+    end
+  end
+end

spec/decision_service_spec.rb

@@ -22,15 +22,19 @@
   let(:config_body_JSON) { OptimizelySpec::V2_CONFIG_BODY_JSON }
   let(:error_handler) { Optimizely::NoOpErrorHandler.new }
   let(:spy_logger) { spy('logger') }
+  let(:spy_user_profile_service) { spy('user_profile_service') }
   let(:config) { Optimizely::ProjectConfig.new(config_body_JSON, spy_logger, error_handler) }
-  let(:decision_service) { Optimizely::DecisionService.new(config) }
+  let(:decision_service) { Optimizely::DecisionService.new(config, spy_user_profile_service) }
 
   describe '#get_variation' do
     before(:example) do
       # stub out bucketer and audience evaluator so we can make sure they are / aren't called
       allow(decision_service.bucketer).to receive(:bucket).and_call_original
       allow(decision_service).to receive(:get_forced_variation_id).and_call_original
       allow(Optimizely::Audience).to receive(:user_in_experiment?).and_call_original
+
+      # by default, spy user profile service should no-op. we override this behavior in specific tests
+      allow(spy_user_profile_service).to receive(:lookup).and_return(nil)
     end
 
     it 'should return the correct variation ID for a given user ID and key of a running experiment' do
@@ -118,5 +122,135 @@
       # bucketing should have occured
       expect(decision_service.bucketer).to have_received(:bucket).once.with('test_experiment', 'forced_user_with_invalid_variation')
     end
+
+    describe 'when a UserProfile service is provided' do
+      it 'should look up the UserProfile, bucket normally, and save the result if no saved profile is found' do
+        expected_user_profile = {
+          :user_id => 'test_user',
+          :experiment_bucket_map => {
+            '111127' => {
+              :variation_id => '111128'
+            }
+          }
+        }
+        expect(spy_user_profile_service).to receive(:lookup).once.and_return(nil)
+
+        expect(decision_service.get_variation('test_experiment', 'test_user')).to eq('111128')
+
+        # bucketing should have occurred
+        expect(decision_service.bucketer).to have_received(:bucket).once
+        # bucketing decision should have been saved
+        expect(spy_user_profile_service).to have_received(:save).once.with(expected_user_profile)
+        expect(spy_logger).to have_received(:log).once
+                          .with(Logger::INFO, "Saved variation ID 111128 of experiment ID 111127 for user 'test_user'.")
+      end
+
+      it 'should look up the user profile and skip normal bucketing if a profile with a saved decision is found' do
+        saved_user_profile = {
+          :user_id => 'test_user',
+          :experiment_bucket_map => {
+            '111127' => {
+              :variation_id => '111129'
+            }
+          }
+        }
+        expect(spy_user_profile_service).to receive(:lookup)
+                                        .with('test_user').once.and_return(saved_user_profile)
+
+        expect(decision_service.get_variation('test_experiment', 'test_user')).to eq('111129')
+        expect(spy_logger).to have_received(:log).once
+                          .with(Logger::INFO, "Returning previously activated variation ID 111129 of experiment 'test_experiment' for user 'test_user' from user profile.")
+
+        # saved user profiles should short circuit bucketing
+        expect(decision_service.bucketer).not_to have_received(:bucket)
+        # saved user profiles should short circuit audience evaluation
+        expect(Optimizely::Audience).not_to have_received(:user_in_experiment?)
+        # the user profile should not be updated if bucketing did not take place
+        expect(spy_user_profile_service).not_to have_received(:save)
+      end
+
+      it 'should look up the user profile and bucket normally if a profile without a saved decision is found' do
+        saved_user_profile = {
+          :user_id => 'test_user',
+          :experiment_bucket_map => {
+            # saved decision, but not for this experiment
+            '122227' => {
+              :variation_id => '122228'
+            }
+          }
+        }
+        expect(spy_user_profile_service).to receive(:lookup)
+                                        .once.with('test_user').and_return(saved_user_profile)
+
+        expect(decision_service.get_variation('test_experiment', 'test_user')).to eq('111128')
+
+        # bucketing should have occurred
+        expect(decision_service.bucketer).to have_received(:bucket).once
+
+        # user profile should have been updated with bucketing decision
+        expected_user_profile = {
+          :user_id => 'test_user',
+          :experiment_bucket_map => {
+            '111127' => {
+              :variation_id => '111128'
+            },
+            '122227' => {
+              :variation_id => '122228'
+            }
+          }
+        }
+        expect(spy_user_profile_service).to have_received(:save).once.with(expected_user_profile)
+      end
+
+      it 'should bucket normally if the user profile contains a variation ID not in the datafile' do
+        saved_user_profile = {
+          :user_id => 'test_user',
+          :experiment_bucket_map => {
+            # saved decision, but with invalid variation ID
+            '111127' => {
+              :variation_id => '111111'
+            }
+          }
+        }
+        expect(spy_user_profile_service).to receive(:lookup)
+                                        .once.with('test_user').and_return(saved_user_profile)
+
+        expect(decision_service.get_variation('test_experiment', 'test_user')).to eq('111128')
+
+        # bucketing should have occurred
+        expect(decision_service.bucketer).to have_received(:bucket).once
+
+        # user profile should have been updated with bucketing decision
+        expected_user_profile = {
+          :user_id => 'test_user',
+          :experiment_bucket_map => {
+            '111127' => {
+              :variation_id => '111128'
+            }
+          }
+        }
+        expect(spy_user_profile_service).to have_received(:save).with(expected_user_profile)
+      end
+
+      it 'should bucket normally if the user profile service throws an error during lookup' do
+        expect(spy_user_profile_service).to receive(:lookup).once.with('test_user').and_throw(:LookupError)
+
+        expect(decision_service.get_variation('test_experiment', 'test_user')).to eq('111128')
+
+        expect(spy_logger).to have_received(:log).once
+                          .with(Logger::ERROR, "Error while looking up user profile for user ID 'test_user': uncaught throw :LookupError.")
+        # bucketing should have occurred
+        expect(decision_service.bucketer).to have_received(:bucket).once
+      end
+
+      it 'should log an error if the user profile service throws an error during save' do
+        expect(spy_user_profile_service).to receive(:save).once.and_throw(:SaveError)
+
+        expect(decision_service.get_variation('test_experiment', 'test_user')).to eq('111128')
+
+        expect(spy_logger).to have_received(:log).once
+                          .with(Logger::ERROR, "Error while saving user profile for user ID 'test_user': uncaught throw :SaveError.")
+      end
+    end
   end
 end