Skip to content

[FSSDK-11167] Implement CMAB service #367

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 5 commits into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
153 changes: 153 additions & 0 deletions lib/optimizely/cmab/cmab_service.rb
Original file line number Diff line number Diff line change
@@ -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
4 changes: 3 additions & 1 deletion lib/optimizely/config/datafile_project_config.rb
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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']
Expand Down
3 changes: 3 additions & 0 deletions lib/optimizely/decide/optimizely_decide_option.rb
Original file line number Diff line number Diff line change
Expand Up @@ -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
15 changes: 14 additions & 1 deletion lib/optimizely/odp/lru_cache.rb
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# frozen_string_literal: true

#
# Copyright 2022, Optimizely and contributors
# Copyright 2022-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.
Expand Down Expand Up @@ -91,6 +91,19 @@ def peek(key)

@cache_mutex.synchronize { @map[key]&.value }
end

# Remove the element associated with the provided key from the cache
#
# @param key - The key to remove

def remove(key)
return if @capacity <= 0

@cache_mutex.synchronize do
@map.delete(key)
end
nil
end
end

class CacheElement
Expand Down
File renamed without changes.
Loading