hackle-ruby-sdk 1.0.0 → 2.0.0

data/lib/hackle/internal/event/user_event_dispatcher.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'hackle/internal/http/http'
+
+module Hackle
+  class UserEventDispatcher
+    # @param http_client [HttpClient]
+    # @param executor [ThreadPoolExecutor]
+    # @param serializer [UserEventSerializer]
+    def initialize(http_client:, executor:, serializer:)
+      # @type [HttpClient]
+      @http_client = http_client
+      # @type [ThreadPoolExecutor]
+      @executor = executor
+      @serializer = serializer
+      @url = '/api/v2/events'
+    end
+
+    # @param http_client [HttpClient]
+    # @param executor [ThreadPoolExecutor]
+    def self.create(http_client:, executor:)
+      UserEventDispatcher.new(
+        http_client: http_client,
+        executor: executor,
+        serializer: UserEventSerializer.new
+      )
+    end
+
+    # @param events [Array<UserEvent>]
+    def dispatch(events)
+      payload = @serializer.serialize(events)
+      begin
+        @executor.post { dispatch_internal(payload) }
+      rescue => e
+        Log.get.error { "Unexpected error while posting events: #{e.inspect}" }
+      end
+    end
+
+    def shutdown
+      @executor.shutdown
+      return if @executor.wait_for_termination(10)
+
+      Log.get.warn { 'Failed to dispatch previously submitted events' }
+    end
+
+    private
+
+    # @param payload [Hash]
+    def dispatch_internal(payload)
+      request = create_request(payload)
+      response = @http_client.execute(request)
+      handle_response(response)
+    rescue => e
+      Log.get.error { "Failed to dispatch events: #{e.inspect}" }
+    end
+
+    # @param payload [Hash]
+    # @return [Net::HTTPRequest]
+    def create_request(payload)
+      request = Net::HTTP::Post.new(@url)
+      request.content_type = 'application/json'
+      request.body = payload.to_json
+      request
+    end
+
+    # @param response [Net::HTTPResponse]
+    def handle_response(response)
+      raise "http status code: #{response.code}" unless HTTP.successful? response
+    end
+  end
+
+  class UserEventSerializer
+    # @param events [Array<UserEvent>]
+    # @return [Hash]
+    def serialize(events)
+      exposure_events = []
+      track_events = []
+      remote_config_events = []
+
+      events.each do |event|
+        exposure_events << exposure_event(event) if event.is_a? ExposureEvent
+        track_events << track_event(event) if event.is_a? TrackEvent
+        remote_config_events << remote_config_event(event) if event.is_a? RemoteConfigEvent
+      end
+      {
+        exposureEvents: exposure_events,
+        trackEvents: track_events,
+        remoteConfigEvents: remote_config_events
+      }
+    end
+
+    # @param event [ExposureEvent]
+    # @return [Hash]
+    def exposure_event(event)
+      {
+        insertId: event.insert_id,
+        timestamp: event.timestamp,
+
+        userId: event.user.identifiers['$id'],
+        identifiers: event.user.identifiers,
+        userProperties: event.user.properties,
+        hackleProperties: {},
+
+        experimentId: event.experiment.id,
+        experimentKey: event.experiment.key,
+        experimentType: event.experiment.type.name,
+        experimentVersion: event.experiment.version,
+        variationId: event.variation_id,
+        variationKey: event.variation_key,
+        decisionReason: event.decision_reason,
+        properties: event.properties
+      }
+    end
+
+    # @param event [TrackEvent]
+    # @return [Hash]
+    def track_event(event)
+      {
+        insertId: event.insert_id,
+        timestamp: event.timestamp,
+
+        userId: event.user.identifiers['$id'],
+        identifiers: event.user.identifiers,
+        userProperties: event.user.properties,
+        hackleProperties: {},
+
+        eventTypeId: event.event_type.id,
+        eventTypeKey: event.event_type.key,
+        value: event.event.value,
+        properties: event.event.properties
+      }
+    end
+
+    # @param event [RemoteConfigEvent]
+    # @return [Hash]
+    def remote_config_event(event)
+      {
+        insertId: event.insert_id,
+        timestamp: event.timestamp,
+
+        userId: event.user.identifiers['$id'],
+        identifiers: event.user.identifiers,
+        userProperties: event.user.properties,
+        hackleProperties: {},
+
+        parameterId: event.parameter.id,
+        parameterKey: event.parameter.key,
+        parameterType: event.parameter.type.name,
+        valueId: event.value_id,
+        decisionReason: event.decision_reason,
+        properties: event.properties
+      }
+    end
+  end
+end

data/lib/hackle/internal/event/user_event_factory.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require 'hackle/internal/evaluation/evaluator/experiment/experiment_evaluator'
+
+module Hackle
+  class UserEventFactory
+    # @param clock [Clock]
+    def initialize(clock:)
+      # @type [Clock]
+      @clock = clock
+    end
+
+    # @param request [EvaluatorRequest]
+    # @param evaluation [EvaluatorEvaluation]
+    # @return [Array<UserEvent>]
+    def create(request, evaluation)
+      timestamp = @clock.current_millis
+      events = []
+
+      root_event = create_internal(request, evaluation, timestamp, PropertiesBuilder.new)
+      events << root_event unless root_event.nil?
+
+      evaluation.target_evaluations.each do |target_evaluation|
+        properties_builder = PropertiesBuilder.new
+        properties_builder.add('$targetingRootType', request.key.type)
+        properties_builder.add('$targetingRootId', request.key.id)
+        target_event = create_internal(request, target_evaluation, timestamp, properties_builder)
+        events << target_event unless target_event.nil?
+      end
+
+      events
+    end
+
+    private
+
+    # @param request [EvaluatorRequest]
+    # @param evaluation [EvaluatorEvaluation]
+    # @param timestamp [Integer]
+    # @param properties_builder [PropertiesBuilder]
+    # @return [UserEvent, nil]
+    def create_internal(request, evaluation, timestamp, properties_builder)
+      e = evaluation
+      case e
+      when ExperimentEvaluation
+        properties_builder.add('$parameterConfigurationId', e.config&.id)
+        properties_builder.add('$experiment_version', e.experiment.version)
+        properties_builder.add('$execution_version', e.experiment.execution_version)
+        UserEvent.exposure(e, properties_builder.build, request.user, timestamp)
+      when RemoteConfigEvaluation
+        properties_builder.add_all(e.properties)
+        UserEvent.remote_config(e, properties_builder.build, request.user, timestamp)
+      else
+        Log.get.error { "unsupported evaluator evaluation: #{e.class}" }
+        nil
+      end
+    end
+  end
+end

data/lib/hackle/internal/event/user_event_processor.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require 'hackle/internal/logger/logger'
+
+module Hackle
+  module UserEventProcessor
+    # @param event [UserEvent]
+    def process(event) end
+
+    def start
+    end
+
+    def stop
+    end
+
+    def resume
+    end
+  end
+
+  # noinspection RubyTooManyInstanceVariablesInspection
+  class DefaultUserEventProcessor
+    include UserEventProcessor
+    # @param queue [SizedQueue]
+    # @param event_dispatcher [UserEventDispatcher]
+    # @param event_dispatch_size [Integer]
+    # @param flush_scheduler [Scheduler]
+    # @param flush_interval_seconds [Float]
+    # @param shutdown_timeout_seconds [Float]
+    def initialize(
+      queue:,
+      event_dispatcher:,
+      event_dispatch_size:,
+      flush_scheduler:,
+      flush_interval_seconds:,
+      shutdown_timeout_seconds:
+    )
+      # @type [SizedQueue]
+      @queue = queue
+
+      # @type [UserEventDispatcher]
+      @event_dispatcher = event_dispatcher
+
+      # @type [Integer]
+      @event_dispatch_size = event_dispatch_size
+
+      # @type [Scheduler]
+      @flush_scheduler = flush_scheduler
+
+      # @type [Float]
+      @flush_interval_seconds = flush_interval_seconds
+
+      # @type [Float]
+      @shutdown_timeout_seconds = shutdown_timeout_seconds
+
+      # @type [ScheduledJob, nil]
+      @flushing_job = nil
+
+      # @type [Thread, nil]
+      @consuming_task = nil
+
+      # @type [boolean]
+      @is_started = false
+
+      # @type [Array<UserEvent>]
+      @current_batch = []
+    end
+
+    # @param event [UserEvent]
+    def process(event)
+      produce(message: Message::Event.new(event))
+    end
+
+    def start
+      if @is_started
+        Log.get.info { "#{UserEventProcessor} is already started." }
+        return
+      end
+
+      @consuming_task = Thread.new { consuming }
+      @flushing_job = @flush_scheduler.schedule_periodically(@flush_interval_seconds, -> { flush })
+      @is_started = true
+      Log.get.info { "#{UserEventProcessor} started. Flush event every #{@flush_interval_seconds} seconds." }
+    end
+
+    def stop
+      return unless @is_started
+
+      Log.get.info { "Shutting down #{UserEventProcessor}" }
+
+      @flushing_job&.cancel
+
+      produce(message: Message::Shutdown.new, non_block: false)
+      @consuming_task&.join(@shutdown_timeout_seconds)
+
+      @event_dispatcher.shutdown
+
+      @is_started = false
+    end
+
+    def resume
+      @consuming_task = Thread.new { consuming } if @consuming_task.nil? || !@consuming_task.alive?
+
+      @flushing_job&.cancel
+      @flushing_job = @flush_scheduler.schedule_periodically(@flush_interval_seconds, -> { flush })
+
+      @is_started = true
+    end
+
+    private
+
+    # @param message [Message]
+    # @param non_block [boolean]
+    def produce(message:, non_block: true)
+      @queue.push(message, non_block)
+    rescue ThreadError
+      Log.get.warn { 'Events are produced faster than can be consumed. Some events will be dropped.' }
+    end
+
+    def flush
+      produce(message: Message::Flush.new)
+    end
+
+    def consuming
+      loop do
+        message = @queue.pop
+        case message
+        when Message::Event
+          consume_event(message.event)
+        when Message::Flush
+          dispatch_events
+        when Message::Shutdown
+          break
+        else
+          Log.get.error { "Unsupported message type: #{message.class}" }
+        end
+      rescue => e
+        Log.get.error { "Unexpected error in event processor: #{e.inspect}" }
+      end
+    rescue => e
+      Log.get.error { "Unexpected error in event processor: #{e.inspect}" }
+    ensure
+      dispatch_events
+    end
+
+    # @param event [UserEvent]
+    def consume_event(event)
+      @current_batch << event
+      dispatch_events if @current_batch.size >= @event_dispatch_size
+    end
+
+    def dispatch_events
+      return if @current_batch.empty?
+
+      begin
+        @event_dispatcher.dispatch(@current_batch)
+        @current_batch = []
+      rescue => e
+        Log.get.error { "Failed to dispatch events: #{e.inspect}" }
+      end
+    end
+
+    class Message
+      class Event < Message
+        # @return [UserEvent]
+        attr_reader :event
+
+        # @param event [UserEvent]
+        def initialize(event)
+          super()
+          @event = event
+        end
+      end
+
+      class Flush < Message
+      end
+
+      class Shutdown < Message
+      end
+    end
+  end
+end

data/lib/hackle/internal/http/http.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'net/http'
+
+module Hackle
+  module HTTP
+
+    def self.client(base_url:)
+      uri = URI.parse(base_url)
+      # noinspection RubyMismatchedArgumentType
+      client = Net::HTTP.new(uri.host, uri.port)
+      client.use_ssl = uri.scheme == 'https'
+      client.open_timeout = 5
+      client.read_timeout = 10
+      client
+    end
+
+    # @param response [Net::HTTPResponse]
+    def self.successful?(response)
+      response.code.start_with?('2')
+    end
+
+    # @param response [Net::HTTPResponse]
+    def self.not_modified?(response)
+      response.code == '304'
+    end
+  end
+end

data/lib/hackle/internal/http/http_client.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'hackle/internal/http/http'
+require 'hackle/internal/clock/clock'
+
+module Hackle
+  class HttpClient
+
+    # @param http [Net::HTTP]
+    # @param sdk [Sdk]
+    # @param clock [Clock]
+    def initialize(http:, sdk:, clock:)
+      # @type [Net::HTTP]
+      @http = http
+      @sdk = sdk
+      @clock = clock
+    end
+
+    # @param base_url [String]
+    # @param sdk [Sdk]
+    # @param clock [Clock]
+    # @return [HttpClient]
+    def self.create(base_url:, sdk:, clock: SystemClock.instance)
+      HttpClient.new(
+        http: HTTP.client(base_url: base_url),
+        sdk: sdk,
+        clock: clock
+      )
+    end
+
+    # @param request [Net::HTTPRequest]
+    # @return [Net::HTTPResponse]
+    def execute(request)
+      decorate(request)
+      @http.request(request)
+    end
+
+    private
+
+    # @param request [Net::HTTPRequest]
+    def decorate(request)
+      request['X-HACKLE-SDK-KEY'] = @sdk.key
+      request['X-HACKLE-SDK-NAME'] = @sdk.name
+      request['X-HACKLE-SDK-VERSION'] = @sdk.version
+      request['X-HACKLE-SDK-TIME'] = @clock.current_millis.to_s
+    end
+  end
+end

data/lib/hackle/internal/identifiers/identifier_builder.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'hackle/internal/logger/logger'
+
+module Hackle
+  class IdentifiersBuilder
+    def initialize
+      # @type [Hash{String => String}]
+      @identifiers = {}
+    end
+
+    # @param identifier_type [String]
+    # @param identifier_value [String, nil]
+    # @return [Hackle::IdentifiersBuilder]
+    def add(identifier_type, identifier_value)
+      value = IdentifiersBuilder.sanitize_value_or_nil(identifier_value)
+
+      if valid_type?(identifier_type) && !value.nil?
+        @identifiers[identifier_type] = value
+      else
+        Log.get.warn { "Invalid user identifier [type=#{identifier_type}] value=#{identifier_value}]" }
+      end
+
+      self
+    end
+
+    # @param identifiers [Hash]
+    # @return [Hackle::IdentifiersBuilder]
+    def add_all(identifiers)
+      identifiers.each do |identifier_type, identifier_value|
+        add(identifier_type, identifier_value)
+      end
+      self
+    end
+
+    # @return [Hash{String => String}]
+    def build
+      @identifiers.dup
+    end
+
+    def self.sanitize_value_or_nil(identifier_value)
+      return nil if identifier_value.nil?
+
+      if identifier_value.is_a?(String) && !identifier_value.empty? && identifier_value.length <= MAX_IDENTIFIER_VALUE_LENGTH
+        return identifier_value
+      end
+
+      return identifier_value.to_s if identifier_value.is_a?(Numeric)
+
+      nil
+    end
+
+    private
+
+    MAX_IDENTIFIER_TYPE_LENGTH = 128
+    MAX_IDENTIFIER_VALUE_LENGTH = 512
+
+    def valid_type?(identifier_type)
+      return false if identifier_type.nil?
+      return false unless identifier_type.is_a?(String)
+      return false if identifier_type.empty?
+      return false if identifier_type.length > MAX_IDENTIFIER_TYPE_LENGTH
+
+      true
+    end
+  end
+end

data/lib/hackle/internal/logger/logger.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+module Hackle
+
+  class Log
+
+    attr_accessor :logger
+
+    def initialize
+      @logger = Logger.new($stdout)
+    end
+
+    @instance = new
+
+    # @return [Log]
+    def self.instance
+      @instance
+    end
+
+    def self.init(logger)
+      instance.logger = logger
+    end
+
+    # @return [Logger]
+    def self.get
+      Log.instance.logger
+    end
+  end
+end

data/lib/hackle/internal/model/action.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Hackle
+  class Action
+
+    # @!attribute [r] type
+    #   @return [ActionType]
+    # @!attribute [r] variation_id
+    #   @return [Integer, nil]
+    # @!attribute [r] bucket_id
+    #   @return [Integer, nil]
+    attr_reader :type, :variation_id, :bucket_id
+
+    # @param type [ActionType]
+    # @param variation_id [Integer, nil]
+    # @param bucket_id [Integer, nil]
+    def initialize(type:, variation_id: nil, bucket_id: nil)
+      @type = type
+      @variation_id = variation_id
+      @bucket_id = bucket_id
+    end
+  end
+
+  class ActionType
+    # @!attribute [r] name
+    #   @return [String]
+    attr_reader :name
+
+    # @param name [String]
+    def initialize(name)
+      @name = name
+    end
+
+    def to_s
+      name
+    end
+
+    VARIATION = new('VARIATION')
+    BUCKET = new('BUCKET')
+
+    @types = {
+      'VARIATION' => VARIATION,
+      'BUCKET' => BUCKET
+    }.freeze
+
+    # @param name [String]
+    # @return [ActionType, nil]
+    def self.from_or_nil(name)
+      @types[name.upcase]
+    end
+
+    # @return [Array<ActionType>]
+    def self.values
+      @types.values
+    end
+  end
+end

data/lib/hackle/internal/model/bucket.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Hackle
+
+  class Bucket
+
+    # @!attribute [r] id
+    #   @return [Integer]
+    # @!attribute [r] seed
+    #   @return [Integer]
+    # @!attribute [r] slot_size
+    #   @return [Integer]
+    # @!attribute [r] slots
+    #   @return [Array<Slot>]
+    attr_accessor :id, :seed, :slot_size, :slots
+
+    # @param id [Integer]
+    # @param seed [Integer]
+    # @param slot_size [Integer]
+    # @param slots [Array<Slot>]
+    def initialize(id:, seed:, slot_size:, slots:)
+      @id = id
+      @seed = seed
+      @slot_size = slot_size
+      @slots = slots
+    end
+
+    # @param slot_number [Integer]
+    # @return [Slot, nil]
+    def get_slot_or_nil(slot_number)
+      slots.each do |slot|
+        return slot if slot.contains?(slot_number)
+      end
+      nil
+    end
+  end
+
+  class Slot
+    # @!attribute [r] variation_id
+    #   @return [Integer]
+    attr_reader :variation_id
+
+    # @param start_inclusive [Integer]
+    # @param end_exclusive [Integer]
+    # @param variation_id [Integer]
+    def initialize(start_inclusive:, end_exclusive:, variation_id:)
+      @start_inclusive = start_inclusive
+      @end_exclusive = end_exclusive
+      @variation_id = variation_id
+    end
+
+    # @param slot_number [Integer]
+    # @return [boolean]
+    def contains?(slot_number)
+      @start_inclusive <= slot_number && slot_number < @end_exclusive
+    end
+  end
+end