orchestrate 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: de6f6df430a397bac87d65a6c13679705f5de9ab
-  data.tar.gz: 7bc42ee2220a8dec27c24689922a3989a9e03f25
+  metadata.gz: 896e56c8c6989701ac79594cb43f20cc16e64947
+  data.tar.gz: a508bdaa4ee26fb3effc1aa70718439f40f026c2
 SHA512:
-  metadata.gz: bbb8f4f4a9f18f5f1d245eaef876e7d726ca1009a23fab327de7d860742dc8fbb3174afb103a66c6fe4909fbfdc6273b8e2f205de9ab532e97d09b25f1a80470
-  data.tar.gz: 8d2a0dd9bc39b57c51f0b4058ed0980062d76bf1cae40c94a51ed2eb479f696cb52825a2a3cd139cdf0629c902701259e94119359de3436ad928a5e66f12b687
+  metadata.gz: 2b5eb9d59dabc325fa6c694bf5770b32bf1b002e03395efa4429737aa115efe9219df7e8d276a7c2522d2bdaad4dd7d04d3a14fe1507216211e3857ccf5343c1
+  data.tar.gz: 37e4a6d198dc537124d01efd46be0bf90e78a140e6c837f61039c94ac5403f9272ff50a91eb0ae8ba22a8b77ad90ae9ca089976cff3fdf8c0351c1edc52ddc51

data/.yardopts

@@ -0,0 +1 @@
+-m markdown - LICENSE

data/README.md

@@ -11,13 +11,7 @@ Ruby client interface for the [Orchestrate.io](http://orchestrate.io) REST API.
 Provide your API key:
 
 ``` ruby
-Orchestrate::Configuration.api_key = '8ce391a...'
-```
-
-Create a client:
-
-``` ruby
-client = Orchestrate::Client.new
+client = Orchestrate::Client.new('8ce391a...')
 ```
 
 and start making requests:
@@ -43,7 +37,7 @@ You may use Faraday's `test` adapter to stub out calls to the Orchestrate API in
 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.
 
 ``` ruby
-client = Orchestrate::Client.new
+client = Orchestrate::Client.new(api_key)
 
 responses = client.in_parallel do |r|
   r[:list] = client.list(:my_collection)
@@ -52,7 +46,7 @@ responses = client.in_parallel do |r|
 end
 # will return when all requests have completed
 
-responses[:user] = #<Faraday::Response:0x00...>
+responses[:user] = #<Orchestrate::API::ItemResponse:0x00...>
 ```
 
 ### Callback Support
@@ -60,7 +54,6 @@ responses[:user] = #<Faraday::Response:0x00...>
 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
-client = Orchestrate::Client.new
 response = client.list(:my_collection)
 response.finished? # false
 response.on_complete do
@@ -79,9 +72,8 @@ Typhoeus is backed by libcurl and enables parallelization.
 require 'typhoeus'
 require 'typhoeus/adapters/faraday'
 
-Orchestrate.configure do |config|
-  config.faraday = {|f| f.adapter :typhoeus }
-  config.api_key = "my_api_key"
+client = Orchestrate::Client.new(api_key) do |conn|
+  conn.adapter :typhoeus
 end
 ```
 
@@ -93,23 +85,39 @@ EM-HTTP-Request is an HTTP client for Event Machine.  It enables callback suppor
 ``` ruby
 require 'em-http-request'
 
-Orchestrate.configure do |config|
-  config.faraday = {|f| f.adapter :em_http }
-  config.api_key = "my_api_key"
+client = Orchestrate::Client.new(api_key) do |conn|
+  conn.adapter :em_http
 end
 ```
 
-### Using with EM-Syncrony
+### Using with EM-Synchrony
 
 EM-Synchrony is a collection of utility classes for EventMachine to help untangle evented code.  It enables parallelization.
 
 ``` ruby
 require 'em-synchrony'
 
-Orchestrate.configure do |config|
-  config.faraday = {|f| f.adapter :em_synchrony }
-  config.api_key = "my_api_key"
+client = Orchestrate::Client.new(api_key) do |conn|
+  conn.adapter = f.adapter :em_synchrony
 end
 ```
 
+## Release Notes
+- June 12, 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
+  - Provide basic response wrappers specific to generic request types.
+  - Raise Exceptions on error response from Orchestrate API.
+  - 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
+  - Fix problem with legacy code preventing gem from loading in some environments
+
+- 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/api/errors.rb

@@ -1,57 +1,119 @@
 module Orchestrate::API
 
-  # Not used. But it does contain nice summary of orchestrate.io api errors.
-  #
-  module Error
-    def errors
-      @@errors ||= [
-        { :status => 400,
-          :code   => :api_bad_request,
-          :desc   => 'The API request is malformed.'
-        },
-        { :status => 500,
-          :code   => :security_authentication,
-          :desc   => 'An error occurred while trying to authenticate.'
-        },
-        { :status => 401,
-          :code   => :security_unauthorized,
-          :desc   => 'Valid credentials are required.'
-        },
-        { :status => 400,
-          :code   => :search_param_invalid,
-          :desc   => 'A provided search query param is invalid.'
-        },
-        { :status => 500,
-          :code   => :search_index_not_found,
-          :desc   => 'Index could not be queried for this application.'
-        },
-        { :status => 500,
-          :code   => :internal_error,
-          :desc   => 'Internal Error.'
-        },
-        { :status => 404,
-          :code   => :items_not_found,
-          :desc   => 'The requested items could not be found.'
-        },
-        { :status => 412,
-          :code   => :item_version_mismatch,
-          :desc   => 'The version of the item does not match.'
-        },
-        { :status => 412,
-          :code   => :item_already_present,
-          :desc   => 'The item is already present.'
-        },
-        { :status => 400,
-          :code   => :item_ref_malformed,
-          :desc   => 'The provided Item Ref is malformed.'
-        },
-        { :status => 409,
-          :code   => :indexing_conflict,
-          :desc   => 'The item has been stored but conflicts were detected ' +
-                     'when indexing. Conflicting fields have not been indexed.'
-        },
-    ]
+  # Base class for Errors from Orchestrate.
+  class BaseError < StandardError
+    # class-level attr-reader for the error's response code.
+    # @return [Integer] Status code for error.
+    def self.status; @status; end
+
+    # class-level attr-reader for the error's code.
+    # @return [String] API's error code.
+    def self.code; @code; end
+
+    # @return [Faraday::Response] The response that caused the error.
+    attr_reader :response
+
+    # @param response [Faraday::Response] The response that caused the error.
+    def initialize(response)
+      @response = response
+      if response.headers['Content-Type'] == 'application/json'
+        super(response.body['message'])
+      else
+        super(response.body)
+      end
     end
   end
 
-end
+  # indicates a 4xx-class response, and the problem was with the request.
+  class RequestError < BaseError; end
+
+  # The client provided a malformed request.
+  class BadRequest < RequestError
+    @status = 400
+    @code   = 'api_bad_request'
+  end
+
+  # The client provided a malformed search query.
+  class MalformedSearch < RequestError
+    @status = 400
+    @code   = 'search_query_malformed'
+  end
+
+  # The client provided a ref value that is not valid.
+  class MalformedRef < RequestError
+    @status = 400
+    @code   = 'item_ref_malformed'
+  end
+
+  # When a Search Parameter is recognized, but not valid.  For example, a limit
+  # exceeding 100.
+  class InvalidSearchParam < RequestError
+    @status = 400
+    @code   = 'search_param_invalid'
+  end
+
+  # A Valid API key was not provided.
+  class Unauthorized < RequestError
+    @status = 401
+    @code   = 'security_unauthorized'
+  end
+
+  # Something the user expected to be there was not.
+  class NotFound < RequestError
+    @status = 404
+    @code   = 'items_not_found'
+  end
+
+  # When a new collection is created by its first KV document, a schema is created
+  # for indexing, including the types of the values for the KV document.  This error
+  # will occur when a new document provides values with different types.  Values with
+  # unexpected types will not be indexed.  Since search is an implicit feature
+  # of the service, this is an error and worth raising an exception over.
+  #
+  # @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'
+  end
+
+  # Client provided a ref that is not the current ref.
+  class VersionMismatch < RequestError
+    @status = 412
+    @code   = 'item_version_mismatch'
+  end
+
+  # Client provided "If-None-Match", but something matched.
+  class AlreadyPresent < RequestError
+    @status = 412
+    @code   = 'item_already_present'
+  end
+
+  # indicates a 500-class response, the problem is on Orchestrate's end
+  class ServiceError < BaseError; end
+
+  class SecurityAuthentication < ServiceError
+    @status = 500
+    @code = 'security_authentication'
+  end
+
+  class SearchIndexNotFound < ServiceError
+    @status = 500
+    @code = 'search_index_not_found'
+  end
+
+  class InternalError < ServiceError
+    @status = 500
+    @code = 'internal_error'
+  end
+
+  # The full complement of Error classes.
+  ERRORS=[ BadRequest, MalformedSearch, MalformedRef, InvalidSearchParam,
+           Unauthorized, NotFound, IndexingConflict,
+           VersionMismatch, AlreadyPresent,
+           SecurityAuthentication, SearchIndexNotFound, InternalError
+          ]
+
+end

data/lib/orchestrate/api/helpers.rb

@@ -0,0 +1,48 @@
+module Orchestrate::API
+  module Helpers
+
+    extend self
+
+    # Suffixes a params hash for range bounds with the given type.  Modifies the hash in-place.
+    # @param suffix [String] the suffix for the range keys
+    # @param params [Hash{Symbol=>Value}]
+    # @option params :start The inclusive start of the range
+    # @option params :after The exclusive start of the range
+    # @option params :before The exclusive end of the range
+    # @option params :end The inclusive end of the range
+    # @example Transforming an Event Range
+    #   keys = { start: Value }
+    #   Orchestrate::Helpers.range_keys!('event', keys)
+    #   keys #=> { startEvent: Value }
+    def range_keys!(suffix, params)
+      suffix = suffix.capitalize
+      [:start, :end, :before, :after].each do |key|
+        if params[key]
+          params["#{key}#{suffix}"] = params[key]
+          params.delete(key)
+        end
+      end
+    end
+
+    # Coerces a Date or Time object to Integer Milliseconds, per the Timestamps documentation:
+    # http://orchestrate.io/docs/api/#events/timestamps
+    # If provided a value other than Date or Time, will return it untouched.
+    # @overload timestamp(time)
+    #   @param time [Date, Time] The timestamp in Date or Time form.
+    #   @return [Integer] The timestamp in integer milliseconds since epoch.
+    def timestamp(time)
+      time = time.to_time if time.kind_of?(Date)
+      time = (time.getutc.to_f * 1000).to_i if time.kind_of?(Time)
+      time
+    end
+
+
+    # Formats the provided 'ref' to be quoted per API specification.
+    # @param ref [String] The ref desired.
+    # @return [String] The ref, quoted.  If already quoted, does not double-quote.
+    def format_ref(ref)
+      "\"#{ref.gsub(/"/,'')}\""
+    end
+
+  end
+end

data/lib/orchestrate/api/response.rb

@@ -0,0 +1,111 @@
+require 'forwardable'
+require 'webrick'
+
+module Orchestrate::API
+
+  # A generic response from the API.
+  class Response
+
+    extend Forwardable
+    def_delegators :@response, :status, :body, :headers, :success?, :finished?, :on_complete
+    # @!attribute [r] status
+    #   @return [Integer] The HTTP Status code of the response.
+    # @!attribute [r] body
+    #   @return [Hash, String] The response body, de-serialized from JSON.
+    # @!attribute [r] headers
+    #   @return [Hash{String => String}] The response headers
+    # @!method success?()
+    #   @return [true, false] If the response is 1xx-3xx class response or a 4xx-5xx class response.
+    # @!method finished?()
+    #   @return [true, false] If the response is finished or not.
+    # @!method on_complete()
+    #   @yield [block] A block to be called when the response has completed.
+
+    # @return [String] The Orchestrate API Request ID.  For use when troubleshooting.
+    attr_reader :request_id
+
+    # @return [Time] The time at which the response was made.
+    attr_reader :request_time
+
+    # @return [Orchestrate::Client] The client used to generate the response.
+    attr_reader :client
+
+    # 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'])
+    end
+
+  end
+
+  # A generic response for a single entity (K/V, Ref, Event)
+  class ItemResponse < Response
+
+    # @return [String] The 'Location' of the item.
+    attr_reader :location
+
+    # @return [String] The canonical 'ref' of the item.
+    attr_reader :ref
+
+    # (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('"','')
+    end
+  end
+
+  # A generic response for a collection of entities (K/V, Refs, Events, Search)
+  class CollectionResponse < Response
+
+    # @return [Integer] The number of items in this response
+    attr_reader :count
+
+    # @return [Integer, nil] If provided, the number of total items for this collection
+    attr_reader :total_count
+
+    # @return [Array] The items in the response.
+    attr_reader :results
+
+    # @return [String] The location for the next page of results
+    attr_reader :next_link
+
+    # @return [String] The location for the previous page of results
+    attr_reader :prev_link
+
+    # (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']
+    end
+
+    # Retrieves the next page of results, if available
+    # @return [nil, Orchestrate::API::CollectionResponse]
+    def next_results
+      fire_request(next_link)
+    end
+
+    # Retrieves the previous page of results, if available
+    # @return [nil, Orchestrate::API::CollectionResponse]
+    def previous_results
+      fire_request(prev_link)
+    end
+
+    private
+    def fire_request(link)
+      return nil unless link
+      uri = URI(link)
+      params = WEBrick::HTTPUtils.parse_query(uri.query)
+      path = uri.path.split("/")[2..-1]
+      @client.send_request(:get, path, { query: params, response: self.class })
+    end
+  end
+end

data/lib/orchestrate/api.rb

@@ -2,13 +2,11 @@ require "orchestrate"
 
 module Orchestrate
 
-  #
-  # Ruby gem +orchestrate-api+ provides an interface to the
-  # [Orchestrate](http://orchestrate.io) API.
-  #
-  # The Client class is used to setup the client and make HTTP requests.
-  #
   module API
   end
 
 end
+
+require_relative 'api/response'
+require_relative 'api/errors'
+require_relative 'api/helpers'