keen 0.3.0 → 0.4.1

data/.gitignore

@@ -0,0 +1,5 @@
+*.bundle
+Gemfile.lock
+tmp
+.env
+log

data/.rspec

@@ -0,0 +1,2 @@
+--format progress
+--color

data/.travis.yml

@@ -0,0 +1,17 @@
+language: ruby
+bundler_args: --without development
+
+rvm:
+  - 1.8.7
+  - 1.9.3
+  - jruby-19mode
+  - rbx-19mode
+
+env:
+  global:
+    - KEEN_API_KEY=f806128f31c349fda124b62d1f4cf4b2
+    - KEEN_PROJECT_ID=50e5ffa6897a2c319b000000
+
+script:
+  - bundle exec rake spec
+  - bundle exec rake integration

data/Gemfile

@@ -1,14 +1,32 @@
-source "http://rubygems.org"
-# Add dependencies required to use your gem here.
-gem "json", ">= 1.6.5"
+source :rubygems
+
+gemspec
+
+group :development, :test do
+  gem 'rake'
+  gem 'rspec'
+  gem 'em-http-request'
+  gem 'webmock'
+end
 
-# Add dependencies to develop your gem here.
-# Include everything needed to run rake, tests, features, etc.
 group :development do
-  gem "shoulda", ">= 0"
-  gem "rdoc", "~> 3.12"
-  gem "bundler", ">= 1.1.4"
-  gem "jeweler", "~> 1.8.3"
-  gem "rspec", ">= 2.9.0"
-  gem "cucumber", ">= 1.2.1"
+  # guard cross-platform listener trick
+  gem 'rb-inotify', :require => false
+  gem 'rb-fsevent', :require => false
+  gem 'rb-fchange', :require => false
+
+  # guard notifications
+  gem 'ruby_gntp'
+
+  # fix guard prompt
+  gem 'rb-readline' # or compile ruby w/ readline
+
+  # guard
+  gem 'guard'
+  gem 'guard-rspec'
+
+  # debuggers
+  gem 'ruby-debug', :platforms => :mri_18
+  gem 'debugger', :platforms => :mri_19
 end
+

data/Guardfile

@@ -0,0 +1,16 @@
+group :unit do
+  guard 'rspec', :spec_paths => "spec/keen" do
+    watch('spec/spec_helper.rb')  { "spec" }
+    watch('spec/keen/spec_helper.rb')  { "spec" }
+    watch(%r{^spec/keen/.+_spec\.rb$})
+    watch(%r{^lib/(.+)\.rb$})     { |m| "spec/keen/#{m[1]}_spec.rb" }
+  end
+end
+
+group :integration do
+  guard 'rspec', :spec_paths => "spec/integration" do
+    watch('spec/spec_helper.rb')  { "spec" }
+    watch('spec/integration/spec_helper.rb')  { "spec" }
+    watch(%r{^spec/integration/.+_spec\.rb$})
+  end
+end

data/README.md

@@ -1,33 +1,105 @@
-Keen Ruby Client Library
-========================
-
-Usage
------
-
-`gem install keen`
-
-Ruby Client Usage Guide
-http://keen.io/static/docs/clients/ruby/usage_guide.html
-
-see Also the Cucumber and Rspec stuff in /features/ for usage details)
-
-Contributing to keen
---------------------
- 
- * If you have gem release access, use Jeweler to increase version & release:
-   * rake version:bump:major
-   * rake release
- * Make sure all tests pass in 1.9.2 and 1.9.3
- * Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
- * Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
- * Fork the project.
- * Start a feature/bugfix branch.
- * Commit and push until you are happy with your contribution.
- * Make sure to add tests for it. This is important so we don't break it in a future version unintentionally.  If at all possible, please use BDD principles to drive your feature development with Cucumber.
- * Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
- 
-Copyright
----------
-
-Copyright (c) 2012 Keen Labs, Inc. See LICENSE.txt for further details.
+# Keen IO Official Ruby Client Library
+
+[![Build Status](https://secure.travis-ci.org/keenlabs/keen-gem.png?branch=master)](http://travis-ci.org/keenlabs/keen-gem)
+
+keen-gem is the official Ruby Client for the [Keen IO](https://keen.io/) API. The
+Keen IO API lets developers build analytics features directly into their apps.
+
+### Installation
+
+Add to your Gemfile:
+
+    gem 'keen'
+
+or install from Rubygems:
+
+    gem install keen
+
+keen is tested with Ruby 1.8 and 1.9 on:
+
+* MRI
+* Rubinius
+* jRuby (except for asynchronous methods - no TLS support for EM on jRuby)
+
+### Usage
+
+Before making any API calls, you must supply the keen gem with a Project ID and an API Key.
+(If you need a Keen IO account, [sign up here](https://keen.io/) - it's free.)
+
+The recommended way to do this is to set `KEEN_PROJECT_ID` and `KEEN_API_KEY` in your
+environment. If you're using [foreman](http://ddollar.github.com/foreman/), add this to your `.env` file:
+
+    KEEN_PROJECT_ID=your-project-id
+    KEEN_API_KEY=your-api-key
+
+When you deploy, make sure your production environment variables are also set. For example,
+set [config vars](https://devcenter.heroku.com/articles/config-vars) on Heroku. (We recommend this
+environment-based approach because it keeps sensitive credentials out of the codebase. If you can't do this, see the alternatives below.)
+
+If your environment is set up property, `Keen` is ready go immediately. Publish an event like this:
+
+    Keen.publish("sign_ups", { :username => "lloyd", :referred_by => "harry" })
+
+This will publish an event to the 'sign_ups' collection with the `username` and `referred_by` properties set.
+
+The event properties are arbitrary JSON, and the event collection need not exist in advance.
+If it doesn't exist, Keen IO will create it on the first request.
+
+You can learn more about data modeling with Keen IO with the [Data Modeling Guide](https://keen.io/docs/event-data-modeling/event-data-intro/).
+
+### Asynchronous publishing
+
+Publishing events shouldn't slow your application down. It shouldn't make your
+users wait longer for their request to finish.
+
+The Keen IO API is fast, but any synchronous network call you make will
+negatively impact response times. For this reason, we recommend you use the `publish_async`
+method to send events.
+
+To compare asychronous vs. synchronous performance, check out the [keen-gem-example](http://keen-gem-example.herokuapp.com/) app.
+
+To publish asynchronously, first add
+[em-http-request](https://github.com/igrigorik/em-http-request) to your Gemfile.
+
+Next, run an instance of EventMachine. If you're using an EventMachine-based web server like
+thin or goliath you're already doing this. Otherwise, you'll need to start an EventMachine loop manually as follows:
+
+    Thread.new { EventMachine.run }
+
+The best place for this is in an initializer, or anywhere that runs when your app boots up.
+Here's a good blog article that explains more about this approach - [EventMachine and Passenger](http://railstips.org/blog/archives/2011/05/04/eventmachine-and-passenger/).
+
+Now, in your code, replace `publish` with `publish_async`. Bind callbacks if you require them.
+
+    http = Keen.publish_async("sign_ups", { :username => "lloyd", :referred_by => "harry" })
+    http.callback { |response| puts "Success: #{response}"}
+    http.errback { puts "was a failurrr :,(" }
+
+This will schedule the network call into the event loop and allow your request thread
+to resume processing immediately.
+
+### Other code examples
+
+##### Authentication
+
+To configure the keen gem credentials in code, do as follows:
+
+    Keen.project_id = 'your-project-id'
+    Keen.api_key = 'your-api-key'
+
+You can also configure individual client instances as follows:
+
+    keen = new Keen::Client.new(:project_id => 'your-project-id',
+                                :api_key => 'your-api'key)
+
+##### On keen.io
+
+For more information and examples visit the
+Keen IO [Ruby Usage Guide](https://keen.io/docs/clients/ruby/usage-guide/).
+
+### Questions & Support
+
+If you have any questions, bugs, or suggestions, please
+report them via Github Issues. Or, come chat with us anytime
+at [users.keen.io](http://users.keen.io). We'd love to hear your feedback and ideas!
 

data/Rakefile

@@ -1,48 +1,15 @@
-# encoding: utf-8
-
-require 'rubygems'
 require 'bundler'
-begin
-  Bundler.setup(:default, :development)
-rescue Bundler::BundlerError => e
-  $stderr.puts e.message
-  $stderr.puts "Run `bundle install` to install missing gems"
-  exit e.status_code
-end
-require 'rake'
+require 'rspec/core/rake_task'
 
-require 'jeweler'
-Jeweler::Tasks.new do |gem|
-  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
-  gem.name = "keen"
-  gem.homepage = "http://github.com/dorkitude/keen"
-  gem.license = "MIT"
-  gem.summary = %Q{A library for batching and sending arbitrary events to the Keen API at http://keen.io}
-  gem.description = %Q{See the github repo or examples.rb for usage information.}
-  gem.email = "kyle@keen.io"
-  gem.authors = ["dorkitude"]
-  # dependencies defined in Gemfile
+desc "Run Rspec unit tests"
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.pattern = "spec/keen/**/*_spec.rb"
 end
-Jeweler::RubygemsDotOrgTasks.new
 
-require 'rake/testtask'
-Rake::TestTask.new(:test) do |test|
-  test.libs << 'lib' << 'test'
-  test.pattern = 'test/**/test_*.rb'
-  test.verbose = true
+desc "Run Rspec integration tests"
+RSpec::Core::RakeTask.new(:integration) do |t|
+  t.pattern = "spec/integration/**/*_spec.rb"
 end
 
-require 'cucumber/rake/task'
-Cucumber::Rake::Task.new(:features)
-
-task :default => :test
-
-require 'rdoc/task'
-Rake::RDocTask.new do |rdoc|
-  version = File.exist?('VERSION') ? File.read('VERSION') : ""
-
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "keen #{version}"
-  rdoc.rdoc_files.include('README*')
-  rdoc.rdoc_files.include('lib/**/*.rb')
-end
+task :default => :spec
+task :test => [:spec]

data/keen.gemspec

@@ -1,77 +1,22 @@
-# Generated by jeweler
-# DO NOT EDIT THIS FILE DIRECTLY
-# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "keen/version"
 
 Gem::Specification.new do |s|
-  s.name = "keen"
-  s.version = "0.3.0"
+  s.name        = "keen"
+  s.version     = Keen::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Kyle Wild", "Josh Dzielak"]
+  s.email       = "josh@keen.io"
+  s.homepage    = "https://github.com/keenlabs/keen-gem"
+  s.summary     = "Keen IO API Client"
+  s.description = "Batch and send events to the Keen IO API. Supports asychronous requests."
 
-  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
-  s.authors = ["dorkitude"]
-  s.date = "2012-11-26"
-  s.description = "See the github repo or examples.rb for usage information."
-  s.email = "kyle@keen.io"
-  s.extra_rdoc_files = [
-    "LICENSE.txt",
-    "README.md"
-  ]
-  s.files = [
-    ".rvmrc",
-    "Gemfile",
-    "LICENSE.txt",
-    "README.md",
-    "Rakefile",
-    "VERSION.yml",
-    "conf/cacert.pem",
-    "examples.rb",
-    "features/add_event.feature",
-    "features/step_definitions/keen_steps.rb",
-    "features/support/before_and_after.rb",
-    "features/support/env.rb",
-    "keen.gemspec",
-    "keen.gemspec.old",
-    "lib/keen.rb",
-    "lib/keen/client.rb",
-    "lib/keen/event.rb",
-    "lib/keen/keys.rb",
-    "lib/keen/utils.rb",
-    "lib/keen/version.rb"
-  ]
-  s.homepage = "http://github.com/dorkitude/keen"
-  s.licenses = ["MIT"]
-  s.require_paths = ["lib"]
-  s.rubygems_version = "1.8.19"
-  s.summary = "A library for batching and sending arbitrary events to the Keen API at http://keen.io"
-
-  if s.respond_to? :specification_version then
-    s.specification_version = 3
+  s.add_dependency "multi_json", "~> 1.0"
+  s.add_dependency "jruby-openssl" if defined?(JRUBY_VERSION)
 
-    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
-      s.add_runtime_dependency(%q<json>, [">= 1.6.5"])
-      s.add_development_dependency(%q<shoulda>, [">= 0"])
-      s.add_development_dependency(%q<rdoc>, ["~> 3.12"])
-      s.add_development_dependency(%q<bundler>, [">= 1.1.4"])
-      s.add_development_dependency(%q<jeweler>, ["~> 1.8.3"])
-      s.add_development_dependency(%q<rspec>, [">= 2.9.0"])
-      s.add_development_dependency(%q<cucumber>, [">= 1.2.1"])
-    else
-      s.add_dependency(%q<json>, [">= 1.6.5"])
-      s.add_dependency(%q<shoulda>, [">= 0"])
-      s.add_dependency(%q<rdoc>, ["~> 3.12"])
-      s.add_dependency(%q<bundler>, [">= 1.1.4"])
-      s.add_dependency(%q<jeweler>, ["~> 1.8.3"])
-      s.add_dependency(%q<rspec>, [">= 2.9.0"])
-      s.add_dependency(%q<cucumber>, [">= 1.2.1"])
-    end
-  else
-    s.add_dependency(%q<json>, [">= 1.6.5"])
-    s.add_dependency(%q<shoulda>, [">= 0"])
-    s.add_dependency(%q<rdoc>, ["~> 3.12"])
-    s.add_dependency(%q<bundler>, [">= 1.1.4"])
-    s.add_dependency(%q<jeweler>, ["~> 1.8.3"])
-    s.add_dependency(%q<rspec>, [">= 2.9.0"])
-    s.add_dependency(%q<cucumber>, [">= 1.2.1"])
-  end
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
 end
-

data/lib/keen.rb

@@ -1,5 +1,47 @@
+require 'logger'
+require 'forwardable'
+require 'multi_json'
+
 require 'keen/client'
-require 'keen/event'
-require 'keen/keys'
-require 'keen/utils'
-require 'keen/version'
+
+module Keen
+  class Error < RuntimeError
+    attr_accessor :original_error
+    def initialize(message, _original_error=nil)
+      self.original_error = _original_error
+      super(message)
+    end
+  end
+
+  class ConfigurationError < Error; end
+  class HttpError < Error; end
+  class BadRequestError < HttpError; end
+  class AuthenticationError < HttpError; end
+  class NotFoundError < HttpError; end
+
+  class << self
+    extend Forwardable
+
+    def_delegators :default_client, :project_id, :api_key,
+                   :project_id=, :api_key=, :publish, :publish_async
+
+    attr_writer :logger
+
+    def logger
+      @logger ||= lambda {
+        logger = Logger.new($stdout)
+        logger.level = Logger::INFO
+        logger
+      }.call
+    end
+
+    private
+
+    def default_client
+      @default_client || Keen::Client.new(
+        :project_id => ENV['KEEN_PROJECT_ID'],
+        :api_key => ENV['KEEN_API_KEY']
+      )
+    end
+  end
+end

data/lib/keen/client.rb

@@ -1,94 +1,118 @@
-require "json"
-require "uri"
-require "time"
-require "net/http"
-require "net/https"
-
+require 'keen/version'
+require 'keen/http'
 
 module Keen
   class Client
-    attr_accessor :project_id, :api_key, :options, :logging
-
-    def base_url
-      if @options[:base_url]
-        @options[:base_url]
-      else
-        "https://api.keen.io/3.0"
+    attr_accessor :project_id, :api_key
+
+    CONFIG = {
+      :api_host => "api.keen.io",
+      :api_port => 443,
+      :api_sync_http_options => {
+        :use_ssl => true,
+        :verify_mode => OpenSSL::SSL::VERIFY_PEER,
+        :verify_depth => 5,
+        :ca_file => File.expand_path("../../../config/cacert.pem", __FILE__) },
+      :api_async_http_options => {},
+      :api_headers => {
+        "Content-Type" => "application/json",
+        "User-Agent" => "keen-gem v#{Keen::VERSION}"
+      }
+    }
+
+    def initialize(*args)
+      options = args[0]
+      unless options.is_a?(Hash)
+        # deprecated, pass a hash of options instead
+        options = {
+          :project_id => args[0],
+          :api_key => args[1],
+        }.merge(args[2] || {})
       end
-    end
 
-    def ssl_cert_file
-      File.expand_path("../../../conf/cacert.pem", __FILE__)
+      @project_id, @api_key = options.values_at(
+        :project_id, :api_key)
     end
 
-    def initialize(project_id, api_key, options = {})
-      raise "project_id must be string" unless project_id.kind_of? String
-      raise "api_key must be string" unless api_key.kind_of? String
+    def publish(event_name, properties)
+      check_configuration!
+      begin
+        response = Keen::HTTP::Sync.new(
+          api_host, api_port, api_sync_http_options).post(
+            :path => api_path(event_name),
+            :headers => api_headers_with_auth,
+            :body => MultiJson.encode(properties))
+      rescue Exception => http_error
+        raise HttpError.new("Couldn't connect to Keen IO: #{http_error.message}", http_error)
+      end
+      process_response(response.code, response.body.chomp)
+    end
 
-      default_options = {
-        :logging => true,
+    def publish_async(event_name, properties)
+      check_configuration!
+
+      deferrable = EventMachine::DefaultDeferrable.new
+
+      http_client = Keen::HTTP::Async.new(api_host, api_port, api_async_http_options)
+      http = http_client.post({
+        :path => api_path(event_name),
+        :headers => api_headers_with_auth,
+        :body => MultiJson.encode(properties)
+      })
+      http.callback {
+        begin
+          response = process_response(http.response_header.status, http.response.chomp)
+          deferrable.succeed(response)
+        rescue Exception => e
+          deferrable.fail(e)
+        end
+      }
+      http.errback {
+        Keen.logger.warn("Couldn't connect to Keen IO: #{http.error}")
+        deferrable.fail(Error.new("Couldn't connect to Keen IO: #{http.error}"))
       }
 
-      options = default_options.update(options)
-
-      @project_id = project_id
-      @api_key = api_key
-
-      @logging = options[:logging]
-      @options = options
+      deferrable
     end
 
-    def add_event(event_collection, event_properties, timestamp=nil)
-      #
-      # `event_collection` should be a string
-      #
-      # `event` should be a JSON-serializable hash
-      #
-      # `timestamp` is optional. If sent, it should be a Time instance.  
-      #  If it's not sent, we'll use the current time.
-      
-      validate_event_collection(event_collection)
-
-      if timestamp
-        timestamp = timestamp.utc.iso8601
-      end
-
-      event = Keen::Event.new(event_collection, event_properties)
+    # deprecated
+    def add_event(event_name, properties, options={})
+      self.publish(event_name, properties, options)
+    end
 
-      # build the request:
-      if event.properties.is_a?(Array)
-        url = "#{base_url}/projects/#{project_id}/events"
-        body = {event_collection => event.properties}
+    private
+
+    def process_response(status_code, response_body)
+      body = MultiJson.decode(response_body)
+      case status_code.to_i
+      when 200..201
+        return body
+      when 400
+        raise BadRequestError.new(body)
+      when 401
+        raise AuthenticationError.new(body)
+      when 404
+        raise NotFoundError.new(body)
       else
-        url = "#{base_url}/projects/#{project_id}/events/#{event_collection}"
-        body = event.properties
-      end
-      uri = URI.parse(url)
-      http = Net::HTTP.new(uri.host, uri.port)
-      http.use_ssl = true
-      http.ca_file = ssl_cert_file
-      http.verify_mode = OpenSSL::SSL::VERIFY_PEER
-      http.verify_depth = 5
-
-      request = Net::HTTP::Post.new(uri.path)
-
-      if timestamp
-        request.body[:keen] = {
-          :timestamp => timestamp
-        }
+        raise HttpError.new(body)
       end
+    end
 
-      request.body = JSON.generate(body)
+    def api_path(collection)
+      "/3.0/projects/#{project_id}/events/#{collection}"
+    end
 
-      request["Content-Type"] = "application/json"
-      request["Authorization"] = @api_key
+    def api_headers_with_auth
+      api_headers.merge("Authorization" => api_key)
+    end
 
-      response = http.request(request)
-      JSON.parse response.body
+    def check_configuration!
+      raise ConfigurationError, "Project ID must be set" unless project_id
+      raise ConfigurationError, "API Key must be set" unless api_key
     end
 
-    def validate_event_collection(event_collection)
-      # TODO
+    def method_missing(_method, *args, &block)
+      CONFIG[_method.to_sym] || super
     end
   end
 end