heap 0.3.0 → 1.0.0

data/lib/heap/errors.rb

@@ -0,0 +1,18 @@
+# Superclass for all Heap-related errors.
+class HeapAPI::Error < RuntimeError
+end
+
+# Raised when the Heap API server returns an error response.
+class HeapAPI::ApiError < HeapAPI::Error
+  # @param [Faraday::Response] response the error response returned by the Heap
+  #   analytics server
+  def initialize(response)
+    @response = response
+
+    super "Heap API server error: #{response.status} #{response.body}"
+  end
+
+  # @return [Faraday::Response] response the error response returned by the
+  #   Heap analytics server
+  attr_reader :response
+end

data/lib/heap/validations.rb

@@ -0,0 +1,57 @@
+# Internal methods used to validate API input.
+
+class HeapAPI::Client
+  # Makes sure that the client's app_id property is set.
+  #
+  # @raise RuntimeError if the client's app_id is nil
+  # @return [HeapAPI::Client] self
+  def ensure_valid_app_id!
+    raise RuntimeError, 'Heap app_id not set' unless @app_id
+    self
+  end
+  private :ensure_valid_app_id!
+
+  # Validates a Heap server-side API event name.
+  #
+  # @param [String] event the name of the server-side event
+  # @raise ArgumentError if the event name is invalid
+  # @return [HeapAPI::Client] self
+  def ensure_valid_event_name!(event)
+    raise ArgumentError, 'Missing or empty event name' if event.empty?
+    raise ArgumentError, 'Event name too long' if event.length > 1024
+    self
+  end
+  private :ensure_valid_event_name!
+
+  # Validates a bag of properties sent to a Heap server-side API.
+  #
+  # @param [Hash<String, String|Number>] properties key-value property bag;
+  #   each key must have fewer than 1024 characters; each value must be a
+  #   Number or String with fewer than 1024 characters
+  # @raise ArgumentError if the property bag is invalid
+  # @return [HeapAPI::Client] self
+  def ensure_valid_properties!(properties)
+    unless properties.respond_to?(:each)
+      raise ArgumentError, 'Properties object does not implement #each'
+    end
+
+    properties.each do |key, value|
+      if key.to_s.length > 1024
+        raise ArgumentError, "Property name #{key} too long; " +
+            "#{key.to_s.length} is above the 1024-character limit"
+      end
+      if value.kind_of? Numeric
+        # TODO(pwnall): Check numerical limits, if necessary.
+      elsif value.kind_of?(String) || value.kind_of?(Symbol)
+        if value.to_s.length > 1024
+          raise ArgumentError, "Property #{key} value #{value.inspect} too " +
+              "long; #{value.to_s.length} is above the 1024-character limit"
+        end
+      else
+        raise ArgumentError,
+            "Unsupported type for property #{key} value #{value.inspect}"
+      end
+    end
+  end
+  private :ensure_valid_properties!
+end

data/test/client_add_user_properties_test.rb

@@ -0,0 +1,124 @@
+require 'helper'
+
+class ClientAddUserPropertiesTest < MiniTest::Test
+  def setup
+    @stubs = Faraday::Adapter::Test::Stubs.new
+    @heap = HeapAPI::Client.new
+    @heap.app_id = 'test-app-id'
+    @heap.faraday_adapter = :test
+    @heap.faraday_adapter_args = [@stubs]
+  end
+
+  def teardown
+    @stubs.verify_stubbed_calls
+  end
+
+  def test_add_user_properties_without_app_id
+    @heap.app_id = nil
+    exception = assert_raises RuntimeError do
+      @heap.add_user_properties 'test-handle', 'key' => 'value'
+    end
+    assert_equal RuntimeError, exception.class
+    assert_equal 'Heap app_id not set', exception.message
+  end
+
+  def test_add_user_properties_with_long_property_name
+    long_name = 'A' * 1025
+
+    exception = assert_raises ArgumentError do
+      @heap.add_user_properties 'test-handle', long_name => 'value'
+    end
+    assert_equal ArgumentError, exception.class
+    assert_equal "Property name #{long_name} too long; " +
+        '1025 is above the 1024-character limit', exception.message
+  end
+
+  def test_add_user_properties_with_long_string_property_value
+    long_value = 'A' * 1025
+    exception = assert_raises ArgumentError do
+      @heap.add_user_properties 'test-handle', 'long_value_name' => long_value
+    end
+    assert_equal ArgumentError, exception.class
+    assert_equal "Property long_value_name value \"#{long_value}\" too " +
+        'long; 1025 is above the 1024-character limit', exception.message
+  end
+
+  def test_add_user_properties_with_long_symbol_property_value
+    long_value = ('A' * 1025).to_sym
+    exception = assert_raises ArgumentError do
+      @heap.add_user_properties 'test-handle', 'long_value_name' => long_value
+    end
+    assert_equal ArgumentError, exception.class
+    assert_equal "Property long_value_name value :#{long_value} too long; " +
+        '1025 is above the 1024-character limit', exception.message
+  end
+
+  def test_add_user_properties_with_array_property_value
+    exception = assert_raises ArgumentError do
+      @heap.add_user_properties 'test-handle', 'array_value_name' => []
+    end
+    assert_equal ArgumentError, exception.class
+    assert_equal 'Unsupported type for property array_value_name value []',
+        exception.message
+  end
+
+
+  def test_add_user_properties
+    @stubs.post '/api/identify' do |env|
+      golden_body = {
+        'app_id' => 'test-app-id',
+        'identity' => 'test-handle',
+        'properties' => { 'foo' => 'bar', 'heap' => 'hurray' }
+      }
+      assert_equal 'application/json', env[:request_headers]['Content-Type']
+      assert_equal @heap.user_agent, env[:request_headers]['User-Agent']
+      assert_equal golden_body, JSON.parse(env[:body])
+
+      [200, { 'Content-Type' => 'text/plain; encoding=utf8' }, '']
+    end
+
+    assert_equal @heap, @heap.add_user_properties('test-handle',
+        'foo' => 'bar', :heap => :hurray)
+  end
+
+  def test_add_user_properties_error
+    @stubs.post '/api/identify' do |env|
+      [400, { 'Content-Type' => 'text/plain; encoding=utf8' }, 'Bad request']
+    end
+
+    exception = assert_raises HeapAPI::Error do
+      @heap.add_user_properties 'test-handle', 'foo' => 'bar'
+    end
+
+    assert_equal HeapAPI::ApiError, exception.class
+    assert_equal 'Heap API server error: 400 Bad request', exception.message
+    assert_kind_of Faraday::Response, exception.response
+    assert_equal 400, exception.response.status
+  end
+
+  def test_add_user_properties_integration
+    @heap.app_id = '3000610572'
+    @heap.faraday_adapter = :net_http
+    @heap.faraday_adapter_args = []
+
+    assert_equal @heap, @heap.add_user_properties('test-handle',
+        'language/ruby' => 1, 'heap/heap-ruby' => 1)
+  end
+
+  def test_add_user_properties_error_integration
+    @heap.faraday_adapter = :net_http
+    @heap.faraday_adapter_args = []
+
+    assert_raises HeapAPI::Error do
+      @heap.add_user_properties 'test-handle',
+          'language/ruby' => 1, 'heap/heap-ruby' => 1
+    end
+  end
+
+  def test_add_user_properties_with_stubbed_connection
+    @heap.stubbed = true
+
+    assert_equal @heap, @heap.add_user_properties('test-handle',
+        'foo' => 'bar', :heap => :hurray)
+  end
+end

data/test/client_test.rb

@@ -0,0 +1,78 @@
+require 'helper'
+
+class ClientTest < MiniTest::Test
+  def setup
+    @heap = HeapAPI::Client.new
+  end
+
+  def test_default_app_id
+    assert_equal nil, @heap.app_id
+  end
+
+  def test_default_stubbed
+    assert_equal false, @heap.stubbed
+  end
+
+  def test_default_faraday_adapter
+    assert_equal Faraday.default_adapter, @heap.faraday_adapter
+  end
+
+  def test_default_faraday_adapter_args
+    assert_equal([], @heap.faraday_adapter_args)
+  end
+
+  def test_faraday_adapter_args_setter
+    stubs = Faraday::Adapter::Test::Stubs.new
+    @heap.faraday_adapter_args = [stubs]
+    assert_equal([stubs], @heap.faraday_adapter_args)
+
+    @heap.faraday_adapter = :test
+    @heap.connection  # Materialize the Faraday connection.
+    exception = assert_raises RuntimeError do
+      @heap.faraday_adapter_args = [:derp]
+    end
+    assert_equal RuntimeError, exception.class
+    assert_equal 'Faraday connection already initialized', exception.message
+    assert_equal [stubs], @heap.faraday_adapter_args
+  end
+
+  def test_stubbed_setter
+    @heap.app_id = 'test-app-id'
+    @heap.faraday_adapter = :net_http
+
+    @heap.stubbed = true
+    assert_equal @heap, @heap.track('test_stubbed_setter', 'test-handle',
+        'language' => 'ruby', 'project' => 'heap/heap-ruby')
+    stubbed_connection = @heap.connection
+
+    @heap.stubbed = false
+    assert_raises HeapAPI::Error do
+      @heap.track 'test_stubbed_setter', 'test-handle',
+          'language' => 'ruby', 'project' => 'heap/heap-ruby'
+    end
+    live_connection = @heap.connection
+
+    @heap.stubbed = true
+    assert_equal stubbed_connection, @heap.connection
+
+    @heap.stubbed = false
+    assert_equal live_connection, @heap.connection
+  end
+
+  def test_default_user_agent
+    assert_match(/^heap-ruby\/[0-9.]+ /, @heap.user_agent)
+    assert_match(/ faraday\/[0-9.]+ /, @heap.user_agent)
+    assert_match(/ ruby\/[0-9.]+ \(.+\)$/, @heap.user_agent)
+  end
+
+  def test_user_agent_setter
+    @heap.user_agent = 'sparky/4.2'
+    assert_equal 'sparky/4.2', @heap.user_agent
+  end
+
+  def test_constructor_options
+    heap = Heap.new :app_id => 'test-app-id', :stubbed => true
+    assert_equal 'test-app-id', heap.app_id
+    assert_equal true, heap.stubbed
+  end
+end

data/test/client_track_test.rb

@@ -0,0 +1,151 @@
+require 'helper'
+
+class ClientTrackTest < MiniTest::Test
+  def setup
+    @stubs = Faraday::Adapter::Test::Stubs.new do |stub|
+    end
+    @heap = HeapAPI::Client.new
+    @heap.app_id = 'test-app-id'
+    @heap.faraday_adapter = :test
+    @heap.faraday_adapter_args = [@stubs]
+  end
+
+  def teardown
+    @stubs.verify_stubbed_calls
+  end
+
+  def test_track_without_app_id
+    @heap.app_id = nil
+    exception = assert_raises RuntimeError do
+      @heap.track 'test_track_without_app_id', 'test-handle'
+    end
+    assert_equal RuntimeError, exception.class
+    assert_equal 'Heap app_id not set', exception.message
+  end
+
+  def test_track_without_event_name
+    exception = assert_raises ArgumentError do
+      @heap.track '', 'test-handle'
+    end
+    assert_equal ArgumentError, exception.class
+    assert_equal 'Missing or empty event name', exception.message
+  end
+
+  def test_track_with_long_event_name
+    exception = assert_raises ArgumentError do
+      @heap.track 'A' * 1025, 'test-handle'
+    end
+    assert_equal ArgumentError, exception.class
+    assert_equal 'Event name too long', exception.message
+  end
+
+  def test_track_with_long_property_name
+    long_name = 'A' * 1025
+    exception = assert_raises ArgumentError do
+      @heap.track 'test_track_with_long_property_name', 'test-handle',
+          long_name => 'value'
+    end
+    assert_equal ArgumentError, exception.class
+    assert_equal "Property name #{long_name} too long; " +
+        "1025 is above the 1024-character limit", exception.message
+  end
+
+  def test_track_with_long_string_property_value
+    long_value = 'A' * 1025
+    exception = assert_raises ArgumentError do
+      @heap.track 'test_track_with_long_string_property_value', 'test-handle',
+          'long_value_name' => long_value
+    end
+    assert_equal ArgumentError, exception.class
+    assert_equal "Property long_value_name value \"#{long_value}\" too " +
+        'long; 1025 is above the 1024-character limit', exception.message
+  end
+
+  def test_track_with_long_symbol_property_value
+    long_value = ('A' * 1025).to_sym
+    exception = assert_raises ArgumentError do
+      @heap.track 'test_track_with_long_symbol_property_value', 'test-handle',
+          'long_value_name' => long_value
+    end
+    assert_equal ArgumentError, exception.class
+    assert_equal "Property long_value_name value :#{long_value} too long; " +
+        '1025 is above the 1024-character limit', exception.message
+  end
+
+  def test_track
+    @stubs.post '/api/track' do |env|
+      golden_body = {
+        'app_id' => 'test-app-id',
+        'identity' => 'test-handle',
+        'event' => 'test_track',
+      }
+      assert_equal 'application/json', env[:request_headers]['Content-Type']
+      assert_equal @heap.user_agent, env[:request_headers]['User-Agent']
+      assert_equal golden_body, JSON.parse(env[:body])
+
+      [200, { 'Content-Type' => 'text/plain; encoding=utf8' }, '']
+    end
+
+    assert_equal @heap, @heap.track('test_track', 'test-handle')
+  end
+
+  def test_track_with_properties
+    @stubs.post '/api/track' do |env|
+      golden_body = {
+        'app_id' => 'test-app-id',
+        'identity' => 'test-handle',
+        'event' => 'test_track_with_properties',
+        'properties' => { 'foo' => 'bar', 'heap' => 'hurray' }
+      }
+      assert_equal 'application/json', env[:request_headers]['Content-Type']
+      assert_equal @heap.user_agent, env[:request_headers]['User-Agent']
+      assert_equal golden_body, JSON.parse(env[:body])
+
+      [200, { 'Content-Type' => 'text/plain; encoding=utf8' }, '']
+    end
+
+    assert_equal @heap, @heap.track('test_track_with_properties',
+        'test-handle','foo' => 'bar', :heap => :hurray)
+  end
+
+  def test_track_error
+    @stubs.post '/api/track' do |env|
+      [400, { 'Content-Type' => 'text/plain; encoding=utf8' }, 'Bad request']
+    end
+
+    exception = assert_raises HeapAPI::Error do
+      @heap.track('test-handle', 'test_track')
+    end
+    assert_equal HeapAPI::ApiError, exception.class
+    assert_equal 'Heap API server error: 400 Bad request', exception.message
+    assert_kind_of Faraday::Response, exception.response
+    assert_equal 400, exception.response.status
+  end
+
+  def test_track_integration
+    @heap.app_id = '3000610572'
+    @heap.faraday_adapter = :net_http
+    @heap.faraday_adapter_args = []
+
+    assert_equal @heap, @heap.track('test_track_integration', 'test-handle',
+        'language' => 'ruby', 'project' => 'heap/heap-ruby')
+  end
+
+  def test_track_error_integration
+    @heap.faraday_adapter = :net_http
+    @heap.faraday_adapter_args = []
+
+    assert_raises HeapAPI::Error do
+      @heap.track('test_track_integration', 'test-handle',
+          'language' => 'ruby', 'project' => 'heap/heap-ruby')
+    end
+  end
+
+
+  def test_track_with_stubbed_connection
+    @heap.stubbed = true
+
+    assert_equal @heap, @heap.add_user_properties('test-handle',
+        'foo' => 'bar', :heap => :hurray)
+  end
+end

data/test/heap_test.rb

@@ -0,0 +1,23 @@
+require 'helper'
+
+class HeapTest < MiniTest::Test
+  def test_heap_app_id
+    assert_equal nil,  Heap.app_id
+    begin
+      Heap.app_id = 'global-app-id'
+      assert_equal 'global-app-id', Heap.app_id
+    ensure
+      Heap.app_id = nil
+    end
+  end
+
+  def test_heap_stubbed
+    assert_equal false, Heap.stubbed
+  end
+
+  def test_heap_new
+    client = Heap.new :app_id => 'local-app-id', :stubbed => true
+    assert_equal 'local-app-id', client.app_id
+    assert_equal true, client.stubbed
+  end
+end