berkeley_library-util 0.1.6 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a17e4e3e2e6e03e0dda795450e724650a0a7f7ae44db3b7a558bc371d8bed1b7
-  data.tar.gz: 106ff7e21c1e9568f4bdabc116023c292878f4fd629e5ee3ada934b2c2a10b43
+  metadata.gz: 81d92682b9ea2f5466198ab26b0a31775704f3d52408e67453b1af8871367aa8
+  data.tar.gz: 296f6fd7ad69c125e732b423f9eb75f338cc866b9a7c19dae6c550d754a2c285
 SHA512:
-  metadata.gz: b4fbde8aa9e43a7ad7c414b92b488c5d2af1ae29c7f28a7ecd8f6ceb308e42c3c27a2256994362b15cba5133ec00feb32d5fe76f0b774577b292be6c2ba08528
-  data.tar.gz: 23c41cbed1b0befc458c8989792c45cf7429905b06e2deec72a88478f8eb7676a6e3be96dae5fa308239bb4f70b19acae421593711c20dd22d305f55262b0f64
+  metadata.gz: f632ee12e255ca16fcd22effc3df7d1ddcf7cb4a93ac49c4ca7d3beef8ba29143b8bc1f96097236fdf9dde1802625423990052ac12a4920cb0e8a074715b3cf4
+  data.tar.gz: c9ab1aa8a055caf6ba968af662fdcf3dbe782fdce4c0e884032db10a427dae4049f48fde9297d415336374760183ec23058c355bed3ee8bb9f90593bf3844841

data/CHANGES.md

@@ -1,3 +1,14 @@
+# 0.1.8 (2023-03-20)
+
+- Add `Retry-After` support to `Requester` for `429 Too Many Requests` and `503 Service Unavailable`. 
+
+# 0.1.7 (2023-03-15)
+
+- Allow passing `log: false` to `Requester` methods (and corresponding `URIs` convenience
+  methods) to suppress logging of each request URL and response code.
+- Allow constructing `Requester` instances with delayed execution
+- Fix documentation for `get_response` and `head_response` in `URIs` and `Requester`
+
 # 0.1.6 (2023-03-09)
 
 - Fix issue in `Requester` where query parameters would not be appended properly

data/lib/berkeley_library/util/module_info.rb

@@ -7,7 +7,7 @@ module BerkeleyLibrary
       SUMMARY = 'Miscellaneous Ruby utilities for the UC Berkeley Library'.freeze
       DESCRIPTION = 'A collection of miscellaneous Ruby routines for the UC Berkeley Library.'.freeze
       LICENSE = 'MIT'.freeze
-      VERSION = '0.1.6'.freeze
+      VERSION = '0.1.8'.freeze
       HOMEPAGE = 'https://github.com/BerkeleyLibrary/util'.freeze
     end
   end

data/lib/berkeley_library/util/uris/appender.rb

@@ -39,6 +39,14 @@ module BerkeleyLibrary
           end
         end
 
+        # Returns the new URI as a string.
+        #
+        # @return [String] a new URI appending the joined path elements, as a string.
+        # @raise URI::InvalidComponentError if appending the specified elements would create an invalid URI
+        def to_url_str
+          to_uri.to_s
+        end
+
         private
 
         def handle_element(element, elem_index)

data/lib/berkeley_library/util/uris/exceptions.rb

@@ -0,0 +1,15 @@
+class RetryDelayTooLarge < RestClient::Exception
+  def initialize(response, delay:, max_delay:)
+    super(response, response.code)
+
+    self.message = 'Retry delay of %0.2gs exceeds limit of %0.2gs' % [delay, max_delay]
+  end
+end
+
+class RetryLimitExceeded < RestClient::Exception
+  def initialize(response, max_retries:)
+    super(response, response.code)
+
+    self.message = "Retry limit (#{max_retries}) exceeded"
+  end
+end

data/lib/berkeley_library/util/uris/requester/class_methods.rb

@@ -0,0 +1,89 @@
+module BerkeleyLibrary
+  module Util
+    module URIs
+      class Requester
+        # rubocop:disable Metrics/ParameterLists
+        module ClassMethods
+          # Performs a GET request and returns the response body as a string.
+          #
+          # @param uri [URI, String] the URI to GET
+          # @param params [Hash] the query parameters to add to the URI. (Note that the URI may already include query parameters.)
+          # @param headers [Hash] the request headers.
+          # @return [String] the body as a string.
+          # @param log [Boolean] whether to log each request URL and response code
+          # @param max_retries [Integer] the maximum number of times to retry after a 429 or 503 with Retry-After
+          # @param max_retry_delay [Integer] the maximum retry delay (in seconds) to accept in a Retry-After header
+          # @raise [RestClient::Exception] in the event of an unsuccessful request.
+          def get(uri, params: {}, headers: {}, log: true, max_retries: MAX_RETRIES, max_retry_delay: MAX_RETRY_DELAY_SECONDS)
+            resp = make_request(:get, uri, params, headers, log, max_retries, max_retry_delay)
+            resp.body
+          end
+
+          # Performs a HEAD request and returns the response status as an integer.
+          # Note that unlike {Requester#get}, this does not raise an error in the
+          # event of an unsuccessful request.
+          #
+          # @param uri [URI, String] the URI to HEAD
+          # @param params [Hash] the query parameters to add to the URI. (Note that the URI may already include query parameters.)
+          # @param headers [Hash] the request headers.
+          # @param log [Boolean] whether to log each request URL and response code
+          # @return [Integer] the response code as an integer.
+          def head(uri, params: {}, headers: {}, log: true, max_retries: MAX_RETRIES, max_retry_delay: MAX_RETRY_DELAY_SECONDS)
+            head_response(uri, params: params, headers: headers, log: log, max_retries: max_retries, max_retry_delay: max_retry_delay).code
+          end
+
+          # Performs a GET request and returns the response, even in the event of
+          # a failed request.
+          #
+          # @param uri [URI, String] the URI to GET
+          # @param params [Hash] the query parameters to add to the URI. (Note that the URI may already include query parameters.)
+          # @param headers [Hash] the request headers.
+          # @param log [Boolean] whether to log each request URL and response code
+          # @return [RestClient::Response] the response
+          def get_response(uri, params: {}, headers: {}, log: true, max_retries: MAX_RETRIES, max_retry_delay: MAX_RETRY_DELAY_SECONDS)
+            make_request(:get, uri, params, headers, log, max_retries, max_retry_delay)
+          rescue RestClient::Exception => e
+            e.response
+          end
+
+          # Performs a HEAD request and returns the response, even in the event of
+          # a failed request.
+          #
+          # @param uri [URI, String] the URI to HEAD
+          # @param params [Hash] the query parameters to add to the URI. (Note that the URI may already include query parameters.)
+          # @param headers [Hash] the request headers.
+          # @param log [Boolean] whether to log each request URL and response code
+          # @return [RestClient::Response] the response
+          def head_response(uri, params: {}, headers: {}, log: true, max_retries: MAX_RETRIES, max_retry_delay: MAX_RETRY_DELAY_SECONDS)
+            make_request(:head, uri, params, headers, log, max_retries, max_retry_delay)
+          rescue RestClient::Exception => e
+            e.response
+          end
+
+          private
+
+          def make_request(method, url, params, headers, log, max_retries, max_retry_delay)
+            Requester.new(
+              method,
+              url,
+              params: params,
+              headers: headers,
+              log: log,
+              max_retries: max_retries,
+              max_retry_delay: max_retry_delay
+            ).make_request
+          end
+
+        end
+        # rubocop:enable Metrics/ParameterLists
+
+        # ------------------------------------------------------------
+        # Class methods
+
+        class << self
+          include ClassMethods
+        end
+      end
+    end
+  end
+end

data/lib/berkeley_library/util/uris/requester.rb

@@ -1,108 +1,166 @@
+require 'time'
 require 'rest-client'
 require 'berkeley_library/util/uris/appender'
+require 'berkeley_library/util/uris/exceptions'
 require 'berkeley_library/util/uris/validator'
+require 'berkeley_library/util/uris/requester/class_methods'
 require 'berkeley_library/logging'
 
 module BerkeleyLibrary
   module Util
     module URIs
-      module Requester
-        class << self
-          include BerkeleyLibrary::Logging
-
-          # Performs a GET request and returns the response body as a string.
-          #
-          # @param uri [URI, String] the URI to GET
-          # @param params [Hash] the query parameters to add to the URI. (Note that the URI may already include query parameters.)
-          # @param headers [Hash] the request headers.
-          # @return [String] the body as a string.
-          # @raise [RestClient::Exception] in the event of an unsuccessful request.
-          def get(uri, params: {}, headers: {})
-            resp = make_request(:get, uri, params, headers)
-            resp.body
-          end
+      class Requester
+        include BerkeleyLibrary::Logging
 
-          # Performs a HEAD request and returns the response status as an integer.
-          # Note that unlike {Requester#get}, this does not raise an error in the
-          # event of an unsuccessful request.
-          #
-          # @param uri [URI, String] the URI to HEAD
-          # @param params [Hash] the query parameters to add to the URI. (Note that the URI may already include query parameters.)
-          # @param headers [Hash] the request headers.
-          # @return [Integer] the response code as an integer.
-          def head(uri, params: {}, headers: {})
-            head_response(uri, params: params, headers: headers).code
-          end
+        # ------------------------------------------------------------
+        # Constants
 
-          # Performs a GET request and returns the response, even in the event of
-          # a failed request.
-          #
-          # @param uri [URI, String] the URI to GET
-          # @param params [Hash] the query parameters to add to the URI. (Note that the URI may already include query parameters.)
-          # @param headers [Hash] the request headers.
-          # @return [RestClient::Response] the body as a string.
-          def get_response(uri, params: {}, headers: {})
-            make_request(:get, uri, params, headers)
-          rescue RestClient::Exception => e
-            e.response
-          end
+        SUPPORTED_METHODS = %i[get head].freeze
+        RETRY_HEADER = :retry_after
+        RETRY_STATUSES = [429, 503].freeze
+        MAX_RETRY_DELAY_SECONDS = 10
+        MAX_RETRIES = 3
 
-          # Performs a HEAD request and returns the response, even in the event of
-          # a failed request.
-          #
-          # @param uri [URI, String] the URI to HEAD
-          # @param params [Hash] the query parameters to add to the URI. (Note that the URI may already include query parameters.)
-          # @param headers [Hash] the request headers.
-          # @return [RestClient::Response] the body as a string.
-          def head_response(uri, params: {}, headers: {})
-            make_request(:head, uri, params, headers)
-          rescue RestClient::Exception => e
-            e.response
-          end
+        # ------------------------------------------------------------
+        # Attributes
+
+        attr_reader :method, :url_str, :headers, :log, :max_retries, :max_retry_delay
+
+        # ------------------------------------------------------------
+        # Initializer
+
+        # Initializes a new Requester.
+        #
+        # @param method [:get, :head] the HTTP method to use
+        # @param url [String, URI] the URL or URI to request
+        # @param params [Hash] the query parameters to add to the URI. (Note that the URI may already include query parameters.)
+        # @param headers [Hash] the request headers.
+        # @param log [Boolean] whether to log each request URL and response code
+        # @param max_retries [Integer] the maximum number of times to retry after a 429 or 503 with Retry-After
+        # @param max_retry_delay [Integer] the maximum retry delay (in seconds) to accept in a Retry-After header
+        # @raise URI::InvalidURIError if the specified URL is invalid
+        # rubocop:disable Metrics/ParameterLists
+        def initialize(method, url, params: {}, headers: {}, log: true, max_retries: MAX_RETRIES, max_retry_delay: MAX_RETRY_DELAY_SECONDS)
+          raise ArgumentError, "#{method} not supported" unless SUPPORTED_METHODS.include?(method)
+          raise ArgumentError, 'url cannot be nil' unless (uri = Validator.uri_or_nil(url))
+
+          @method = method
+          @url_str = url_str_with_params(uri, params)
+          @headers = headers
+          @log = log
+          @max_retries = max_retries
+          @max_retry_delay = max_retry_delay
+        end
+
+        # rubocop:enable Metrics/ParameterLists
 
-          private
+        # ------------------------------------------------------------
+        # Public instance methods
 
-          # @return [RestClient::Response]
-          def make_request(method, uri, params, headers)
-            url_str = url_str_with_params(uri, params)
-            req_resp_or_raise(method, url_str, headers)
+        # @return [RestClient::Response]
+        def make_request
+          execute_request.tap do |resp|
+            log_response(resp)
           end
+        rescue RestClient::Exception => e
+          log_response(e.response)
+          raise
+        end
+
+        # ------------------------------------------------------------
+        # Private methods
 
-          def url_str_with_params(url, params)
-            raise ArgumentError, 'url cannot be nil' unless (uri = Validator.uri_or_nil(url))
+        private
 
-            elements = [].tap do |ee|
-              ee << uri
-              next if params.empty?
+        def log_response(response)
+          return unless log
 
-              ee << (uri.query ? '&' : '?')
-              ee << URI.encode_www_form(params)
-            end
+          logger.info("#{method.to_s.upcase} #{url_str} returned #{response.code}")
+        end
 
-            uri = Appender.new(*elements).to_uri
-            uri.to_s
+        def url_str_with_params(uri, params)
+          elements = [uri]
+          if params.any?
+            elements << (uri.query ? '&' : '?')
+            elements << URI.encode_www_form(params)
           end
 
-          # @return [RestClient::Response]
-          def req_resp_or_raise(method, url_str, headers)
-            resp = RestClient::Request.execute(method: method, url: url_str, headers: headers)
-            begin
-              return resp if (status = resp.code) == 200
-
-              raise(exception_for(resp, status))
-            ensure
-              # noinspection RubyMismatchedReturnType
-              logger.info("#{method.to_s.upcase} #{url_str} returned #{status}")
-            end
+          Appender.new(*elements).to_url_str
+        end
+
+        def execute_request(retries_remaining = max_retries)
+          try_execute_request
+        rescue RestClient::Exception => e
+          response = e.response
+          raise unless (retry_delay = retry_delay_from(response))
+
+          wait_for_retry(response, retry_delay, retries_remaining)
+          execute_request(retries_remaining - 1)
+        end
+
+        def try_execute_request
+          RestClient::Request.execute(method: method, url: url_str, headers: headers).tap do |response|
+            # Not all failed RestClient requests throw exceptions
+            raise(exception_for(response)) unless response.code == 200
           end
+        end
+
+        def wait_for_retry(response, retry_delay, retries_remaining)
+          raise RetryLimitExceeded.new(response, max_retries: max_retries) unless retries_remaining > 0
+          raise RetryDelayTooLarge.new(response, delay: retry_delay, max_delay: max_retry_delay) if retry_delay > max_retry_delay
 
-          def exception_for(resp, status)
-            RestClient::RequestFailed.new(resp, status).tap do |ex|
-              status_message = RestClient::STATUSES[status] || '(Unknown)'
-              ex.message = "#{status} #{status_message}"
-            end
+          sleep(retry_delay)
+        end
+
+        def exception_for(resp)
+          status = resp.code
+          ex_class_for(status).new(resp, status).tap do |ex|
+            status_message = RestClient::STATUSES[status] || '(Unknown)'
+            ex.message = "#{status} #{status_message}"
           end
         end
+
+        def ex_class_for(status)
+          RestClient::Exceptions::EXCEPTIONS_MAP[status] || RestClient::RequestFailed
+        end
+
+        # Returns the retry interval for the specified exception, or `nil`
+        # if the response does not allow a retry.
+        #
+        # @param resp [RestClient::Response] the response
+        # @return [Integer, nil] the retry delay in seconds, or `nil` if the response
+        #         does not allow a retry
+        def retry_delay_from(resp)
+          return unless RETRY_STATUSES.include?(resp.code)
+          return unless (retry_header_value = resp.headers[RETRY_HEADER])
+          return unless (retry_delay_seconds = parse_retry_header_value(retry_header_value))
+
+          [1, retry_delay_seconds.ceil].max
+        end
+
+        # @return [Float, nil] the retry delay in seconds, or `nil` if the delay cannot be parsed
+        def parse_retry_header_value(v)
+          # start by assuming it's a delay in seconds
+          Float(v) # should be an integer but let's not count on it
+        rescue ArgumentError
+          # assume it's an HTTP-date
+          parse_retry_after_date(v)
+        end
+
+        # Parses the specified RFC2822 datetime string and returns the interval between that
+        # datetime and the current time in seconds
+        #
+        # @param date_str [String] an RFC2822 datetime string
+        # @return [Float, nil] the interval between the current time and the specified datetime,
+        #   or nil if `date_str` cannot be parsed
+        def parse_retry_after_date(date_str)
+          retry_after = DateTime.rfc2822(date_str).to_time
+          retry_after - Time.now
+        rescue ArgumentError
+          logger.warn("Can't parse #{RETRY_HEADER} value #{date_str}")
+          nil
+        end
+
       end
     end
   end

data/lib/berkeley_library/util/uris.rb

@@ -31,10 +31,11 @@ module BerkeleyLibrary
       # @param uri [URI, String] the URI to GET
       # @param params [Hash] the query parameters to add to the URI. (Note that the URI may already include query parameters.)
       # @param headers [Hash] the request headers.
+      # @param log [Boolean] whether to log each request URL and response code
       # @return [String] the body as a string.
       # @raise [RestClient::Exception] in the event of an unsuccessful request.
-      def get(uri, params: {}, headers: {})
-        Requester.get(uri, params: params, headers: headers)
+      def get(uri, params: {}, headers: {}, log: true)
+        Requester.get(uri, params: params, headers: headers, log: log)
       end
 
       # Performs a HEAD request and returns the response status as an integer.
@@ -44,9 +45,10 @@ module BerkeleyLibrary
       # @param uri [URI, String] the URI to HEAD
       # @param params [Hash] the query parameters to add to the URI. (Note that the URI may already include query parameters.)
       # @param headers [Hash] the request headers.
+      # @param log [Boolean] whether to log each request URL and response code
       # @return [Integer] the response code as an integer.
-      def head(uri, params: {}, headers: {})
-        Requester.head(uri, params: params, headers: headers)
+      def head(uri, params: {}, headers: {}, log: true)
+        Requester.head(uri, params: params, headers: headers, log: log)
       end
 
       # Performs a GET request and returns the response, even in the event of
@@ -55,9 +57,10 @@ module BerkeleyLibrary
       # @param uri [URI, String] the URI to GET
       # @param params [Hash] the query parameters to add to the URI. (Note that the URI may already include query parameters.)
       # @param headers [Hash] the request headers.
-      # @return [RestClient::Response] the body as a string.
-      def get_response(uri, params: {}, headers: {})
-        Requester.get_response(uri, params: params, headers: headers)
+      # @param log [Boolean] whether to log each request URL and response code
+      # @return [RestClient::Response] the response
+      def get_response(uri, params: {}, headers: {}, log: true)
+        Requester.get_response(uri, params: params, headers: headers, log: log)
       end
 
       # Performs a HEAD request and returns the response, even in the event of
@@ -66,9 +69,10 @@ module BerkeleyLibrary
       # @param uri [URI, String] the URI to HEAD
       # @param params [Hash] the query parameters to add to the URI. (Note that the URI may already include query parameters.)
       # @param headers [Hash] the request headers.
-      # @return [RestClient::Response] the body as a string.
-      def head_response(uri, params: {}, headers: {})
-        Requester.head_response(uri, params: params, headers: headers)
+      # @param log [Boolean] whether to log each request URL and response code
+      # @return [RestClient::Response] the response
+      def head_response(uri, params: {}, headers: {}, log: true)
+        Requester.head_response(uri, params: params, headers: headers, log: log)
       end
 
       # Returns the specified URL as a URI, or `nil` if the URL is `nil`.

data/spec/berkeley_library/util/uris/requester_spec.rb

@@ -65,6 +65,250 @@ module BerkeleyLibrary
             result = Requester.get(url1)
             expect(result).to eq(expected_body)
           end
+
+          describe 'retries' do
+            let(:url) { 'https://example.org/' }
+            let(:expected_body) { 'Help! I am trapped in a unit test' }
+
+            context 'handling 429 Too Many Requests' do
+              context 'with Retry-After' do
+                context 'in seconds' do
+                  it 'retries after the specified delay' do
+                    retry_after_seconds = 1
+
+                    stub_request(:get, url)
+                      .to_return(status: 429, headers: { 'Retry-After' => retry_after_seconds.to_s })
+                      .to_return(status: 200, body: expected_body)
+
+                    requester = Requester.new(:get, url)
+                    expect(requester).to receive(:sleep).with(1).once
+
+                    result = requester.make_request
+                    expect(result).to eq(expected_body)
+                  end
+
+                  it 'handles a non-integer retry delay' do
+                    retry_after_seconds = 1.5
+                    stub_request(:get, url)
+                      .to_return(status: 429, headers: { 'Retry-After' => retry_after_seconds.to_s })
+                      .to_return(status: 200, body: expected_body)
+
+                    requester = Requester.new(:get, url)
+                    expect(requester).to receive(:sleep).with(2).once
+
+                    result = requester.make_request
+                    expect(result).to eq(expected_body)
+                  end
+
+                  it 'raises RetryDelayTooLarge if the delay is too large' do
+                    retry_after_seconds = 1 + BerkeleyLibrary::Util::URIs::Requester::MAX_RETRY_DELAY_SECONDS
+
+                    stub_request(:get, url)
+                      .to_return(status: 429, headers: { 'Retry-After' => retry_after_seconds.to_s })
+
+                    requester = Requester.new(:get, url)
+                    expect(requester).not_to receive(:sleep)
+
+                    expect { requester.make_request }.to raise_error(RetryDelayTooLarge) do |ex|
+                      expect(ex.cause).to be_a(RestClient::TooManyRequests)
+                    end
+                  end
+
+                  it 'raises RetryLimitExceeded if there are too many retries' do
+                    retry_after_seconds = 1
+
+                    stub_request(:get, url)
+                      .to_return(status: 429, headers: { 'Retry-After' => retry_after_seconds.to_s })
+                      .to_return(status: 429, headers: { 'Retry-After' => retry_after_seconds.to_s })
+
+                    requester = Requester.new(:get, url, max_retries: 1)
+                    expect(requester).to receive(:sleep).with(1).once
+
+                    expect { requester.make_request }.to raise_error(RetryLimitExceeded) do |ex|
+                      expect(ex.cause).to be_a(RestClient::TooManyRequests)
+                    end
+                  end
+                end
+
+                context 'as RFC2822 datetime' do
+                  it 'retries after the specified delay' do
+                    retry_after_seconds = 1
+                    retry_after_datetime = (Time.now + retry_after_seconds)
+
+                    stub_request(:get, url)
+                      .to_return(status: 429, headers: { 'Retry-After' => retry_after_datetime.rfc2822 })
+                      .to_return(status: 200, body: expected_body)
+
+                    requester = Requester.new(:get, url)
+                    expect(requester).to receive(:sleep).with(1).once
+
+                    result = requester.make_request
+                    expect(result).to eq(expected_body)
+                  end
+
+                  it 'handles a non-integer retry delay' do
+                    retry_after_seconds = 2.75
+                    retry_after_datetime = (Time.now + retry_after_seconds)
+
+                    stub_request(:get, url)
+                      .to_return(status: 429, headers: { 'Retry-After' => retry_after_datetime.rfc2822 })
+                      .to_return(status: 200, body: expected_body)
+
+                    requester = Requester.new(:get, url)
+                    expected_value = a_value_within(1).of(retry_after_seconds)
+                    expect(requester).to receive(:sleep).with(expected_value).once
+
+                    result = requester.make_request
+                    expect(result).to eq(expected_body)
+                  end
+
+                  it 'raises RetryDelayTooLarge if the delay is too large' do
+                    retry_after_seconds = 1 + BerkeleyLibrary::Util::URIs::Requester::MAX_RETRY_DELAY_SECONDS
+                    retry_after_datetime = (Time.now + retry_after_seconds)
+
+                    stub_request(:get, url)
+                      .to_return(status: 429, headers: { 'Retry-After' => retry_after_datetime.rfc2822 })
+
+                    requester = Requester.new(:get, url)
+                    expect(requester).not_to receive(:sleep)
+
+                    expect { requester.make_request }.to raise_error(RetryDelayTooLarge) do |ex|
+                      expect(ex.cause).to be_a(RestClient::TooManyRequests)
+                    end
+                  end
+
+                  it 'raises RetryLimitExceeded if there are too many retries' do
+                    retry_after_seconds = 1
+                    retry_after_datetime = (Time.now + retry_after_seconds)
+
+                    stub_request(:get, url)
+                      .to_return(status: 429, headers: { 'Retry-After' => retry_after_datetime.rfc2822 })
+                      .to_return(status: 429, headers: { 'Retry-After' => retry_after_datetime.rfc2822 })
+
+                    requester = Requester.new(:get, url, max_retries: 1)
+                    expect(requester).to receive(:sleep).with(1).once
+
+                    expect { requester.make_request }.to raise_error(RetryLimitExceeded) do |ex|
+                      expect(ex.cause).to be_a(RestClient::TooManyRequests)
+                    end
+                  end
+
+                end
+
+                it 'ignores an invalid Retry-After' do
+                  stub_request(:get, url)
+                    .to_return(status: 429, headers: { 'Retry-After' => 'the end of the world' })
+
+                  requester = Requester.new(:get, url)
+                  expect { requester.make_request }.to raise_error(RestClient::TooManyRequests)
+                end
+              end
+            end
+
+            context 'handling 503 Service Unavailable' do
+              context 'with Retry-After' do
+                context 'in seconds' do
+                  it 'retries after the specified delay' do
+                    retry_after_seconds = 1
+
+                    stub_request(:get, url)
+                      .to_return(status: 503, headers: { 'Retry-After' => retry_after_seconds.to_s })
+                      .to_return(status: 200, body: expected_body)
+
+                    requester = Requester.new(:get, url)
+                    expect(requester).to receive(:sleep).with(1).once
+
+                    result = requester.make_request
+                    expect(result).to eq(expected_body)
+                  end
+
+                  it 'handles a non-integer retry delay' do
+                    retry_after_seconds = 0.75
+                    stub_request(:get, url)
+                      .to_return(status: 503, headers: { 'Retry-After' => retry_after_seconds.to_s })
+                      .to_return(status: 200, body: expected_body)
+
+                    requester = Requester.new(:get, url)
+                    expect(requester).to receive(:sleep).with(1).once
+
+                    result = requester.make_request
+                    expect(result).to eq(expected_body)
+                  end
+
+                  it 'raises RetryDelayTooLarge if the delay is too large' do
+                    retry_after_seconds = 1 + BerkeleyLibrary::Util::URIs::Requester::MAX_RETRY_DELAY_SECONDS
+
+                    stub_request(:get, url)
+                      .to_return(status: 503, headers: { 'Retry-After' => retry_after_seconds.to_s })
+
+                    requester = Requester.new(:get, url)
+                    expect(requester).not_to receive(:sleep)
+
+                    expect { requester.make_request }.to raise_error(RetryDelayTooLarge) do |ex|
+                      expect(ex.cause).to be_a(RestClient::ServiceUnavailable)
+                    end
+                  end
+                end
+
+                context 'as RFC2822 datetime' do
+                  it 'retries after the specified delay' do
+                    retry_after_seconds = 1
+                    retry_after_datetime = (Time.now + retry_after_seconds)
+
+                    stub_request(:get, url)
+                      .to_return(status: 503, headers: { 'Retry-After' => retry_after_datetime.rfc2822 })
+                      .to_return(status: 200, body: expected_body)
+
+                    requester = Requester.new(:get, url)
+                    expect(requester).to receive(:sleep).with(1).once
+
+                    result = requester.make_request
+                    expect(result).to eq(expected_body)
+                  end
+
+                  it 'handles a non-integer retry delay' do
+                    retry_after_seconds = 1.75
+                    retry_after_datetime = (Time.now + retry_after_seconds)
+
+                    stub_request(:get, url)
+                      .to_return(status: 503, headers: { 'Retry-After' => retry_after_datetime.rfc2822 })
+                      .to_return(status: 200, body: expected_body)
+
+                    requester = Requester.new(:get, url)
+                    expected_value = a_value_within(1).of(retry_after_seconds)
+                    expect(requester).to receive(:sleep).with(expected_value).once
+
+                    result = requester.make_request
+                    expect(result).to eq(expected_body)
+                  end
+
+                  it 'raises RetryDelayTooLarge if the delay is too large' do
+                    retry_after_seconds = 1 + BerkeleyLibrary::Util::URIs::Requester::MAX_RETRY_DELAY_SECONDS
+                    retry_after_datetime = (Time.now + retry_after_seconds)
+
+                    stub_request(:get, url)
+                      .to_return(status: 503, headers: { 'Retry-After' => retry_after_datetime.rfc2822 })
+
+                    requester = Requester.new(:get, url)
+                    expect(requester).not_to receive(:sleep)
+
+                    expect { requester.make_request }.to raise_error(RetryDelayTooLarge) do |ex|
+                      expect(ex.cause).to be_a(RestClient::ServiceUnavailable)
+                    end
+                  end
+                end
+
+                it 'ignores an invalid Retry-After' do
+                  stub_request(:get, url)
+                    .to_return(status: 503, headers: { 'Retry-After' => 'the end of the world' })
+
+                  requester = Requester.new(:get, url)
+                  expect { requester.make_request }.to raise_error(RestClient::ServiceUnavailable)
+                end
+              end
+            end
+          end
+
         end
 
         describe :head do
@@ -145,6 +389,112 @@ module BerkeleyLibrary
             expect { Requester.head(nil) }.to raise_error(ArgumentError)
           end
         end
+
+        describe 'logging' do
+          attr_reader :logger
+
+          before do
+            @logger = instance_double(BerkeleyLibrary::Logging::Logger)
+            allow(BerkeleyLibrary::Logging).to receive(:logger).and_return(logger)
+          end
+
+          context 'GET' do
+            it 'logs request URLs and response codes for successful GET requests' do
+              url = 'https://example.org/'
+              expected_body = 'Help! I am trapped in a unit test'
+              stub_request(:get, url).to_return(body: expected_body)
+
+              expect(logger).to receive(:info).with(/#{url}.*200/)
+              Requester.send(:get, url)
+            end
+
+            it 'can suppress logging for successful GET requests' do
+              url = 'https://example.org/'
+              expected_body = 'Help! I am trapped in a unit test'
+              stub_request(:get, url).to_return(body: expected_body)
+
+              expect(logger).not_to receive(:info)
+              Requester.send(:get, url, log: false)
+            end
+
+            it 'logs request URLs and response codes for failed GET requests' do
+              url = 'https://example.org/'
+              status = 500
+              stub_request(:get, url).to_return(status: status)
+
+              expect(logger).to receive(:info).with(/#{url}.*#{status}/)
+              expect { Requester.send(:get, url) }.to raise_error(RestClient::InternalServerError)
+            end
+
+            it 'can suppress logging for failed GET requests' do
+              url = 'https://example.org/'
+              stub_request(:get, url).to_return(status: 500)
+
+              expect(logger).not_to receive(:info)
+              expect { Requester.send(:get, url, log: false) }.to raise_error(RestClient::InternalServerError)
+            end
+          end
+
+          context 'HEAD' do
+            it 'logs request URLs and response codes for successful HEAD requests' do
+              url = 'https://example.org/'
+              expected_body = 'Help! I am trapped in a unit test'
+              stub_request(:head, url).to_return(body: expected_body)
+
+              expect(logger).to receive(:info).with(/#{url}.*200/)
+              Requester.send(:head, url)
+            end
+
+            it 'can suppress logging for successful HEAD requests' do
+              url = 'https://example.org/'
+              expected_body = 'Help! I am trapped in a unit test'
+              stub_request(:head, url).to_return(body: expected_body)
+
+              expect(logger).not_to receive(:info)
+              Requester.send(:head, url, log: false)
+            end
+
+            it 'logs request URLs and response codes for failed HEAD requests' do
+              url = 'https://example.org/'
+              status = 500
+              stub_request(:head, url).to_return(status: status)
+
+              expect(logger).to receive(:info).with(/#{url}.*#{status}/)
+              expect(Requester.send(:head, url)).to eq(status)
+            end
+
+            it 'can suppress logging for failed HEAD requests' do
+              url = 'https://example.org/'
+              status = 500
+              stub_request(:head, url).to_return(status: status)
+
+              expect(logger).not_to receive(:info)
+              expect(Requester.send(:head, url, log: false)).to eq(status)
+            end
+          end
+        end
+
+        describe :new do
+          it 'rejects invalid URIs' do
+            url = 'not a uri'
+            Requester::SUPPORTED_METHODS.each do |method|
+              expect { Requester.new(method, url) }.to raise_error(URI::InvalidURIError)
+            end
+          end
+
+          it 'rejects nil URIs' do
+            Requester::SUPPORTED_METHODS.each do |method|
+              expect { Requester.new(method, nil) }.to raise_error(ArgumentError)
+            end
+          end
+
+          it 'rejects unsupported methods' do
+            url = 'https://example.org/'
+            %i[put patch post].each do |method|
+              expect { Requester.new(method, url) }.to raise_error(ArgumentError)
+            end
+          end
+        end
       end
     end
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: berkeley_library-util
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.1.8
 platform: ruby
 authors:
 - David Moles
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-03-09 00:00:00.000000000 Z
+date: 2023-03-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: berkeley_library-logging
@@ -241,7 +241,9 @@ files:
 - lib/berkeley_library/util/times.rb
 - lib/berkeley_library/util/uris.rb
 - lib/berkeley_library/util/uris/appender.rb
+- lib/berkeley_library/util/uris/exceptions.rb
 - lib/berkeley_library/util/uris/requester.rb
+- lib/berkeley_library/util/uris/requester/class_methods.rb
 - lib/berkeley_library/util/uris/validator.rb
 - rakelib/.rubocop.yml
 - rakelib/coverage.rake