hackle-ruby-sdk 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2eb9518d11c4980c9a6abf036b8400fad5de381db6c60d2fc98b68e37cda8851
-  data.tar.gz: faf6536122c01e9a55f95eef4e6497313a7e09e2ff16ea1123ca6c7fdc56470a
+  metadata.gz: 572cfbd5a794b4516be482e888dffdbfbf98485ea566ceef44187b8555f754d8
+  data.tar.gz: 80c1c73b16728ee50eab4a613c0810f42883db15154a0b697d796e003a222274
 SHA512:
-  metadata.gz: cbf193163d0b5926f052e76b7b01e0ca472297ef5da32b2317e90a1f35450cefa6496a72bcd0e9d6c7faf83947b6a9379e07be7111f5fa0a5030b891013c6c1c
-  data.tar.gz: e9d8ed3a4439684fb0b3308edb0a2e48c36ba041fa8f081e33ddad237ee8a5b546f0c98a1ec05b5c4123f76fe9289bc2ea3e84d9b02b068a3833472eec77691e
+  metadata.gz: 9f68e02af4c482fba3d10f8598ffc832240524791ad66e29db644996d128236e594c79602ec37e040ba800e6a77f3bab8eb226e5f336aa852c0b9e60eedbc723
+  data.tar.gz: 11eaa326223fd384bc0c0261c1ea3ef6ab7fbff6885570cf62ce3c124cdd0104d63f6525420c5a976c2e14cac932320f07e7aef80f1e0b751be6d1702e11b26d

data/lib/hackle/client.rb

@@ -1,127 +1,226 @@
 # frozen_string_literal: true
 
-require 'hackle/decision/bucketer'
-require 'hackle/decision/decider'
-
-require 'hackle/events/user_event'
-require 'hackle/events/event_dispatcher'
-require 'hackle/events/event_processor'
-
-require 'hackle/http/http'
-
-require 'hackle/models/bucket'
-require 'hackle/models/event'
-require 'hackle/models/event_type'
-require 'hackle/models/experiment'
-require 'hackle/models/slot'
-require 'hackle/models/user'
-require 'hackle/models/variation'
-
-require 'hackle/workspaces/http_workspace_fetcher'
-require 'hackle/workspaces/polling_workspace_fetcher'
-require 'hackle/workspaces/workspace'
+require 'hackle/event'
+require 'hackle/decision'
+require 'hackle/config'
+require 'hackle/remote_config'
+require 'hackle/version'
+require 'hackle/internal/concurrent/executors'
+require 'hackle/internal/logger/logger'
+require 'hackle/internal/model/sdk'
+require 'hackle/internal/model/decision_reason'
+require 'hackle/internal/config/parameter_config'
+require 'hackle/internal/workspace/http_workspace_fetcher'
+require 'hackle/internal/workspace/polling_workspace_fetcher'
+require 'hackle/internal/event/user_event_dispatcher'
+require 'hackle/internal/event/user_event_processor'
+require 'hackle/internal/http/http_client'
+require 'hackle/internal/core/hackle_core'
+require 'hackle/internal/user/hackle_user_resolver'
 
 module Hackle
-
   #
-  # A client for Hackle API.
+  # The entry point of Hackle SDKs.
   #
   class Client
+    # @param core [Hackle::Core]
+    # @param user_resolver [Hackle::HackleUserResolver]
+    def initialize(core:, user_resolver:)
+      # @type [Hackle::Core]
+      @core = core
+
+      # @type [Hackle::HackleUserResolver]
+      @user_resolver = user_resolver
+    end
+
+    @instance = {}
+
+    #
+    # Instantiates a Hackle client.
+    #
+    # @param sdk_key [String]
+    # @param config [Hackle::Config]
+    # @return [Hackle::Client]
+    #
+    def self.create(sdk_key:, config: Config.builder.build)
+      client = @instance[sdk_key]
+      unless client.nil?
+        client.__resume
+        return client
+      end
 
+      Log.init(config.logger)
+
+      sdk = Sdk.new(name: 'ruby-sdk', version: Hackle::VERSION, key: sdk_key)
+
+      http_workspace_fetcher = HttpWorkspaceFetcher.new(
+        http_client: HttpClient.create(base_url: config.sdk_url, sdk: sdk),
+        sdk: sdk
+      )
+      workspace_fetcher = PollingWorkspaceFetcher.new(
+        http_workspace_fetcher: http_workspace_fetcher,
+        scheduler: Executors.scheduler,
+        polling_interval_seconds: 10.0
+      )
+
+      event_dispatcher = UserEventDispatcher.create(
+        http_client: HttpClient.create(base_url: config.event_url, sdk: sdk),
+        executor: Executors.thread_pool(pool_size: 2, queue_capacity: 64)
+      )
+
+      event_processor = DefaultUserEventProcessor.new(
+        queue: SizedQueue.new(10_000),
+        event_dispatcher: event_dispatcher,
+        event_dispatch_size: 100,
+        flush_scheduler: Executors.scheduler,
+        flush_interval_seconds: 10.0,
+        shutdown_timeout_seconds: 10.0
+      )
+
+      workspace_fetcher.start
+      event_processor.start
+
+      core = Core.create(
+        workspace_fetcher: workspace_fetcher,
+        event_processor: event_processor
+      )
+
+      new_client = Client.new(
+        core: core,
+        user_resolver: HackleUserResolver.new
+      )
+      @instance[sdk_key] = new_client
+      new_client
+    end
+
+    #
+    # Decide the variation to expose to the user for experiment.
     #
-    # Initializes a Hackle client.
+    # @param experiment_key [Integer]
+    # @param user [Hackle::User]
     #
-    # @param config [Config]
-    # @param workspace_fetcher [PollingWorkspaceFetcher]
-    # @param event_processor [EventProcessor]
-    # @param decider [Decider]
+    # @return [String] the decided variation for the user
     #
-    def initialize(config:, workspace_fetcher:, event_processor:, decider:)
-      @logger = config.logger
+    def variation(experiment_key, user)
+      variation_detail(experiment_key, user).variation
+    end
 
-      # @type [PollingWorkspaceFetcher]
-      @workspace_fetcher = workspace_fetcher
+    #
+    # Decide the variation to expose to the user for experiment, and returns an object that
+    # describes the way the variation was decided.
+    #
+    # @param experiment_key [Integer] the unique key of the experiment. MUST NOT be nil.
+    # @param user [Hackle::User] the user to participate in the experiment. MUST NOT be nil.
+    #
+    # @return [Hackle::ExperimentDecision] an object describing the result
+    #
+    def variation_detail(experiment_key, user)
+      unless experiment_key.is_a?(Integer)
+        Log.get.warn { "Invalid experiment key: #{experiment_key} (expected: integer)" }
+        return ExperimentDecision.new('A', DecisionReason::INVALID_INPUT, ParameterConfig.empty)
+      end
 
-      # @type [EventProcessor]
-      @event_processor = event_processor
+      hackle_user = @user_resolver.resolve_or_nil(user)
+      if hackle_user.nil?
+        Log.get.warn { "Invalid hackle user: #{user}" }
+        return ExperimentDecision.new('A', DecisionReason::INVALID_INPUT, ParameterConfig.empty)
+      end
 
-      # @type [Decider]
-      @decider = decider
+      @core.experiment(experiment_key, hackle_user, 'A')
+    rescue => e
+      Log.get.error { "Unexpected error while deciding variation of experiment[#{experiment_key}]: #{e.inspect}]" }
+      ExperimentDecision.new('A', DecisionReason::EXCEPTION, ParameterConfig.empty)
     end
 
     #
-    # Decide the variation to expose to the user for experiment.
+    # Decide whether the feature is turned on to the user.
+    #
+    # @param feature_key [Integer] the unique key of the feature.
+    # @param user [Hackle::User] the user requesting the feature.
+    #
+    # @return [TrueClass] of the feature is on
+    # @return [FalseClass] of the feature is off
+    #
+    def is_feature_on(feature_key, user)
+      feature_flag_detail(feature_key, user).is_on
+    end
+
     #
-    # This method return the control variation 'A' if:
-    # - The experiment key is invalid
-    # - The experiment has not started yet
-    # - The user is not allocated to the experiment
-    # - The decided variation has been dropped
-    #
-    # @param experiment_key [Integer] The unique key of the experiment. MUST NOT be nil.
-    # @param user [User] the user to participate in the experiment. MUST NOT be nil.
-    # @param default_variation [String] The default variation of the experiment.
-    #
-    # @return [String] The decided variation for the user, or default variation
-    #
-    def variation(experiment_key:, user:, default_variation: 'A')
-
-      return default_variation if experiment_key.nil? || !experiment_key.is_a?(Integer)
-      return default_variation if user.nil? || !user.is_a?(User) || !user.valid?
-
-      workspace = @workspace_fetcher.fetch
-      return default_variation if workspace.nil?
-
-      experiment = workspace.get_experiment(experiment_key: experiment_key)
-      return default_variation if experiment.nil?
-
-      decision = @decider.decide(experiment: experiment, user: user)
-      case decision
-      when Decision::NotAllocated
-        default_variation
-      when Decision::ForcedAllocated
-        decision.variation_key
-      when Decision::NaturalAllocated
-        exposure_event = UserEvent::Exposure.new(user: user, experiment: experiment, variation: decision.variation)
-        @event_processor.process(event: exposure_event)
-        decision.variation.key
-      else
-        default_variation
+    # Decide whether the feature is turned on to the user, and returns an object that
+    # describes the way the value was decided.
+    #
+    # @param feature_key [Integer] the unique key of the feature.
+    # @param user [Hackle::User] the user requesting the feature.
+    #
+    # @return [Hackle::FeatureFlagDecision] an object describing the result
+    #
+    def feature_flag_detail(feature_key, user)
+      unless feature_key.is_a?(Integer)
+        Log.get.warn { "Invalid feature key: #{feature_key} (expected: integer)" }
+        return FeatureFlagDecision.new(false, DecisionReason::INVALID_INPUT, ParameterConfig.empty)
       end
 
+      hackle_user = @user_resolver.resolve_or_nil(user)
+      if hackle_user.nil?
+        Log.get.warn { "Invalid hackle user: #{user}" }
+        return FeatureFlagDecision.new(false, DecisionReason::INVALID_INPUT, ParameterConfig.empty)
+      end
+
+      @core.feature_flag(feature_key, hackle_user)
     rescue => e
-      @logger.error { "Unexpected error while deciding variation for experiment[#{experiment_key}]. Returning default variation[#{default_variation}]: #{e.inspect}" }
-      default_variation
+      Log.get.error { "Unexpected error while deciding feature flag[#{feature_key}]: #{e.inspect}]" }
+      FeatureFlagDecision.new(false, DecisionReason::EXCEPTION, ParameterConfig.empty)
     end
 
     #
-    # Records the event that occurred by the user.
+    # Returns a instance of Hackle::RemoteConfig.
     #
-    # @param event [Event] the event that occurred.
-    # @param user [User] the user that occurred the event.
+    # @param user [Hackle::User] the user requesting the remote config.
     #
-    def track(event:, user:)
+    # @return [Hackle::RemoteConfig]
+    #
+    def remote_config(user)
+      RemoteConfig.new(user: user, user_resolver: @user_resolver, core: @core)
+    end
 
-      return if event.nil? || !event.is_a?(Event) || !event.valid?
-      return if user.nil? || !user.is_a?(User) || !user.valid?
+    #
+    # Records the event that occurred by the user.
+    #
+    # @param event [Hackle::Event] the event that occurred.
+    # @param user [Hackle::User] the user that occurred the event.
+    #
+    def track(event, user)
+      unless event.is_a?(Event)
+        Log.get.warn { "Invalid event: #{event} (expected: Hackle::Event)" }
+        return
+      end
 
-      workspace = @workspace_fetcher.fetch
-      return if workspace.nil?
+      unless event.valid?
+        Log.get.error { "Invalid event: #{event.error_or_nil}" }
+        return
+      end
 
-      event_type = workspace.get_event_type(event_type_key: event.key)
-      track_event = UserEvent::Track.new(user: user, event_type: event_type, event: event)
-      @event_processor.process(event: track_event)
+      hackle_user = @user_resolver.resolve_or_nil(user)
+      if hackle_user.nil?
+        Log.get.warn { "Invalid hackle user: #{user}" }
+        return FeatureFlagDecision.new(false, DecisionReason::INVALID_INPUT, ParameterConfig.empty)
+      end
 
+      @core.track(event, hackle_user)
     rescue => e
-      @logger.error { "Unexpected error while tracking event: #{e.inspect}" }
+      Log.get.error { "Unexpected error while tracking event: #{e.inspect}]" }
     end
 
     #
     # Shutdown the background task and release the resources used for the background task.
+    # This should only be called when the application shutdown.
     #
     def close
-      @workspace_fetcher.stop!
-      @event_processor.stop!
+      @core.close
+    end
+
+    def __resume
+      @core.resume
     end
   end
 end

data/lib/hackle/config.rb

@@ -4,30 +4,72 @@ require 'logger'
 
 module Hackle
   class Config
+    # @return [Logger]
+    attr_reader :logger
 
-    def initialize(options = {})
-      @logger = options[:logger] || Config.default_logger
-      @base_uri = options[:base_uri] || Config.default_base_uri
-      @event_uri = options[:event_uri] || Config.default_event_uri
-    end
+    # @return [String]
+    attr_reader :sdk_url
 
-    attr_reader :logger
-    attr_reader :base_uri
-    attr_reader :event_uri
+    # @return [String]
+    attr_reader :event_url
 
-    def self.default_base_uri
-      'https://sdk.hackle.io'
+    # @param logger [Logger]
+    # @param sdk_url [String]
+    # @param event_url [String]
+    def initialize(
+      logger:,
+      sdk_url:,
+      event_url:
+    )
+      @logger = logger
+      @sdk_url = sdk_url
+      @event_url = event_url
     end
 
-    def self.default_event_uri
-      'https://event.hackle.io'
+    def self.builder
+      Builder.new
     end
 
-    def self.default_logger
-      if defined?(Rails) && Rails.logger
-        Rails.logger
-      else
-        Logger.new($stdout)
+    class Builder
+      def initialize
+        # noinspection RubyResolve
+        @logger = if defined?(Rails) && Rails.logger
+                    Rails.logger
+                  else
+                    Logger.new($stdout)
+                  end
+        @sdk_url = 'https://sdk.hackle.io'
+        @event_url = 'https://event.hackle.io'
+      end
+
+      # @param logger [Logger]
+      # @return [Hackle::Config::Builder]
+      def logger(logger)
+        @logger = logger
+        self
+      end
+
+      # @param sdk_url [String]
+      # @return [Hackle::Config::Builder]
+      def sdk_url(sdk_url)
+        @sdk_url = sdk_url
+        self
+      end
+
+      # @param event_url [String]
+      # @return [Hackle::Config::Builder]
+      def event_url(event_url)
+        @event_url = event_url
+        self
+      end
+
+      # @return [Hackle::Config]
+      def build
+        Config.new(
+          logger: @logger,
+          sdk_url: @sdk_url,
+          event_url: @event_url
+        )
       end
     end
   end

data/lib/hackle/decision.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Hackle
+  class ExperimentDecision
+
+    # @return [String]
+    attr_reader :variation
+
+    # @return [String]
+    attr_reader :reason
+
+    # @return [ParameterConfig]
+    attr_reader :config
+
+    # @param variation [String]
+    # @param reason [String]
+    # @param config [ParameterConfig]
+    def initialize(variation, reason, config)
+      @config = config
+      @variation = variation
+      @reason = reason
+    end
+
+    # @param key [String]
+    # @param default_value [Object, nil]
+    # @return [Object, nil]
+    def get(key, default_value = nil)
+      config.get(key, default_value)
+    end
+
+    def ==(other)
+      other.is_a?(self.class) &&
+        variation == other.variation &&
+        reason == other.reason &&
+        config == other.config
+    end
+
+    def to_s
+      "ExperimentDecision(variation=#{variation}, reason=#{reason}, config=#{config})"
+    end
+
+  end
+
+  class FeatureFlagDecision
+
+    # @return [boolean]
+    attr_accessor :is_on
+
+    # @return [String]
+    attr_accessor :reason
+
+    # @return [ParameterConfig]
+    attr_reader :config
+
+    # @param is_on [boolean]
+    # @param reason [String]
+    # @param config [ParameterConfig]
+    def initialize(is_on, reason, config)
+      @is_on = is_on
+      @reason = reason
+      @config = config
+    end
+
+    # @return [boolean]
+    def on?
+      @is_on
+    end
+
+    # @param key [String]
+    # @param default_value [Object, nil]
+    # @return [Object, nil]
+    def get(key, default_value = nil)
+      config.get(key, default_value)
+    end
+
+    def ==(other)
+      other.is_a?(FeatureFlagDecision) &&
+        is_on == other.is_on &&
+        reason == other.reason &&
+        config == other.config
+    end
+
+    def to_s
+      "FeatureFlagDecision(is_on=#{is_on}, reason=#{reason}, config=#{config})"
+    end
+  end
+
+  class RemoteConfigDecision
+
+    # @return [Object, nil]
+    attr_reader :value
+
+    # @return [String]
+    attr_reader :reason
+
+    # @param value [Object, nil]
+    # @param reason [String]
+    def initialize(value, reason)
+      @value = value
+      @reason = reason
+    end
+
+    def ==(other)
+      other.is_a?(RemoteConfigDecision) &&
+        value == other.value &&
+        reason == other.reason
+    end
+
+    def to_s
+      "RemoteConfigDecision(value=#{value}, reason=#{reason})"
+    end
+  end
+end

data/lib/hackle/event.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require 'hackle/internal/properties/properties_builder'
+
+module Hackle
+  class Event
+    # @return [String]
+    attr_reader :key
+
+    # @return [Float, nil]
+    attr_reader :value
+
+    # @return [Hash{String => Object}]
+    attr_reader :properties
+
+    # @param key [String]
+    # @param value [Numeric, nil]
+    # @param properties [Hash{String => Object}]
+    def initialize(key:, value:, properties:)
+      @key = key
+      @value = value
+      @properties = properties
+    end
+
+    # @return [boolean]
+    def valid?
+      error_or_nil.nil?
+    end
+
+    # @return [String, nil]
+    def error_or_nil
+      return "Invalid event key: #{key} (expected: not empty string)" unless ValueType.not_empty_string?(key)
+      return "Invalid event value: #{value} (expected: number)" if !value.nil? && !ValueType.number?(value)
+      return "Invalid event properties: #{properties} (expected: Hash)" if !properties.nil? && !properties.is_a?(Hash)
+
+      nil
+    end
+
+    def ==(other)
+      other.is_a?(Event) && other.key == key && other.value == value && other.properties == properties
+    end
+
+    def to_s
+      "Hackle::Event(key: #{key}, value: #{value}, properties: #{properties})"
+    end
+
+    # @param key [String]
+    # @return [Hackle::Event::Builder]
+    def self.builder(key)
+      Builder.new(key)
+    end
+
+    class Builder
+      # @param key [String]
+      def initialize(key)
+        @key = key
+        @value = nil
+        @properties = PropertiesBuilder.new
+      end
+
+      # @param value [Float, nil]
+      # @return [Hackle::Event::Builder]
+      def value(value)
+        @value = value
+        self
+      end
+
+      # @param key [String]
+      # @param value [Object, nil]
+      # @return [Hackle::Event::Builder]
+      def property(key, value)
+        @properties.add(key, value)
+        self
+      end
+
+      # @param properties [Hash{String => Object}]
+      # @return [Hackle::Event::Builder]
+      def properties(properties)
+        @properties.add_all(properties)
+        self
+      end
+
+      # @return [Hackle::Event]
+      def build
+        Event.new(key: @key, value: @value, properties: @properties.build)
+      end
+    end
+  end
+end

data/lib/hackle/internal/clock/clock.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Hackle
+  module Clock
+    # @return [Integer]
+    def current_millis; end
+
+    # @return [Integer]
+    def tick; end
+  end
+
+  class SystemClock
+    include Clock
+
+    @instance = new
+
+    # @return [SystemClock]
+    def self.instance
+      @instance
+    end
+
+    def current_millis
+      (Time.now.to_f * 1000).to_i
+    end
+
+    def tick
+      (Time.now.to_f * 1000 * 1000 * 1000).to_i
+    end
+  end
+
+  class FixedClock
+    include Clock
+
+    # @param time [Integer]
+    def initialize(time)
+      @time = time
+    end
+
+    def current_millis
+      @time
+    end
+
+    def tick
+      @time
+    end
+  end
+end

data/lib/hackle/internal/concurrent/executors.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'concurrent'
+require 'hackle/internal/concurrent/schedule/timer_scheduler'
+
+module Hackle
+  class Executors
+    # @param pool_size [Integer]
+    # @param queue_capacity [Integer]
+    # @return [Concurrent::ThreadPoolExecutor]
+    def self.thread_pool(pool_size:, queue_capacity:)
+      Concurrent::ThreadPoolExecutor.new(min_threads: pool_size, max_threads: pool_size, max_queue: queue_capacity)
+    end
+
+    # @return [TimerScheduler]
+    def self.scheduler
+      TimerScheduler.new
+    end
+  end
+end