hackle-ruby-sdk 1.0.0 → 2.0.0

data/lib/hackle/internal/evaluation/evaluator/remoteconfig/remote_config_evaluator.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require 'hackle/internal/model/value_type'
+require 'hackle/internal/model/decision_reason'
+require 'hackle/internal/properties/properties_builder'
+
+module Hackle
+  class RemoteConfigEvaluator
+    include ContextualEvaluator
+
+    # @param target_rule_determiner [RemoteConfigTargetRuleDeterminer]
+    def initialize(target_rule_determiner:)
+      # @type [RemoteConfigTargetRuleDeterminer]
+      @target_rule_determiner = target_rule_determiner
+    end
+
+    def supports?(request)
+      request.is_a?(RemoteConfigRequest)
+    end
+
+    # @param request [RemoteConfigRequest]
+    # @param context [EvaluatorContext]
+    # @return [RemoteConfigEvaluation]
+    def evaluate_internal(request, context)
+      properties_builder = PropertiesBuilder.new
+                                            .add('requestValueType', request.required_type.name)
+                                            .add('requestDefaultValue', request.default_value)
+
+      if request.user.identifiers[request.parameter.identifier_type].nil?
+        return RemoteConfigEvaluation.create_default(
+          request, context, DecisionReason::IDENTIFIER_NOT_FOUND, properties_builder
+        )
+      end
+
+      target_rule = @target_rule_determiner.determine_or_nil(request, context)
+      unless target_rule.nil?
+        properties_builder.add('targetRuleKey', target_rule.key)
+        properties_builder.add('targetRuleName', target_rule.name)
+        return evaluation(request, context, target_rule.value, DecisionReason::TARGET_RULE_MATCH, properties_builder)
+      end
+
+      evaluation(request, context, request.parameter.default_value, DecisionReason::DEFAULT_RULE, properties_builder)
+    end
+
+    private
+
+    # @param request [RemoteConfigRequest]
+    # @param context [EvaluatorContext]
+    # @param parameter_value [RemoteConfigValue]
+    # @param reason [String]
+    # @param properties_builder [PropertiesBuilder]
+    # @return [RemoteConfigEvaluation]
+    def evaluation(request, context, parameter_value, reason, properties_builder)
+      if valid?(request.required_type, parameter_value.raw_value)
+        RemoteConfigEvaluation.create(request, context, parameter_value.id, parameter_value.raw_value, reason,
+                                      properties_builder)
+      else
+        RemoteConfigEvaluation.create_default(request, context, DecisionReason::TYPE_MISMATCH, properties_builder)
+      end
+    end
+
+    # @param required_type [ValueType]
+    # @param value [Object]
+    # @return [boolean]
+    def valid?(required_type, value)
+      case required_type
+      when ValueType::NULL
+        true
+      when ValueType::STRING
+        value.is_a?(String)
+      when ValueType::NUMBER
+        value.is_a?(Numeric)
+      when ValueType::BOOLEAN
+        value.is_a?(TrueClass) || value.is_a?(FalseClass)
+      else
+        false
+      end
+    end
+  end
+
+  class RemoteConfigRequest < EvaluatorRequest
+    # @return [RemoteConfigParameter]
+    attr_reader :parameter
+
+    # @return [ValueType]
+    attr_reader :required_type
+
+    # @return [Object, nil]
+    attr_reader :default_value
+
+    # @param key [EvaluatorKey]
+    # @param workspace [Workspace]
+    # @param user [HackleUser]
+    # @param parameter [RemoteConfigParameter]
+    # @param required_type [ValueType]
+    # @param default_value [Object, nil]
+    def initialize(key:, workspace:, user:, parameter:, required_type:, default_value:)
+      super(key: key, workspace: workspace, user: user)
+      @parameter = parameter
+      @required_type = required_type
+      @default_value = default_value
+    end
+
+    # @param workspace [Workspace]
+    # @param user [HackleUser]
+    # @param parameter [RemoteConfigParameter]
+    # @param required_type [ValueType]
+    # @param default_value [Object, nil]
+    def self.create(workspace, user, parameter, required_type, default_value)
+      RemoteConfigRequest.new(
+        key: EvaluatorKey.new(type: 'REMOTE_CONFIG', id: parameter.id),
+        workspace: workspace,
+        user: user,
+        parameter: parameter,
+        required_type: required_type,
+        default_value: default_value
+      )
+    end
+  end
+
+  class RemoteConfigEvaluation < EvaluatorEvaluation
+    # @return [RemoteConfigParameter]
+    attr_reader :parameter
+
+    # @return [Integer, nil]
+    attr_reader :value_id
+
+    # @return [Object]
+    attr_reader :value
+
+    # @return [Hash<String => Object>]
+    attr_reader :properties
+
+    # @param reason [String]
+    # @param target_evaluations [Array<EvaluatorEvaluation>]
+    # @param parameter [RemoteConfigParameter]
+    # @param value_id [Integer, nil]
+    # @param value [Object, nil]
+    # @param properties [Hash<String => Object>]
+    def initialize(reason:, target_evaluations:, parameter:, value_id:, value:, properties:)
+      super(reason: reason, target_evaluations: target_evaluations)
+      @parameter = parameter
+      @value_id = value_id
+      @value = value
+      @properties = properties
+    end
+
+    # @param request [RemoteConfigRequest]
+    # @param context [EvaluatorContext]
+    # @param value_id [Integer, nil]
+    # @param value [Object, nil]
+    # @param reason [String]
+    # @param properties_builder [PropertiesBuilder]
+    def self.create(request, context, value_id, value, reason, properties_builder)
+      properties_builder.add('returnValue', value)
+      RemoteConfigEvaluation.new(
+        reason: reason,
+        target_evaluations: context.evaluations,
+        parameter: request.parameter,
+        value_id: value_id,
+        value: value,
+        properties: properties_builder.build
+      )
+    end
+
+    # @param request [RemoteConfigRequest]
+    # @param context [EvaluatorContext]
+    # @param reason [String]
+    # @param properties_builder [PropertiesBuilder]
+    def self.create_default(request, context, reason, properties_builder)
+      create(request, context, nil, request.default_value, reason, properties_builder)
+    end
+  end
+end

data/lib/hackle/internal/evaluation/flow/evaluation_flow.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Hackle
+  module EvaluationFlow
+    # @param request [EvaluatorRequest]
+    # @param context [EvaluatorContext]
+    # @return [EvaluatorEvaluation, nil]
+    def evaluate(request, context) end
+
+    # @param evaluators [Array<FlowEvaluator>]
+    # @return [Hackle::EvaluationFlow]
+    def self.create(evaluators)
+      flow = End.new
+      evaluators.reverse_each do |evaluator|
+        flow = Decision.new(evaluator, flow)
+      end
+      flow
+    end
+
+    class End
+      include EvaluationFlow
+
+      def evaluate(request, context)
+        nil
+      end
+    end
+
+    class Decision
+      include EvaluationFlow
+
+      # @return [FlowEvaluator]
+      attr_reader :evaluator
+
+      # @return [EvaluationFlow]
+      attr_reader :next_flow
+
+      # @param evaluator [FlowEvaluator]
+      # @param next_flow [EvaluationFlow]
+      def initialize(evaluator, next_flow)
+        @evaluator = evaluator
+        @next_flow = next_flow
+      end
+
+      def evaluate(request, context)
+        evaluator.evaluate(request, context, next_flow)
+      end
+    end
+  end
+end

data/lib/hackle/internal/evaluation/flow/flow_evaluator.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Hackle
+  module FlowEvaluator
+    # @param request [EvaluatorRequest]
+    # @param context [EvaluatorContext]
+    # @param next_flow [EvaluationFlow]
+    # @return [EvaluatorEvaluation, nil]
+    def evaluate(request, context, next_flow) end
+  end
+end

data/lib/hackle/internal/evaluation/match/condition/condition_matcher.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Hackle
+  module ConditionMatcher
+    # @param request [EvaluatorRequest]
+    # @param context [EvaluatorContext]
+    # @param condition [TargetCondition]
+    # @return [boolean]
+    def matches(request, context, condition) end
+  end
+end

data/lib/hackle/internal/evaluation/match/condition/condition_matcher_factory.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require 'hackle/internal/evaluation/match/value/value_operator_matcher'
+require 'hackle/internal/evaluation/match/value/value_matcher_factory'
+require 'hackle/internal/evaluation/match/operator/operator_matcher_factory'
+require 'hackle/internal/evaluation/match/condition/user/user_condition_matcher'
+require 'hackle/internal/evaluation/match/condition/segment/segment_condition_matcher'
+require 'hackle/internal/evaluation/match/condition/experiment/experiment_condition_matcher'
+require 'hackle/internal/evaluation/match/condition/experiment/experiment_evaluator_matcher'
+
+module Hackle
+  class ConditionMatcherFactory
+    # @param evaluator [Evaluator]
+    def initialize(evaluator:)
+      value_operator_matcher = ValueOperatorMatcher.new(
+        value_matcher_factory: ValueMatcherFactory.new,
+        operator_matcher_factory: OperatorMatcherFactory.new
+      )
+      @user_condition_matcher = UserConditionMatcher.new(
+        user_value_resolver: UserValueResolver.new,
+        value_operator_matcher: value_operator_matcher
+      )
+      @segment_condition_matcher = SegmentConditionMatcher.new(
+        segment_matcher: SegmentMatcher.new(user_condition_matcher: @user_condition_matcher)
+      )
+      @experiment_condition_matcher = ExperimentConditionMatcher.new(
+        ab_test_matcher: AbTestEvaluatorMatcher.new(
+          evaluator: evaluator,
+          value_operator_matcher: value_operator_matcher
+        ),
+        feature_flag_matcher: FeatureFlagEvaluatorMatcher.new(
+          evaluator: evaluator,
+          value_operator_matcher: value_operator_matcher
+        )
+      )
+    end
+
+    # @param key_type [TargetKeyType]
+    # @return [ConditionMatcher]
+    def get(key_type)
+      case key_type
+      when TargetKeyType::USER_ID, TargetKeyType::USER_PROPERTY, TargetKeyType::HACKLE_PROPERTY
+        @user_condition_matcher
+      when TargetKeyType::SEGMENT
+        @segment_condition_matcher
+      when TargetKeyType::AB_TEST, TargetKeyType::FEATURE_FLAG
+        @experiment_condition_matcher
+      else
+        raise ArgumentError, "unsupported TargetKeyType [#{key_type}]"
+      end
+    end
+  end
+end

data/lib/hackle/internal/evaluation/match/condition/experiment/experiment_condition_matcher.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'hackle/internal/evaluation/match/condition/condition_matcher'
+
+module Hackle
+  class ExperimentConditionMatcher
+    include ConditionMatcher
+
+    # @param ab_test_matcher [ExperimentEvaluatorMatcher]
+    # @param feature_flag_matcher [ExperimentEvaluatorMatcher]
+    def initialize(ab_test_matcher:, feature_flag_matcher:)
+      # @type [ExperimentEvaluatorMatcher]
+      @ab_test_matcher = ab_test_matcher
+      # @type [ExperimentEvaluatorMatcher]
+      @feature_flag_matcher = feature_flag_matcher
+    end
+
+    def matches(request, context, condition)
+      case condition.key.type
+      when TargetKeyType::AB_TEST
+        @ab_test_matcher.matches(request, context, condition)
+      when TargetKeyType::FEATURE_FLAG
+        @feature_flag_matcher.matches(request, context, condition)
+      else
+        raise ArgumentError, "unsupported TargetKeyType [#{condition.key.type}]"
+      end
+    end
+  end
+end

data/lib/hackle/internal/evaluation/match/condition/experiment/experiment_evaluator_matcher.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require 'hackle/internal/model/decision_reason'
+require 'hackle/internal/evaluation/evaluator/experiment/experiment_evaluator'
+
+module Hackle
+  class ExperimentEvaluatorMatcher
+    # @param evaluator [Evaluator]
+    def initialize(evaluator:)
+      # @type [Evaluator]
+      @evaluator = evaluator
+    end
+
+    # @param request [EvaluatorRequest]
+    # @param context [EvaluatorContext]
+    # @param condition [TargetCondition]
+    # @return [boolean]
+    def matches(request, context, condition)
+      key = Integer(condition.key.name, exception: false)
+      raise ArgumentError, "invalid key [#{condition.key.type}, #{condition.key.name}]" if key.nil?
+
+      experiment = experiment_or_nil(request, key)
+      return false if experiment.nil?
+
+      evaluation = get_evaluation_or_nil(context, experiment)
+      evaluation = evaluate(request, context, experiment) if evaluation.nil?
+
+      evaluation_matches(evaluation, condition)
+    end
+
+    private
+
+    # @param request [EvaluatorRequest]
+    # @param context [EvaluatorContext]
+    # @param experiment [Experiment]
+    # @return [Hackle::ExperimentEvaluation]
+    def evaluate(request, context, experiment)
+      experiment_request = ExperimentRequest.create_by(request, experiment)
+      evaluation = @evaluator.evaluate(experiment_request, context)
+      unless evaluation.is_a?(ExperimentEvaluation)
+        raise ArgumentError, "unexpected evaluation: #{evaluation.class} (expected: ExperimentEvaluation)"
+      end
+
+      resolved_evaluation = resolve_evaluation(request, evaluation)
+      context.add_evaluation(resolved_evaluation)
+      resolved_evaluation
+    end
+
+    # @param context [EvaluatorContext]
+    # @param experiment [Experiment]
+    # @return [ExperimentEvaluation, nil]
+    def get_evaluation_or_nil(context, experiment)
+      context.evaluations.each do |evaluation|
+        return evaluation if evaluation.is_a?(ExperimentEvaluation) && evaluation.experiment.id == experiment.id
+      end
+      nil
+    end
+
+    # @abstract
+    # @param request [EvaluatorRequest]
+    # @param key [Integer]
+    # @return [Experiment, nil]
+    def experiment_or_nil(request, key) end
+
+    # @abstract
+    # @param request [EvaluatorRequest]
+    # @param evaluation [ExperimentEvaluation]
+    # @return [ExperimentEvaluation]
+    def resolve_evaluation(request, evaluation) end
+
+    # @abstract
+    # @param evaluation [ExperimentEvaluation]
+    # @param condition [TargetCondition]
+    # @return [boolean]
+    def evaluation_matches(evaluation, condition) end
+  end
+
+  class AbTestEvaluatorMatcher < ExperimentEvaluatorMatcher
+    # @param evaluator [Evaluator]
+    # @param value_operator_matcher [ValueOperatorMatcher]
+    def initialize(evaluator:, value_operator_matcher:)
+      super(evaluator: evaluator)
+      # @type [ValueOperatorMatcher]
+      @value_operator_matcher = value_operator_matcher
+    end
+
+    def experiment_or_nil(request, key)
+      request.workspace.get_experiment_or_nil(key)
+    end
+
+    def resolve_evaluation(request, evaluation)
+      if request.is_a?(ExperimentRequest) && evaluation.reason == DecisionReason::TRAFFIC_ALLOCATED
+        return evaluation.with(DecisionReason::TRAFFIC_ALLOCATED_BY_TARGETING)
+      end
+
+      evaluation
+    end
+
+    def evaluation_matches(evaluation, condition)
+      return false if AB_TEST_MATCHED_REASONS.none?(evaluation.reason)
+
+      @value_operator_matcher.matches(evaluation.variation_key, condition.match)
+    end
+
+    AB_TEST_MATCHED_REASONS = [
+      DecisionReason::OVERRIDDEN,
+      DecisionReason::TRAFFIC_ALLOCATED,
+      DecisionReason::TRAFFIC_ALLOCATED_BY_TARGETING,
+      DecisionReason::EXPERIMENT_COMPLETED
+    ].freeze
+  end
+
+  class FeatureFlagEvaluatorMatcher < ExperimentEvaluatorMatcher
+    # @param evaluator [Evaluator]
+    # @param value_operator_matcher [ValueOperatorMatcher]
+    def initialize(evaluator:, value_operator_matcher:)
+      super(evaluator: evaluator)
+      # @type [ValueOperatorMatcher]
+      @value_operator_matcher = value_operator_matcher
+    end
+
+    def experiment_or_nil(request, key)
+      request.workspace.get_feature_flag_or_nil(key)
+    end
+
+    def resolve_evaluation(_request, evaluation)
+      evaluation
+    end
+
+    def evaluation_matches(evaluation, condition)
+      on = evaluation.variation_key != 'A'
+      @value_operator_matcher.matches(on, condition.match)
+    end
+  end
+end

data/lib/hackle/internal/evaluation/match/condition/segment/segment_condition_matcher.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'hackle/internal/model/target'
+require 'hackle/internal/evaluation/match/condition/condition_matcher'
+
+module Hackle
+  class SegmentConditionMatcher
+    include ConditionMatcher
+
+    # @param segment_matcher [SegmentMatcher]
+    def initialize(segment_matcher:)
+      # @type [SegmentMatcher]
+      @segment_matcher = segment_matcher
+    end
+
+    def matches(request, context, condition)
+      if condition.key.type != TargetKeyType::SEGMENT
+        raise ArgumentError, "unsupported TargetKeyType [#{condition.key.type}]"
+      end
+
+      matches = condition.match.values.any? { |it| value_matches(request, context, it) }
+      TargetMatchType.matches(condition.match.type, matches)
+    end
+
+    private
+
+    # @param request [EvaluatorRequest]
+    # @param context [EvaluatorContext]
+    # @param value [Object]
+    # @return [boolean]
+    def value_matches(request, context, value)
+      segment_key = value
+      raise ArgumentError, "segment key [#{value}]" unless segment_key.is_a?(String)
+
+      segment = request.workspace.get_segment_or_nil(segment_key)
+      raise ArgumentError, "segment [#{segment_key}]" unless segment
+
+      @segment_matcher.matches(request, context, segment)
+    end
+  end
+
+  class SegmentMatcher
+    # @param user_condition_matcher [ConditionMatcher]
+    def initialize(user_condition_matcher:)
+      # @type [ConditionMatcher]
+      @user_condition_matcher = user_condition_matcher
+    end
+
+    # @param request [EvaluatorRequest]
+    # @param context [EvaluatorContext]
+    # @param segment [Segment]
+    # @return [boolean]
+    def matches(request, context, segment)
+      segment.targets.any? { |it| target_matches(request, context, it) }
+    end
+
+    private
+
+    # @param request [EvaluatorRequest]
+    # @param context [EvaluatorContext]
+    # @param target [Target]
+    # @return [boolean]
+    def target_matches(request, context, target)
+      target.conditions.all? { |it| @user_condition_matcher.matches(request, context, it) }
+    end
+  end
+end

data/lib/hackle/internal/evaluation/match/condition/user/user_condition_matcher.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'hackle/internal/model/target'
+require 'hackle/internal/evaluation/match/condition/condition_matcher'
+
+module Hackle
+  class UserConditionMatcher
+    include ConditionMatcher
+
+    # @param user_value_resolver [UserValueResolver]
+    # @param value_operator_matcher [ValueOperatorMatcher]
+    def initialize(user_value_resolver:, value_operator_matcher:)
+      # @type [UserValueResolver]
+      @user_value_resolver = user_value_resolver
+      # @type [ValueOperatorMatcher]
+      @value_operator_matcher = value_operator_matcher
+    end
+
+    def matches(request, context, condition)
+      user_value = @user_value_resolver.resolve_or_nil(request.user, condition.key)
+      return false if user_value.nil?
+
+      @value_operator_matcher.matches(user_value, condition.match)
+    end
+  end
+
+  class UserValueResolver
+    # @param user [HackleUser]
+    # @param key [TargetKey]
+    # @return [Object, nil]
+    def resolve_or_nil(user, key)
+      case key.type
+      when TargetKeyType::USER_ID
+        user.identifiers[key.name]
+      when TargetKeyType::USER_PROPERTY
+        user.properties[key.name]
+      when TargetKeyType::HACKLE_PROPERTY
+        nil
+      else
+        raise ArgumentError, "unsupported TargetKeyType: #{key.type}"
+      end
+    end
+  end
+end