hackle-ruby-sdk 0.0.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 81db70f8f36a1dca6c3f03bfef469313434fd8f17e053ab32baee9c7f029f8ac
-  data.tar.gz: beb13a5d67bbb19d4e7a11556021cc8ca911d8e20902d191fc98973aa0683581
+  metadata.gz: 2eb9518d11c4980c9a6abf036b8400fad5de381db6c60d2fc98b68e37cda8851
+  data.tar.gz: faf6536122c01e9a55f95eef4e6497313a7e09e2ff16ea1123ca6c7fdc56470a
 SHA512:
-  metadata.gz: a8c56e2a506eb133d44bbcce75cfe523e29105813147a458b0bef4728e90fa833f630b9a4432c9b7642ba1c201397755dd501eec4db5f69c55d311dbbdeaeee8
-  data.tar.gz: 1685a42a07a605653b86b3b7af369abdde427dba4308fcf763c9a4a3fad07ddcd87b1ba6a1561d2cb84ff14b878f86eea34e7b4aea1206a358e168961cb70fca
+  metadata.gz: cbf193163d0b5926f052e76b7b01e0ca472297ef5da32b2317e90a1f35450cefa6496a72bcd0e9d6c7faf83947b6a9379e07be7111f5fa0a5030b891013c6c1c
+  data.tar.gz: e9d8ed3a4439684fb0b3308edb0a2e48c36ba041fa8f081e33ddad237ee8a5b546f0c98a1ec05b5c4123f76fe9289bc2ea3e84d9b02b068a3833472eec77691e

data/README.md

@@ -1,8 +1,6 @@
 # Hackle::Ruby::Sdk
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/hackle/ruby/sdk`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-TODO: Delete this and the text above, and describe your gem
+Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/hackle`.
 
 ## Installation
 

data/hackle-ruby-sdk.gemspec

@@ -2,7 +2,7 @@
 
 lib = File.expand_path('lib', __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require 'hackle-ruby-sdk/version'
+require 'hackle/version'
 
 Gem::Specification.new do |spec|
   spec.name          = 'hackle-ruby-sdk'

data/lib/hackle-ruby-sdk.rb

@@ -1,22 +1,3 @@
-require 'hackle-ruby-sdk/decision/bucketer'
-require 'hackle-ruby-sdk/decision/decider'
+# frozen_string_literal: true
 
-require 'hackle-ruby-sdk/events/event'
-require 'hackle-ruby-sdk/events/event_dispatcher'
-require 'hackle-ruby-sdk/events/event_processor'
-
-require 'hackle-ruby-sdk/http/http'
-
-require 'hackle-ruby-sdk/models/bucket'
-require 'hackle-ruby-sdk/models/event_type'
-require 'hackle-ruby-sdk/models/experiment'
-require 'hackle-ruby-sdk/models/slot'
-require 'hackle-ruby-sdk/models/variation'
-
-require 'hackle-ruby-sdk/workspaces/http_workspace_fetcher'
-require 'hackle-ruby-sdk/workspaces/polling_workspace_fetcher'
-require 'hackle-ruby-sdk/workspaces/workspace'
-
-require 'hackle-ruby-sdk/client'
-require 'hackle-ruby-sdk/config'
-require 'hackle-ruby-sdk/version'
+require 'hackle'

data/lib/hackle.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require 'hackle/client'
+require 'hackle/config'
+require 'hackle/version'
+
+module Hackle
+
+  #
+  # Instantiates a Hackle client.
+  #
+  # @see Client#initialize
+  #
+  # @param sdk_key [String] The SDK key of your Hackle environment
+  # @param options Optional parameters of configuration options
+  #
+  # @return [Client] The Hackle client instance.
+  #
+  def self.client(sdk_key:, **options)
+    config = Config.new(options)
+    sdk_info = SdkInfo.new(key: sdk_key)
+
+    http_workspace_fetcher = HttpWorkspaceFetcher.new(config: config, sdk_info: sdk_info)
+    polling_workspace_fetcher = PollingWorkspaceFetcher.new(config: config, http_fetcher: http_workspace_fetcher)
+
+    event_dispatcher = EventDispatcher.new(config: config, sdk_info: sdk_info)
+    event_processor = EventProcessor.new(config: config, event_dispatcher: event_dispatcher)
+
+    polling_workspace_fetcher.start!
+    event_processor.start!
+
+    Client.new(
+      config: config,
+      workspace_fetcher: polling_workspace_fetcher,
+      event_processor: event_processor,
+      decider: Decider.new
+    )
+  end
+
+  #
+  # Instantiate a user to be used for the hackle sdk.
+  #
+  # The only required parameter is `id`, which must uniquely identify each user.
+  #
+  # @example
+  #  Hackle.user(id: 'ae2182e0')
+  #  Hackle.user(id: 'ae2182e0', app_version: '1.0.1', paying_customer: false)
+  #
+  # @param id [String] The identifier of the user. (e.g. device_id, account_id etc.)
+  # @param properties Additional properties of the user. (e.g. app_version, membership_grade, etc.)
+  #
+  # @return [User] The configured user object.
+  #
+  def self.user(id:, **properties)
+    User.new(id: id, properties: properties)
+  end
+
+  #
+  # Instantiate an event to be used for the hackle sdk.
+  #
+  # The only required parameter is `key`, which must uniquely identify each event.
+  #
+  # @example
+  #  Hackle.event(key: 'purchase')
+  #  Hackle.event(key: 'purchase', value: 42000.0, app_version: '1.0.1', payment_method: 'CARD' )
+  #
+  # @param key [String] The unique key of the events.
+  # @param value [Float] Optional numeric value of the events (e.g. purchase_amount, quantity, etc.)
+  # @param properties Additional properties of the events (e.g. app_version, os_type, etc.)
+  #
+  # @return [Event] The configured event object.
+  #
+  def self.event(key:, value: nil, **properties)
+    Event.new(key: key, value: value, properties: properties)
+  end
+end

data/lib/hackle/client.rb

@@ -0,0 +1,127 @@
+# 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'
+
+module Hackle
+
+  #
+  # A client for Hackle API.
+  #
+  class Client
+
+    #
+    # Initializes a Hackle client.
+    #
+    # @param config [Config]
+    # @param workspace_fetcher [PollingWorkspaceFetcher]
+    # @param event_processor [EventProcessor]
+    # @param decider [Decider]
+    #
+    def initialize(config:, workspace_fetcher:, event_processor:, decider:)
+      @logger = config.logger
+
+      # @type [PollingWorkspaceFetcher]
+      @workspace_fetcher = workspace_fetcher
+
+      # @type [EventProcessor]
+      @event_processor = event_processor
+
+      # @type [Decider]
+      @decider = decider
+    end
+
+    #
+    # Decide the variation to expose to the user for experiment.
+    #
+    # 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
+      end
+
+    rescue => e
+      @logger.error { "Unexpected error while deciding variation for experiment[#{experiment_key}]. Returning default variation[#{default_variation}]: #{e.inspect}" }
+      default_variation
+    end
+
+    #
+    # Records the event that occurred by the user.
+    #
+    # @param event [Event] the event that occurred.
+    # @param user [User] the user that occurred the event.
+    #
+    def track(event:, user:)
+
+      return if event.nil? || !event.is_a?(Event) || !event.valid?
+      return if user.nil? || !user.is_a?(User) || !user.valid?
+
+      workspace = @workspace_fetcher.fetch
+      return if workspace.nil?
+
+      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)
+
+    rescue => e
+      @logger.error { "Unexpected error while tracking event: #{e.inspect}" }
+    end
+
+    #
+    # Shutdown the background task and release the resources used for the background task.
+    #
+    def close
+      @workspace_fetcher.stop!
+      @event_processor.stop!
+    end
+  end
+end

data/lib/{hackle-ruby-sdk → hackle}/config.rb

@@ -20,7 +20,7 @@ module Hackle
     end
 
     def self.default_event_uri
-      'https://events.hackle.io'
+      'https://event.hackle.io'
     end
 
     def self.default_logger

data/lib/hackle/decision/bucketer.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'murmurhash3'
+
+module Hackle
+  class Bucketer
+
+    # @param bucket [Bucket]
+    # @param user [User]
+    #
+    # @return [Slot, nil]
+    def bucketing(bucket:, user:)
+      slot_number = calculate_slot_number(
+        seed: bucket.seed,
+        slot_size: bucket.slot_size,
+        user_id: user.id
+      )
+      bucket.get_slot(slot_number: slot_number)
+    end
+
+    # @param seed [Integer]
+    # @param slot_size [Integer]
+    # @param user_id [String]
+    #
+    # @return [Integer]
+    def calculate_slot_number(seed:, slot_size:, user_id:)
+      hash_value = hash(data: user_id, seed: seed)
+      hash_value.abs % slot_size
+    end
+
+    # @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/decision/decider.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Hackle
+  class Decision
+
+    class NotAllocated < Decision
+    end
+
+    class ForcedAllocated < Decision
+      # @return [String]
+      attr_reader :variation_key
+
+      # @param variation_key [String]
+      def initialize(variation_key:)
+        @variation_key = variation_key
+      end
+    end
+
+    class NaturalAllocated < Decision
+      # @return [Variation]
+      attr_reader :variation
+
+      # @param variation [Variation]
+      def initialize(variation:)
+        @variation = variation
+      end
+    end
+  end
+
+  class Decider
+    def initialize
+      @bucketer = Bucketer.new
+    end
+
+    # @param experiment [Experiment]
+    # @param user [User]
+    #
+    # @return [Decision]
+    def decide(experiment:, user:)
+      case experiment
+      when Experiment::Completed
+        Decision::ForcedAllocated.new(variation_key: experiment.winner_variation_key)
+      when Experiment::Running
+        decide_running(running_experiment: experiment, user: user)
+      else
+        NotAllocated.new
+      end
+    end
+
+    # @param running_experiment [Experiment::Running]
+    # @param user [User]
+    #
+    # @return [Decision]
+    def decide_running(running_experiment:, user:)
+
+      overridden_variation = running_experiment.get_overridden_variation(user: user)
+      return Decision::ForcedAllocated.new(variation_key: overridden_variation.key) unless overridden_variation.nil?
+
+      allocated_slot = @bucketer.bucketing(bucket: running_experiment.bucket, user: user)
+      return Decision::NotAllocated.new if allocated_slot.nil?
+
+      allocated_variation = running_experiment.get_variation(variation_id: allocated_slot.variation_id)
+      return Decision::NotAllocated.new if allocated_variation.nil?
+      return Decision::NotAllocated.new if allocated_variation.dropped
+
+      Decision::NaturalAllocated.new(variation: allocated_variation)
+    end
+  end
+end

data/lib/{hackle-ruby-sdk → hackle}/events/event_dispatcher.rb

@@ -6,10 +6,10 @@ module Hackle
     DEFAULT_DISPATCH_WORKER_SIZE = 2
     DEFAULT_DISPATCH_QUEUE_CAPACITY = 50
 
-    def initialize(config, sdk_info)
+    def initialize(config:, sdk_info:)
       @logger = config.logger
-      @client = HTTP.client(config.event_uri)
-      @headers = HTTP.sdk_headers(sdk_info)
+      @client = HTTP.client(base_uri: config.event_uri)
+      @headers = HTTP.sdk_headers(sdk_info: sdk_info)
       @dispatcher_executor = Concurrent::ThreadPoolExecutor.new(
         min_threads: DEFAULT_DISPATCH_WORKER_SIZE,
         max_threads: DEFAULT_DISPATCH_WORKER_SIZE,
@@ -17,10 +17,10 @@ module Hackle
       )
     end
 
-    def dispatch(events)
-      payload = create_payload(events)
+    def dispatch(events:)
+      payload = create_payload(events: events)
       begin
-        @dispatcher_executor.post { dispatch_payload(payload) }
+        @dispatcher_executor.post { dispatch_payload(payload: payload) }
       rescue Concurrent::RejectedExecutionError
         @logger.warn { 'Dispatcher executor queue is full. Event dispatch rejected' }
       end
@@ -35,7 +35,7 @@ module Hackle
 
     private
 
-    def dispatch_payload(payload)
+    def dispatch_payload(payload:)
       request = Net::HTTP::Post.new('/api/v1/events', @headers)
       request.content_type = 'application/json'
       request.body = payload.to_json
@@ -43,19 +43,19 @@ module Hackle
       response = @client.request(request)
 
       status_code = response.code.to_i
-      HTTP.check_successful(status_code)
+      HTTP.check_successful(status_code: status_code)
     rescue => e
       @logger.error { "Failed to dispatch events: #{e.inspect}" }
     end
 
-    def create_payload(events)
+    def create_payload(events:)
       exposure_events = []
       track_events = []
       events.each do |event|
         case event
-        when Event::Exposure
+        when UserEvent::Exposure
           exposure_events << create_exposure_event(event)
-        when Event::Track
+        when UserEvent::Track
           track_events << create_track_event(event)
         end
       end
@@ -65,24 +65,31 @@ module Hackle
       }
     end
 
-    def create_exposure_event(event)
+    #
+    # @param exposure [UserEvent::Exposure]
+    #
+    def create_exposure_event(exposure)
       {
-        timestamp: event.timestamp,
-        userId: event.user_id,
-        experimentId: event.experiment.id,
-        experimentKey: event.experiment.key,
-        variationId: event.variation.id,
-        variationKey: event.variation.key
+        timestamp: exposure.timestamp,
+        userId: exposure.user.id,
+        experimentId: exposure.experiment.id,
+        experimentKey: exposure.experiment.key,
+        variationId: exposure.variation.id,
+        variationKey: exposure.variation.key
       }
     end
 
-    def create_track_event(event)
+    #
+    # @param track [UserEvent::Track]
+    #
+    def create_track_event(track)
       {
-        timestamp: event.timestamp,
-        userId: event.user_id,
-        eventTypeId: event.event_type.id,
-        eventTypeKey: event.event_type.key,
-        value: event.value
+        timestamp: track.timestamp,
+        userId: track.user.id,
+        eventTypeId: track.event_type.id,
+        eventTypeKey: track.event_type.key,
+        value: track.event.value,
+        properties: track.event.properties
       }
     end
   end