clearbit 0.2.7 → 0.3.3

data/lib/clearbit/analytics/backoff_policy.rb

@@ -0,0 +1,49 @@
+require 'clearbit/analytics/defaults'
+
+module Clearbit
+  class Analytics
+    class BackoffPolicy
+      include Clearbit::Analytics::Defaults::BackoffPolicy
+
+      # @param [Hash] opts
+      # @option opts [Numeric] :min_timeout_ms The minimum backoff timeout
+      # @option opts [Numeric] :max_timeout_ms The maximum backoff timeout
+      # @option opts [Numeric] :multiplier The value to multiply the current
+      #   interval with for each retry attempt
+      # @option opts [Numeric] :randomization_factor The randomization factor
+      #   to use to create a range around the retry interval
+      def initialize(opts = {})
+        @min_timeout_ms = opts[:min_timeout_ms] || MIN_TIMEOUT_MS
+        @max_timeout_ms = opts[:max_timeout_ms] || MAX_TIMEOUT_MS
+        @multiplier = opts[:multiplier] || MULTIPLIER
+        @randomization_factor = opts[:randomization_factor] || RANDOMIZATION_FACTOR
+
+        @attempts = 0
+      end
+
+      # @return [Numeric] the next backoff interval, in milliseconds.
+      def next_interval
+        interval = @min_timeout_ms * (@multiplier**@attempts)
+        interval = add_jitter(interval, @randomization_factor)
+
+        @attempts += 1
+
+        [interval, @max_timeout_ms].min
+      end
+
+      private
+
+      def add_jitter(base, randomization_factor)
+        random_number = rand
+        max_deviation = base * randomization_factor
+        deviation = random_number * max_deviation
+
+        if random_number < 0.5
+          base - deviation
+        else
+          base + deviation
+        end
+      end
+    end
+  end
+end

data/lib/clearbit/analytics/client.rb

@@ -0,0 +1,189 @@
+require 'thread'
+require 'time'
+
+require 'clearbit/analytics/defaults'
+require 'clearbit/analytics/logging'
+require 'clearbit/analytics/utils'
+require 'clearbit/analytics/worker'
+
+module Clearbit
+  class Analytics
+    class Client
+      include Clearbit::Analytics::Utils
+      include Clearbit::Analytics::Logging
+
+      # @param [Hash] opts
+      # @option opts [String] :write_key Your project's write_key
+      # @option opts [FixNum] :max_queue_size Maximum number of calls to be
+      #   remain queued.
+      # @option opts [Proc] :on_error Handles error calls from the API.
+      def initialize(opts = {})
+        symbolize_keys!(opts)
+
+        @queue = Queue.new
+        @write_key = opts[:write_key]
+        @max_queue_size = opts[:max_queue_size] || Defaults::Queue::MAX_SIZE
+        @worker_mutex = Mutex.new
+        @worker = Worker.new(@queue, @write_key, opts)
+
+        check_write_key!
+
+        at_exit { @worker_thread && @worker_thread[:should_exit] = true }
+      end
+
+      # Synchronously waits until the worker has flushed the queue.
+      #
+      # Use only for scripts which are not long-running, and will specifically
+      # exit
+      def flush
+        while !@queue.empty? || @worker.is_requesting?
+          ensure_worker_running
+          sleep(0.1)
+        end
+      end
+
+      # @!macro common_attrs
+      #   @option attrs [String] :anonymous_id ID for a user when you don't know
+      #     who they are yet. (optional but you must provide either an
+      #     `anonymous_id` or `user_id`)
+      #   @option attrs [Hash] :context ({})
+      #   @option attrs [Hash] :integrations What integrations this event
+      #     goes to (optional)
+      #   @option attrs [String] :message_id ID that uniquely
+      #     identifies a message across the API. (optional)
+      #   @option attrs [Time] :timestamp When the event occurred (optional)
+      #   @option attrs [String] :user_id The ID for this user in your database
+      #     (optional but you must provide either an `anonymous_id` or `user_id`)
+      #   @option attrs [Hash] :options Options such as user traits (optional)
+
+      # Tracks an event
+      #
+      # @see https://segment.com/docs/sources/server/ruby/#track
+      #
+      # @param [Hash] attrs
+      #
+      # @option attrs [String] :event Event name
+      # @option attrs [Hash] :properties Event properties (optional)
+      # @macro common_attrs
+      def track(attrs)
+        symbolize_keys! attrs
+        enqueue(FieldParser.parse_for_track(attrs))
+      end
+
+      # Identifies a user
+      #
+      # @see https://segment.com/docs/sources/server/ruby/#identify
+      #
+      # @param [Hash] attrs
+      #
+      # @option attrs [Hash] :traits User traits (optional)
+      # @macro common_attrs
+      def identify(attrs)
+        symbolize_keys! attrs
+        enqueue(FieldParser.parse_for_identify(attrs))
+      end
+
+      # Aliases a user from one id to another
+      #
+      # @see https://segment.com/docs/sources/server/ruby/#alias
+      #
+      # @param [Hash] attrs
+      #
+      # @option attrs [String] :previous_id The ID to alias from
+      # @macro common_attrs
+      def alias(attrs)
+        symbolize_keys! attrs
+        enqueue(FieldParser.parse_for_alias(attrs))
+      end
+
+      # Associates a user identity with a group.
+      #
+      # @see https://segment.com/docs/sources/server/ruby/#group
+      #
+      # @param [Hash] attrs
+      #
+      # @option attrs [String] :group_id The ID of the group
+      # @option attrs [Hash] :traits User traits (optional)
+      # @macro common_attrs
+      def group(attrs)
+        symbolize_keys! attrs
+        enqueue(FieldParser.parse_for_group(attrs))
+      end
+
+      # Records a page view
+      #
+      # @see https://segment.com/docs/sources/server/ruby/#page
+      #
+      # @param [Hash] attrs
+      #
+      # @option attrs [String] :name Name of the page
+      # @option attrs [Hash] :properties Page properties (optional)
+      # @macro common_attrs
+      def page(attrs)
+        symbolize_keys! attrs
+        enqueue(FieldParser.parse_for_page(attrs))
+      end
+
+      # Records a screen view (for a mobile app)
+      #
+      # @param [Hash] attrs
+      #
+      # @option attrs [String] :name Name of the screen
+      # @option attrs [Hash] :properties Screen properties (optional)
+      # @option attrs [String] :category The screen category (optional)
+      # @macro common_attrs
+      def screen(attrs)
+        symbolize_keys! attrs
+        enqueue(FieldParser.parse_for_screen(attrs))
+      end
+
+      # @return [Fixnum] number of messages in the queue
+      def queued_messages
+        @queue.length
+      end
+
+      private
+
+      # private: Enqueues the action.
+      #
+      # returns Boolean of whether the item was added to the queue.
+      def enqueue(action)
+        # add our request id for tracing purposes
+        action[:messageId] ||= uid
+
+        if @queue.length < @max_queue_size
+          @queue << action
+          ensure_worker_running
+
+          true
+        else
+          logger.warn(
+            'Queue is full, dropping events. The :max_queue_size ' \
+            'configuration parameter can be increased to prevent this from ' \
+            'happening.'
+          )
+          false
+        end
+      end
+
+      # private: Checks that the write_key is properly initialized
+      def check_write_key!
+        raise ArgumentError, 'Write key must be initialized' if @write_key.nil?
+      end
+
+      def ensure_worker_running
+        return if worker_running?
+        @worker_mutex.synchronize do
+          return if worker_running?
+          @worker_thread = Thread.new do
+            @worker.run
+          end
+        end
+      end
+
+      def worker_running?
+        @worker_thread && @worker_thread.alive?
+      end
+    end
+  end
+end

data/lib/clearbit/analytics/defaults.rb

@@ -0,0 +1,36 @@
+module Clearbit
+  class Analytics
+    module Defaults
+      module Request
+        HOST = 'x.clearbit.com'
+        PORT = 443
+        PATH = '/v1/import'
+        SSL = true
+        HEADERS = { 'Accept' => 'application/json',
+                    'Content-Type' => 'application/json',
+                    'User-Agent' => "clearbit-ruby/#{Clearbit::VERSION}" }
+        RETRIES = 10
+      end
+
+      module Queue
+        MAX_SIZE = 10000
+      end
+
+      module Message
+        MAX_BYTES = 32768 # 32Kb
+      end
+
+      module MessageBatch
+        MAX_BYTES = 512_000 # 500Kb
+        MAX_SIZE = 100
+      end
+
+      module BackoffPolicy
+        MIN_TIMEOUT_MS = 100
+        MAX_TIMEOUT_MS = 10000
+        MULTIPLIER = 1.5
+        RANDOMIZATION_FACTOR = 0.5
+      end
+    end
+  end
+end

data/lib/clearbit/analytics/field_parser.rb

@@ -0,0 +1,192 @@
+module Clearbit
+  class Analytics
+    # Handles parsing fields according to the Segment Spec
+    #
+    # @see https://segment.com/docs/spec/
+    class FieldParser
+      class << self
+        include Clearbit::Analytics::Utils
+
+        # In addition to the common fields, track accepts:
+        #
+        # - "event"
+        # - "properties"
+        def parse_for_track(fields)
+          common = parse_common_fields(fields)
+
+          event = fields[:event]
+          properties = fields[:properties] || {}
+
+          check_presence!(event, 'event')
+          check_is_hash!(properties, 'properties')
+
+          isoify_dates! properties
+
+          common.merge({
+            :type => 'track',
+            :event => event.to_s,
+            :properties => properties
+          })
+        end
+
+        # In addition to the common fields, identify accepts:
+        #
+        # - "traits"
+        def parse_for_identify(fields)
+          common = parse_common_fields(fields)
+
+          traits = fields[:traits] || {}
+          check_is_hash!(traits, 'traits')
+          isoify_dates! traits
+
+          common.merge({
+            :type => 'identify',
+            :traits => traits
+          })
+        end
+
+        # In addition to the common fields, alias accepts:
+        #
+        # - "previous_id"
+        def parse_for_alias(fields)
+          common = parse_common_fields(fields)
+
+          previous_id = fields[:previous_id]
+          check_presence!(previous_id, 'previous_id')
+
+          common.merge({
+            :type => 'alias',
+            :previousId => previous_id
+          })
+        end
+
+        # In addition to the common fields, group accepts:
+        #
+        # - "group_id"
+        # - "traits"
+        def parse_for_group(fields)
+          common = parse_common_fields(fields)
+
+          group_id = fields[:group_id]
+          traits = fields[:traits] || {}
+
+          check_presence!(group_id, 'group_id')
+          check_is_hash!(traits, 'traits')
+
+          isoify_dates! traits
+
+          common.merge({
+            :type => 'group',
+            :groupId => group_id,
+            :traits => traits
+          })
+        end
+
+        # In addition to the common fields, page accepts:
+        #
+        # - "name"
+        # - "properties"
+        def parse_for_page(fields)
+          common = parse_common_fields(fields)
+
+          name = fields[:name] || ''
+          properties = fields[:properties] || {}
+
+          check_is_hash!(properties, 'properties')
+
+          isoify_dates! properties
+
+          common.merge({
+            :type => 'page',
+            :name => name.to_s,
+            :properties => properties
+          })
+        end
+
+        # In addition to the common fields, screen accepts:
+        #
+        # - "name"
+        # - "properties"
+        # - "category" (Not in spec, retained for backward compatibility"
+        def parse_for_screen(fields)
+          common = parse_common_fields(fields)
+
+          name = fields[:name]
+          properties = fields[:properties] || {}
+          category = fields[:category]
+
+          check_presence!(name, 'name')
+          check_is_hash!(properties, 'properties')
+
+          isoify_dates! properties
+
+          parsed = common.merge({
+            :type => 'screen',
+            :name => name,
+            :properties => properties
+          })
+
+          parsed[:category] = category if category
+
+          parsed
+        end
+
+        private
+
+        def parse_common_fields(fields)
+          timestamp = fields[:timestamp] || Time.new
+          message_id = fields[:message_id].to_s if fields[:message_id]
+          context = fields[:context] || {}
+
+          check_user_id! fields
+          check_timestamp! timestamp
+
+          add_context! context
+
+          parsed = {
+            :context => context,
+            :messageId => message_id,
+            :timestamp => datetime_in_iso8601(timestamp)
+          }
+
+          parsed[:userId] = fields[:user_id] if fields[:user_id]
+          parsed[:anonymousId] = fields[:anonymous_id] if fields[:anonymous_id]
+          parsed[:integrations] = fields[:integrations] if fields[:integrations]
+
+          # Not in spec, retained for backward compatibility
+          parsed[:options] = fields[:options] if fields[:options]
+
+          parsed
+        end
+
+        def check_user_id!(fields)
+          unless fields[:user_id] || fields[:anonymous_id]
+            raise ArgumentError, 'Must supply either user_id or anonymous_id'
+          end
+        end
+
+        def check_timestamp!(timestamp)
+          raise ArgumentError, 'Timestamp must be a Time' unless timestamp.is_a? Time
+        end
+
+        def add_context!(context)
+          context[:library] = { :name => 'clearbit-ruby', :version => Clearbit::VERSION.to_s }
+        end
+
+        # private: Ensures that a string is non-empty
+        #
+        # obj    - String|Number that must be non-blank
+        # name   - Name of the validated value
+        def check_presence!(obj, name)
+          if obj.nil? || (obj.is_a?(String) && obj.empty?)
+            raise ArgumentError, "#{name} must be given"
+          end
+        end
+
+        def check_is_hash!(obj, name)
+          raise ArgumentError, "#{name} must be a Hash" unless obj.is_a? Hash
+        end
+      end
+    end
+  end
+end