bento-sdk 0.5.0

data/lib/bento/sdk/client.rb

@@ -0,0 +1,123 @@
+require "time"
+
+require "bento/sdk/defaults"
+require "bento/sdk/logging"
+require "bento/sdk/utils"
+require "bento/sdk/worker"
+
+module Bento
+  class Analytics
+    class Client
+      include Bento::Analytics::Utils
+      include Bento::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]
+
+        logger.debug("🍱Tracked events will be sent to: #{@write_key}")
+
+        @max_queue_size = opts[:max_queue_size] || Defaults::Queue::MAX_SIZE
+        @worker_mutex = Mutex.new
+        @worker = Bento::Analytics::Worker.new(@queue, @write_key, opts)
+        @worker_thread = nil
+
+        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
+      #
+      # @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
+        track_but_parsed = FieldParser.parse_for_track(attrs, @write_key)
+        enqueue(track_but_parsed)
+      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)
+        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 {
+            @worker.run
+          }
+        end
+      end
+
+      def worker_running?
+        @worker_thread && @worker_thread.alive?
+      end
+    end
+  end
+end

data/lib/bento/sdk/configuration.rb

@@ -0,0 +1,85 @@
+module Bento
+  class Configuration
+    DEFAULT_CONFIGURATION = {
+      site_uuid: nil,
+      publishable_key: nil,
+      secret_key: nil,
+      dev_mode: false,
+      sync_strategy: nil,
+      sync_strategy_options: {},
+      log_level: :warn,
+    }.freeze
+
+    def initialize(config_from_initialize = {})
+      @config = default_config
+        .merge(config_from_initialize)
+        .merge(config_from_environment)
+    end
+
+    def self.inherit(parent, config_from_arguments)
+      config = allocate
+      config.instance_variable_set(:@parent, parent)
+      config.instance_variable_set(:@config, config_from_arguments.to_hash)
+      config
+    end
+
+    def merge(other_config)
+      self.class.inherit(self, other_config)
+    end
+
+    def to_hash
+      config
+    end
+
+    def to_h
+      parent ? parent.to_h.merge(config) : to_hash
+    end
+
+    def ==(other)
+      config == other.config && parent == other.parent
+    end
+
+  protected
+
+    attr_reader :config, :parent
+
+    def default_config
+      DEFAULT_CONFIGURATION
+    end
+
+    def config_from_environment
+      default_config.keys.each_with_object({}) do |key, config|
+        value = ENV.fetch("BENTO_#{key.to_s.upcase}", nil)
+        config[key] = value if value
+      end
+    end
+
+    def key?(key)
+      config.key?(key) || parent&.key?(key)
+    end
+
+    def [](key)
+      config.key?(key) ? config[key] : parent && parent[key]
+    end
+
+    def []=(key, value)
+      config[key] = value
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      name = name.to_s.sub(/=$/, '')
+      key?(name.to_sym) || super
+    end
+
+    def method_missing(name, *args, &block)
+      if respond_to_missing?(name)
+        name = name.to_s
+        method = name =~ /=$/ ? :[]= : :[]
+        name = name.sub(/=$/, '').to_sym
+        send(method, name, *args, &block)
+      else
+        super
+      end
+    end
+  end
+end

data/lib/bento/sdk/defaults.rb

@@ -0,0 +1,37 @@
+module Bento
+  class Analytics
+    module Defaults
+      module Request
+        HOST = "app.bentonow.com"
+        PORT = 443
+        PATH = "/tracking/events/"
+        SSL = true
+
+        HEADERS = {"Accept" => "application/json",
+                   "Content-Type" => "application/json",
+                   "User-Agent" => "bento-ruby",}
+        RETRIES = 15
+      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/bento/sdk/field_parser.rb

@@ -0,0 +1,104 @@
+require 'digest'
+
+module Bento
+  class Analytics
+    class FieldParser
+      class << self
+        include Bento::Analytics::Utils
+
+        def parse_for_track(fields, write_key)
+          common = parse_common_fields(fields)
+
+          event = fields[:event]
+
+          custom_fields = fields[:custom_fields] || {}
+          details = fields[:details] || {}
+          identity = fields[:identity] || {}
+          visitor_uuid = fields[:visitor_uuid] || Digest::SHA2.hexdigest("api" + identity.to_s + write_key)
+          page = fields[:page] || {}
+
+          check_presence!(event, "event")
+          check_is_hash!(details, "details")
+          check_is_hash!(page, "page")
+          check_is_hash!(identity, "identity")
+          check_is_hash!(custom_fields, "custom_fields")
+
+          isoify_dates! details
+
+          final_event = {
+            id: SecureRandom.hex(10),
+            site: write_key,
+            identity: identity,
+            visit: Digest::SHA2.hexdigest(Time.now.strftime("%B %e, %Y") + identity.to_s + write_key),
+            visitor: visitor_uuid,
+            type: event.to_s,
+            date: Time.now,
+            browser: {
+              "user_agent" => "Bento/API (Rails)",
+            },
+            page: page,
+            details: details,
+            fields: custom_fields,
+          }
+
+          common = common.merge(final_event)
+          common
+        end
+
+        private
+
+        def parse_common_fields(fields)
+          timestamp = fields[:date] || Time.new
+          message_id = fields[:message_id].to_s if fields[:message_id]
+          page = fields[:page] || {}
+          context = {}
+
+          check_user_id! fields
+
+          check_timestamp! timestamp
+
+          add_context! context
+
+          parsed = {
+            page: page,
+            date: datetime_in_iso8601(timestamp),
+            identity: {email: nil},
+          }
+
+          parsed[:identity][:email] = fields[:identity][:email] if fields[:identity]
+          parsed[:visitor_uuid] = fields[:visitor_uuid] if fields[:visitor_uuid]
+
+          parsed
+        end
+
+        def check_user_id!(fields)
+          unless fields[:identity] || fields[:visitor_uuid]
+            raise ArgumentError, "Must supply either visitor_uuid or identity"
+          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: "bento-ruby"}
+        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

data/lib/bento/sdk/logging.rb

@@ -0,0 +1,60 @@
+require "logger"
+
+module Bento
+  class Analytics
+    # Wraps an existing logger and adds a prefix to all messages
+    class PrefixedLogger
+      def initialize(logger, prefix)
+        @logger = logger
+        @prefix = prefix
+      end
+
+      def debug(msg)
+        @logger.debug("#{@prefix} #{msg}")
+      end
+
+      def info(msg)
+        @logger.info("#{@prefix} #{msg}")
+      end
+
+      def warn(msg)
+        @logger.warn("#{@prefix} #{msg}")
+      end
+
+      def error(msg)
+        @logger.error("#{@prefix} #{msg}")
+      end
+    end
+
+    module Logging
+      class << self
+        def logger
+          return @logger if @logger
+
+          base_logger = if defined?(Rails)
+            Rails.logger
+          else
+            logger = Logger.new STDOUT
+            logger.progname = "Bento::Analytics"
+            logger
+          end
+          @logger = PrefixedLogger.new(base_logger, "[bento-sdk]")
+        end
+
+        attr_writer :logger
+      end
+
+      def self.included(base)
+        class << base
+          def logger
+            Logging.logger
+          end
+        end
+      end
+
+      def logger
+        Logging.logger
+      end
+    end
+  end
+end

data/lib/bento/sdk/message_batch.rb

@@ -0,0 +1,72 @@
+require "forwardable"
+require "bento/sdk/logging"
+
+module Bento
+  class Analytics
+    # A batch of `Message`s to be sent to the API
+    class MessageBatch
+      class JSONGenerationError < StandardError; end
+
+      extend Forwardable
+      include Bento::Analytics::Logging
+      include Bento::Analytics::Defaults::MessageBatch
+
+      def initialize(max_message_count)
+        @messages = []
+        @max_message_count = max_message_count
+        @json_size = 0
+      end
+
+      def <<(message)
+        begin
+          message_json = message.to_json
+        rescue => e
+          raise JSONGenerationError, "Serialization error: #{e}"
+        end
+
+        message_json_size = message_json.bytesize
+        if message_too_big?(message_json_size)
+          logger.error("a message exceeded the maximum allowed size")
+        else
+          @messages << message
+          @json_size += message_json_size + 1 # One byte for the comma
+        end
+      end
+
+      def full?
+        item_count_exhausted? || size_exhausted?
+      end
+
+      def clear
+        @messages.clear
+        @json_size = 0
+      end
+
+      def_delegators :@messages, :to_json
+      def_delegators :@messages, :empty?
+      def_delegators :@messages, :length
+
+      private
+
+      def item_count_exhausted?
+        @messages.length >= @max_message_count
+      end
+
+      def message_too_big?(message_json_size)
+        message_json_size > Bento::Analytics::Defaults::Message::MAX_BYTES
+      end
+
+      # We consider the max size here as just enough to leave room for one more
+      # message of the largest size possible. This is a shortcut that allows us
+      # to use a native Ruby `Queue` that doesn't allow peeking. The tradeoff
+      # here is that we might fit in less messages than possible into a batch.
+      #
+      # The alternative is to use our own `Queue` implementation that allows
+      # peeking, and to consider the next message size when calculating whether
+      # the message can be accomodated in this batch.
+      def size_exhausted?
+        @json_size >= (MAX_BYTES - Bento::Analytics::Defaults::Message::MAX_BYTES)
+      end
+    end
+  end
+end

data/lib/bento/sdk/response.rb

@@ -0,0 +1,15 @@
+module Bento
+  class Analytics
+    class Response
+      attr_reader :status, :error
+
+      # public: Simple class to wrap responses from the API
+      #
+      #
+      def initialize(status = 200, error = nil)
+        @status = status
+        @error = error
+      end
+    end
+  end
+end

data/lib/bento/sdk/transport.rb

@@ -0,0 +1,144 @@
+require "bento/sdk/defaults"
+require "bento/sdk/utils"
+require "bento/sdk/response"
+require "bento/sdk/logging"
+require "bento/sdk/backoff_policy"
+require "net/http"
+require "net/https"
+require "json"
+
+module Bento
+  class Analytics
+    class Transport
+      include Bento::Analytics::Defaults::Request
+      include Bento::Analytics::Utils
+      include Bento::Analytics::Logging
+
+      def initialize(options = {})
+        options[:host] ||= HOST
+        options[:port] ||= PORT
+        options[:ssl] ||= SSL
+        @headers = options[:headers] || HEADERS
+        @path = options[:path] || PATH
+        @retries = options[:retries] || RETRIES
+        @backoff_policy =
+          options[:backoff_policy] || Bento::Analytics::BackoffPolicy.new
+
+        http = Net::HTTP.new(options[:host], options[:port])
+        http.use_ssl = options[:ssl]
+        http.read_timeout = 8
+        http.open_timeout = 4
+
+        @http = http
+      end
+
+      # Sends a batch of messages to the API
+      #
+      # @return [Response] API response
+      def send(write_key, batch)
+        logger.debug("Sending request for #{batch.length} items")
+        last_response, exception = retry_with_backoff(@retries) {
+          status_code, body = send_request(write_key, batch)
+
+          error = ""
+
+          should_retry = should_retry_request?(status_code, body)
+          logger.debug("🍱Response status code: #{status_code}")
+          logger.debug("🍱Response error (if any): #{error}") if error
+
+          [Bento::Analytics::Response.new(status_code, error), should_retry]
+        }
+
+        if exception
+          logger.error(exception.message)
+          exception.backtrace.each { |line| logger.error(line) }
+          Bento::Analytics::Response.new(-1, exception.to_s)
+        else
+          last_response
+        end
+      end
+
+      # Closes a persistent connection if it exists
+      def shutdown
+        @http.finish if @http.started?
+      end
+
+      private
+
+      def should_retry_request?(status_code, body)
+        if status_code >= 500
+          true # Server error
+        elsif status_code == 429
+          true # Rate limited
+        elsif status_code >= 400
+          logger.error(body)
+          false # Client error. Do not retry, but log
+        else
+          false
+        end
+      end
+
+      # Takes a block that returns [result, should_retry].
+      #
+      # Retries upto `retries_remaining` times, if `should_retry` is false or
+      # an exception is raised. `@backoff_policy` is used to determine the
+      # duration to sleep between attempts
+      #
+      # Returns [last_result, raised_exception]
+      def retry_with_backoff(retries_remaining, &block)
+        result, caught_exception = nil
+        should_retry = false
+
+        begin
+          result, should_retry = yield
+          return [result, nil] unless should_retry
+        rescue => e
+          should_retry = true
+          caught_exception = e
+        end
+
+        if should_retry && (retries_remaining > 1)
+          logger.debug("Retrying request, #{retries_remaining} retries left")
+          sleep(@backoff_policy.next_interval.to_f / 500)
+          retry_with_backoff(retries_remaining - 1, &block)
+        else
+          [result, caught_exception]
+        end
+      end
+
+      # Sends a request for the batch, returns [status_code, body]
+      def send_request(write_key, batch)
+        batch_to_json = JSON.parse(batch.to_json)
+        batch_to_hash = Hash[batch_to_json.each_with_index.map { |value, index| [index, value] }]
+
+        payload = JSON.generate("events" => batch_to_hash)
+        payload = JSON.parse(payload).to_json
+
+        request = Net::HTTP::Post.new(@path, @headers)
+
+        request.content_type = "application/json"
+        request["Accept"] = "application/json"
+        request.basic_auth(write_key, nil)
+
+        if self.class.stub
+          logger.debug "stubbed request to #{@path}: " \
+            "write key = #{write_key}, batch = #{JSON.generate(batch)}"
+
+          [200, "{}"]
+        else
+          @http.start unless @http.started? # Maintain a persistent connection
+          response = @http.request(request, payload)
+          [response.code.to_i, response.body]
+        end
+      end
+
+      class << self
+        attr_writer :stub
+
+        def stub
+          @stub || ENV["STUB"]
+        end
+      end
+    end
+  end
+end