orchestrate 0.6.3 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 280e11fed61bfb3b020de4fbed4b67d4392fd8f7
-  data.tar.gz: b454f95ec082424d99e99882ca4c9707da555f55
+  metadata.gz: a997f89d7ead7ddaa902fa36b7c50d5dcaa36fe9
+  data.tar.gz: e767f9630b2a2c619c22d4606f8005a11e35e079
 SHA512:
-  metadata.gz: e642894e20da91faa3aa746f217b6678273f9060e47aa4ad1664e3515208e8b96df6ebe4277d6b54c53995448ad7e74fc74dacae8760368821a1a42851275528
-  data.tar.gz: 03daed3e82a28e5c34de96568605dc313bb16338cf43369900eda1effee84ac000f380f6534c816341ad37353f734b2cd7418ef81f4ae0910618946145a703cd
+  metadata.gz: 6a0d8dabd889acb31b465972186862317f3a19d0709d9c96c188fadf06b0cf22748af04821e3331c47111b6f59e8af4390877004bf4a926eb5f2962d89539615
+  data.tar.gz: c76d14585febf3df794571aa6c2442820c89bdbcd6395ace403bcb7ad714ed8ef120461c7c73b686b5008c7f73643687cb4184446a776ea969554f521a7fc969

data/README.md

@@ -8,36 +8,69 @@ Ruby client interface for the [Orchestrate.io](http://orchestrate.io) REST API.
 
 ## Getting Started
 
-Provide your API key:
+The Orchestrate Gem provides two interfaces currently, the _method_ client and the _object_ client.  The method client is a solid but basic interface that provides a single entry point to an Orchestrate Application.  The object client uses the method client under the hood, and maps Orchestrate's domain objects (Collections, KeyValues, etc) to Ruby classes, and is still very much in progress.  This guide will show you how to use both.
 
-``` ruby
-client = Orchestrate::Client.new('8ce391a...')
+### Object client use
+
+#### Setup the Application and a Collection
+```ruby
+app = Orchestrate::Application.new(api_key)
+users = app[:users]
 ```
 
-and start making requests:
+#### Store some KeyValues, List them
+```ruby
+users[:joe] = { "name" => "Joe" }           # PUTs joe, returns the input, as per Ruby convention on #[]=
+users.set(:jack, { "name" => "Jack" })      # PUTs jack, returns a KeyValue
+users.create(:jill, { "name" => "Jill" })   # PUT-If-Absent hill, returns a KeyValue
+users << { "name" => "Unknown" }            # POSTs the body, returns a KeyValue
+users.map {|user| [user.key, user.ref]}     # enumerates over ALL items in collection
+```
 
+#### Manipulate KeyValues
+```ruby
+jill = users[:jill]
+jill[:name]                                 # "Jill"
+jill[:location] = "On the Hill"
+jill.value                                  # { "name" => "Jill", "location" => "On the Hill" }
+jill.save                                   # PUT-If-Match, updates ref
+```
+
+### Method Client use
+
+#### Create a Client
 ``` ruby
-client.list(:my_collection)
+# method client
+client = Orchestrate::Client.new(api_key)
 ```
 
-## Swapping out the HTTP backend
+#### Query Collections, Keys and Values
+``` ruby
+# method client
+client.put(:users, :jane, {"name"=>"Jane"}) # PUTs jane, returns API::ItemResponse
+jack = client.get(:users, :jack)            # GETs jack, returns API::ItemResponse
+client.delete(:users, :jack, jack.ref)      # DELETE-If-Match, returns API::Response
+client.list(:users)                         # LIST users, returns API::CollectionResposne
+```
 
-This gem uses [Faraday][] for its HTTP needs -- and Faraday allows you to change the underlying HTTP client used.  It defaults to `Net::HTTP` but if you wanted to use [Typhoeus][] or [EventMachine HTTP][em-http], doing so would be easy.  Alternate Faraday backends enable using callbacks or parallel request support.
+## Swapping out the HTTP back end
 
-In your Orchestrate configuration, simply provide a `faraday` key with a block that will be called with the `Faraday::Connection` object.  You may decorate it with middleware or change the adapter as described in the Faraday README.  Examples are below.
+This gem uses [Faraday][] for its HTTP needs -- and Faraday allows you to change the underlying HTTP client used.  The Orchestrate client defaults to [net-http-persistent][nhp] for speed on repeat requests without having to resort to a compiled library.  You can easily swap in [Typhoeus][] which uses libcurl to enable fast, parallel requests, or [EventMachine HTTP][em-http] to use a non-blocking, callback-based interface.  Examples are below.
 
 You may use Faraday's `test` adapter to stub out calls to the Orchestrate API in your tests.  See `tests/test_helper.rb` and the tests in `tests/orchestrate/api/*_test.rb` for examples.
 
 [Faraday]: https://github.com/lostisland/faraday/
+[nhp]: http://docs.seattlerb.org/net-http-persistent/
 [Typhoeus]: https://github.com/typhoeus/typhoeus#readme
 [em-http]: https://github.com/igrigorik/em-http-request#readme
 
 ### Parallel HTTP requests
 
-If you're using a Faraday backend that enables parallelization, such as Typhoeus, EM-HTTP-Request, or EM-Synchrony you can use `Orchestrate::Client#in_parallel` to fire off multiple requests at once.  If your Faraday backend does not support this, the method will still work as expected, but Faraday will output a warning to STDERR and the requests will be performed in series.
+If you're using a Faraday back end that enables parallelization, such as Typhoeus, EM-HTTP-Request, or EM-Synchrony you can use `Orchestrate::Client#in_parallel` to fire off multiple requests at once.  If your Faraday back end does not support this, the method will still work as expected, but Faraday will output a warning to STDERR and the requests will be performed in series.
 
+#### method client
 ``` ruby
-client = Orchestrate::Client.new(api_key)
+client = Orchestrate::Client.new(api_key) {|f| f.adapter :typhoeus }
 
 responses = client.in_parallel do |r|
   r[:list] = client.list(:my_collection)
@@ -49,27 +82,26 @@ end
 responses[:user] = #<Orchestrate::API::ItemResponse:0x00...>
 ```
 
-### Callback Support
+#### object client
+```ruby
+app = Orchestrate::Application.new(api_key) {|f| f.adapter :typhoeus }
 
-If you're using a Faraday backend that enables callbacks, such as EM-HTTP-Request or EM-Synchrony, you may use the callback interface to designate actions to perform when the request completes.
-
-``` ruby
-response = client.list(:my_collection)
-response.finished? # false
-response.on_complete do
-  # do stuff with the response as normal
+app.in_parallel do
+  @items = app[:my_collection].lazy.take(100)
+  @user = app[:users][current_user_id]
 end
 ```
 
-If the Faraday backend adapter does not support callbacks, the block provided will be executed when `Orchestrate::Client#on_complete` is called.
+Note that values are not available inside of the `in_parallel` block.  The `r[:list]` or `@items` objects are placeholders for their future values and will be available after the `in_parallel` block returns.  Since `take` and other enumerable methods normally attempt to access the value when called, you **must** convert the `app[:my_collection]` enumerator to a lazy enumerator with #lazy.  Attempting to access the enumerator's values (for example, without using `#lazy` or by using `#any?` or `#find`) while inside the `in_parallel` block will raise an `Orchestrate::ResultsNotReady` exception.
 
+Lazy Enumerators are not available by default in Ruby 1.9.
 
 ### Using with Typhoeus
 
 Typhoeus is backed by libcurl and enables parallelization.
 
 ``` ruby
-require 'typhoeus'
+require 'orchestrate'
 require 'typhoeus/adapters/faraday'
 
 client = Orchestrate::Client.new(api_key) do |conn|
@@ -104,21 +136,26 @@ end
 
 ## Release Notes
 
-- June 24, 2014: release 0.6.3
+### July 1, 2014: release 0.7.0
+  - Fix #66 to make parallel mode work properly
+  - Switch the default Faraday adapter to the `net-http-persistent` gem, which in casual testing yields much better performance for sustained use.
+  - Introduced the object client, `Orchestrate::Application`, `Orchestrate::Collection` & `Orchestrate::KeyValue`
+
+### June 24, 2014: release 0.6.3
   - Fix #55 to handle ping responses when unauthorized
 
-- June 24, 2014: release 0.6.2
+### June 24, 2014: release 0.6.2
   - Fix #48 to remove trailing -gzip from Etag header for ref value.
-  - Custom #to_s and #inspect methods for Client, Response classes.
+  - Custom `#to_s` and `#inspect` methods for Client, Response classes.
   - Implement `If-Match` header for Client#purge
   - Implement Client#post for auto-generated keys endpoint
 
-- June 17, 2014: release 0.6.1
+### June 17, 2014: release 0.6.1
   - Fix #43 for If-None-Match on Client#put
   - Fix #46 for Client#ping
   - License changed to ASLv2
 
-- June 16, 2014: release 0.6.0
+### June 16, 2014: release 0.6.0
   - **BACKWARDS-INCOMPATIBLE** Reworked Client constructor to take API key and
     optional Faraday configuration block.  See 9045ffc for details.
   - Migrated documentation to YARD
@@ -127,10 +164,10 @@ end
   - Remove custom logger in favor of the option to use Faraday middleware.
   - Accept Time/Date objects for Timestamp arguments to Event-related methods.
 
-- May 29, 2014: release 0.5.1
+### May 29, 2014: release 0.5.1
   - Fix problem with legacy code preventing gem from loading in some environments
 
-- May 21, 2014: release 0.5.0
+### May 21, 2014: release 0.5.0
   Initial Port from @jimcar
   - Uses Faraday HTTP Library as backend, with examples of alternate adapters
   - Cleanup client method signatures

data/lib/orchestrate.rb

@@ -1,9 +1,14 @@
 require "orchestrate/api"
 require "orchestrate/client"
+require "orchestrate/application"
+require "orchestrate/collection"
+require "orchestrate/key_value"
 require "orchestrate/version"
-
 #
 # A library for supporting connections to the \Orchestrate API.
 #
 module Orchestrate
+
+  # If you attempt to enumerate over results in an in_parallel block
+  class ResultsNotReady < StandardError; end
 end

data/lib/orchestrate/api.rb

@@ -2,6 +2,7 @@ require "orchestrate"
 
 module Orchestrate
 
+  # Namespace for concerns related to the Orchestrate API
   module API
   end
 

data/lib/orchestrate/api/errors.rb

@@ -73,7 +73,6 @@ module Orchestrate::API
   # @example This is the example provided to me by the Orchestrate team:
   #   client.put(:test, :first, { "count" => 0 }) # establishes 'count' as a Long
   #   client.put(:test, :second, { "count" => "none" }) # 'count' is not a Long
-  #
   class IndexingConflict < RequestError
     @status = 409
     @code   = 'indexing_conflict'
@@ -94,16 +93,19 @@ module Orchestrate::API
   # indicates a 500-class response, the problem is on Orchestrate's end
   class ServiceError < BaseError; end
 
+  # An error occurred while validating authentication
   class SecurityAuthentication < ServiceError
     @status = 500
     @code = 'security_authentication'
   end
 
+  # An error occurred while searching
   class SearchIndexNotFound < ServiceError
     @status = 500
     @code = 'search_index_not_found'
   end
 
+  # An unknown 500-class error occurred.
   class InternalError < ServiceError
     @status = 500
     @code = 'internal_error'

data/lib/orchestrate/api/helpers.rb

@@ -1,4 +1,5 @@
 module Orchestrate::API
+  # Some convenience methods for constructing API requests or reading responses.
   module Helpers
 
     extend self

data/lib/orchestrate/api/response.rb

@@ -1,5 +1,6 @@
 require 'forwardable'
 require 'webrick'
+require 'json' unless defined?(::JSON)
 
 module Orchestrate::API
 
@@ -7,7 +8,7 @@ module Orchestrate::API
   class Response
 
     extend Forwardable
-    def_delegators :@response, :status, :body, :headers, :success?, :finished?, :on_complete
+    def_delegators :@response, :status, :headers, :success?, :finished?, :on_complete
     # @!attribute [r] status
     #   @return [Integer] The HTTP Status code of the response.
     # @!attribute [r] body
@@ -30,14 +31,25 @@ module Orchestrate::API
     # @return [Orchestrate::Client] The client used to generate the response.
     attr_reader :client
 
+    # @return [String, Hash] The response body from Orchestrate
+    attr_reader :body
+
     # Instantiate a new Respose
     # @param faraday_response [Faraday::Response] The Faraday response object.
     # @param client [Orchestrate::Client] The client used to generate the response.
     def initialize(faraday_response, client)
       @client = client
       @response = faraday_response
-      @request_id = headers['X-Orchestrate-Req-Id']
-      @request_time = Time.parse(headers['Date'])
+      @response.on_complete do
+        @request_id = headers['X-Orchestrate-Req-Id'] if headers['X-Orchestrate-Req-Id']
+        @request_time = Time.parse(headers['Date']) if headers['Date']
+        if headers['Content-Type'] =~ /json/ && !@response.body.strip.empty?
+          @body = JSON.parse(@response.body)
+        else
+          @body = @response.body
+        end
+        handle_error_response unless success?
+      end
     end
 
     # @!visibility private
@@ -46,6 +58,23 @@ module Orchestrate::API
     end
     alias :inspect :to_s
 
+    private
+    def handle_error_response
+      err_type = if body && body['code']
+        ERRORS.find {|err| err.status == status && err.code == body['code'] }
+      else
+        errors = ERRORS.select {|err| err.status == status}
+        errors.length == 1 ? errors.first : nil
+      end
+      if err_type
+        raise err_type.new(self)
+      elsif status < 500
+        raise RequestError.new(self)
+      else
+        raise ServiceError.new(self)
+      end
+    end
+
   end
 
   # A generic response for a single entity (K/V, Ref, Event)
@@ -60,8 +89,10 @@ module Orchestrate::API
     # (see Orchestrate::API::Response#initialize)
     def initialize(faraday_response, client)
       super(faraday_response, client)
-      @location = headers['Content-Location'] || headers['Location']
-      @ref = headers.fetch('Etag','').gsub('"','').sub(/-gzip$/,'')
+      @response.on_complete do
+        @location = headers['Content-Location'] || headers['Location']
+        @ref = headers.fetch('Etag','').gsub('"','').sub(/-gzip$/,'')
+      end
     end
 
   end
@@ -87,11 +118,13 @@ module Orchestrate::API
     # (see Orchestrate::API::Response#initialize)
     def initialize(faraday_response, client)
       super(faraday_response, client)
-      @count = body['count']
-      @total_count = body['total_count']
-      @results = body['results']
-      @next_link = body['next']
-      @prev_link = body['prev']
+      @response.on_complete do
+        @count = body['count']
+        @total_count = body['total_count']
+        @results = body['results']
+        @next_link = body['next']
+        @prev_link = body['prev']
+      end
     end
 
     # Retrieves the next page of results, if available

data/lib/orchestrate/application.rb

@@ -0,0 +1,55 @@
+module Orchestrate
+
+  # Applications in Orchestrate are the highest level of your project.
+  class Application
+
+    # @return [String] The API key provided
+    attr_reader :api_key
+
+    # @return [Orchestrate::Client] The client tied to this application.
+    attr_reader :client
+
+    # Instantiate a new Application
+    # @param client_or_api_key [#to_s] The API key for your Orchestrate Application.
+    # @param client_or_api_key [Orchestrate::Client] A client instantiated with an Application and Faraday setup.
+    # @yieldparam [Faraday::Connection] connection Setup for the Faraday connection.
+    # @return Orchestrate::Application
+    def initialize(client_or_api_key, &client_setup)
+      if client_or_api_key.kind_of?(Orchestrate::Client)
+        @client = client_or_api_key
+        @api_key = client.api_key
+      else
+        @api_key = client_or_api_key
+        @client = Client.new(api_key, &client_setup)
+      end
+      client.ping
+    end
+
+    # Accessor for Collections
+    # @param collection_name [#to_s] The name of the collection.
+    # @return Orchestrate::Collection
+    def [](collection_name)
+      Collection.new(self, collection_name)
+    end
+
+    # Performs requests in parallel.  Requires using a Faraday adapter that supports parallel requests.
+    # @yieldparam accumulator [Hash] A place to store the results of the parallel responses.
+    # @example Performing three requests at once
+    #   responses = app.in_parallel do |r|
+    #     r[:some_items] = app[:site_globals].lazy
+    #     r[:user]       = app[:users][current_user_key]
+    #     r[:user_feed]  = app.client.list_events(:users, current_user_key, :notices)
+    #   end
+    # @see README See the Readme for more examples.
+    def in_parallel(&block)
+      client.in_parallel(&block)
+    end
+
+    # @return a pretty-printed representation of the application.
+    def to_s
+      "#<Orchestrate::Application api_key=#{api_key[0..7]}...>"
+    end
+    alias :inspect :to_s
+
+  end
+end

data/lib/orchestrate/client.rb

@@ -1,8 +1,9 @@
 require 'faraday'
-require 'faraday_middleware'
 
 module Orchestrate
 
+  # The "method client": A single entry point to an Orchestrate Application,
+  # with methods for accessing each API endpoint.
   class Client
 
     # @return [String] The API key provided
@@ -23,15 +24,12 @@ module Orchestrate
       @api_key = api_key
       @faraday_configuration = block
       @http = Faraday.new("https://api.orchestrate.io") do |faraday|
-        block = lambda{|f| f.adapter Faraday.default_adapter } unless block
+        block = lambda{|f| f.adapter :net_http_persistent } unless block
         block.call faraday
 
         # faraday seems to want you do specify these twice.
         faraday.request :basic_auth, api_key, ''
         faraday.basic_auth api_key, ''
-
-        # parses JSON responses
-        faraday.response :json, :content_type => /\bjson$/
       end
     end
 
@@ -386,7 +384,7 @@ module Orchestrate
       headers['User-Agent'] = "ruby/orchestrate/#{Orchestrate::VERSION}"
       headers['Accept'] = 'application/json' if method == :get
 
-      response = http.send(method) do |request|
+      http_response = http.send(method) do |request|
         request.url path, query_string
         if [:put, :post].include?(method)
           headers['Content-Type'] = 'application/json'
@@ -395,25 +393,8 @@ module Orchestrate
         headers.each {|header, value| request[header] = value }
       end
 
-      if ! response.success?
-        err_type = if response.body
-          API::ERRORS.find do |err|
-            err.status == response.status && err.code == response.body['code']
-          end
-        else
-          errors = API::ERRORS.select {|err| err.status == response.status }
-          errors.length == 1 ? errors.first : nil
-        end
-        if err_type
-          raise err_type.new(response)
-        elsif response.status >= 500
-          raise API::ServiceError.new(response)
-        elsif response.status >= 400
-          raise API::RequestError.new(response)
-        end
-      end
       response_class = options.fetch(:response, API::Response)
-      response_class.new(response, self)
+      response_class.new(http_response, self)
     end
   end