diff --git a/lib/optimizely/cmab/cmab_client.rb b/lib/optimizely/cmab/cmab_client.rb new file mode 100644 index 00000000..113f1d4a --- /dev/null +++ b/lib/optimizely/cmab/cmab_client.rb @@ -0,0 +1,223 @@ +# 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 = 3 + 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) + # 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. + @http_client = http_client || DefaultHttpClient.new + @retry_config = retry_config || CmabRetryConfig.new + @logger = logger || NoOpLogger.new + 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 = "https://prediction.cmab.optimizely.com/predict/#{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]['variationId'] + 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?('variationId') + 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 diff --git a/lib/optimizely/exceptions.rb b/lib/optimizely/exceptions.rb index 5d608b2f..073433af 100644 --- a/lib/optimizely/exceptions.rb +++ b/lib/optimizely/exceptions.rb @@ -190,4 +190,28 @@ def initialize(msg = 'Provided semantic version is invalid.') super end end + + class CmabError < Error + # Base exception for CMAB errors + + def initialize(msg = 'CMAB error occurred.') + super + end + end + + class CmabFetchError < CmabError + # Exception raised when CMAB fetch fails + + def initialize(msg = 'CMAB decision fetch failed with status:') + super + end + end + + class CmabInvalidResponseError < CmabError + # Exception raised when CMAB fetch returns an invalid response + + def initialize(msg = 'Invalid CMAB fetch response') + super + end + end end diff --git a/lib/optimizely/helpers/constants.rb b/lib/optimizely/helpers/constants.rb index 7b57a268..af3e5a08 100644 --- a/lib/optimizely/helpers/constants.rb +++ b/lib/optimizely/helpers/constants.rb @@ -469,6 +469,9 @@ module Constants 'IF_MODIFIED_SINCE' => 'If-Modified-Since', 'LAST_MODIFIED' => 'Last-Modified' }.freeze + + CMAB_FETCH_FAILED = 'CMAB decision fetch failed (%s).' + INVALID_CMAB_FETCH_RESPONSE = 'Invalid CMAB fetch response' end end end diff --git a/spec/cmab_client_spec.rb b/spec/cmab_client_spec.rb new file mode 100644 index 00000000..f25c78fa --- /dev/null +++ b/spec/cmab_client_spec.rb @@ -0,0 +1,198 @@ +# 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 'spec_helper' +require 'optimizely/logger' +require 'optimizely/cmab/cmab_client' +require 'webmock/rspec' + +describe Optimizely::DefaultCmabClient do + let(:spy_logger) { spy('logger') } + let(:retry_config) { Optimizely::CmabRetryConfig.new(max_retries: 3, initial_backoff: 0.01, max_backoff: 1, backoff_multiplier: 2) } + let(:rule_id) { 'test_rule' } + let(:user_id) { 'user123' } + let(:attributes) { {'attr1': 'value1', 'attr2': 'value2'} } + let(:cmab_uuid) { 'uuid-1234' } + let(:expected_url) { "https://prediction.cmab.optimizely.com/predict/#{rule_id}" } + let(:expected_body_for_webmock) do + { + instances: [{ + visitorId: user_id, + experimentId: rule_id, + attributes: [ + {'id' => 'attr1', 'value' => 'value1', 'type' => 'custom_attribute'}, + {'id' => 'attr2', 'value' => 'value2', 'type' => 'custom_attribute'} + ], + cmabUUID: cmab_uuid + }] + }.to_json + end + let(:expected_headers) { {'Content-Type' => 'application/json'} } + + before do + allow(Kernel).to receive(:sleep) + WebMock.disable_net_connect! + end + + after do + RSpec::Mocks.space.proxy_for(spy_logger).reset + WebMock.reset! + WebMock.allow_net_connect! + end + + context 'when client is configured without retries' do + let(:client) { described_class.new(nil, Optimizely::CmabRetryConfig.new(max_retries: 0), spy_logger) } + + it 'should return the variation id on success' do + WebMock.stub_request(:post, expected_url) + .with(body: expected_body_for_webmock, headers: expected_headers) + .to_return(status: 200, body: {'predictions' => [{'variationId' => 'abc123'}]}.to_json, headers: {'Content-Type' => 'application/json'}) + + result = client.fetch_decision(rule_id, user_id, attributes, cmab_uuid) + + expect(result).to eq('abc123') + expect(WebMock).to have_requested(:post, expected_url) + .with(body: expected_body_for_webmock, headers: expected_headers).once + expect(Kernel).not_to have_received(:sleep) + end + + it 'should raise error on http client exception' do + WebMock.stub_request(:post, expected_url) + .with(body: expected_body_for_webmock, headers: expected_headers) + .to_raise(StandardError.new('Connection error')) + + expect do + client.fetch_decision(rule_id, user_id, attributes, cmab_uuid) + end.to raise_error(Optimizely::CmabFetchError, /Connection error/) + + expect(WebMock).to have_requested(:post, expected_url) + .with(body: expected_body_for_webmock, headers: expected_headers).once + expect(spy_logger).to have_received(:log).with(Logger::ERROR, a_string_including('Connection error')) + expect(Kernel).not_to have_received(:sleep) + end + + it 'should raise error on non success status' do + WebMock.stub_request(:post, expected_url) + .with(body: expected_body_for_webmock, headers: expected_headers) + .to_return(status: 500) + + expect do + client.fetch_decision(rule_id, user_id, attributes, cmab_uuid) + end.to raise_error(Optimizely::CmabFetchError, /500/) + + expect(WebMock).to have_requested(:post, expected_url) + .with(body: expected_body_for_webmock, headers: expected_headers).once + expect(spy_logger).to have_received(:log).with(Logger::ERROR, a_string_including('500')) + expect(Kernel).not_to have_received(:sleep) + end + + it 'should raise error on invalid json response' do + WebMock.stub_request(:post, expected_url) + .with(body: expected_body_for_webmock, headers: expected_headers) + .to_return(status: 200, body: 'this is not json', headers: {'Content-Type' => 'text/plain'}) + + expect do + client.fetch_decision(rule_id, user_id, attributes, cmab_uuid) + end.to raise_error(Optimizely::CmabInvalidResponseError, /Invalid CMAB fetch response/) + + expect(WebMock).to have_requested(:post, expected_url) + .with(body: expected_body_for_webmock, headers: expected_headers).once + expect(spy_logger).to have_received(:log).with(Logger::ERROR, a_string_including('Invalid CMAB fetch response')) + expect(Kernel).not_to have_received(:sleep) + end + + it 'should raise error on invalid response structure' do + WebMock.stub_request(:post, expected_url) + .with(body: expected_body_for_webmock, headers: expected_headers) + .to_return(status: 200, body: {'no_predictions' => []}.to_json, headers: {'Content-Type' => 'application/json'}) + + expect do + client.fetch_decision(rule_id, user_id, attributes, cmab_uuid) + end.to raise_error(Optimizely::CmabInvalidResponseError, /Invalid CMAB fetch response/) + + expect(WebMock).to have_requested(:post, expected_url) + .with(body: expected_body_for_webmock, headers: expected_headers).once + expect(spy_logger).to have_received(:log).with(Logger::ERROR, a_string_including('Invalid CMAB fetch response')) + expect(Kernel).not_to have_received(:sleep) + end + end + + context 'when client is configured with retries' do + let(:client_with_retry) { described_class.new(nil, retry_config, spy_logger) } + + it 'should return the variation id on first try' do + WebMock.stub_request(:post, expected_url) + .with(body: expected_body_for_webmock, headers: expected_headers) + .to_return(status: 200, body: {'predictions' => [{'variationId' => 'abc123'}]}.to_json, headers: {'Content-Type' => 'application/json'}) + + result = client_with_retry.fetch_decision(rule_id, user_id, attributes, cmab_uuid) + + expect(result).to eq('abc123') + expect(WebMock).to have_requested(:post, expected_url) + .with(body: expected_body_for_webmock, headers: expected_headers).once + expect(Kernel).not_to have_received(:sleep) + end + + it 'should return the variation id on third try' do + WebMock.stub_request(:post, expected_url) + .with(body: expected_body_for_webmock, headers: expected_headers) + .to_return({status: 500}, + {status: 500}, + {status: 200, body: {'predictions' => [{'variationId' => 'xyz456'}]}.to_json, headers: {'Content-Type' => 'application/json'}}) + + result = client_with_retry.fetch_decision(rule_id, user_id, attributes, cmab_uuid) + + expect(result).to eq('xyz456') + expect(WebMock).to have_requested(:post, expected_url) + .with(body: expected_body_for_webmock, headers: expected_headers).times(3) + + expect(spy_logger).to have_received(:log).with(Logger::INFO, 'Retrying CMAB request (attempt 1) after 0.01 seconds...').once + expect(spy_logger).to have_received(:log).with(Logger::INFO, 'Retrying CMAB request (attempt 2) after 0.02 seconds...').once + expect(spy_logger).not_to have_received(:log).with(Logger::INFO, a_string_including('Retrying CMAB request (attempt 3)')) + + expect(Kernel).to have_received(:sleep).with(0.01).once + expect(Kernel).to have_received(:sleep).with(0.02).once + expect(Kernel).not_to have_received(:sleep).with(0.04) + end + + it 'should exhaust all retry attempts' do + WebMock.stub_request(:post, expected_url) + .with(body: expected_body_for_webmock, headers: expected_headers) + .to_return({status: 500}, + {status: 500}, + {status: 500}, + {status: 500}) + + expect do + client_with_retry.fetch_decision(rule_id, user_id, attributes, cmab_uuid) + end.to raise_error(Optimizely::CmabFetchError) + + expect(WebMock).to have_requested(:post, expected_url) + .with(body: expected_body_for_webmock, headers: expected_headers).times(4) + + expect(spy_logger).to have_received(:log).with(Logger::INFO, 'Retrying CMAB request (attempt 1) after 0.01 seconds...').once + expect(spy_logger).to have_received(:log).with(Logger::INFO, 'Retrying CMAB request (attempt 2) after 0.02 seconds...').once + expect(spy_logger).to have_received(:log).with(Logger::INFO, 'Retrying CMAB request (attempt 3) after 0.04 seconds...').once + + expect(Kernel).to have_received(:sleep).with(0.01).once + expect(Kernel).to have_received(:sleep).with(0.02).once + expect(Kernel).to have_received(:sleep).with(0.04).once + + expect(spy_logger).to have_received(:log).with(Logger::ERROR, a_string_including('Max retries exceeded for CMAB request')) + end + end +end