hackle-ruby-sdk 0.1.0 → 2.0.0

data/lib/hackle/internal/concurrent/schedule/scheduler.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Hackle
+  module Scheduler
+    def schedule_periodically(interval_seconds, task) end
+  end
+
+  module ScheduledJob
+    def cancel
+    end
+  end
+end

data/lib/hackle/internal/concurrent/schedule/timer_scheduler.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'concurrent'
+require 'hackle/internal/concurrent/schedule/scheduler'
+
+module Hackle
+  class TimerScheduler
+    include Scheduler
+
+    def schedule_periodically(interval_seconds, task)
+      timer_task = Concurrent::TimerTask.new(execution_interval: interval_seconds, interval_type: :fixed_rate) do
+        task.call
+      end
+      timer_task.execute
+      TimerScheduledJob.new(timer_task)
+    end
+  end
+
+  class TimerScheduledJob
+    include ScheduledJob
+
+    def initialize(task)
+      @task = task
+    end
+
+    def cancel
+      @task.shutdown
+    end
+  end
+end

data/lib/hackle/internal/config/parameter_config.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Hackle
+  class ParameterConfig
+
+    # @return [Hash{String => Object}]
+    attr_reader :parameters
+
+    # @param parameters [Hash{String => Object}]
+    def initialize(parameters)
+      @parameters = parameters
+    end
+
+    @empty = new({})
+
+    # @return [Hackle::ParameterConfig]
+    def self.empty
+      @empty
+    end
+
+    def ==(other)
+      other.is_a?(self.class) && other.parameters == parameters
+    end
+
+    def to_s
+      "Hackle::ParameterConfig(#{parameters})"
+    end
+
+    # @param key [String]
+    # @param default_value [Object, nil]
+    # @return [Object, nil]
+    def get(key, default_value = nil)
+      parameter_value = parameters.fetch(key, default_value)
+
+      return default_value if parameter_value.nil?
+      return parameter_value if default_value.nil?
+
+      case default_value
+      when String
+        parameter_value.is_a?(String) ? parameter_value : default_value
+      when Numeric
+        parameter_value.is_a?(Numeric) ? parameter_value : default_value
+      when TrueClass, FalseClass
+        parameter_value.is_a?(TrueClass) || parameter_value.is_a?(FalseClass) ? parameter_value : default_value
+      else
+        default_value
+      end
+    end
+  end
+end

data/lib/hackle/internal/core/hackle_core.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require 'hackle/internal/event/user_event'
+require 'hackle/internal/model/decision_reason'
+require 'hackle/internal/evaluation/evaluator/delegating/delegating_evaluator'
+require 'hackle/internal/evaluation/match/condition/condition_matcher_factory'
+require 'hackle/internal/evaluation/match/target/target_matcher'
+require 'hackle/internal/evaluation/bucketer/bucketer'
+require 'hackle/internal/evaluation/evaluator/experiment/experiment_evaluator'
+require 'hackle/internal/evaluation/evaluator/experiment/experiment_evaluation_flow_factory'
+require 'hackle/internal/evaluation/evaluator/remoteconfig/remote_config_evaluator'
+require 'hackle/internal/evaluation/evaluator/remoteconfig/remote_config_determiner'
+require 'hackle/internal/event/user_event_factory'
+require 'hackle/internal/clock/clock'
+
+module Hackle
+  class Core
+
+    # @param experiment_evaluator [ExperimentEvaluator]
+    # @param remote_config_evaluator [RemoteConfigEvaluator]
+    # @param workspace_fetcher [WorkspaceFetcher]
+    # @param event_factory [UserEventFactory]
+    # @param event_processor [UserEventProcessor]
+    # @param clock [Clock]
+    def initialize(
+      experiment_evaluator:,
+      remote_config_evaluator:,
+      workspace_fetcher:,
+      event_factory:,
+      event_processor:,
+      clock:
+    )
+      # @type experiment_evaluator [ExperimentEvaluator]
+      @experiment_evaluator = experiment_evaluator
+      # @type remote_config_evaluator [RemoteConfigEvaluator]
+      @remote_config_evaluator = remote_config_evaluator
+      # @type workspace_fetcher [WorkspaceFetcher]
+      @workspace_fetcher = workspace_fetcher
+      # @type event_factory [UserEventFactory]
+      @event_factory = event_factory
+      # @type event_processor [UserEventProcessor]
+      @event_processor = event_processor
+      # @type clock [Clock]
+      @clock = clock
+    end
+
+    # @param workspace_fetcher [WorkspaceFetcher]
+    # @param event_processor [UserEventProcessor]
+    # @return [Core]
+    def self.create(workspace_fetcher:, event_processor:)
+      delegating_evaluator = DelegatingEvaluator.new
+
+      condition_matcher_factory = ConditionMatcherFactory.new(evaluator: delegating_evaluator)
+      target_matcher = TargetMatcher.new(condition_matcher_factory: condition_matcher_factory)
+      bucketer = Bucketer.new(hasher: Hasher.new)
+
+      experiment_evaluator = ExperimentEvaluator.new(
+        flow_factory: ExperimentEvaluationFlowFactory.new(
+          target_matcher: target_matcher,
+          bucketer: bucketer
+        )
+      )
+      delegating_evaluator.add(experiment_evaluator)
+
+      remote_config_evaluator = RemoteConfigEvaluator.new(
+        target_rule_determiner: RemoteConfigTargetRuleDeterminer.new(
+          matcher: RemoteConfigTargetRuleMatcher.new(
+            target_matcher: target_matcher,
+            bucketer: bucketer
+          )
+        )
+      )
+      delegating_evaluator.add(remote_config_evaluator)
+
+      Core.new(
+        experiment_evaluator: experiment_evaluator,
+        remote_config_evaluator: remote_config_evaluator,
+        workspace_fetcher: workspace_fetcher,
+        event_factory: UserEventFactory.new(clock: SystemClock.instance),
+        event_processor: event_processor,
+        clock: SystemClock.instance
+      )
+    end
+
+    # @param experiment_key [Integer]
+    # @param user [HackleUser]
+    # @param default_variation [String]
+    # @return [ExperimentDecision]
+    def experiment(experiment_key, user, default_variation)
+      workspace = @workspace_fetcher.fetch
+      return ExperimentDecision.new(default_variation, DecisionReason::SDK_NOT_READY, ParameterConfig.empty) if workspace.nil?
+
+      experiment = workspace.get_experiment_or_nil(experiment_key)
+      return ExperimentDecision.new(default_variation, DecisionReason::EXPERIMENT_NOT_FOUND, ParameterConfig.empty) if experiment.nil?
+
+      request = ExperimentRequest.create(workspace, user, experiment, default_variation)
+      evaluation = @experiment_evaluator.evaluate(request, Evaluator.context)
+
+      events = @event_factory.create(request, evaluation)
+      events.each do |event|
+        @event_processor.process(event)
+      end
+
+      ExperimentDecision.new(evaluation.variation_key, evaluation.reason, evaluation.parameter_config)
+    end
+
+    # @param feature_key [Integer]
+    # @param user [HackleUser]
+    # @return [FeatureFlagDecision]
+    def feature_flag(feature_key, user)
+      workspace = @workspace_fetcher.fetch
+      return FeatureFlagDecision.new(false, DecisionReason::SDK_NOT_READY, ParameterConfig.empty) if workspace.nil?
+
+      feature_flag = workspace.get_feature_flag_or_nil(feature_key)
+      return FeatureFlagDecision.new(false, DecisionReason::FEATURE_FLAG_NOT_FOUND, ParameterConfig.empty) if feature_flag.nil?
+
+      request = ExperimentRequest.create(workspace, user, feature_flag, 'A')
+      evaluation = @experiment_evaluator.evaluate(request, Evaluator.context)
+
+      events = @event_factory.create(request, evaluation)
+      events.each do |event|
+        @event_processor.process(event)
+      end
+
+      is_on = evaluation.variation_key != 'A'
+      FeatureFlagDecision.new(is_on, evaluation.reason, evaluation.parameter_config)
+    end
+
+    # @param parameter_key [String]
+    # @param user [HackleUser]
+    # @param required_type [ValueType]
+    # @param default_value [Object, nil]
+    def remote_config(parameter_key, user, required_type, default_value)
+      workspace = @workspace_fetcher.fetch
+      return RemoteConfigDecision.new(default_value, DecisionReason::SDK_NOT_READY) if workspace.nil?
+
+      parameter = workspace.get_remote_config_parameter_or_nil(parameter_key)
+      return RemoteConfigDecision.new(default_value, DecisionReason::REMOTE_CONFIG_PARAMETER_NOT_FOUND) if parameter.nil?
+
+      request = RemoteConfigRequest.create(workspace, user, parameter, required_type, default_value)
+      evaluation = @remote_config_evaluator.evaluate(request, Evaluator.context)
+
+      events = @event_factory.create(request, evaluation)
+      events.each do |event|
+        @event_processor.process(event)
+      end
+
+      RemoteConfigDecision.new(evaluation.value, evaluation.reason)
+    end
+
+    # @param event [Event]
+    # @param user [HackleUser]
+    def track(event, user)
+      event_type = event_type(event)
+      @event_processor.process(UserEvent.track(event_type, event, user, @clock.current_millis))
+    end
+
+    def close
+      @workspace_fetcher.stop
+      @event_processor.stop
+    end
+
+    def resume
+      @workspace_fetcher.resume
+      @event_processor.resume
+    end
+
+    private
+
+    # @param event [Event]
+    # @return [EventType]
+    def event_type(event)
+      workspace = @workspace_fetcher.fetch
+      return EventType.new(id: 0, key: event.key) if workspace.nil?
+
+      event_type = workspace.get_event_type_or_nil(event.key)
+      return EventType.new(id: 0, key: event.key) if event_type.nil?
+
+      event_type
+    end
+  end
+end

data/lib/hackle/internal/evaluation/bucketer/bucketer.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'murmurhash3'
+
+module Hackle
+  class Bucketer
+
+    # @param hasher [Hasher]
+    def initialize(hasher:)
+      # @type [Hasher]
+      @hasher = hasher
+    end
+
+    # @param bucket [Bucket]
+    # @param identifier [String]
+    # @return [Slot, nil]
+    def bucketing(bucket, identifier)
+      slot_number = calculate_slot_number(seed: bucket.seed, slot_size: bucket.slot_size, value: identifier)
+      bucket.get_slot_or_nil(slot_number)
+    end
+
+    # @param seed [Integer]
+    # @param slot_size [Integer]
+    # @param value [String]
+    # @return [Integer]
+    def calculate_slot_number(seed:, slot_size:, value:)
+      hash_value = @hasher.hash(value, seed)
+      hash_value.abs % slot_size
+    end
+
+  end
+
+  class Hasher
+    # @param data [String]
+    # @param seed [Integer]
+    # @return [Integer]
+    def hash(data, seed)
+      unsigned_value = MurmurHash3::V32.str_hash(data, seed)
+      if (unsigned_value & 0x80000000).zero?
+        unsigned_value
+      else
+        -((unsigned_value ^ 0xFFFFFFFF) + 1)
+      end
+    end
+  end
+end

data/lib/hackle/internal/evaluation/evaluator/contextual/contextual_evaluator.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'hackle/internal/evaluation/evaluator/evaluator'
+
+module Hackle
+  module ContextualEvaluator
+    include Evaluator
+
+    # @param request [EvaluatorRequest]
+    # @return [boolean]
+    def supports?(request) end
+
+    # @param request [EvaluatorRequest]
+    # @param context [EvaluatorContext]
+    # @return [EvaluatorEvaluation]
+    def evaluate_internal(request, context) end
+
+    def evaluate(request, context)
+      raise ArgumentError, 'circular evaluation has occurred' if context.request_include?(request)
+
+      context.add_request(request)
+      begin
+        evaluate_internal(request, context)
+      ensure
+        context.remove_request(request)
+      end
+    end
+  end
+end

data/lib/hackle/internal/evaluation/evaluator/delegating/delegating_evaluator.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'hackle/internal/evaluation/evaluator/evaluator'
+
+module Hackle
+  class DelegatingEvaluator
+    include Evaluator
+
+    def initialize
+      # @type [Array<ContextualEvaluator>]
+      @evaluators = []
+    end
+
+    # @param evaluator [ContextualEvaluator]
+    def add(evaluator)
+      @evaluators << evaluator
+    end
+
+    def evaluate(request, context)
+      evaluator = @evaluators.find { |it| it.supports?(request) }
+      raise ArgumentError, "unsupported EvaluatorRequest [#{request.class}]" if evaluator.nil?
+
+      evaluator.evaluate(request, context)
+    end
+  end
+end

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

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Hackle
+
+  module Evaluator
+    # @param request [EvaluatorRequest]
+    # @param context [EvaluatorContext]
+    # @return [EvaluatorEvaluation]
+    def evaluate(request, context) end
+
+    # @return [EvaluatorContext]
+    def self.context
+      EvaluatorContext.new
+    end
+  end
+
+  class EvaluatorRequest
+
+    # @return [EvaluatorKey]
+    attr_reader :key
+
+    # @return [Workspace]
+    attr_reader :workspace
+
+    # @return [HackleUser]
+    attr_reader :user
+
+    # @param key [EvaluatorKey]
+    # @param workspace [Workspace]
+    # @param user [HackleUser]
+    def initialize(key:, workspace:, user:)
+      @key = key
+      @workspace = workspace
+      @user = user
+    end
+
+    def ==(other)
+      other.is_a?(EvaluatorRequest) && key == other.key
+    end
+  end
+
+  class EvaluatorEvaluation
+
+    # @return [String]
+    attr_reader :reason
+
+    # @return [Array<EvaluatorEvaluation>]
+    attr_reader :target_evaluations
+
+    # @param reason [String]
+    # @param target_evaluations [Array<EvaluatorEvaluation>]
+    def initialize(reason:, target_evaluations:)
+      @reason = reason
+      @target_evaluations = target_evaluations
+    end
+  end
+
+  class EvaluatorContext
+
+    def initialize
+      # @type [Array<EvaluatorRequest>]
+      @requests = []
+      # @type [Array<EvaluatorEvaluation>]
+      @evaluations = []
+    end
+
+    # @return [Array<EvaluatorRequest>]
+    def requests
+      @requests.dup
+    end
+
+    # @param request [EvaluatorRequest]
+    # @return [boolean]
+    def request_include?(request)
+      @requests.include?(request)
+    end
+
+    # @param request [EvaluatorRequest]
+    def add_request(request)
+      @requests << request
+    end
+
+    # @param request [EvaluatorRequest]
+    def remove_request(request)
+      @requests.delete(request)
+    end
+
+    # @return [Array<EvaluatorEvaluation>]
+    def evaluations
+      @evaluations.dup
+    end
+
+    # @param evaluation [EvaluatorEvaluation]
+    def add_evaluation(evaluation)
+      @evaluations << evaluation
+    end
+  end
+
+  class EvaluatorKey
+    # @return [String]
+    attr_reader :type
+
+    # @return [Integer]
+    attr_reader :id
+
+    # @param type [String]
+    # @param id [Integer]
+    def initialize(type:, id:)
+      @type = type
+      @id = id
+    end
+
+    def ==(other)
+      other.is_a?(EvaluatorKey) && type == other.type && id == other.id
+    end
+  end
+end

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

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'hackle/internal/model/experiment'
+require 'hackle/internal/evaluation/flow/evaluation_flow'
+require 'hackle/internal/evaluation/evaluator/experiment/experiment_resolver'
+require 'hackle/internal/evaluation/evaluator/experiment/experiment_flow_evaluator'
+
+module Hackle
+  class ExperimentEvaluationFlowFactory
+    # @param target_matcher [TargetMatcher]
+    # @param bucketer [Bucketer]
+    def initialize(target_matcher:, bucketer:)
+
+      action_resolver = ExperimentActionResolver.new(bucketer: bucketer)
+      override_resolver = ExperimentOverrideResolver.new(
+        target_matcher: target_matcher,
+        action_resolver: action_resolver
+      )
+      container_resolver = ExperimentContainerResolver.new(bucketer: bucketer)
+      target_determiner = ExperimentTargetDeterminer.new(target_matcher: target_matcher)
+      target_rule_determiner = ExperimentTargetRuleDeterminer.new(target_matcher: target_matcher)
+
+      # @type [ExperimentFlow]
+      @ab_test_flow = EvaluationFlow.create(
+        [
+          OverrideExperimentFlowEvaluator.new(override_resolver: override_resolver),
+          IdentifierExperimentFlowEvaluator.new,
+          ContainerExperimentFlowEvaluator.new(container_resolver: container_resolver),
+          TargetExperimentFlowEvaluator.new(target_determiner: target_determiner),
+          DraftExperimentFlowEvaluator.new,
+          PausedExperimentFlowEvaluator.new,
+          CompletedExperimentFlowEvaluator.new,
+          TrafficAllocateExperimentFlowEvaluator.new(action_resolver: action_resolver)
+        ]
+      )
+
+      # @type [ExperimentFlow]
+      @feature_flag_flow = EvaluationFlow.create(
+        [
+          DraftExperimentFlowEvaluator.new,
+          PausedExperimentFlowEvaluator.new,
+          CompletedExperimentFlowEvaluator.new,
+          OverrideExperimentFlowEvaluator.new(override_resolver: override_resolver),
+          IdentifierExperimentFlowEvaluator.new,
+          TargetRuleExperimentFlowEvaluator.new(
+            target_rule_determiner: target_rule_determiner,
+            action_resolver: action_resolver
+          ),
+          DefaultRuleExperimentFlowEvaluator.new(action_resolver: action_resolver)
+        ]
+      )
+    end
+
+    # @param experiment_type [ExperimentType]
+    # @return [ExperimentFlow]
+    def get(experiment_type)
+      case experiment_type
+      when ExperimentType::AB_TEST
+        @ab_test_flow
+      when ExperimentType::FEATURE_FLAG
+        @feature_flag_flow
+      else
+        raise ArgumentError, "unsupported ExperimentType [#{experiment_type}]"
+      end
+    end
+  end
+end