my_john_deere_api 2.3.4 → 2.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b6ea750328ecdcb653d61bbadf19ab4ab23ef2fb712963bda1351736ffedb37
-  data.tar.gz: '059eab2d2bbb7d8d716bde8f61f5ce935c46039dfbe6c82b933041e4f90fd072'
+  metadata.gz: ba69ef151796a688f69eba0f6a396d277baa893aa9e589922f2f2eac7b4e3a6a
+  data.tar.gz: e0539d88ae84a348113be06e9f81299b64a5c74598428e9d2a33ec00b0b49584
 SHA512:
-  metadata.gz: d9e2285aa182a610b45b757707a26edad1e2ae342ce7ba62609c6a486f247fe3beaaad9e7df39a2ce2077b099b1a31edd53b1732fcdcde1d5b7253da648a7bdb
-  data.tar.gz: a9fad3831aa447433ee0969eb839d8e21245a29e955b1602ba560b75a989c8737c10c1489474d3982a7f71398407adfb9900968a240fd3cd677b05990e9dc3de
+  metadata.gz: 9a40c8720b6e44da21bb5c2d0247055cf8b4f7d04e5b6d9e5d6db03778af368e64b5d2ba375aa02aa671aebdbf3d64d87c8090beb958bb7dc83ef5b1da52196e
+  data.tar.gz: 77bac482b0518e59b534d1916b9155c2a59e75308cc71e93354c9a3d071fa10c35362ee836f3eb456b15f612b73d503f06c735d7af942d220415a39c6943c606

data/README.md

@@ -24,6 +24,7 @@ without having to code your own oAuth process, API requests, and pagination.
   * [Organizations](#organizations)
   * [Assets](#assets)
   * [Asset Locations](#asset-locations)
+  * [Fields](#fields)
 * [Direct API Requests](#direct-api-requests)
   * [GET](#get)
   * [POST](#post)
@@ -346,7 +347,7 @@ organization.links
 # =>  {
 #       'self' => 'https://sandboxapi.deere.com/platform/organizations/1234',
 #       'machines' => 'https://sandboxapi.deere.com/platform/organizations/1234/machines',
-#       'wdtCapableMachines' => 'ttps://sandboxapi.deere.com/platform/organizations/1234/machines?capability=wdt'   
+#       'wdtCapableMachines' => 'https://sandboxapi.deere.com/platform/organizations/1234/machines?capability=wdt'   
 #     }
 
 organization.assets
@@ -558,6 +559,115 @@ Note that locations are called "Asset Locations" in John Deere, but we call the
 `asset.locations`, for brevity.
 
 
+### [Fields](https://developer.deere.com/#!documentation&doc=myjohndeere%2FfieldsADS.htm)
+
+Handles an organization's fields. Field collections support the following methods:
+
+* all
+* count
+* first
+* find(field\_id)
+
+An individual field supports the following methods and associations:
+
+* id
+* name
+* archived?
+* links
+* flags (collection of this field's flags)
+
+The `count` method only requires loading the first page of results, so it's a relatively cheap call. On the other hand,
+`all` forces the entire collection to be loaded from John Deere's API, so use with caution. Fields can be
+created via the API, but there is no `create` method on this collection yet.
+
+```ruby
+organization.fields
+# => collection of fields under this organization
+
+organization.fields.count
+# => 15
+
+organization.fields.first
+# => an individual field object
+
+field = organization.fields.find(1234)
+# => an individual field object, fetched by ID
+
+field.name
+# => 'Smith Field'
+
+field.archived?
+# => false
+
+field.links
+# => a hash of API urls related to this field
+
+field.flags
+# => collection of flags belonging to this field
+```
+
+
+### [Flags](https://developer.deere.com/#!documentation&doc=.%2Fmyjohndeere%2Fflags.htm)
+
+Handles a field's flags. Flag collections support the following methods. Note, John Deere does not provide an endpoint to retrieve a specific flag by id:
+
+* all
+* count
+* first
+
+An individual flag supports the following methods and associations:
+
+* id
+* notes
+* geometry
+* archived?
+* proximity\_alert\_enabled?
+* links
+
+The `count` method only requires loading the first page of results, so it's a relatively cheap call. On the other hand,
+`all` forces the entire collection to be loaded from John Deere's API, so use with caution. Flags can be
+created via the API, but there is no `create` method on this collection yet.
+
+```ruby
+field.flags
+# => collection of flags under this field
+
+field.flags.count
+# => 15
+
+flag = field.flags.first
+# => an individual flag object
+
+flag.notes
+# => 'A big rock on the left after entering the field'
+
+flag.geometry
+# =>  a GeoJSON formatted hash, for example:
+#     {
+#       "type"=>"Feature",
+#       "geometry"=>{
+#         "geometries"=>[
+#             {
+#               "coordinates"=>[-95.123456, 40.123456], 
+#               "type"=>"Point"
+#             }
+#           ],
+#         "type"=>"GeometryCollection"
+#       }
+#     }
+
+
+field.archived?
+# => false
+
+field.proximity_alert_enabled?
+# => true
+
+field.links
+# => a hash of API urls related to this flag
+```
+
+
 ## Direct API Requests
 
 While the goal of the client is to eliminate the need to make/interpret calls to the John Deere API, it's important

data/lib/my_john_deere_api.rb

@@ -13,4 +13,5 @@ module MyJohnDeereApi
   autoload :Validators,     'my_john_deere_api/validators'
 
   require 'my_john_deere_api/errors'
+  require 'my_john_deere_api/net_http_retry'
 end

data/lib/my_john_deere_api/client.rb

@@ -4,10 +4,11 @@ module MyJohnDeereApi
     include Helpers::CaseConversion
 
     attr_accessor :contribution_definition_id
-    attr_reader :api_key, :api_secret, :access_token, :access_secret
+    attr_reader :api_key, :api_secret, :access_token, :access_secret, :http_retry_options
 
     DEFAULTS = {
-      environment: :live
+      environment: :live,
+      http_retry: {}
     }
 
     ##
@@ -37,6 +38,7 @@ module MyJohnDeereApi
 
       self.environment = options[:environment]
       @contribution_definition_id = options[:contribution_definition_id]
+      @http_retry_options = options[:http_retry]
     end
 
     ##
@@ -45,7 +47,15 @@ module MyJohnDeereApi
 
     def accessor
       return @accessor if defined?(@accessor)
-      @accessor = OAuth::AccessToken.new(consumer.user_get, access_token, access_secret)
+
+      @accessor = NetHttpRetry::Decorator.new(
+        OAuth::AccessToken.new(
+          consumer.user_get,
+          access_token,
+          access_secret
+        ),
+        http_retry_options
+      )
     end
 
     ##

data/lib/my_john_deere_api/net_http_retry.rb

@@ -0,0 +1,4 @@
+require 'my_john_deere_api/net_http_retry/decorator'
+
+require 'my_john_deere_api/net_http_retry/invalid_response_error'
+require 'my_john_deere_api/net_http_retry/max_retries_exceeded_error'

data/lib/my_john_deere_api/net_http_retry/decorator.rb

@@ -0,0 +1,62 @@
+module MyJohnDeereApi
+  module NetHttpRetry
+    class Decorator
+      attr_reader :object, :request_methods, :retry_delay_exponent, :max_retries, :retry_codes, :valid_codes
+
+      DEFAULTS = {
+        request_methods:      [:get, :post, :put, :delete],
+        retry_delay_exponent: 2,
+        max_retries: 12,
+        retry_codes: ['429', '503'],
+        valid_codes: ['200', '201', '204'],
+      }
+
+      def initialize(object, options={})
+        @object = object
+
+        # defaults that can be used as-is
+        [:request_methods, :retry_delay_exponent, :max_retries].each do |option|
+          instance_variable_set(:"@#{option}", options[option] || DEFAULTS[option])
+        end
+
+        # defaults that require casting as string arrays
+        [:retry_codes, :valid_codes].each do |option|
+          instance_variable_set(:"@#{option}", (options[option] || DEFAULTS[option]).map(&:to_s))
+        end
+      end
+
+      def request(method_name, *args)
+        retries = 0
+        result = object.send(method_name, *args)
+
+        while retry_codes.include?(result.code)
+          if retries >= max_retries
+            raise MaxRetriesExceededError.new(method_name, "#{result.code} #{result.message}")
+          end
+
+          delay = [result['retry-after'].to_i, retry_delay_exponent ** retries].max
+          sleep(delay)
+
+          result = object.send(method_name, *args)
+          retries += 1
+        end
+
+        unless valid_codes.include?(result.code)
+          raise InvalidResponseError.new(result)
+        end
+
+        result
+      end
+
+      private
+
+      def method_missing(method_name, *args, &block)
+        if request_methods.include?(method_name)
+          request(method_name, *args)
+        else
+          object.send(method_name, *args, &block)
+        end
+      end
+    end
+  end
+end

data/lib/my_john_deere_api/net_http_retry/invalid_response_error.rb

@@ -0,0 +1,23 @@
+module MyJohnDeereApi
+  module NetHttpRetry
+    ##
+    # This error is used when a single request has exceeded
+    # the number of retries allowed by NetHttpRetry::Decorator::MAX_RETRIES.
+
+    class InvalidResponseError < StandardError
+
+      ##
+      # argument is a string which describes the attempted request
+
+      def initialize(response)
+        message = {
+          code: response.code,
+          message: response.message,
+          body: response.body,
+        }.to_json
+
+        super(message)
+      end
+    end
+  end
+end

data/lib/my_john_deere_api/net_http_retry/max_retries_exceeded_error.rb

@@ -0,0 +1,20 @@
+module MyJohnDeereApi
+  module NetHttpRetry
+    ##
+    # This error is used when a single request has exceeded
+    # the number of retries allowed by NetHttpRetry::Decorator::MAX_RETRIES.
+
+    class MaxRetriesExceededError < StandardError
+
+      ##
+      # argument is a string which describes the attempted request
+
+      def initialize(request_method, response_message)
+        message = "Max retries exceeded for #{request_method.to_s.upcase} " +
+                  "request: #{response_message}"
+
+        super(message)
+      end
+    end
+  end
+end

data/lib/my_john_deere_api/version.rb

@@ -1,3 +1,3 @@
 module MyJohnDeereApi
-  VERSION='2.3.4'
+  VERSION='2.5.0'
 end

data/test/lib/my_john_deere_api/client_test.rb

@@ -6,7 +6,7 @@ describe 'MyJohnDeereApi::Client' do
     assert_equal 'thisIsATest', client.send(:camelize, :this_is_a_test)
   end
 
-  describe '#initialize(api_key, api_secret)' do
+  describe '#initialize(api_key, api_secret, options={})' do
     it 'sets the api key/secret' do
       client = JD::Client.new(api_key, api_secret)
 
@@ -35,6 +35,23 @@ describe 'MyJohnDeereApi::Client' do
       client = JD::Client.new(api_key, api_secret, contribution_definition_id: contribution_definition_id)
       assert_equal contribution_definition_id, client.contribution_definition_id
     end
+
+    it 'accepts a list of parameters for NetHttpRetry' do
+      custom_retries = JD::NetHttpRetry::Decorator::DEFAULTS[:max_retries] + 10
+
+      VCR.use_cassette('catalog') do
+        new_client = JD::Client.new(
+          api_key,
+          api_secret,
+          contribution_definition_id: contribution_definition_id,
+          environment: :sandbox,
+          access: [access_token, access_secret],
+          http_retry: {max_retries: custom_retries}
+        )
+
+        assert_equal custom_retries, new_client.accessor.max_retries
+      end
+    end
   end
 
   describe '#contribution_definition_id' do
@@ -130,7 +147,7 @@ describe 'MyJohnDeereApi::Client' do
 
     it 'sends the request' do
       response = VCR.use_cassette('put_asset') { client.put("/assets/#{asset_id}", attributes) }
-      puts "HASH!! #{response.inspect}" if response.is_a?(Hash)
+
       assert_equal '204', response.code
       assert_equal 'No Content', response.message
     end
@@ -199,7 +216,7 @@ describe 'MyJohnDeereApi::Client' do
 
   describe '#accessor' do
     it 'returns an object that can make user-specific requests' do
-      assert_kind_of OAuth::AccessToken, accessor
+      assert_kind_of JD::NetHttpRetry::Decorator, accessor
       assert_kind_of OAuth::Consumer, accessor.consumer
       assert_equal access_token, accessor.token
       assert_equal access_secret, accessor.secret

data/test/lib/my_john_deere_api/net_http_retry/decorator_test.rb

@@ -0,0 +1,208 @@
+require 'support/helper'
+
+describe 'JD::NetHttpRetry::Decorator' do
+  REQUESTS = {
+    get:    '/',
+    post:   '/organizations/000000/assets',
+    put:    '/assets/00000000-0000-0000-0000-000000000000',
+    delete: '/assets/00000000-0000-0000-0000-000000000000'
+  }
+
+  REQUEST_METHODS = REQUESTS.keys
+
+  let(:klass) { JD::NetHttpRetry::Decorator }
+  let(:object) { klass.new(mock, options) }
+
+  let(:options) do
+    {
+      request_methods: request_methods,
+      retry_delay_exponent: retry_delay_exponent,
+      max_retries: max_retries,
+      retry_codes: retry_codes,
+      valid_codes: valid_codes
+    }
+  end
+
+  let(:request_methods) { nil }
+  let(:retry_delay_exponent) { nil }
+  let(:max_retries) { nil }
+  let(:retry_codes) { nil }
+  let(:valid_codes) { nil }
+
+  let(:retry_values) { [13, 17, 19, 23] }
+  let(:exponential_retries) { (0..klass::DEFAULTS[:max_retries]-1).map{|i| 2 ** i} }
+
+  it 'wraps a "net-http"-responsive object' do
+    assert_kind_of OAuth::AccessToken, accessor.object
+  end
+
+  describe '#initialize' do
+    describe 'when request methods are specified' do
+      let(:request_methods) { [:banana, :fana, :fofana] }
+
+      it 'uses the supplied values' do
+        assert_equal request_methods, object.request_methods
+      end
+    end
+
+    describe 'when request methods are not specified' do
+      it 'uses the default values' do
+        assert_equal klass::DEFAULTS[:request_methods], object.request_methods
+      end
+    end
+
+    describe 'when retry_delay_exponent is specified' do
+      let(:retry_delay_exponent) { 42 }
+
+      it 'uses the supplied value' do
+        assert_equal retry_delay_exponent, object.retry_delay_exponent
+      end
+    end
+
+    describe 'when retry_delay_exponent is not specified' do
+      it 'uses the default value' do
+        assert_equal klass::DEFAULTS[:retry_delay_exponent], object.retry_delay_exponent
+      end
+    end
+
+    describe 'when max_retries is specified' do
+      let(:max_retries) { 42 }
+
+      it 'uses the supplied value' do
+        assert_equal max_retries, object.max_retries
+      end
+    end
+
+    describe 'when max_retries is not specified' do
+      it 'uses the default value' do
+        assert_equal klass::DEFAULTS[:max_retries], object.max_retries
+      end
+    end
+
+    describe 'when retry_codes are specified' do
+      let(:retry_codes) { ['200', '201'] }
+
+      it 'uses the supplied values' do
+        assert_equal retry_codes, object.retry_codes
+      end
+    end
+
+    describe 'when retry_codes are specified as integers' do
+      let(:retry_codes) { [200, 201] }
+
+      it 'uses the stringified versions of the supplied values' do
+        assert_equal retry_codes.map(&:to_s), object.retry_codes
+      end
+    end
+
+    describe 'when retry_codes are not specified' do
+      it 'uses the default values' do
+        assert_equal klass::DEFAULTS[:retry_codes], object.retry_codes
+      end
+    end
+
+    describe 'when valid_codes are specified' do
+      let(:valid_codes) { ['123', '234'] }
+
+      it 'uses the supplied values' do
+        assert_equal valid_codes, object.valid_codes
+      end
+    end
+
+    describe 'when valid_codes are specified as integers' do
+      let(:valid_codes) { [123, 234] }
+
+      it 'uses the stringified versions of the supplied values' do
+        assert_equal valid_codes.map(&:to_s), object.valid_codes
+      end
+    end
+
+    describe 'when valid_codes are not specified' do
+      it 'uses the default values' do
+        assert_kind_of Array, klass::DEFAULTS[:valid_codes]
+        refute klass::DEFAULTS[:valid_codes].empty?
+
+        assert_equal klass::DEFAULTS[:valid_codes], object.valid_codes
+      end
+    end
+  end
+
+  describe "honors Retry-After headers" do
+    REQUEST_METHODS.each do |request_method|
+      it "in #{request_method.to_s.upcase} requests" do
+        retry_values.each do |retry_seconds|
+          accessor.expects(:sleep).with(retry_seconds)
+        end
+
+        VCR.use_cassette("accessor/#{request_method}_retry") do
+          accessor.send(request_method, REQUESTS[request_method])
+        end
+      end
+    end
+  end
+
+  describe 'employs exponential wait times for automatic retries' do
+    REQUEST_METHODS.each do |request_method|
+      it "in #{request_method.to_s.upcase} requests" do
+        exponential_retries[0,8].each do |retry_seconds|
+          accessor.expects(:sleep).with(retry_seconds)
+        end
+
+        VCR.use_cassette("accessor/#{request_method}_failed") do
+          accessor.send(request_method, REQUESTS[request_method])
+        end
+      end
+    end
+  end
+
+  describe 'when Retry-After is shorter than exponential wait time' do
+    REQUEST_METHODS.each do |request_method|
+      it "chooses longer exponential time in #{request_method.to_s.upcase} requests" do
+        exponential_retries[0,4].each do |retry_seconds|
+          accessor.expects(:sleep).with(retry_seconds)
+        end
+
+        VCR.use_cassette("accessor/#{request_method}_retry_too_soon") do
+          accessor.send(request_method, REQUESTS[request_method])
+        end
+      end
+    end
+  end
+
+  describe 'when max retries have been reached' do
+    REQUEST_METHODS.each do |request_method|
+      it "returns an error for #{request_method.to_s.upcase} requests" do
+        exponential_retries.each do |retry_seconds|
+          accessor.expects(:sleep).with(retry_seconds)
+        end
+
+        exception = assert_raises(JD::NetHttpRetry::MaxRetriesExceededError) do
+          VCR.use_cassette("accessor/#{request_method}_max_failed") do
+            accessor.send(request_method, REQUESTS[request_method])
+          end
+        end
+
+        expected_error = "Max retries exceeded for #{request_method.to_s.upcase} request: 429 Too Many Requests"
+        assert_equal expected_error, exception.message
+      end
+    end
+  end
+
+  describe 'when an invalid response code is returned' do
+    REQUEST_METHODS.each do |request_method|
+      it "returns an error for #{request_method.to_s.upcase} requests" do
+        exception = assert_raises(JD::NetHttpRetry::InvalidResponseError) do
+          VCR.use_cassette("accessor/#{request_method}_invalid") do
+            accessor.send(request_method, REQUESTS[request_method])
+          end
+        end
+
+        exception_json = JSON.parse(exception.message)
+
+        assert_equal '500', exception_json['code']
+        assert_equal 'Internal Error', exception_json['message']
+        assert_equal 'You Have Died of Dysentery', exception_json['body']
+      end
+    end
+  end
+end