fieldhand 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: d9c3e17513d85f7e8dec36a7fb9b52fa547e1f2c
-  data.tar.gz: dd74e19d59725bb667f959166a30bdd8506e7c85
+SHA256:
+  metadata.gz: de831124ad540a3a7de6bab3bc7554764913e7f0459f90d28ea98036137f45e3
+  data.tar.gz: 0fb070d672d59d83718dd4d4f468d08c44ca6f8afec8cb984ec4d7068b3a6c3f
 SHA512:
-  metadata.gz: c69eb6a4cc5d8f45716f465a4dcf1b35b760bd8c7d47449168aaa66afe1b29e70eee22cc25b31b900fbd6dfb547b594b79e31fe69132b4d22e2e9a12b756b970
-  data.tar.gz: a1a4fd53a7ce8e5ebd611515d9d0ae76b7e12c52d415ec05c2f0f020ddaeb74c0f7a83fcd5483aa4ff8b4842bd4b15e4c807ef3941c3de6d8ac5229896878866
+  metadata.gz: 8977050a19ec07e3824fa11a2c090b2e90ec4c997db74bf40baf7a3df7811cbe0d3bd71d50dee9f5614a6e2ebf2fabe19c26f27e745e50c027b31ea6db295f7f
+  data.tar.gz: bfb840d375eda0660640325ed8521ff51586b726737ff0827211dd3c82f687b17cc1814c3ac30c6b40b98da0680a9ffd00133c45b5ec15032498e6361f4606db

data/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2017-2018 Altmetric LLP
+Copyright (c) 2017-2019 Altmetric and Paul Mucur
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,20 +1,20 @@
-# Fieldhand [![Build Status](https://travis-ci.org/altmetric/fieldhand.svg?branch=master)](https://travis-ci.org/altmetric/fieldhand)
+# Fieldhand [![Build Status](https://travis-ci.org/fieldhand/fieldhand.svg?branch=master)](https://travis-ci.org/fieldhand/fieldhand)
 
 A Ruby library for harvesting metadata from [OAI-PMH](https://www.openarchives.org/OAI/openarchivesprotocol.html) repositories.
 
-**Current version:** 0.11.0  
-**Supported Ruby versions:** 1.8.7, 1.9.2, 1.9.3, 2.0, 2.1, 2.2
+**Current version:** 0.12.0  
+**Supported Ruby versions:** 1.8.7, 1.9.2, 1.9.3, 2.0, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6
 
 ## Installation
 
 ```
-gem install fieldhand -v '~> 0.11'
+gem install fieldhand -v '~> 0.12'
 ```
 
 Or, in your `Gemfile`:
 
 ```ruby
-gem 'fieldhand', '~> 0.11'
+gem 'fieldhand', '~> 0.12'
 ```
 
 ## Usage
@@ -116,14 +116,17 @@ Fieldhand::Repository.new('http://www.example.com/oai')
 Fieldhand::Repository.new(URI('http://www.example.com/oai'))
 Fieldhand::Repository.new('http://www.example.com/oai', :logger => Logger.new(STDOUT), :timeout => 10, :bearer_token => 'decafbad')
 Fieldhand::Repository.new('http://www.example.com/oai', :logger => Logger.new(STDOUT), :timeout => 10, :headers => { 'Custom header' => 'decafbad' })
+Fieldhand::Repository.new('http://www.example.com/oai', :logger => Logger.new(STDOUT), :retries => 5, :interval => 30)
 ```
 
 Return a new [`Repository`](#fieldhandrepository) instance accessible at the given `uri` (specified
 either as a [`URI`][URI] or
-something that can be coerced into a `URI` such as a `String`) with three options passed as a `Hash`:
+something that can be coerced into a `URI` such as a `String`) with options passed as a `Hash`:
 
 * `:logger`: a [`Logger`](http://ruby-doc.org/stdlib/libdoc/logger/rdoc/Logger.html)-compatible `logger`, defaults to a platform-specific null logger;
 * `:timeout`: a `Numeric` number of seconds to wait before timing out any HTTP requests, defaults to 60;
+* `:retries`: a `Numeric` maximum number of times an HTTP request will be retried before raising an error, defaults to 0;
+* `:interval`: a `Numeric` number of seconds to wait before the next retry attempt, defaults to 10;
 * `:bearer_token`: a `String` bearer token to authorize any HTTP requests, defaults to `nil`.
 * `:headers`: a `Hash` containing custom HTTP headers, defaults to `{}`.
  
@@ -635,6 +638,6 @@ This can be used to rescue all the following child error types.
 
 ## License
 
-Copyright © 2017-2018 Altmetric LLP
+Copyright © 2017-2019 Altmetric and Paul Mucur
 
 Distributed under the MIT License.

data/lib/fieldhand.rb

@@ -1 +1,3 @@
+# frozen_string_literal: true
+
 require 'fieldhand/repository'

data/lib/fieldhand/arguments.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'fieldhand/datestamp'
 
 module Fieldhand

data/lib/fieldhand/datestamp.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'date'
 require 'time'
 

data/lib/fieldhand/get_record_parser.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'fieldhand/record'
 
 module Fieldhand

data/lib/fieldhand/header.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'fieldhand/datestamp'
 
 module Fieldhand

data/lib/fieldhand/identify.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'fieldhand/datestamp'
 require 'uri'
 

data/lib/fieldhand/identify_parser.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'fieldhand/identify'
 
 module Fieldhand

data/lib/fieldhand/list_identifiers_parser.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'fieldhand/header'
 
 module Fieldhand

data/lib/fieldhand/list_metadata_formats_parser.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'fieldhand/metadata_format'
 
 module Fieldhand

data/lib/fieldhand/list_records_parser.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'fieldhand/record'
 
 module Fieldhand

data/lib/fieldhand/list_sets_parser.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'fieldhand/set'
 
 module Fieldhand

data/lib/fieldhand/logger.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'logger'
 require 'rbconfig'
 

data/lib/fieldhand/metadata_format.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'uri'
 
 module Fieldhand

data/lib/fieldhand/network_errors.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Fieldhand
   NetworkError = ::Class.new(::StandardError)
 

data/lib/fieldhand/options.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'fieldhand/logger'
 
 module Fieldhand
@@ -16,6 +18,8 @@ module Fieldhand
     # * :logger - A `Logger`-compatible class for logging the activity of the library, defaults to a platform-specific
     #             null logger
     # * :timeout - A `Numeric` number of seconds to wait for any HTTP requests, defaults to 60 seconds
+    # * :retries - A `Numeric` maximum number of times a request is retried before erroring, defaults to 0
+    # * :interval - A `Numeric` number of seconds before an erroring request is retried, defaults to 10
     # * :bearer_token - A `String` bearer token to use when sending any HTTP requests, defaults to nil
     # * :headers - A `Hash` containing custom HTTP headers, defaults to {}.
     def initialize(logger_or_options = {})
@@ -32,6 +36,16 @@ module Fieldhand
       options.fetch(:logger) { Logger.null }
     end
 
+    # Return the current maximum number of retries.
+    def retries
+      options.fetch(:retries, 0)
+    end
+
+    # Return the current retry interval in seconds.
+    def interval
+      options.fetch(:interval, 10)
+    end
+
     # Return the current bearer token.
     def bearer_token
       options[:bearer_token]

data/lib/fieldhand/paginator.rb

@@ -1,7 +1,10 @@
+# frozen_string_literal: true
+
 require 'fieldhand/network_errors'
 require 'fieldhand/options'
 require 'fieldhand/response_parser'
 require 'cgi'
+require 'forwardable'
 require 'net/http'
 require 'uri'
 
@@ -11,25 +14,28 @@ module Fieldhand
   #
   # See https://www.openarchives.org/OAI/openarchivesprotocol.html#FlowControl
   class Paginator
-    attr_reader :uri, :logger, :timeout, :headers, :http
+    attr_reader :uri, :options, :http
+
+    extend Forwardable
+    def_delegators :options, :logger, :timeout, :retries, :interval, :headers
 
-    # Return a new paginator for the given repository base URI and optional logger, timeout, bearer token and headers.
+    # Return a new paginator for the given repository base URI and optional
+    # logger, timeout, maximum number of retries, retry interval, bearer token
+    # and headers.
     #
     # The URI can be passed as either a `URI` or something that can be parsed as a URI such as a string.
     #
-    # The logger will default to a null logger appropriate to this platform, timeout will default to 60 seconds, the
-    # bearer token will default to nil and headers will default to empty hash.
+    # The logger will default to a null logger appropriate to this platform,
+    # timeout will default to 60 seconds, maximum number of retries will
+    # default to 0, the retry interval will default to 10 seconds, the bearer
+    # token will default to nil and headers will default to empty hash.
     def initialize(uri, logger_or_options = {})
       @uri = uri.is_a?(::URI) ? uri : URI(uri)
-
-      options = Options.new(logger_or_options)
-      @logger = options.logger
-      @timeout = options.timeout
-      @headers = options.headers
+      @options = Options.new(logger_or_options)
 
       @http = ::Net::HTTP.new(@uri.host, @uri.port)
-      @http.read_timeout = @timeout
-      @http.open_timeout = @timeout
+      @http.read_timeout = @options.timeout
+      @http.open_timeout = @options.timeout
       @http.use_ssl = true if @uri.scheme == 'https'
     end
 
@@ -75,9 +81,7 @@ module Fieldhand
     private
 
     def parse_response(query = {})
-      response = request(query)
-      raise ResponseError, response unless response.is_a?(::Net::HTTPSuccess)
-
+      response = retry_request(query)
       response_parser = ResponseParser.new(response.body)
       response_parser.errors.each do |error|
         raise error
@@ -86,6 +90,28 @@ module Fieldhand
       response_parser
     end
 
+    def retry_request(query = {})
+      remaining_retries = retries
+
+      begin
+        ensure_successful_request(query)
+      rescue ResponseError => e
+        raise e unless remaining_retries > 0
+
+        remaining_retries -= 1
+        sleep(interval)
+
+        retry
+      end
+    end
+
+    def ensure_successful_request(query = {})
+      response = request(query)
+      raise ResponseError, response unless response.is_a?(::Net::HTTPSuccess)
+
+      response
+    end
+
     def request(query = {})
       request_uri = uri.dup
       request_uri.query = encode_query(query)

data/lib/fieldhand/record.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'fieldhand/header'
 require 'ox'
 

data/lib/fieldhand/repository.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'fieldhand/arguments'
 require 'fieldhand/get_record_parser'
 require 'fieldhand/identify_parser'
@@ -7,6 +9,7 @@ require 'fieldhand/list_records_parser'
 require 'fieldhand/list_sets_parser'
 require 'fieldhand/options'
 require 'fieldhand/paginator'
+require 'forwardable'
 require 'uri'
 
 module Fieldhand
@@ -14,23 +17,26 @@ module Fieldhand
   #
   # See https://www.openarchives.org/OAI/openarchivesprotocol.html
   class Repository
-    attr_reader :uri, :logger, :timeout, :headers
+    attr_reader :uri, :logger_or_options
+
+    # Allow the user to query the repository's current options.
+    extend Forwardable
+    def_delegators :paginator, :logger, :timeout, :retries, :interval, :headers
 
-    # Return a new repository with the given base URL and an optional logger, timeout, bearer token and headers.
+    # Return a new repository with the given base URL and an optional logger,
+    # timeout, maximum number of retries, retry interval, bearer token and
+    # headers.
     #
     # The base URL can be passed as a `URI` or anything that can be parsed as a URI such as a string.
     #
     # For backward compatibility, the second argument can either be a logger or a hash containing
-    # a logger, timeout, bearer token and headers.
+    # a logger, timeout, maximum number of retries, retry interval, bearer token and headers.
     #
-    # Defaults to using a null logger specific to this platform, a timeout of 60 seconds, no bearer token and no headers.
+    # Defaults to using a null logger specific to this platform, a timeout of 60 seconds, a maximum
+    # number of retries of 0, a retry interval of 10 seconds, no bearer token and no headers.
     def initialize(uri, logger_or_options = {})
       @uri = uri.is_a?(::URI) ? uri : URI(uri)
-
-      options = Options.new(logger_or_options)
-      @logger = options.logger
-      @timeout = options.timeout
-      @headers = options.headers
+      @logger_or_options = logger_or_options
     end
 
     # Send an Identify request to the repository and return an `Identify` response.
@@ -134,7 +140,7 @@ module Fieldhand
     private
 
     def paginator
-      @paginator ||= Paginator.new(uri, :logger => logger, :timeout => timeout, :headers => headers)
+      @paginator ||= Paginator.new(uri, logger_or_options)
     end
   end
 end

data/lib/fieldhand/response_parser.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'fieldhand/datestamp'
 require 'ox'
 

data/lib/fieldhand/set.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'ox'
 
 module Fieldhand

data/spec/fieldhand/arguments_spec.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'fieldhand/arguments'
 require 'fieldhand/metadata_format'
 require 'fieldhand/set'

data/spec/fieldhand/datestamp_spec.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'fieldhand/datestamp'
 
 module Fieldhand

data/spec/fieldhand/header_spec.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'fieldhand/header'
 require 'ox'
 

data/spec/fieldhand/identify_spec.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'fieldhand/identify'
 require 'ox'
 

data/spec/fieldhand/metadata_format_spec.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'fieldhand/metadata_format'
 require 'ox'
 

data/spec/fieldhand/options_spec.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'fieldhand/options'
 
 module Fieldhand
@@ -56,6 +58,34 @@ module Fieldhand
       end
     end
 
+    describe '#retries' do
+      it 'defaults to 0' do
+        options = described_class.new({})
+
+        expect(options.retries).to be_zero
+      end
+
+      it 'can be overridden by passing an option' do
+        options = described_class.new(:retries => 5)
+
+        expect(options.retries).to eq(5)
+      end
+    end
+
+    describe '#interval' do
+      it 'defaults to 10' do
+        options = described_class.new({})
+
+        expect(options.interval).to eq(10)
+      end
+
+      it 'can be overridden by passing an option' do
+        options = described_class.new(:interval => 5)
+
+        expect(options.interval).to eq(5)
+      end
+    end
+
     describe '#bearer_token' do
       it 'defaults to nil' do
         options = described_class.new({})

data/spec/fieldhand/paginator_spec.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'fieldhand/get_record_parser'
 require 'fieldhand/identify_parser'
 require 'fieldhand/list_metadata_formats_parser'
@@ -85,6 +87,25 @@ module Fieldhand
           to raise_error(NoSetHierarchyError)
       end
 
+      it 'retries unsuccessful requests' do
+        stub_request(:get, 'http://www.example.com/oai?verb=Identify').
+          to_return({ :status => 503 }, { :status => 500 }, { :status => 200, :body => fixture('identify.xml') })
+
+        paginator = described_class.new('http://www.example.com/oai', :retries => 3, :interval => 0)
+
+        expect(paginator.items('Identify', IdentifyParser).first).to be_a(Identify)
+      end
+
+      it 'retries each unsuccessful request separately' do
+        stub_request(:get, 'http://www.example.com/oai?verb=Identify').
+          to_return({ :status => 500 }, { :status => 200, :body => fixture('identify.xml') }, { :status => 500 }, { :status => 200, :body => fixture('identify.xml') })
+
+        paginator = described_class.new('http://www.example.com/oai', :retries => 1, :interval => 0)
+        paginator.items('Identify', IdentifyParser).first
+
+        expect(paginator.items('Identify', IdentifyParser).first).to be_a(Identify)
+      end
+
       it 'raises a Response Error if an unsuccessful response is returned' do
         stub_request(:get, 'http://www.example.com/oai?verb=Identify').
           to_return(:status => 503, :body => 'Retry after 5 seconds')
@@ -94,6 +115,15 @@ module Fieldhand
           to raise_error(ResponseError)
       end
 
+      it 'raises a Response Error if an unsuccessful response is returned after the last retry attempt' do
+        stub_request(:get, 'http://www.example.com/oai?verb=Identify').
+          to_return({ :status => 500 }, { :status => 500 }, { :status => 500 }, { :status => 200, :body => fixture('identify.xml') })
+        paginator = described_class.new('http://www.example.com/oai', :retries => 2, :interval => 0)
+
+        expect { paginator.items('Identify', IdentifyParser).first }.
+          to raise_error(ResponseError)
+      end
+
       it 'raises a Response Error containing a response object' do
         stub_request(:get, 'http://www.example.com/oai?verb=Identify').
           to_return(:status => 503, :body => 'Retry after 5 seconds')
@@ -146,6 +176,34 @@ module Fieldhand
       end
     end
 
+    describe '#retries' do
+      it 'defaults to 0' do
+        paginator = described_class.new('http://www.example.com/oai')
+
+        expect(paginator.retries).to be_zero
+      end
+
+      it 'can be overridden with an option' do
+        paginator = described_class.new('http://www.example.com/oai', :retries => 5)
+
+        expect(paginator.retries).to eq(5)
+      end
+    end
+
+    describe '#interval' do
+      it 'defaults to 10' do
+        paginator = described_class.new('http://www.example.com/oai')
+
+        expect(paginator.interval).to eq(10)
+      end
+
+      it 'can be overridden with an option' do
+        paginator = described_class.new('http://www.example.com/oai', :interval => 15)
+
+        expect(paginator.interval).to eq(15)
+      end
+    end
+
     describe '#headers' do
       it 'defaults to an empty hash' do
         paginator = described_class.new('http://www.example.com/oai')

data/spec/fieldhand/record_spec.rb

@@ -1,4 +1,5 @@
 # encoding: utf-8
+# frozen_string_literal: true
 
 require 'fieldhand/record'
 require 'ox'

data/spec/fieldhand/repository_spec.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'fieldhand/repository'
 
 module Fieldhand
@@ -256,6 +258,34 @@ module Fieldhand
       end
     end
 
+    describe '#retries' do
+      it 'defaults to 0' do
+        repository = described_class.new('http://www.example.com/oai')
+
+        expect(repository.retries).to be_zero
+      end
+
+      it 'can be overridden with an option' do
+        repository = described_class.new('http://www.example.com/oai', :retries => 5)
+
+        expect(repository.retries).to eq(5)
+      end
+    end
+
+    describe '#interval' do
+      it 'defaults to 10' do
+        repository = described_class.new('http://www.example.com/oai')
+
+        expect(repository.interval).to eq(10)
+      end
+
+      it 'can be overridden with an option' do
+        repository = described_class.new('http://www.example.com/oai', :interval => 15)
+
+        expect(repository.interval).to eq(15)
+      end
+    end
+
     describe '#headers' do
       it 'defaults to an empty hash' do
         repository = described_class.new('http://www.example.com/oai')

data/spec/fieldhand/set_spec.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'fieldhand/set'
 require 'ox'
 

data/spec/spec_helper.rb

@@ -1,6 +1,10 @@
+# frozen_string_literal: true
+
 require 'date'
 require 'webmock/rspec'
 
+FIXTURES_DIR = File.expand_path('../fixtures', __FILE__).freeze
+
 RSpec.configure do |config|
   config.shared_context_metadata_behavior = :apply_to_host_groups
   config.filter_run_when_matching :focus
@@ -21,9 +25,10 @@ RSpec.configure do |config|
   end
 
   def stub_oai_request(uri, fixture)
-    fixtures_dir = File.expand_path('../fixtures', __FILE__)
+    stub_request(:get, uri).to_return(:body => fixture(fixture))
+  end
 
-    stub_request(:get, uri).
-      to_return(:body => File.read(File.join(fixtures_dir, fixture)))
+  def fixture(fixture)
+    File.read(File.join(FIXTURES_DIR, fixture))
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fieldhand
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.12.0
 platform: ruby
 authors:
 - Paul Mucur
@@ -9,10 +9,11 @@ authors:
 - Giovanni Derks
 - Abeer Salameh
 - Anna Klimas
+- Marco Bagnasco
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-11-12 00:00:00.000000000 Z
+date: 2019-09-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ox
@@ -121,7 +122,7 @@ files:
 - spec/fieldhand/repository_spec.rb
 - spec/fieldhand/set_spec.rb
 - spec/spec_helper.rb
-homepage: https://github.com/altmetric/fieldhand
+homepage: https://github.com/fieldhand/fieldhand
 licenses:
 - MIT
 metadata: {}
@@ -140,8 +141,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.6.14
+rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
 summary: An OAI-PMH harvester