optimizely-sdk 5.1.0 → 5.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 79f6fce62ba26147eef50a92fefb2cb443df50b2b3a0f4c15f75352f4052aaa8
-  data.tar.gz: d09bfd23ad927fa5ae62c03467647c65bc21ac68d19d88dc81ef6dea441a25bf
+  metadata.gz: f3e60440f1cc553ee8c1eac5ffc7657b6f4de011a4d53a31674c0f5f68843b68
+  data.tar.gz: 2e9f30000ddabe5118f32d4afda400f02db039b0e1e8ffca23d0bd96439ef71c
 SHA512:
-  metadata.gz: 74e1e587ffdcadfcbbea0677d0de60376e7f677a8254d1e121d37994301c5ebd1959e21ff7bfea1493a441835a20e135dc4d4a4f1577939772b6e167d35f2789
-  data.tar.gz: 57c17f7508daeaed88755b9dc4463f019fb5b5a523c32cf5639375c06a07dd563786001282e59496d5e8c149c5d884ea5c16522d52edef03c40a0b9ff1890879
+  metadata.gz: b563647ea0496d3c1b65d478c00918729e95b32b74e1260c34b92c2115d791101bfa0f22450b92185172773a8c16ae2cb36854f69792652da259b99499f28acd
+  data.tar.gz: '038f0fd4bf0280b7d68a33bf7b0bb27f3efe482ef94995bb53751966e9fa7c4b3229fb62a513c2b88458557280b27e339a3222a459649d8b91e837e3e13adb00'

data/lib/optimizely/audience.rb

@@ -49,7 +49,7 @@ module Optimizely
       logger.log(Logger::DEBUG, message)
 
       # Return true if there are no audiences
-      if audience_conditions.empty?
+      if audience_conditions.nil? || audience_conditions.empty?
         message = format(logs_hash['AUDIENCE_EVALUATION_RESULT_COMBINED'], logging_key, 'TRUE')
         logger.log(Logger::INFO, message)
         decide_reasons.push(message)
@@ -72,6 +72,20 @@ module Optimizely
         decide_reasons.push(message)
 
         audience_conditions = JSON.parse(audience_conditions) if audience_conditions.is_a?(String)
+        # Convert all symbol keys to string keys in the parsed conditions
+        stringify_keys = lambda do |obj|
+          case obj
+          when Hash
+            obj.transform_keys(&:to_s).transform_values { |v| stringify_keys.call(v) }
+          when Array
+            obj.map { |item| stringify_keys.call(item) }
+          else
+            obj
+          end
+        end
+
+        audience_conditions = stringify_keys.call(audience_conditions)
+
         result = ConditionTreeEvaluator.evaluate(audience_conditions, evaluate_user_conditions)
         result_str = result.nil? ? 'UNKNOWN' : result.to_s.upcase
         message = format(logs_hash['AUDIENCE_EVALUATION_RESULT'], audience_id, result_str)

data/lib/optimizely/bucketer.rb

@@ -44,6 +44,31 @@ module Optimizely
       # user_id - String ID for user.
       #
       # Returns variation in which visitor with ID user_id has been placed. Nil if no variation.
+
+      if experiment.nil? || experiment['key'].to_s.strip.empty?
+        message = 'Invalid entity key provided for bucketing. Returning nil.'
+        @logger.log(Logger::DEBUG, message)
+        return nil, []
+      end
+
+      variation_id, decide_reasons = bucket_to_entity_id(project_config, experiment, bucketing_id, user_id)
+      if variation_id && variation_id != ''
+        experiment_id = experiment['id']
+        variation = project_config.get_variation_from_id_by_experiment_id(experiment_id, variation_id)
+        return variation, decide_reasons
+      end
+
+      # Handle the case when the traffic range is empty due to sticky bucketing
+      if variation_id == ''
+        message = 'Bucketed into an empty traffic range. Returning nil.'
+        @logger.log(Logger::DEBUG, message)
+        decide_reasons.push(message)
+      end
+
+      [nil, decide_reasons]
+    end
+
+    def bucket_to_entity_id(project_config, experiment, bucketing_id, user_id)
       return nil, [] if experiment.nil?
 
       decide_reasons = []
@@ -84,22 +109,18 @@ module Optimizely
       end
 
       traffic_allocations = experiment['trafficAllocation']
+      if experiment['cmab']
+        traffic_allocations = [
+          {
+            'entityId' => '$',
+            'endOfRange' => experiment['cmab']['trafficAllocation']
+          }
+        ]
+      end
       variation_id, find_bucket_reasons = find_bucket(bucketing_id, user_id, experiment_id, traffic_allocations)
       decide_reasons.push(*find_bucket_reasons)
 
-      if variation_id && variation_id != ''
-        variation = project_config.get_variation_from_id_by_experiment_id(experiment_id, variation_id)
-        return variation, decide_reasons
-      end
-
-      # Handle the case when the traffic range is empty due to sticky bucketing
-      if variation_id == ''
-        message = 'Bucketed into an empty traffic range. Returning nil.'
-        @logger.log(Logger::DEBUG, message)
-        decide_reasons.push(message)
-      end
-
-      [nil, decide_reasons]
+      [variation_id, decide_reasons]
     end
 
     def find_bucket(bucketing_id, user_id, parent_id, traffic_allocations)

data/lib/optimizely/cmab/cmab_client.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+#
+#    Copyright 2025 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.
+#
+require 'optimizely/helpers/http_utils'
+require 'optimizely/helpers/constants'
+
+module Optimizely
+  # Default constants for CMAB requests
+  DEFAULT_MAX_RETRIES = 1
+  DEFAULT_INITIAL_BACKOFF = 0.1 # in seconds (100 ms)
+  DEFAULT_MAX_BACKOFF = 10 # in seconds
+  DEFAULT_BACKOFF_MULTIPLIER = 2.0
+  MAX_WAIT_TIME = 10
+
+  class CmabRetryConfig
+    # Configuration for retrying CMAB requests.
+    # Contains parameters for maximum retries, backoff intervals, and multipliers.
+    attr_reader :max_retries, :initial_backoff, :max_backoff, :backoff_multiplier
+
+    def initialize(max_retries: DEFAULT_MAX_RETRIES, initial_backoff: DEFAULT_INITIAL_BACKOFF, max_backoff: DEFAULT_MAX_BACKOFF, backoff_multiplier: DEFAULT_BACKOFF_MULTIPLIER)
+      @max_retries = max_retries
+      @initial_backoff = initial_backoff
+      @max_backoff = max_backoff
+      @backoff_multiplier = backoff_multiplier
+    end
+  end
+
+  class DefaultCmabClient
+    # Client for interacting with the CMAB service.
+    # Provides methods to fetch decisions with optional retry logic.
+
+    def initialize(http_client: nil, retry_config: nil, logger: nil, prediction_endpoint: nil)
+      # Initialize the CMAB client.
+      # Args:
+      #   http_client: HTTP client for making requests.
+      #   retry_config: Configuration for retry settings.
+      #   logger: Logger for logging errors and info.
+      #   prediction_endpoint: Custom prediction endpoint URL template.
+      #                        Use #{rule_id} as placeholder for rule_id.
+      @http_client = http_client || DefaultHttpClient.new
+      @retry_config = retry_config || CmabRetryConfig.new
+      @logger = logger || NoOpLogger.new
+      @prediction_endpoint = if prediction_endpoint.to_s.strip.empty?
+                               'https://prediction.cmab.optimizely.com/predict/%s'
+                             else
+                               prediction_endpoint
+                             end
+    end
+
+    def fetch_decision(rule_id, user_id, attributes, cmab_uuid, timeout: MAX_WAIT_TIME)
+      # Fetches a decision from the CMAB service.
+      # Args:
+      #   rule_id: The rule ID for the experiment.
+      #   user_id: The user ID for the request.
+      #   attributes: User attributes for the request.
+      #   cmab_uuid: Unique identifier for the CMAB request.
+      #   timeout: Maximum wait time for the request to respond in seconds. (default is 10 seconds).
+      # Returns:
+      #   The variation ID.
+      url = format(@prediction_endpoint, rule_id)
+      cmab_attributes = attributes.map { |key, value| {'id' => key.to_s, 'value' => value, 'type' => 'custom_attribute'} }
+
+      request_body = {
+        instances: [{
+          visitorId: user_id,
+          experimentId: rule_id,
+          attributes: cmab_attributes,
+          cmabUUID: cmab_uuid
+        }]
+      }
+
+      if @retry_config && @retry_config.max_retries.to_i.positive?
+        _do_fetch_with_retry(url, request_body, @retry_config, timeout)
+      else
+        _do_fetch(url, request_body, timeout)
+      end
+    end
+
+    def _do_fetch(url, request_body, timeout)
+      # Perform a single fetch request to the CMAB prediction service.
+
+      # Args:
+      #   url: The endpoint URL.
+      #   request_body: The request payload.
+      #   timeout: Maximum wait time for the request to respond in seconds.
+      # Returns:
+      #   The variation ID from the response.
+
+      headers = {'Content-Type' => 'application/json'}
+      begin
+        response = @http_client.post(url, json: request_body, headers: headers, timeout: timeout.to_i)
+      rescue StandardError => e
+        error_message = Optimizely::Helpers::Constants::CMAB_FETCH_FAILED % e.message
+        @logger.log(Logger::ERROR, error_message)
+        raise CmabFetchError, error_message
+      end
+
+      unless (200..299).include?(response.status_code)
+        error_message = Optimizely::Helpers::Constants::CMAB_FETCH_FAILED % response.status_code
+        @logger.log(Logger::ERROR, error_message)
+        raise CmabFetchError, error_message
+      end
+
+      begin
+        body = response.json
+      rescue JSON::ParserError, Optimizely::CmabInvalidResponseError
+        error_message = Optimizely::Helpers::Constants::INVALID_CMAB_FETCH_RESPONSE
+        @logger.log(Logger::ERROR, error_message)
+        raise CmabInvalidResponseError, error_message
+      end
+
+      unless validate_response(body)
+        error_message = Optimizely::Helpers::Constants::INVALID_CMAB_FETCH_RESPONSE
+        @logger.log(Logger::ERROR, error_message)
+        raise CmabInvalidResponseError, error_message
+      end
+
+      body['predictions'][0]['variation_id']
+    end
+
+    def validate_response(body)
+      # Validate the response structure from the CMAB service.
+      # Args:
+      #   body: The JSON response body to validate.
+      # Returns:
+      #   true if valid, false otherwise.
+
+      body.is_a?(Hash) &&
+        body.key?('predictions') &&
+        body['predictions'].is_a?(Array) &&
+        !body['predictions'].empty? &&
+        body['predictions'][0].is_a?(Hash) &&
+        body['predictions'][0].key?('variation_id')
+    end
+
+    def _do_fetch_with_retry(url, request_body, retry_config, timeout)
+      # Perform a fetch request with retry logic.
+      # Args:
+      #   url: The endpoint URL.
+      #   request_body: The request payload.
+      #   retry_config: Configuration for retry settings.
+      #   timeout: Maximum wait time for the request to respond in seconds.
+      # Returns:
+      #   The variation ID from the response.
+
+      backoff = retry_config.initial_backoff
+
+      (0..retry_config.max_retries).each do |attempt|
+        variation_id = _do_fetch(url, request_body, timeout)
+        return variation_id
+      rescue StandardError => e
+        if attempt < retry_config.max_retries
+          @logger.log(Logger::INFO, "Retrying CMAB request (attempt #{attempt + 1}) after #{backoff} seconds...")
+          Kernel.sleep(backoff)
+
+          backoff = [
+            backoff * retry_config.backoff_multiplier,
+            retry_config.max_backoff
+          ].min
+        else
+          @logger.log(Logger::ERROR, "Max retries exceeded for CMAB request: #{e.message}")
+          raise Optimizely::CmabFetchError, "CMAB decision fetch failed (#{e.message})."
+        end
+      end
+    end
+  end
+
+  class DefaultHttpClient
+    # Default HTTP client for making requests.
+    # Uses Optimizely::Helpers::HttpUtils to make requests.
+
+    def post(url, json: nil, headers: {}, timeout: nil)
+      # Makes a POST request to the specified URL with JSON body and headers.
+      # Args:
+      #   url: The endpoint URL.
+      #   json: The JSON payload to send in the request body.
+      #   headers: Additional headers for the request.
+      #   timeout: Maximum wait time for the request to respond in seconds.
+      # Returns:
+      #   The response object.
+
+      response = Optimizely::Helpers::HttpUtils.make_request(url, :post, json.to_json, headers, timeout)
+
+      HttpResponseAdapter.new(response)
+    end
+
+    class HttpResponseAdapter
+      # Adapter for HTTP response to provide a consistent interface.
+      # Args:
+      #   response: The raw HTTP response object.
+
+      def initialize(response)
+        @response = response
+      end
+
+      def status_code
+        @response.code.to_i
+      end
+
+      def json
+        JSON.parse(@response.body)
+      rescue JSON::ParserError
+        raise Optimizely::CmabInvalidResponseError, Optimizely::Helpers::Constants::INVALID_CMAB_FETCH_RESPONSE
+      end
+
+      def body
+        @response.body
+      end
+    end
+  end
+
+  class NoOpLogger
+    # A no-operation logger that does nothing.
+    def log(_level, _message); end
+  end
+end

data/lib/optimizely/cmab/cmab_service.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+#
+#    Copyright 2025 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.
+#
+require 'optimizely/odp/lru_cache'
+require 'optimizely/decide/optimizely_decide_option'
+require 'optimizely/logger'
+require 'digest'
+require 'json'
+require 'securerandom'
+require 'murmurhash3'
+
+module Optimizely
+  CmabDecision = Struct.new(:variation_id, :cmab_uuid, keyword_init: true)
+  CmabCacheValue = Struct.new(:attributes_hash, :variation_id, :cmab_uuid, keyword_init: true)
+
+  class DefaultCmabCacheOptions
+    # CMAB Constants
+    DEFAULT_CMAB_CACHE_TIMEOUT = (30 * 60) # in seconds
+    DEFAULT_CMAB_CACHE_SIZE = 10_000
+  end
+
+  # Default CMAB service implementation
+  class DefaultCmabService
+    # Initializes a new instance of the CmabService.
+    #
+    # @param cmab_cache [LRUCache] The cache object used for storing CMAB data. Must be an instance of LRUCache.
+    # @param cmab_client [DefaultCmabClient] The client used to interact with the CMAB service. Must be an instance of DefaultCmabClient.
+    # @param logger [Logger, nil] Optional logger for logging messages. Defaults to nil.
+    #
+    # @raise [ArgumentError] If cmab_cache is not an instance of LRUCache.
+    # @raise [ArgumentError] If cmab_client is not an instance of DefaultCmabClient.
+
+    NUM_LOCK_STRIPES = 1000
+
+    def initialize(cmab_cache, cmab_client, logger = nil)
+      @cmab_cache = cmab_cache
+      @cmab_client = cmab_client
+      @logger = logger || NoOpLogger.new
+      @locks = Array.new(NUM_LOCK_STRIPES) { Mutex.new }
+    end
+
+    def get_decision(project_config, user_context, rule_id, options)
+      lock_index = get_lock_index(user_context.user_id, rule_id)
+
+      @locks[lock_index].synchronize do
+        get_decision_impl(project_config, user_context, rule_id, options)
+      end
+    end
+
+    private
+
+    def get_lock_index(user_id, rule_id)
+      # Create a hash of user_id + rule_id for consistent lock selection
+      hash_input = "#{user_id}#{rule_id}"
+      hash_value = MurmurHash3::V32.str_hash(hash_input, 1) & 0xFFFFFFFF # Convert to unsigned 32-bit equivalent
+      hash_value % NUM_LOCK_STRIPES
+    end
+
+    def get_decision_impl(project_config, user_context, rule_id, options)
+      # Retrieves a decision for a given user and rule, utilizing a cache for efficiency.
+      #
+      # This method filters user attributes, checks for various cache-related options,
+      # and either fetches a fresh decision or returns a cached one if appropriate.
+      # It supports options to ignore the cache, reset the cache, or invalidate a specific user's cache entry.
+      #
+      # @param project_config [Object] The project configuration object.
+      # @param user_context [Object] The user context containing user_id and attributes.
+      # @param rule_id [String] The identifier for the decision rule.
+      # @param options [Array<Symbol>, nil] Optional flags to control cache behavior. Supported options:
+      #   - OptimizelyDecideOption::IGNORE_CMAB_CACHE: Bypass cache and fetch a new decision.
+      #   - OptimizelyDecideOption::RESET_CMAB_CACHE: Reset the entire cache.
+      #   - OptimizelyDecideOption::INVALIDATE_USER_CMAB_CACHE: Invalidate cache for the specific user and rule.
+      #
+      # @return [CmabDecision] The decision object containing variation_id and cmab_uuid.
+
+      filtered_attributes = filter_attributes(project_config, user_context, rule_id)
+      reasons = []
+
+      if options&.include?(Decide::OptimizelyDecideOption::IGNORE_CMAB_CACHE)
+        reason = "Ignoring CMAB cache for user '#{user_context.user_id}' and rule '#{rule_id}'"
+        @logger.log(Logger::DEBUG, reason)
+        reasons << reason
+        cmab_decision = fetch_decision(rule_id, user_context.user_id, filtered_attributes)
+        return [cmab_decision, reasons]
+      end
+
+      if options&.include?(Decide::OptimizelyDecideOption::RESET_CMAB_CACHE)
+        reason = "Resetting CMAB cache for user '#{user_context.user_id}' and rule '#{rule_id}'"
+        @logger.log(Logger::DEBUG, reason)
+        reasons << reason
+        @cmab_cache.reset
+      end
+
+      cache_key = get_cache_key(user_context.user_id, rule_id)
+
+      if options&.include?(Decide::OptimizelyDecideOption::INVALIDATE_USER_CMAB_CACHE)
+        reason = "Invalidating CMAB cache for user '#{user_context.user_id}' and rule '#{rule_id}'"
+        @logger.log(Logger::DEBUG, reason)
+        reasons << reason
+        @cmab_cache.remove(cache_key)
+      end
+
+      cached_value = @cmab_cache.lookup(cache_key)
+      attributes_hash = hash_attributes(filtered_attributes)
+
+      if cached_value
+        if cached_value.attributes_hash == attributes_hash
+          reason = "CMAB cache hit for user '#{user_context.user_id}' and rule '#{rule_id}'"
+          @logger.log(Logger::DEBUG, reason)
+          reasons << reason
+          return [CmabDecision.new(variation_id: cached_value.variation_id, cmab_uuid: cached_value.cmab_uuid), reasons]
+        else
+          reason = "CMAB cache attributes mismatch for user '#{user_context.user_id}' and rule '#{rule_id}', fetching new decision."
+          @logger.log(Logger::DEBUG, reason)
+          reasons << reason
+          @cmab_cache.remove(cache_key)
+        end
+      else
+        reason = "CMAB cache miss for user '#{user_context.user_id}' and rule '#{rule_id}'"
+        @logger.log(Logger::DEBUG, reason)
+        reasons << reason
+      end
+
+      cmab_decision = fetch_decision(rule_id, user_context.user_id, filtered_attributes)
+      reason = "CMAB decision is #{cmab_decision.to_h}"
+      @logger.log(Logger::DEBUG, reason)
+      reasons << reason
+
+      @cmab_cache.save(cache_key,
+                       CmabCacheValue.new(
+                         attributes_hash: attributes_hash,
+                         variation_id: cmab_decision.variation_id,
+                         cmab_uuid: cmab_decision.cmab_uuid
+                       ))
+      [cmab_decision, reasons]
+    end
+
+    def fetch_decision(rule_id, user_id, attributes)
+      # Fetches a decision for a given rule and user, along with user attributes.
+      #
+      # Generates a unique UUID for the decision request, then delegates to the CMAB client
+      # to fetch the variation ID. Returns a CmabDecision object containing the variation ID
+      # and the generated UUID.
+      #
+      # @param rule_id [String] The identifier for the rule to evaluate.
+      # @param user_id [String] The identifier for the user.
+      # @param attributes [Hash] A hash of user attributes to be used in decision making.
+      # @return [CmabDecision] The decision object containing the variation ID and UUID.
+      cmab_uuid = SecureRandom.uuid
+      variation_id = @cmab_client.fetch_decision(rule_id, user_id, attributes, cmab_uuid)
+      CmabDecision.new(variation_id: variation_id, cmab_uuid: cmab_uuid)
+    end
+
+    def filter_attributes(project_config, user_context, rule_id)
+      # Filters the user attributes based on the CMAB attribute IDs defined in the experiment.
+      #
+      # @param project_config [Object] The project configuration object containing experiment and attribute mappings.
+      # @param user_context [Object] The user context object containing user attributes.
+      # @param rule_id [String] The ID of the experiment (rule) to filter attributes for.
+      # @return [Hash] A hash of filtered user attributes whose keys match the CMAB attribute IDs for the given experiment.
+      user_attributes = user_context.user_attributes
+      filtered_user_attributes = {}
+
+      experiment = project_config.experiment_id_map[rule_id]
+      return filtered_user_attributes if experiment.nil? || experiment['cmab'].nil?
+
+      cmab_attribute_ids = experiment['cmab']['attributeIds']
+      cmab_attribute_ids.each do |attribute_id|
+        attribute = project_config.attribute_id_map[attribute_id]
+        next unless attribute
+
+        attribute_key = attribute['key']
+        filtered_user_attributes[attribute_key] = user_attributes[attribute_key] if user_attributes.key?(attribute_key)
+      end
+
+      filtered_user_attributes
+    end
+
+    def get_cache_key(user_id, rule_id)
+      # Generates a cache key string based on the provided user ID and rule ID.
+      #
+      # The cache key is constructed in the format: "<user_id_length>-<user_id>-<rule_id>",
+      # where <user_id_length> is the length of the user_id string.
+      #
+      # @param user_id [String] The unique identifier for the user.
+      # @param rule_id [String] The unique identifier for the rule.
+      # @return [String] The generated cache key.
+      "#{user_id.length}-#{user_id}-#{rule_id}"
+    end
+
+    def hash_attributes(attributes)
+      # Generates an MD5 hash for a given attributes hash.
+      #
+      # The method sorts the attributes by key, serializes them to a JSON string,
+      # and then computes the MD5 hash of the resulting string. This ensures that
+      # the hash is consistent regardless of the original key order in the input hash.
+      #
+      # @param attributes [Hash] The attributes to be hashed.
+      # @return [String] The MD5 hash of the sorted and serialized attributes.
+      sorted_attrs = JSON.generate(attributes.sort.to_h)
+      Digest::MD5.hexdigest(sorted_attrs)
+    end
+  end
+end