greenfinch-ruby 0.1.0

data/demo/faraday_consumer.rb

@@ -0,0 +1,40 @@
+require 'greenfinch-ruby'
+require 'faraday'
+
+# The Mixpanel library's default consumer will use the standard
+# Net::HTTP library to communicate with servers, but you can extend
+# your consumers to use other libraries. This example sends data using
+# the Faraday library (so you'll need that library available to run it)
+
+class FaradayConsumer < Mixpanel::Consumer
+  def request(endpoint, form_data)
+    conn = ::Faraday.new(endpoint)
+    response = conn.post(nil, form_data)
+    [response.status, response.body]
+  end
+end
+
+if __FILE__ == $0
+  # Replace this with the token from your project settings
+  DEMO_TOKEN = '072f77c15bd04a5d0044d3d76ced7fea'
+  faraday_consumer = FaradayConsumer.new
+
+  faraday_tracker = Mixpanel::Tracker.new(DEMO_TOKEN) do |type, message|
+    faraday_consumer.send!(type, message)
+  end
+  faraday_tracker.track('ID', 'Event tracked through Faraday')
+
+  # It's also easy to delegate from a BufferedConsumer to your custom
+  # consumer.
+
+  buffered_faraday_consumer = Mixpanel::BufferedConsumer.new do |type, message|
+    faraday_consumer.send!(type, message)
+  end
+
+  buffered_faraday_tracker = Mixpanel::Tracker.new(DEMO_TOKEN) do |type, message|
+    buffered_faraday_consumer.send!(type, message)
+  end
+
+  buffered_faraday_tracker.track('ID', 'Event tracked (buffered) through faraday')
+  buffered_faraday_consumer.flush
+end

data/demo/out_of_process_consumer.rb

@@ -0,0 +1,71 @@
+require 'greenfinch-ruby'
+require 'thread'
+require 'json'
+require 'securerandom'
+
+# As your application scales, it's likely you'll want to
+# to detect events in one place and send them somewhere
+# else. For example, you might write the events to a queue
+# to be consumed by another process.
+#
+# This demo shows how you might do things, using
+# the block constructor in Mixpanel to enqueue events,
+# and a MixpanelBufferedConsumer to send them to
+# Mixpanel
+
+# Mixpanel uses the Net::HTTP library, which by default
+# will not verify remote SSL certificates. In your app,
+# you'll need to call Mixpanel.config_http with the path
+# to your Certificate authority resources, or the library
+# won't verify the remote certificate identity.
+Mixpanel.config_http do |http|
+  http.ca_path = '/etc/ssl/certs'
+  http.ca_file = "/etc/ssl/certs/ca-certificates.crt"
+  http.use_ssl = true
+  http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+end
+
+class OutOfProcessExample
+  class << self
+    def run(token, distinct_id)
+      open('|-', 'w+') do |subprocess|
+        if subprocess
+          # This is the tracking process. Once we configure
+          # The tracker to write to our subprocess, we can quickly
+          # call #track without delaying our other work.
+          mixpanel_tracker = Mixpanel::Tracker.new(token) do |*message|
+            subprocess.write(message.to_json + "\n")
+          end
+
+          100.times do |i|
+            event = 'Tick'
+            mixpanel_tracker.track(distinct_id, event, {'Tick Number' => i})
+            puts "tick #{i}"
+          end
+
+        else
+          # This is the consumer process. In your applications, code
+          # like this may end up in queue consumers or in a separate
+          # thread.
+          mixpanel_consumer = Mixpanel::BufferedConsumer.new
+          begin
+            $stdin.each_line do |line|
+              message = JSON.load(line)
+              type, content = message
+              mixpanel_consumer.send!(type, content)
+            end
+          ensure
+            mixpanel_consumer.flush
+          end
+        end
+      end
+    end # run
+  end
+end
+
+if __FILE__ == $0
+  # Replace this with the token from your project settings
+  DEMO_TOKEN = '072f77c15bd04a5d0044d3d76ced7fea'
+  run_id = SecureRandom.base64
+  OutOfProcessExample.run(DEMO_TOKEN, run_id)
+end

data/demo/simple_messages.rb

@@ -0,0 +1,9 @@
+$LOAD_PATH << "/Users/terry/Documents/Github/greenfinch-ruby/lib"
+require 'greenfinch-ruby'
+
+if __FILE__ == $0
+  # Replace this with the token from your project settings
+  DEMO_TOKEN = 'eyJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1OTE2NzIwMzksImV4cCI6MzY4NTI3MDAwMDAwMCwic2VydmljZV9uYW1lIjoiZmx5Y2F0Y2hlciJ9.lY6RVf1rsaYkuLCLfCs4cKFRNTvcbmZcR2IXEYZkdzw'
+  tracker = Greenfinch::Tracker.new(DEMO_TOKEN, 'flycatcher', true)
+  tracker.track('ID', 'Script run')
+end

data/greenfinch-ruby.gemspec

@@ -0,0 +1,21 @@
+require File.join(File.dirname(__FILE__), 'lib/greenfinch-ruby/version.rb')
+
+spec = Gem::Specification.new do |spec|
+  spec.name = 'greenfinch-ruby'
+  spec.version = Greenfinch::VERSION
+  spec.files = Dir.glob(`git ls-files`.split("\n"))
+  spec.require_paths = ['lib']
+  spec.summary = 'Official Greenfinch tracking library for ruby'
+  spec.description = 'The official Greenfinch tracking library for ruby'
+  spec.authors = [ 'KoreaCreditData' ]
+  spec.email = 'terry@kcd.co.kr'
+  spec.homepage = 'https://github.com/koreacreditdata/greenfinch-ruby'
+  spec.license = 'Apache-2.0'
+
+  spec.required_ruby_version = '>= 2.0.0'
+
+  spec.add_development_dependency 'activesupport', '~> 4.0'
+  spec.add_development_dependency 'rake', '~> 0'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'webmock', '~> 1.18'
+end

data/lib/greenfinch-ruby.rb

@@ -0,0 +1,3 @@
+require 'greenfinch-ruby/consumer.rb'
+require 'greenfinch-ruby/tracker.rb'
+require 'greenfinch-ruby/version.rb'

data/lib/greenfinch-ruby/consumer.rb

@@ -0,0 +1,271 @@
+require 'base64'
+require 'json'
+require 'net/https'
+
+module Greenfinch
+  @@init_http = nil
+
+  # This method exists for backwards compatibility. The preferred
+  # way to customize or configure the HTTP library of a consumer
+  # is to override Consumer#request.
+  #
+  # Ruby's default SSL does not verify the server certificate.
+  # To verify a certificate, or install a proxy, pass a block
+  # to Greenfinch.config_http that configures the Net::HTTP object.
+  # For example, if running in Ubuntu Linux, you can run
+  #
+  #    Greenfinch.config_http do |http|
+  #        http.ca_path = '/etc/ssl/certs'
+  #        http.ca_file = '/etc/ssl/certs/ca-certificates.crt'
+  #        http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+  #    end
+  #
+  # \Greenfinch Consumer and BufferedConsumer will call your block
+  # to configure their connections
+  def self.config_http(&block)
+    @@init_http = block
+  end
+
+  # A Consumer receives messages from a Greenfinch::Tracker, and
+  # sends them elsewhere- probably to Greenfinch's analytics services,
+  # but can also enqueue them for later processing, log them to a
+  # file, or do whatever else you might find useful.
+  #
+  # You can provide your own consumer to your Greenfinch::Trackers,
+  # either by passing in an argument with a #send! method when you construct
+  # the tracker, or just passing a block to Greenfinch::Tracker.new
+  #
+  #    tracker = Greenfinch::Tracker.new(YOUR_GREENFINCH_TOKEN) do |type, message|
+  #        # type will be one of :event, :profile_update or :import
+  #        @kestrel.set(ANALYTICS_QUEUE, [type, message].to_json)
+  #    end
+  #
+  # You can also instantiate the library consumers yourself, and use
+  # them wherever you would like. For example, the working that
+  # consumes the above queue might work like this:
+  #
+  #     greenfinch = Greenfinch::Consumer
+  #     while true
+  #         message_json = @kestrel.get(ANALYTICS_QUEUE)
+  #         greenfinch.send!(*JSON.load(message_json))
+  #     end
+  #
+  # Greenfinch::Consumer is the default consumer. It sends each message,
+  # as the message is recieved, directly to Greenfinch.
+  class Consumer
+
+    # Create a Greenfinch::Consumer. If you provide endpoint arguments,
+    # they will be used instead of the default Greenfinch endpoints.
+    # This can be useful for proxying, debugging, or if you prefer
+    # not to use SSL for your events.
+    def initialize(events_endpoint=nil,
+                   update_endpoint=nil,
+                   groups_endpoint=nil,
+                   import_endpoint=nil)
+
+      @events_endpoint = events_endpoint || 'https://event.kcd.partners/api/publish'
+      @update_endpoint = update_endpoint || 'https://api.greenfinch.com/engage'
+      @groups_endpoint = groups_endpoint || 'https://api.greenfinch.com/groups'
+      @import_endpoint = import_endpoint || 'https://api.greenfinch.com/import'
+    end
+
+    # Send the given string message to Greenfinch. Type should be
+    # one of :event, :profile_update or :import, which will determine the endpoint.
+    #
+    # Greenfinch::Consumer#send! sends messages to Greenfinch immediately on
+    # each call. To reduce the overall bandwidth you use when communicating
+    # with Greenfinch, you can also use Greenfinch::BufferedConsumer
+    def send!(type, message)
+      type = type.to_sym
+      endpoint = {
+        :event => @events_endpoint,
+        :profile_update => @update_endpoint,
+        :group_update => @groups_endpoint,
+        :import => @import_endpoint,
+      }[type]
+
+      decoded_message = JSON.load(message)
+      jwt_token = decoded_message["jwt_token"]
+      service_name = decoded_message["service_name"]
+      debug = decoded_message["debug"]
+      api_key = decoded_message["api_key"]
+
+      if debug == true
+        endpoint = "https://event-staging.kcd.partners/api/publish/#{service_name}"
+      else
+        endpoint = "#{endpoint}/#{service_name}"
+      end
+
+      data = decoded_message["data"]
+
+      form_data = { "data" => data, "verbose" => 1 }
+      form_data.merge!("api_key" => api_key) if api_key
+
+      begin
+        response_code, response_body = request(endpoint, form_data, jwt_token)
+      rescue => e
+        raise ConnectionError.new("Could not connect to Greenfinch, with error \"#{e.message}\".")
+      end
+
+      result = {}
+      if response_code.to_i == 200
+        begin
+          result = JSON.parse(response_body.to_s)
+        rescue JSON::JSONError
+          raise ServerError.new("Could not interpret Greenfinch server response: '#{response_body}'")
+        end
+      end
+
+      if result['status'] != 1
+        raise ServerError.new("Could not write to Greenfinch, server responded with #{response_code} returning: '#{response_body}'")
+      end
+    end
+
+    # This method was deprecated in release 2.0.0, please use send! instead
+    def send(type, message)
+        warn '[DEPRECATION] send has been deprecated as of release 2.0.0, please use send! instead'
+        send!(type, message)
+    end
+
+    # Request takes an endpoint HTTP or HTTPS url, and a Hash of data
+    # to post to that url. It should return a pair of
+    #
+    # [response code, response body]
+    #
+    # as the result of the response. Response code should be nil if
+    # the request never receives a response for some reason.
+    def request(endpoint, form_data, jwt_token=nil)
+      uri = URI(endpoint)
+
+      headers = {
+        "jwt" => jwt_token,
+        "content-type" => "application/json",
+        "label" => "ruby"
+      }
+
+      client = Net::HTTP.new(uri.host, uri.port)
+      client.use_ssl = true
+      client.open_timeout = 10
+      client.continue_timeout = 10
+      client.read_timeout = 10
+      client.ssl_timeout = 10
+
+      Greenfinch.with_http(client)
+
+      response = client.request_post uri.request_uri, form_data.to_json, headers
+
+      [response.code, response.body]
+    end
+  end
+
+  # BufferedConsumer buffers messages in memory, and sends messages as
+  # a batch.  This can improve performance, but calls to #send! may
+  # still block if the buffer is full.  If you use this consumer, you
+  # should call #flush when your application exits or the messages
+  # remaining in the buffer will not be sent.
+  #
+  # To use a BufferedConsumer directly with a Greenfinch::Tracker,
+  # instantiate your Tracker like this
+  #
+  #    buffered_consumer = Greenfinch::BufferedConsumer.new
+  #    begin
+  #        buffered_tracker = Greenfinch::Tracker.new(YOUR_GREENFINCH_TOKEN) do |type, message|
+  #            buffered_consumer.send!(type, message)
+  #        end
+  #        # Do some tracking here
+  #        ...
+  #    ensure
+  #        buffered_consumer.flush
+  #    end
+  #
+  class BufferedConsumer
+    MAX_LENGTH = 50
+
+    # Create a Greenfinch::BufferedConsumer. If you provide endpoint arguments,
+    # they will be used instead of the default Greenfinch endpoints.
+    # This can be useful for proxying, debugging, or if you prefer
+    # not to use SSL for your events.
+    #
+    # You can also change the preferred buffer size before the
+    # consumer automatically sends its buffered events. The Greenfinch
+    # endpoints have a limit of 50 events per HTTP request, but
+    # you can lower the limit if your individual events are very large.
+    #
+    # By default, BufferedConsumer will use a standard Greenfinch
+    # consumer to send the events once the buffer is full (or on calls
+    # to #flush), but you can override this behavior by passing a
+    # block to the constructor, in the same way you might pass a block
+    # to the Greenfinch::Tracker constructor. If a block is passed to
+    # the constructor, the *_endpoint constructor arguments are
+    # ignored.
+    def initialize(events_endpoint=nil, update_endpoint=nil, import_endpoint=nil, max_buffer_length=MAX_LENGTH, &block)
+      @max_length = [max_buffer_length, MAX_LENGTH].min
+      @buffers = {
+        :event => [],
+        :profile_update => [],
+      }
+
+      if block
+        @sink = block
+      else
+        consumer = Consumer.new(events_endpoint, update_endpoint, import_endpoint)
+        @sink = consumer.method(:send!)
+      end
+    end
+
+    # Stores a message for Greenfinch in memory. When the buffer
+    # hits a maximum length, the consumer will flush automatically.
+    # Flushes are synchronous when they occur.
+    #
+    # Currently, only :event and :profile_update messages are buffered,
+    # :import messages will be send immediately on call.
+    def send!(type, message)
+      type = type.to_sym
+
+      if @buffers.has_key? type
+        @buffers[type] << message
+        flush_type(type) if @buffers[type].length >= @max_length
+      else
+        @sink.call(type, message)
+      end
+    end
+
+    # This method was deprecated in release 2.0.0, please use send! instead
+    def send(type, message)
+        warn '[DEPRECATION] send has been deprecated as of release 2.0.0, please use send! instead'
+        send!(type, message)
+    end
+
+    # Pushes all remaining messages in the buffer to Greenfinch.
+    # You should call #flush before your application exits or
+    # messages may not be sent.
+    def flush
+      @buffers.keys.each { |k| flush_type(k) }
+    end
+
+    private
+
+    def flush_type(type)
+      sent_messages = 0
+      begin
+        @buffers[type].each_slice(@max_length) do |chunk|
+          data = chunk.map {|message| JSON.load(message)['data'] }
+          @sink.call(type, {'data' => data}.to_json)
+          sent_messages += chunk.length
+        end
+      rescue
+        @buffers[type].slice!(0, sent_messages)
+        raise
+      end
+      @buffers[type] = []
+    end
+  end
+
+  private
+
+  def self.with_http(http)
+    if @@init_http
+      @@init_http.call(http)
+    end
+  end
+end

data/lib/greenfinch-ruby/error.rb

@@ -0,0 +1,46 @@
+module Greenfinch
+
+  # Greenfinch specific errors that are thrown in the gem.
+  # In the default consumer we catch all errors and raise
+  # Greenfinch specific errors that can be handled using a
+  # custom error handler.
+  class GreenfinchError < StandardError
+  end
+  
+  class ConnectionError < GreenfinchError
+  end
+  
+  class ServerError < GreenfinchError
+  end
+
+
+  # The default behavior of the gem is to silence all errors
+  # thrown in the consumer.  If you wish to handle GreenfinchErrors
+  # yourself you can pass an instance of a class that extends
+  # Greenfinch::ErrorHandler to Greenfinch::Tracker on initialize.
+  #
+  #    require 'logger'
+  #
+  #    class MyErrorHandler < Greenfinch::ErrorHandler
+  #
+  #      def initialize
+  #        @logger = Logger.new('mylogfile.log')
+  #        @logger.level = Logger::ERROR
+  #      end
+  #    
+  #      def handle(error)
+  #        logger.error "#{error.inspect}\n Backtrace: #{error.backtrace}"
+  #      end
+  #
+  #    end
+  #
+  #    my_error_handler = MyErrorHandler.new
+  #    tracker = Greenfinch::Tracker.new(YOUR_GREENFINCH_TOKEN, my_error_handler)
+  class ErrorHandler
+
+    # Override #handle to customize error handling
+    def handle(error)
+      false
+    end
+  end
+end