[FSSDK-11167] Implement CMAB service (#367)

* update: Extend LRUCache with remove method and corresponding tests

* update: Clean up whitespace in LRUCache implementation and tests

* update: Extend copyright notice to include 2025

* update: Implement Default CMAB Service

* update: Enable keyword initialization for CmabDecision and CmabCacheValue structs (otherwise breaks in ruby version change)

Author: FarhanAnjum-opti

lib/optimizely/cmab/cmab_service.rb

@@ -0,0 +1,153 @@
+# 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 'digest'
+require 'json'
+require 'securerandom'
+
+module Optimizely
+  CmabDecision = Struct.new(:variation_id, :cmab_uuid, keyword_init: true)
+  CmabCacheValue = Struct.new(:attributes_hash, :variation_id, :cmab_uuid, keyword_init: true)
+
+  # 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.
+    def initialize(cmab_cache, cmab_client, logger = nil)
+      @cmab_cache = cmab_cache
+      @cmab_client = cmab_client
+      @logger = logger
+    end
+
+    def get_decision(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)
+
+      return fetch_decision(rule_id, user_context.user_id, filtered_attributes) if options&.include?(Decide::OptimizelyDecideOption::IGNORE_CMAB_CACHE)
+
+      @cmab_cache.reset if options&.include?(Decide::OptimizelyDecideOption::RESET_CMAB_CACHE)
+
+      cache_key = get_cache_key(user_context.user_id, rule_id)
+
+      @cmab_cache.remove(cache_key) if options&.include?(Decide::OptimizelyDecideOption::INVALIDATE_USER_CMAB_CACHE)
+      cached_value = @cmab_cache.lookup(cache_key)
+      attributes_hash = hash_attributes(filtered_attributes)
+
+      if cached_value
+        return CmabDecision.new(variation_id: cached_value.variation_id, cmab_uuid: cached_value.cmab_uuid) if cached_value.attributes_hash == attributes_hash
+
+        @cmab_cache.remove(cache_key)
+      end
+      cmab_decision = fetch_decision(rule_id, user_context.user_id, filtered_attributes)
+      @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
+    end
+
+    private
+
+    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]
+        filtered_user_attributes[attribute.key] = user_attributes[attribute.key] if attribute && 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

lib/optimizely/config/datafile_project_config.rb

@@ -27,7 +27,8 @@ class DatafileProjectConfig < ProjectConfig
     attr_reader :datafile, :account_id, :attributes, :audiences, :typed_audiences, :events,
                 :experiments, :feature_flags, :groups, :project_id, :bot_filtering, :revision,
                 :sdk_key, :environment_key, :rollouts, :version, :send_flag_decisions,
-                :attribute_key_map, :attribute_id_to_key_map, :audience_id_map, :event_key_map, :experiment_feature_map,
+                :attribute_key_map, :attribute_id_to_key_map, :attribute_id_map,
+                :audience_id_map, :event_key_map, :experiment_feature_map,
                 :experiment_id_map, :experiment_key_map, :feature_flag_key_map, :feature_variable_key_map,
                 :group_id_map, :rollout_id_map, :rollout_experiment_id_map, :variation_id_map,
                 :variation_id_to_variable_usage_map, :variation_key_map, :variation_id_map_by_experiment_id,
@@ -82,6 +83,7 @@ def initialize(datafile, logger, error_handler)
 
       # Utility maps for quick lookup
       @attribute_key_map = generate_key_map(@attributes, 'key')
+      @attribute_id_map = generate_key_map(@attributes, 'id')
       @attribute_id_to_key_map = {}
       @attributes.each do |attribute|
         @attribute_id_to_key_map[attribute['id']] = attribute['key']

lib/optimizely/decide/optimizely_decide_option.rb

@@ -23,6 +23,9 @@ module OptimizelyDecideOption
       IGNORE_USER_PROFILE_SERVICE = 'IGNORE_USER_PROFILE_SERVICE'
       INCLUDE_REASONS = 'INCLUDE_REASONS'
       EXCLUDE_VARIABLES = 'EXCLUDE_VARIABLES'
+      IGNORE_CMAB_CACHE = 'IGNORE_CMAB_CACHE'
+      RESET_CMAB_CACHE = 'RESET_CMAB_CACHE'
+      INVALIDATE_USER_CMAB_CACHE = 'INVALIDATE_USER_CMAB_CACHE'
     end
   end
 end