hackle-ruby-sdk 1.0.0 → 2.0.0

data/lib/hackle/internal/evaluation/evaluator/experiment/experiment_evaluator.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require 'hackle/internal/model/decision_reason'
+require 'hackle/internal/evaluation/evaluator/evaluator'
+require 'hackle/internal/evaluation/evaluator/contextual/contextual_evaluator'
+
+module Hackle
+  class ExperimentEvaluator
+    include ContextualEvaluator
+
+    # @param flow_factory [ExperimentEvaluationFlowFactory]
+    def initialize(flow_factory:)
+      # @type [ExperimentEvaluationFlowFactory]
+      @flow_factory = flow_factory
+    end
+
+    def supports?(request)
+      request.is_a?(ExperimentRequest)
+    end
+
+    # @param request [ExperimentRequest]
+    # @param context [EvaluatorContext]
+    # @return [ExperimentEvaluation]
+    def evaluate_internal(request, context)
+      evaluation_flow = @flow_factory.get(request.experiment.type)
+      evaluation = evaluation_flow.evaluate(request, context)
+      return evaluation unless evaluation.nil?
+
+      ExperimentEvaluation.create_default(request, context, DecisionReason::TRAFFIC_NOT_ALLOCATED)
+    end
+  end
+
+  class ExperimentRequest < EvaluatorRequest
+    # @return [Experiment]
+    attr_reader :experiment
+
+    # @return [String]
+    attr_reader :default_variation_key
+
+    # @param key [EvaluatorKey]
+    # @param workspace [Workspace]
+    # @param user [HackleUser]
+    # @param experiment [Experiment]
+    # @param default_variation_key [String]
+    def initialize(key:, workspace:, user:, experiment:, default_variation_key:)
+      super(key: key, workspace: workspace, user: user)
+      @experiment = experiment
+      @default_variation_key = default_variation_key
+    end
+
+    # @param workspace [Workspace]
+    # @param user [HackleUser]
+    # @param experiment [Experiment]
+    # @param default_variation_key [String]
+    # @return [Hackle::ExperimentRequest]
+    def self.create(workspace, user, experiment, default_variation_key)
+      ExperimentRequest.new(
+        key: EvaluatorKey.new(type: 'EXPERIMENT', id: experiment.id),
+        workspace: workspace,
+        user: user,
+        experiment: experiment,
+        default_variation_key: default_variation_key
+      )
+    end
+
+    # @param request [EvaluatorRequest]
+    # @param experiment [Experiment]
+    # @return [Hackle::ExperimentRequest]
+    def self.create_by(request, experiment)
+      ExperimentRequest.new(
+        key: EvaluatorKey.new(type: 'EXPERIMENT', id: experiment.id),
+        workspace: request.workspace,
+        user: request.user,
+        experiment: experiment,
+        default_variation_key: 'A'
+      )
+    end
+  end
+
+  class ExperimentEvaluation < EvaluatorEvaluation
+    # @return [Experiment]
+    attr_reader :experiment
+
+    # @return [Integer, nil]
+    attr_reader :variation_id
+
+    # @return [String]
+    attr_reader :variation_key
+
+    # @return [ParameterConfiguration, nil]
+    attr_reader :config
+
+    # @param reason [String]
+    # @param target_evaluations [Array<EvaluatorEvaluation]
+    # @param experiment [Experiment]
+    # @param variation_id [Integer, nil]
+    # @param variation_key [String]
+    # @param config [ParameterConfiguration, nil]
+    def initialize(reason:, target_evaluations:, experiment:, variation_id:, variation_key:, config:)
+      super(reason: reason, target_evaluations: target_evaluations)
+      @experiment = experiment
+      @variation_id = variation_id
+      @variation_key = variation_key
+      @config = config
+    end
+
+    # @return [ParameterConfig]
+    def parameter_config
+      return ParameterConfig.empty if @config.nil?
+
+      ParameterConfig.new(@config.parameters)
+    end
+
+    # @param reason [String]
+    # @return [Hackle::ExperimentEvaluation]
+    def with(reason)
+      ExperimentEvaluation.new(
+        reason: reason,
+        target_evaluations: target_evaluations,
+        experiment: experiment,
+        variation_id: variation_id,
+        variation_key: variation_key,
+        config: config
+      )
+    end
+
+    # @param request [ExperimentRequest]
+    # @param context [EvaluatorContext]
+    # @param variation [Variation]
+    # @param reason [String]
+    # @return [Hackle::ExperimentEvaluation]
+    def self.create(request, context, variation, reason)
+      configuration = configuration_or_nil(request.workspace, variation)
+      ExperimentEvaluation.new(
+        reason: reason,
+        target_evaluations: context.evaluations,
+        experiment: request.experiment,
+        variation_id: variation.id,
+        variation_key: variation.key,
+        config: configuration
+      )
+    end
+
+    # @param request [ExperimentRequest]
+    # @param context [EvaluatorContext]
+    # @param reason [String]
+    # @return [Hackle::ExperimentEvaluation]
+    def self.create_default(request, context, reason)
+      variation = request.experiment.get_variation_or_nil_by_key(request.default_variation_key)
+      return create(request, context, variation, reason) unless variation.nil?
+
+      ExperimentEvaluation.new(
+        reason: reason,
+        target_evaluations: context.evaluations,
+        experiment: request.experiment,
+        variation_id: nil,
+        variation_key: request.default_variation_key,
+        config: nil
+      )
+    end
+
+    # @param workspace [Workspace]
+    # @param variation [Variation]
+    # @return [Hackle::ParameterConfiguration, nil]
+    def self.configuration_or_nil(workspace, variation)
+      parameter_configuration_id = variation.parameter_configuration_id
+      return nil if parameter_configuration_id.nil?
+
+      workspace.get_parameter_configuration_or_nil(parameter_configuration_id)
+    end
+  end
+end

data/lib/hackle/internal/evaluation/evaluator/experiment/experiment_flow_evaluator.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+require 'hackle/internal/evaluation/evaluator/experiment/experiment_evaluator'
+require 'hackle/internal/evaluation/flow/evaluation_flow'
+require 'hackle/internal/evaluation/flow/flow_evaluator'
+require 'hackle/internal/model/experiment'
+require 'hackle/internal/model/decision_reason'
+
+module Hackle
+  module ExperimentFlow
+    include EvaluationFlow
+
+    # @param request [ExperimentRequest]
+    # @param context [EvaluatorContext]
+    # @return [ExperimentEvaluation, nil]
+    def evaluate(request, context) end
+  end
+
+  module ExperimentFlowEvaluator
+    include FlowEvaluator
+
+    # @param request [ExperimentRequest]
+    # @param context [EvaluatorContext]
+    # @param next_flow [ExperimentFlow]
+    # @return [ExperimentEvaluation, nil]
+    def evaluate(request, context, next_flow) end
+  end
+
+  class OverrideExperimentFlowEvaluator
+    include ExperimentFlowEvaluator
+
+    # @param override_resolver [ExperimentOverrideResolver]
+    def initialize(override_resolver:)
+      # @type [ExperimentOverrideResolver]
+      @override_resolver = override_resolver
+    end
+
+    def evaluate(request, context, next_flow)
+      overridden_variation = @override_resolver.resolve_or_nil(request, context)
+      return next_flow.evaluate(request, context) if overridden_variation.nil?
+
+      case request.experiment.type
+      when ExperimentType::AB_TEST
+        ExperimentEvaluation.create(request, context, overridden_variation, DecisionReason::OVERRIDDEN)
+      when ExperimentType::FEATURE_FLAG
+        ExperimentEvaluation.create(request, context, overridden_variation, DecisionReason::INDIVIDUAL_TARGET_MATCH)
+      else
+        raise ArgumentError, "unsupported experiment type [#{request.experiment.type}]"
+      end
+    end
+  end
+
+  class DraftExperimentFlowEvaluator
+    include ExperimentFlowEvaluator
+
+    def evaluate(request, context, next_flow)
+      return next_flow.evaluate(request, context) if request.experiment.status != ExperimentStatus::DRAFT
+
+      ExperimentEvaluation.create_default(request, context, DecisionReason::EXPERIMENT_DRAFT)
+    end
+  end
+
+  class PausedExperimentFlowEvaluator
+    include ExperimentFlowEvaluator
+
+    def evaluate(request, context, next_flow)
+      return next_flow.evaluate(request, context) if request.experiment.status != ExperimentStatus::PAUSED
+
+      case request.experiment.type
+      when ExperimentType::AB_TEST
+        ExperimentEvaluation.create_default(request, context, DecisionReason::EXPERIMENT_PAUSED)
+      when ExperimentType::FEATURE_FLAG
+        ExperimentEvaluation.create_default(request, context, DecisionReason::FEATURE_FLAG_INACTIVE)
+      else
+        raise ArgumentError, "unsupported experiment type [#{request.experiment.type}]"
+      end
+    end
+  end
+
+  class CompletedExperimentFlowEvaluator
+    include ExperimentFlowEvaluator
+
+    def evaluate(request, context, next_flow)
+      return next_flow.evaluate(request, context) if request.experiment.status != ExperimentStatus::COMPLETED
+
+      winner_variation = request.experiment.winner_variation_or_nil
+      raise ArgumentError, "winner variation [#{request.experiment.id}]" if winner_variation.nil?
+
+      ExperimentEvaluation.create(request, context, winner_variation, DecisionReason::EXPERIMENT_COMPLETED)
+    end
+  end
+
+  class TargetExperimentFlowEvaluator
+    include ExperimentFlowEvaluator
+
+    # @param target_determiner [ExperimentTargetDeterminer]
+    def initialize(target_determiner:)
+      # @type [ExperimentTargetDeterminer]
+      @target_determiner = target_determiner
+    end
+
+    def evaluate(request, context, next_flow)
+      if request.experiment.type != ExperimentType::AB_TEST
+        raise ArgumentError, "experiment type must be AB_TEST [#{request.experiment.id}]"
+      end
+
+      is_user_in_experiment_target = @target_determiner.user_in_experiment_target?(request, context)
+      if is_user_in_experiment_target
+        next_flow.evaluate(request, context)
+      else
+        ExperimentEvaluation.create_default(request, context, DecisionReason::NOT_IN_EXPERIMENT_TARGET)
+      end
+    end
+  end
+
+  class TrafficAllocateExperimentFlowEvaluator
+    include ExperimentFlowEvaluator
+
+    # @param action_resolver [ExperimentActionResolver]
+    def initialize(action_resolver:)
+      # @type [ExperimentActionResolver]
+      @action_resolver = action_resolver
+    end
+
+    def evaluate(request, context, _next_flow)
+      if request.experiment.status != ExperimentStatus::RUNNING
+        raise ArgumentError, "experiment status must be RUNNING [#{request.experiment.id}]"
+      end
+      if request.experiment.type != ExperimentType::AB_TEST
+        raise ArgumentError, "experiment type must be AB_TEST [#{request.experiment.id}]"
+      end
+
+      variation = @action_resolver.resolve_or_nil(request, request.experiment.default_rule)
+      if variation.nil?
+        return ExperimentEvaluation.create_default(request, context, DecisionReason::TRAFFIC_NOT_ALLOCATED)
+      end
+      if variation.is_dropped
+        return ExperimentEvaluation.create_default(request, context, DecisionReason::VARIATION_DROPPED)
+      end
+
+      ExperimentEvaluation.create(request, context, variation, DecisionReason::TRAFFIC_ALLOCATED)
+    end
+  end
+
+  class TargetRuleExperimentFlowEvaluator
+    include ExperimentFlowEvaluator
+
+    # @param target_rule_determiner [ExperimentTargetRuleDeterminer]
+    # @param action_resolver [ExperimentActionResolver]
+    def initialize(target_rule_determiner:, action_resolver:)
+      # @type [ExperimentTargetRuleDeterminer]
+      @target_rule_determiner = target_rule_determiner
+      # @type [ExperimentActionResolver]
+      @action_resolver = action_resolver
+    end
+
+    def evaluate(request, context, next_flow)
+      if request.experiment.status != ExperimentStatus::RUNNING
+        raise ArgumentError, "experiment status must be RUNNING [#{request.experiment.id}]"
+      end
+      if request.experiment.type != ExperimentType::FEATURE_FLAG
+        raise ArgumentError, "experiment type must be FEATURE_FLAG [#{request.experiment.id}]"
+      end
+
+      return next_flow.evaluate(request, context) if request.user.identifiers[request.experiment.identifier_type].nil?
+
+      target_rule = @target_rule_determiner.determine_target_rule_or_nil(request, context)
+      return next_flow.evaluate(request, context) if target_rule.nil?
+
+      variation = @action_resolver.resolve_or_nil(request, target_rule.action)
+      raise ArgumentError, "feature flag must decide the variation [#{request.experiment.id}]" if variation.nil?
+
+      ExperimentEvaluation.create(request, context, variation, DecisionReason::TARGET_RULE_MATCH)
+    end
+  end
+
+  class DefaultRuleExperimentFlowEvaluator
+    include ExperimentFlowEvaluator
+
+    # @param action_resolver [ExperimentActionResolver]
+    def initialize(action_resolver:)
+      # @type [ExperimentActionResolver]
+      @action_resolver = action_resolver
+    end
+
+    def evaluate(request, context, _next_flow)
+      if request.experiment.status != ExperimentStatus::RUNNING
+        raise ArgumentError, "experiment status must be RUNNING [#{request.experiment.id}]"
+      end
+      if request.experiment.type != ExperimentType::FEATURE_FLAG
+        raise ArgumentError, "experiment type must be FEATURE_FLAG [#{request.experiment.id}]"
+      end
+
+      if request.user.identifiers[request.experiment.identifier_type].nil?
+        return ExperimentEvaluation.create_default(request, context, DecisionReason::DEFAULT_RULE)
+      end
+
+      variation = @action_resolver.resolve_or_nil(request, request.experiment.default_rule)
+      raise ArgumentError, "feature flag must decide the variation [#{request.experiment.id}]" if variation.nil?
+
+      ExperimentEvaluation.create(request, context, variation, DecisionReason::DEFAULT_RULE)
+    end
+  end
+
+  class ContainerExperimentFlowEvaluator
+    include ExperimentFlowEvaluator
+
+    # @param container_resolver [ExperimentContainerResolver]
+    def initialize(container_resolver:)
+      # @type [ExperimentContainerResolver]
+      @container_resolver = container_resolver
+    end
+
+    def evaluate(request, context, next_flow)
+      container_id = request.experiment.container_id
+      return next_flow.evaluate(request, context) if container_id.nil?
+
+      container = request.workspace.get_container_or_nil(container_id)
+      raise ArgumentError, "container [#{container_id}]" if container.nil?
+
+      is_user_in_container_group = @container_resolver.user_in_container_group?(request, container)
+      if is_user_in_container_group
+        next_flow.evaluate(request, context)
+      else
+        ExperimentEvaluation.create_default(request, context, DecisionReason::NOT_IN_MUTUAL_EXCLUSION_EXPERIMENT)
+      end
+    end
+  end
+
+  class IdentifierExperimentFlowEvaluator
+    include ExperimentFlowEvaluator
+
+    def evaluate(request, context, next_flow)
+      if request.user.identifiers[request.experiment.identifier_type].nil?
+        ExperimentEvaluation.create_default(request, context, DecisionReason::IDENTIFIER_NOT_FOUND)
+      else
+        next_flow.evaluate(request, context)
+      end
+    end
+  end
+end

data/lib/hackle/internal/evaluation/evaluator/experiment/experiment_resolver.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require 'hackle/internal/model/action'
+require 'hackle/internal/evaluation/bucketer/bucketer'
+
+module Hackle
+  class ExperimentActionResolver
+    # @param bucketer [Bucketer]
+    def initialize(bucketer:)
+      # @type [Bucketer]
+      @bucketer = bucketer
+    end
+
+    # @param request [ExperimentRequest]
+    # @param action [Action]
+    # @return [Hackle::Variation, nil]
+    def resolve_or_nil(request, action)
+      case action.type
+      when ActionType::VARIATION
+        resolve_variation(request, action)
+      when ActionType::BUCKET
+        resolve_bucket(request, action)
+      else
+        raise ArgumentError, "unsupported ActionType [#{action.type}]"
+      end
+    end
+
+    private
+
+    # @param request [ExperimentRequest]
+    # @param action [Action]
+    # @return [Hackle::Variation]
+    def resolve_variation(request, action)
+      variation_id = action.variation_id
+      raise ArgumentError, "action variation [#{request.experiment.id}]" if variation_id.nil?
+
+      variation = request.experiment.get_variation_or_nil_by_id(variation_id)
+      raise ArgumentError, "variation [#{variation_id}]" if variation.nil?
+
+      variation
+    end
+
+    # @param request [ExperimentRequest]
+    # @param action [Action]
+    # @return [Hackle::Variation, nil]
+    def resolve_bucket(request, action)
+      bucket_id = action.bucket_id
+      raise ArgumentError, "action bucket [#{request.experiment.id}]" if bucket_id.nil?
+
+      bucket = request.workspace.get_bucket_or_nil(bucket_id)
+      raise ArgumentError, "bucket [#{bucket_id}]" if bucket.nil?
+
+      identifier = request.user.identifiers[request.experiment.identifier_type]
+      return nil if identifier.nil?
+
+      slot = @bucketer.bucketing(bucket, identifier)
+      return nil if slot.nil?
+
+      request.experiment.get_variation_or_nil_by_id(slot.variation_id)
+    end
+  end
+
+  class ExperimentOverrideResolver
+    # @param target_matcher [TargetMatcher]
+    # @param action_resolver [ExperimentActionResolver]
+
+    def initialize(target_matcher:, action_resolver:)
+      # @type [TargetMatcher]
+      @target_matcher = target_matcher
+      # @type [ExperimentActionResolver]
+      @action_resolver = action_resolver
+    end
+
+    # @param request [ExperimentRequest]
+    # @param context [EvaluatorContext]
+    # @return [Hackle::Variation, nil]
+    def resolve_or_nil(request, context)
+      resolve_user_override(request) || resolve_segment_override(request, context)
+    end
+
+    private
+
+    # @param request [ExperimentRequest]
+    # @return [Hackle::Variation, nil]
+    def resolve_user_override(request)
+      identifier = request.user.identifiers[request.experiment.identifier_type]
+      return nil if identifier.nil?
+
+      overridden_variation_id = request.experiment.user_overrides[identifier]
+      return nil if overridden_variation_id.nil?
+
+      request.experiment.get_variation_or_nil_by_id(overridden_variation_id)
+    end
+
+    # @param request [ExperimentRequest]
+    # @param context [EvaluatorContext]
+    # @return [Hackle::Variation, nil]
+    def resolve_segment_override(request, context)
+      overridden_rule = request.experiment.segment_overrides.find do |it|
+        @target_matcher.matches(request, context, it.target)
+      end
+      return nil if overridden_rule.nil?
+
+      @action_resolver.resolve_or_nil(request, overridden_rule.action)
+    end
+  end
+
+  class ExperimentContainerResolver
+    # @param bucketer [Bucketer]
+    def initialize(bucketer:)
+      # @type [Bucketer]
+      @bucketer = bucketer
+    end
+
+    # @param request [ExperimentRequest]
+    # @param container [Container]
+    def user_in_container_group?(request, container)
+
+      identifier = request.user.identifiers[request.experiment.identifier_type]
+      return false if identifier.nil?
+
+      bucket = request.workspace.get_bucket_or_nil(container.bucket_id)
+      raise ArgumentError, "bucket [#{container.bucket_id}]" if bucket.nil?
+
+      slot = @bucketer.bucketing(bucket, identifier)
+      return false if slot.nil?
+
+      group = container.get_group_or_nil(slot.variation_id)
+      raise ArgumentError, "container group [#{slot.variation_id}]" if group.nil?
+
+      group.experiments.include?(request.experiment.id)
+    end
+  end
+
+  class ExperimentTargetDeterminer
+
+    # @param target_matcher [TargetMatcher]
+    def initialize(target_matcher:)
+      # @type [TargetMatcher]
+      @target_matcher = target_matcher
+    end
+
+    # @param request [ExperimentRequest]
+    # @param context [EvaluatorContext]
+    def user_in_experiment_target?(request, context)
+      return true if request.experiment.target_audiences.empty?
+
+      request.experiment.target_audiences.any? { |it| @target_matcher.matches(request, context, it) }
+    end
+  end
+
+  class ExperimentTargetRuleDeterminer
+    # @param target_matcher [TargetMatcher]
+    def initialize(target_matcher:)
+      # @type [TargetMatcher]
+      @target_matcher = target_matcher
+    end
+
+    # @param request [ExperimentRequest]
+    # @param context [EvaluatorContext]
+    # @return [Hackle::TargetRule, nil]
+    def determine_target_rule_or_nil(request, context)
+      request.experiment.target_rules.find { |it| @target_matcher.matches(request, context, it.target) }
+    end
+  end
+end

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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Hackle
+  class RemoteConfigTargetRuleDeterminer
+
+    # @param matcher [RemoteConfigTargetRuleMatcher]
+    def initialize(matcher:)
+      # @type [RemoteConfigTargetRuleMatcher]
+      @matcher = matcher
+    end
+
+    # @param request [RemoteConfigRequest]
+    # @param context [EvaluatorContext]
+    # @return [RemoteConfigTargetRule, nil]
+    def determine_or_nil(request, context)
+      request.parameter.target_rules.find { |it| @matcher.matches(request, context, it) }
+    end
+  end
+
+  class RemoteConfigTargetRuleMatcher
+    # @param target_matcher [TargetMatcher]
+    # @param bucketer [Bucketer]
+    def initialize(target_matcher:, bucketer:)
+      # @type [TargetMatcher]
+      @target_matcher = target_matcher
+      # @type [Bucketer]
+      @bucketer = bucketer
+    end
+
+    # @param request [RemoteConfigRequest]
+    # @param context [EvaluatorContext]
+    # @param target_rule [RemoteConfigTargetRule]
+    # @return [boolean]
+    def matches(request, context, target_rule)
+      matches = @target_matcher.matches(request, context, target_rule.target)
+      return false unless matches
+
+      identifier = request.user.identifiers[request.parameter.identifier_type]
+      return false if identifier.nil?
+
+      bucket = request.workspace.get_bucket_or_nil(target_rule.bucket_id)
+      raise ArgumentError, "bucket [#{target_rule.bucket_id}]" if bucket.nil?
+
+      allocated = @bucketer.bucketing(bucket, identifier)
+      !allocated.nil?
+    end
+  end
+end