keen 0.8.7 → 0.8.8

data/README.md

@@ -3,7 +3,7 @@
 [![Build Status](https://secure.travis-ci.org/keenlabs/keen-gem.png?branch=master)](http://travis-ci.org/keenlabs/keen-gem) [![Code Climate](https://codeclimate.com/github/keenlabs/keen-gem.png)](https://codeclimate.com/github/keenlabs/keen-gem)
 [![Gem Version](https://badge.fury.io/rb/keen.svg)](http://badge.fury.io/rb/keen)
 
-keen-gem is the official Ruby Client for the [Keen IO](https://keen.io/) API. The
+keen-gem is the official Ruby Client for the [Keen IO](https://keen.io/?s=gh-gem) API. The
 Keen IO API lets developers build analytics features directly into their apps.
 
 ### Installation
@@ -25,14 +25,14 @@ keen is tested with Ruby 1.8 and 1.9 on:
 ### Usage
 
 Before making any API calls, you must supply keen-gem with a Project ID and one or more authentication keys.
-(If you need a Keen IO account, [sign up here](https://keen.io/signup) - it's free.) 
+(If you need a Keen IO account, [sign up here](https://keen.io/signup?s=gh-gem) - it's free.) 
 
 Setting a write key is required for publishing events. Setting a read key is required for running queries. 
 Setting a master key is required for performing deletes. You can find keys for all of your projects
-on [keen.io](https://keen.io).
+on [keen.io](https://keen.io?s=gh-gem).
 
 The recommended way to set keys is via the environment. The keys you can set are 
-`KEEN_PROJECT_ID`, `KEEN_WRITE_KEY`, `KEEN_READ_KEY`, and `KEEN_MASTER_KEY`.
+`KEEN_PROJECT_ID`, `KEEN_WRITE_KEY`, `KEEN_READ_KEY` and `KEEN_MASTER_KEY`.
 You only need to specify the keys that correspond to the API calls you'll be performing. 
 If you're using [foreman](http://ddollar.github.com/foreman/), add this to your `.env` file:
 
@@ -58,7 +58,7 @@ 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 can be any valid Ruby hash. Nested properties are allowed. Lists of objects are also allowed, but not recommended because they can be difficult to query over. See alternatives to lists of objects [here](http://stackoverflow.com/questions/24620330/nested-json-objects-in-keen-io). 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/). 
+The event properties can be any valid Ruby hash. Nested properties are allowed. Lists of objects are also allowed, but not recommended because they can be difficult to query over. See alternatives to lists of objects [here](http://stackoverflow.com/questions/24620330/nested-json-objects-in-keen-io). 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/?s=gh-gem). 
 
 Protip: Marshalling gems like [Blockhead](https://github.com/vinniefranco/blockhead) make converting structs or objects to hashes easier.
 
@@ -106,7 +106,7 @@ to resume processing immediately.
 
 ### Running queries
 
-The Keen IO API provides rich querying capabilities against your event data set. For more information, see the [Data Analysis API Guide](https://keen.io/docs/data-analysis/).
+The Keen IO API provides rich querying capabilities against your event data set. For more information, see the [Data Analysis API Guide](https://keen.io/docs/data-analysis/?s=gh-gem).
 
 Running queries requires that `KEEN_READ_KEY` is set.
 
@@ -121,27 +121,31 @@ Keen.average("purchases", :target_property => "price")  # => 60
 Keen.median("purchases", :target_property => "price")  # => 60
 Keen.percentile("purchases", :target_property => "price", :percentile => 90)  # => 100
 
-Keen.sum("purchases", :target_property => "price", :group_by => "item.id")  # => [{ "item.id": 123, "result": 240 }, { ... }]
+Keen.sum("purchases", :target_property => "price", :group_by => "item.id")  # => [{ "item.id": 123, "result": 240 }]
+Keen.count("purchases", :timeframe => "today", :filters => [{
+    "property_name" => "referred_by",
+    "operator" => "eq",
+    "property_value" => "harry"
+  }]) # => 2
 
 Keen.count_unique("purchases", :target_property => "username")  # => 3
 Keen.select_unique("purchases", :target_property => "username")  # => ["Bob", "Linda", "Travis"]
 
-Keen.extraction("purchases")  # => [{ "price" => 20, ... }, { ... }]
+Keen.extraction("purchases")  # => [{ "keen" => { "timestamp" => "2014-01-01T00:00:00Z" }, "price" => 20 }]
 
-Keen.funnel(:steps => [
-  { :actor_property => "username", :event_collection => "purchases" },
-  { :actor_property => "username", :event_collection => "referrals" },
-  { ... }])  # => [20, 15 ...]
+Keen.funnel(:steps => [{ 
+  :actor_property => "username", :event_collection => "purchases" }, {
+  :actor_property => "username", :event_collection => "referrals" }]) # => [20, 15]
 
 Keen.multi_analysis("purchases", analyses: {
   :gross =>      { :analysis_type => "sum", :target_property => "price" },
   :customers =>  { :analysis_type => "count_unique", :target_property => "username" } },
-  :timeframe => 'today', :group_by => "item.id") # => [{"item.id"=>2, "gross"=>314.49, "customers"=> 8}, { ... }]
+  :timeframe => 'today', :group_by => "item.id") # => [{ "item.id" => 2, "gross" => 314.49, "customers" => 8 } }]
 ```
 
 Many of these queries can be performed with group by, filters, series and intervals. The response is returned as a Ruby Hash or Array.
 
-Detailed information on available parameters for each API resource can be found on the [API Technical Reference](https://keen.io/docs/api/reference/).
+Detailed information on available parameters for each API resource can be found on the [API Technical Reference](https://keen.io/docs/api/reference/?s=gh-gem).
 
 ##### The Query Method
 
@@ -187,7 +191,7 @@ Getting the list of event collections requires that the `KEEN_MASTER_KEY` is set
 
 ### Deleting events
 
-The Keen IO API allows you to [delete events](https://keen.io/docs/maintenance/#deleting-event-collections)
+The Keen IO API allows you to [delete events](https://keen.io/docs/maintenance/#deleting-event-collections?s=gh-gem)
 from event collections, optionally supplying a filter to narrow the scope of what you would like to delete.
 
 Deleting events requires that the `KEEN_MASTER_KEY` is set.
@@ -208,7 +212,7 @@ Keen.delete(:signups, filters: [{
 
 #### Overwriting event timestamps
 
-Two time-related properties are included in your event automatically. The properties “keen.timestamp” and “keen.created_at” are set at the time your event is recorded. You have the ability to overwrite the keen.timestamp property. This could be useful, for example, if you are backfilling historical data. Be sure to use [ISO-8601 Format](https://keen.io/docs/event-data-modeling/event-data-intro/#iso-8601-format).
+Two time-related properties are included in your event automatically. The properties “keen.timestamp” and “keen.created_at” are set at the time your event is recorded. You have the ability to overwrite the keen.timestamp property. This could be useful, for example, if you are backfilling historical data. Be sure to use [ISO-8601 Format](https://keen.io/docs/event-data-modeling/event-data-intro/#iso-8601-format?s=gh-gem).
 
 Keen stores all date and time information in UTC!
 
@@ -266,6 +270,7 @@ Keen.project_id = 'xxxxxxxxxxxxxxx'
 Keen.write_key = 'yyyyyyyyyyyyyyy'
 Keen.read_key = 'zzzzzzzzzzzzzzz'
 Keen.master_key = 'aaaaaaaaaaaaaaa'
+Keen.read_timeoout = 60
 ```
 
 You can also configure unique client instances as follows:
@@ -274,7 +279,8 @@ You can also configure unique client instances as follows:
 keen = Keen::Client.new(:project_id => 'xxxxxxxxxxxxxxx',
                         :write_key  => 'yyyyyyyyyyyyyyy',
                         :read_key   => 'zzzzzzzzzzzzzzz',
-                        :master_key => 'aaaaaaaaaaaaaaa')
+                        :master_key => 'aaaaaaaaaaaaaaa',
+                        :read_timeout => 60)
 ```
 
 #### em-synchrony
@@ -299,22 +305,22 @@ Keen.beacon_url("sign_ups", :recipient => "foo@foo.com")
   # => "https://api.keen.io/3.0/projects/xxxxxx/events/email_opens?api_key=yyyyyy&data=eyJyZWNpcGllbnQiOiJmb29AZm9vLmNvbSJ9"
 ```
 
-To track email opens, simply add an image to your email template that points to this URL. For further information on how to do this, see the [image beacon documentation](https://keen.io/docs/data-collection/image-beacon/).
+To track email opens, simply add an image to your email template that points to this URL. For further information on how to do this, see the [image beacon documentation](https://keen.io/docs/data-collection/image-beacon/?s=gh-gem).
 
 #### Redirect URLs
 Redirect URLs are just like image beacon URLs with the addition of a `redirect` query parameter. This parameter is used
 to issue a redirect to a certain URL after an event is recorded.
 
-```
+``` ruby
 Keen.redirect_url("sign_ups", { :recipient => "foo@foo.com" }, "http://foo.com")
   # => "https://api.keen.io/3.0/projects/xxxxxx/events/email_opens?api_key=yyyyyy&data=eyJyZWNpcGllbnQiOiJmb29AZm9vLmNvbSJ9&redirect=http://foo.com"
 ```
 
-This is helpful for tracking email clickthroughs. See the [redirect documentation](https://keen.io/docs/data-collection/redirect/) for further information.
+This is helpful for tracking email clickthroughs. See the [redirect documentation](https://keen.io/docs/data-collection/redirect/?s=gh-gem) for further information.
 
 #### Generating scoped keys
 
-A [scoped key](https://keen.io/docs/security/#scoped-key) is a string, generated with your API Key, that represents some encrypted authentication and query options.
+A [scoped key](https://keen.io/docs/security/#scoped-key?s=gh-gem) is a string, generated with your API Key, that represents some encrypted authentication and query options.
 Use them to control what data queries have access to.
 
 ``` ruby
@@ -328,6 +334,21 @@ scoped_key = Keen::ScopedKey.new("my-api-key", { "filters" => [{
 
 You can use the scoped key created in Ruby for API requests from any client. Scoped keys are commonly used in JavaScript, where credentials are visible and need to be protected.
 
+### Additional options
+
+##### HTTP Read Timeout
+
+The default `Net:HTTP` timeout is 60 seconds. That's usually enough, but if you're querying over a large collection you may need to increase it. The timeout on the API side is 300 seconds, so that's as far as you'd want to go. You can configure a read timeout (in seconds) by setting a `KEEN_READ_TIMEOUT` environment variable, or by passing in a `read_timeout` option to the client constructor as follows:
+
+```
+keen = Keen::Client.new(:read_timeout => 300)
+```
+
+##### HTTP Proxy
+
+You can set the `KEEN_PROXY_TYPE` and `KEEN_PROXY_URL` environment variables to enable HTTP proxying. `KEEN_PROXY_TYPE` should most likely be set to `socks5`. You can also configure this on client instances by passing in `proxy_type` and `proxy_url` keys.
+
+
 ### Troubleshooting
 
 ##### EventMachine
@@ -343,6 +364,9 @@ EventMachine itself won't do this because it runs in a different thread. Here's
 
 ### Changelog
 
+##### 0.8.8
++ Add support for a configurable read timeout
+
 ##### 0.8.7
 + Add support for returning all keys back from query API responses
 
@@ -351,10 +375,10 @@ EventMachine itself won't do this because it runs in a different thread. Here's
 + Make the `query` method public so code supporting dynamic analysis types is easier to write
 
 ##### 0.8.4
-+ Add support for getting [project details](https://keen.io/docs/api/reference/#project-row-resource)
++ Add support for getting [project details](https://keen.io/docs/api/reference/#project-row-resource?s=gh-gem)
 
 ##### 0.8.3
-+ Add support for getting a list of a [project's collections](https://keen.io/docs/api/reference/#event-resource)
++ Add support for getting a list of a [project's collections](https://keen.io/docs/api/reference/#event-resource?s=gh-gem)
 
 ##### 0.8.2
 + Add support for `median` and `percentile` analysis
@@ -365,9 +389,9 @@ EventMachine itself won't do this because it runs in a different thread. Here's
 
 ##### 0.8.0
 + **UPGRADE WARNING** Do you use spaces in collection names? Or other special characters? Read [this post](https://groups.google.com/forum/?fromgroups#!topic/keen-io-devs/VtCgPuNKrgY) from the mailing list to make sure your collection names don't change.
-+ Add support for generating [scoped keys](https://keen.io/docs/security/#scoped-key).
++ Add support for generating [scoped keys](https://keen.io/docs/security/#scoped-key?s=gh-gem).
 + Make collection name encoding more robust. Make sure collection names are encoded identically for publishing events, running queries, and performing deletes.
-+ Add support for [grouping by multiple properties](https://keen.io/docs/data-analysis/group-by/#grouping-by-multiple-properties).
++ Add support for [grouping by multiple properties](https://keen.io/docs/data-analysis/group-by/#grouping-by-multiple-properties?s=gh-gem).
 
 ##### 0.7.8
 + Add support for redirect URL creation.
@@ -426,9 +450,14 @@ server-side querying processes require a Read key that should not be made public
 
 ### 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!
+For questions, bugs, or suggestions about this gem:
+[File a Github Issue](https://github.com/keenlabs/keen-gem/issues). 
+
+For other Keen-IO related technical questions:
+['keen-io' on Stack Overflow](http://stackoverflow.com/questions/tagged/keen-io)
+
+For general Keen IO discussion & feedback:
+['keen-io-devs' Google Group](https://groups.google.com/forum/#!forum/keen-io-devs)
 
 ### Contributing
 keen-gem is an open source project and we welcome your contributions.

data/lib/keen.rb

@@ -73,7 +73,8 @@ module Keen
         :master_key => ENV['KEEN_MASTER_KEY'],
         :api_url => ENV['KEEN_API_URL'],
         :proxy_url => ENV['KEEN_PROXY_URL'],
-        :proxy_type => ENV['KEEN_PROXY_TYPE']
+        :proxy_type => ENV['KEEN_PROXY_TYPE'],
+        :read_timeout => ENV['KEEN_READ_TIMEOUT']
       )
     end
   end

data/lib/keen/client.rb

@@ -15,7 +15,7 @@ module Keen
     include Keen::Client::QueryingMethods
     include Keen::Client::MaintenanceMethods
 
-    attr_accessor :project_id, :write_key, :read_key, :master_key, :api_url, :proxy_url, :proxy_type
+    attr_accessor :project_id, :write_key, :read_key, :master_key, :api_url, :proxy_url, :proxy_type, :read_timeout
 
     CONFIG = {
       :api_url => "https://api.keen.io",
@@ -49,6 +49,8 @@ module Keen
       self.api_url = options[:api_url] || CONFIG[:api_url]
 
       self.proxy_url, self.proxy_type = options.values_at(:proxy_url, :proxy_type)
+
+      self.read_timeout = options[:read_timeout].to_f unless options[:read_timeout].nil?
     end
 
     private

data/lib/keen/client/maintenance_methods.rb

@@ -16,7 +16,7 @@ module Keen
         query_params = preprocess_params(params) if params != {}
 
         begin
-          response = Keen::HTTP::Sync.new(self.api_url, self.proxy_url).delete(
+          response = http_sync.delete(
               :path => [api_event_collection_resource_path(event_collection), query_params].compact.join('?'),
               :headers => api_headers(self.master_key, "sync"))
         rescue Exception => http_error
@@ -35,7 +35,7 @@ module Keen
         ensure_master_key!
 
         begin
-          response = Keen::HTTP::Sync.new(self.api_url, self.proxy_url).get(
+          response = http_sync.get(
               :path => "/#{api_version}/projects/#{project_id}/events",
               :headers => api_headers(self.master_key, "sync"))
         rescue Exception => http_error
@@ -54,7 +54,7 @@ module Keen
         ensure_master_key!
 
         begin
-          response = Keen::HTTP::Sync.new(self.api_url, self.proxy_url).get(
+          response = http_sync.get(
               :path => "/#{api_version}/projects/#{project_id}",
               :headers => api_headers(self.master_key, "sync"))
         rescue Exception => http_error
@@ -65,6 +65,12 @@ module Keen
         process_response(response.code, response_body)
       end
 
+      private
+
+      def http_sync
+        @http_sync ||= Keen::HTTP::Sync.new(self.api_url, self.proxy_url, self.read_timeout)
+      end
+
     end
   end
 end

data/lib/keen/client/publishing_methods.rb

@@ -161,7 +161,7 @@ module Keen
       def publish_body(path, body, error_method)
         begin
           response = Keen::HTTP::Sync.new(
-            self.api_url, self.proxy_url).post(
+            self.api_url, self.proxy_url, self.read_timeout).post(
               :path => path,
               :headers => api_headers(self.write_key, "sync"),
               :body => body)

data/lib/keen/client/querying_methods.rb

@@ -241,7 +241,7 @@ module Keen
 
       def get_response(url)
         uri = URI.parse(url)
-        Keen::HTTP::Sync.new(self.api_url, self.proxy_url).get(
+        Keen::HTTP::Sync.new(self.api_url, self.proxy_url, self.read_timeout).get(
           :path => "#{uri.path}?#{uri.query}",
           :headers => api_headers(self.read_key, "sync")
         )

data/lib/keen/http.rb

@@ -1,21 +1,16 @@
 module Keen
   module HTTP
     class Sync
-      def initialize(base_url, proxy_url=nil)
+      def initialize(base_url, proxy_url=nil, read_timeout=nil)
         require 'uri'
         require 'net/http'
 
         uri = URI.parse(base_url)
-        if proxy_url
-          proxy_uri = URI.parse(proxy_url)
-          @http = Net::HTTP::Proxy(
-              proxy_uri.host,
-              proxy_uri.port,
-              proxy_uri.user,
-              proxy_uri.password).new(uri.host, uri.port)
-        else
-          @http = Net::HTTP.new(uri.host, uri.port)
-        end
+        arguments = [uri.host, uri.port]
+        arguments+= proxy_arguments_for(proxy_url) if proxy_url
+
+        @http = Net::HTTP.new(*arguments)
+        @http.read_timeout = read_timeout if read_timeout
 
         if uri.scheme == "https"
           require 'net/https'
@@ -26,6 +21,11 @@ module Keen
         end
       end
 
+      def proxy_arguments_for(uri)
+        proxy_uri = URI.parse(proxy_url)
+        [proxy_uri.host, proxy_uri.port, proxy_uri.user, proxy_uri.password]
+      end
+
       def post(options)
         path, headers, body = options.values_at(
           :path, :headers, :body)

data/lib/keen/version.rb

@@ -1,3 +1,3 @@
 module Keen
-  VERSION = "0.8.7"
+  VERSION = "0.8.8"
 end

data/spec/keen/client_spec.rb

@@ -6,12 +6,14 @@ describe Keen::Client do
   let(:read_key) { "abcderead" }
   let(:api_url) { "http://fake.keen.io:fakeport" }
   let(:client) { Keen::Client.new(:project_id => project_id) }
+  let(:read_timeout) { 40 }
 
   before do
     ENV["KEEN_PROJECT_ID"] = nil
     ENV["KEEN_WRITE_KEY"] = nil
     ENV["KEEN_READ_KEY"] = nil
     ENV["KEEN_API_URL"] = nil
+    ENV["KEEN_READ_TIMEOUT"] = nil
   end
 
   describe "#initialize" do
@@ -29,11 +31,13 @@ describe Keen::Client do
         :project_id => project_id,
         :write_key => write_key,
         :read_key => read_key,
-        :api_url => api_url)
+        :api_url => api_url,
+        :read_timeout => read_timeout)
       client.write_key.should == write_key
       client.read_key.should == read_key
       client.project_id.should == project_id
       client.api_url.should == api_url
+      client.read_timeout.should == read_timeout
     end
 
     it "should set a default api_url" do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: keen
 version: !ruby/object:Gem::Version
-  version: 0.8.7
+  version: 0.8.8
   prerelease: 
 platform: ruby
 authors:
@@ -11,7 +11,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-09-18 00:00:00.000000000 Z
+date: 2014-12-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: multi_json