preservation-client 7.4.0 → 8.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4d817dbb112d807e3b070711015fef2a49f7b750152a2295be3035ae50656ee6
-  data.tar.gz: d68da61d268e666137004c72ce3418d9a3e46694e82007dc540819b1456baa35
+  metadata.gz: 52679fa86a95f4bcf47a2cad9aee26613bae86439a4ef3a0bb0cae6a2a392f4d
+  data.tar.gz: 54c90dd6cc933702c4b4e13f66af27cef44883ac4170b374e9dd79371577b6a0
 SHA512:
-  metadata.gz: 1a10922191104b4055c087b00209e4fe8c03608fa821349e3c50d2f8ec14e403c072d6347efdf038d854f517254511906bcf6ed688d89d073fa3daa072960f03
-  data.tar.gz: 87a123f701eca1f7e7791c42684aa291e0801a1a9d29c26ea08f683cae8f696e02d2d6535cf2b199e240defd885d298ddbcbae490024728cdebbbf07832c09af
+  metadata.gz: aac08ec82147c622ab03f32f61138ca9dcf9ac3bb5b8823d8037b685768f492e33ce57164656ed5f667696a02821769175bf9ce424988aec29900d72e7d6f669
+  data.tar.gz: 15e40540086779cb3d93786ba6c0b0d17d86c8c316ea66e5785afd4f85e6dced4d01cc2a00bf5ebe263ecb2a6a05c73533f53ff05a45e5798f74cd606342f54c

data/.circleci/config.yml

@@ -1,6 +1,6 @@
 version: 2.1
 orbs:
-  ruby-rails: sul-dlss/ruby-rails@4.8.0
+  ruby-rails: sul-dlss/ruby-rails@4.12.0
 workflows:
   build:
     jobs:

data/Gemfile.lock

@@ -1,9 +1,10 @@
 PATH
   remote: .
   specs:
-    preservation-client (7.4.0)
+    preservation-client (8.1.0)
       activesupport (>= 4.2)
       faraday (~> 2.0)
+      faraday-retry (~> 2.0)
       moab-versioning (>= 5.0.0, < 7)
       zeitwerk (~> 2.1)
 
@@ -31,27 +32,28 @@ GEM
     byebug (13.0.0)
       reline (>= 0.6.0)
     coderay (1.1.3)
-    concurrent-ruby (1.3.6)
+    concurrent-ruby (1.3.7)
     connection_pool (3.0.2)
     crack (1.0.1)
       bigdecimal
       rexml
     diff-lcs (1.6.2)
-    docile (1.4.1)
     drb (2.2.3)
     druid-tools (3.0.0)
-    faraday (2.14.2)
+    faraday (2.14.3)
       faraday-net_http (>= 2.0, < 3.5)
       json
       logger
-    faraday-net_http (3.4.2)
+    faraday-net_http (3.4.4)
       net-http (~> 0.5)
+    faraday-retry (2.4.0)
+      faraday (~> 2.0)
     hashdiff (1.2.1)
-    i18n (1.14.8)
+    i18n (1.15.2)
       concurrent-ruby (~> 1.0)
     io-console (0.8.2)
-    json (2.19.5)
-    language_server-protocol (3.17.0.5)
+    json (2.21.1)
+    language_server-protocol (3.17.0.6)
     lint_roller (1.1.0)
     logger (1.7.0)
     method_source (1.1.0)
@@ -65,11 +67,11 @@ GEM
       nokogiri-happymapper
     net-http (0.9.1)
       uri (>= 0.11.1)
-    nokogiri (1.19.3-arm64-darwin)
+    nokogiri (1.19.4-arm64-darwin)
       racc (~> 1.4)
-    nokogiri (1.19.3-x86_64-darwin)
+    nokogiri (1.19.4-x86_64-darwin)
       racc (~> 1.4)
-    nokogiri (1.19.3-x86_64-linux-gnu)
+    nokogiri (1.19.4-x86_64-linux-gnu)
       racc (~> 1.4)
     nokogiri-happymapper (0.10.1)
       nokogiri (~> 1.5)
@@ -106,7 +108,7 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
     rspec-support (3.13.7)
-    rubocop (1.86.2)
+    rubocop (1.88.2)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -117,23 +119,19 @@ GEM
       rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.49.1)
+    rubocop-ast (1.50.0)
       parser (>= 3.3.7.2)
       prism (~> 1.7)
     rubocop-rake (0.7.1)
       lint_roller (~> 1.1)
       rubocop (>= 1.72.1)
-    rubocop-rspec (3.9.0)
+    rubocop-rspec (3.10.2)
       lint_roller (~> 1.1)
-      rubocop (~> 1.81)
+      regexp_parser (>= 2.0)
+      rubocop (~> 1.86, >= 1.86.2)
     ruby-progressbar (1.13.0)
     securerandom (0.4.1)
-    simplecov (0.22.0)
-      docile (~> 1.1)
-      simplecov-html (~> 0.11)
-      simplecov_json_formatter (~> 0.1)
-    simplecov-html (0.13.2)
-    simplecov_json_formatter (0.1.4)
+    simplecov (1.0.0)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
     unicode-display_width (3.2.0)
@@ -144,7 +142,7 @@ GEM
       addressable (>= 2.8.0)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)
-    zeitwerk (2.7.5)
+    zeitwerk (2.8.2)
 
 PLATFORMS
   arm64-darwin-23

data/README.md

@@ -60,6 +60,11 @@ See https://github.com/sul-dlss/preservation_catalog#api for info on obtaining a
 
 Note that the preservation service is behind a firewall.
 
+### Retries
+HTTP GET requests will be automatically retried for certain errors. The number of retries (`retries_max`) and interval between retries (`retry_interval`) can be specified as part of the configuration of the client.
+
+Note that there is special retry behavior (cleaning up files on failure) for `content_to_file`, but it uses the same configuration.
+
 ## API Coverage
 
 - druids may be with or without the "druid:" prefix - 'oo000oo0000' or 'druid:oo000oo0000'
@@ -110,7 +115,7 @@ Behavior notes:
 
 ### Validate the Moab
 
-- `client.objects.validate_moab(druid: 'ooo000oo0000')` - validates that the Moab object, used by preservationWF to ensure we have a valid Moab before replicating to various preservation endpoints
+- `client.objects.validate_moab(druid: 'ooo000oo0000', lane_id: 'high)` - validates that the Moab object, used by preservationWF to ensure we have a valid Moab before replicating to various preservation endpoints
 
 ### Get difference information between passed contentMetadata.xml and files in the Moab
 

data/lib/preservation/client/objects.rb

@@ -11,6 +11,12 @@ module Preservation
   class Client
     # API calls that are about Preserved Objects
     class Objects < VersionedApiService # rubocop:disable Metrics/ClassLength
+      def initialize(connection:, streaming_connection:, retry_max:, retry_interval:, api_version: DEFAULT_API_VERSION)
+        super(connection: connection, streaming_connection: streaming_connection, api_version: api_version)
+        @retry_max = retry_max
+        @retry_interval = retry_interval
+      end
+
       # @param [String] druid - with or without prefix: 'druid:bb123cd4567' OR 'bb123cd4567'
       # @return [Hash] the checksums and filesize for the druid
       def checksum(druid:)
@@ -69,14 +75,14 @@ module Preservation
       # @param [String] destination_filepath - absolute or relative path to desired destination file
       # @param [String] version - the version of the file requested (defaults to nil for latest version)
       # @param [String, nil] expected_md5 - optional expected md5 checksum for integrity validation
-      # @param [Integer] max_retries - number of retry attempts after the initial attempt
-      # @param [Float] delay_seconds - base delay for retry backoff
+      # @param [Integer] max - number of retry attempts after the initial attempt
+      # @param [Float] interval - base delay in seconds for exponential retry backoff
       # @raise [Preservation::Client::IntegrityError] if the expected_md5 is provided and does not match the actual md5
       # @raise [Preservation::Client::NotFoundError] if the specified file is not found
       # @raise [Preservation::Client::Error] for other errors encountered during download
       def content_to_file(druid:, filepath:, destination_filepath:, version: nil, expected_md5: nil, # rubocop:disable Metrics/ParameterLists
-                          max_retries: 3, delay_seconds: 0.5)
-        with_retries(max_retries: max_retries, delay_seconds: delay_seconds) do
+                          max: nil, interval: nil)
+        with_retries(max: max || @retry_max, interval: interval || @retry_interval) do
           temp_filepath = nil
 
           begin
@@ -112,10 +118,11 @@ module Preservation
       # calls the endpoint to queue a ValidateMoab job for a specific druid
       # typically called by a preservationIngestWF robot
       # @param [String] druid - with or without prefix: 'druid:ab123cd4567' or 'ab123cd4567'
+      # @param [String, nil] lane_id - low, default, or high
       # @return [String] "ok" when job queued
       # @raise [Preservation::Client::NotFoundError] when druid is not found
-      def validate_moab(druid:)
-        get("objects/#{druid}/validate_moab", {}, on_data: nil)
+      def validate_moab(druid:, lane_id: nil)
+        get("objects/#{druid}/validate_moab", { 'lane-id': lane_id }.compact, on_data: nil)
       end
 
       # convenience method for retrieving latest Moab::SignatureCatalog from a Moab object,
@@ -138,16 +145,15 @@ module Preservation
         get("objects/#{druid}/file", { category: category, filepath: filepath, version: version }, on_data: on_data)
       end
 
-      def with_retries(max_retries:, delay_seconds:)
+      def with_retries(max:, interval:)
         attempt = 0
 
         begin
           yield
         rescue StandardError => e
-          raise if !retryable_error?(e) || attempt >= max_retries
+          raise if !retryable_error?(e) || attempt >= max
 
-          sleep_seconds = delay_seconds.to_f * (attempt + 1)
-          sleep(sleep_seconds) unless sleep_seconds.nil?
+          sleep(interval.to_f * (Client::RETRY_BACKOFF_FACTOR**attempt))
           attempt += 1
           retry
         end

data/lib/preservation/client/version.rb

@@ -2,6 +2,6 @@
 
 module Preservation
   class Client
-    VERSION = '7.4.0'
+    VERSION = '8.1.0'
   end
 end

data/lib/preservation/client/versioned_api_service.rb

@@ -4,14 +4,15 @@ module Preservation
   class Client
     # @abstract API calls to a versioned endpoint
     class VersionedApiService
-      def initialize(connection:, api_version: DEFAULT_API_VERSION)
+      def initialize(connection:, api_version: DEFAULT_API_VERSION, streaming_connection: nil)
         @connection = connection
         @api_version = api_version
+        @streaming_connection = streaming_connection
       end
 
       private
 
-      attr_reader :connection, :api_version
+      attr_reader :connection, :api_version, :streaming_connection
 
       # @param path [String] path to be appended to connection url (no leading slash)
       def get_json(path, object_id)
@@ -42,7 +43,7 @@ module Preservation
         return http_response(:get, path, params) unless on_data
 
         req_url = "#{api_version}/#{path}"
-        connection.get("#{api_version}/#{path}", params) do |req|
+        (streaming_connection || connection).get("#{api_version}/#{path}", params) do |req|
           req.options.on_data = proc do |chunk, size, env|
             if env.status >= 300
               errmsg = "Preservation::Client.#{caller_locations.first.label} " \

data/lib/preservation/client.rb

@@ -4,6 +4,7 @@ require 'active_support/core_ext/hash/indifferent_access'
 require 'active_support/core_ext/module/delegation'
 require 'active_support/core_ext/object/blank'
 require 'faraday'
+require 'faraday/retry'
 require 'singleton'
 require 'zeitwerk'
 
@@ -53,13 +54,18 @@ module Preservation
 
     DEFAULT_API_VERSION = 'v1'
     DEFAULT_TIMEOUT = 300
+    DEFAULT_RETRY_MAX = 3
+    DEFAULT_RETRY_INTERVAL = 0.5
+    RETRY_BACKOFF_FACTOR = 2
     TOKEN_HEADER = 'Authorization'
 
     include Singleton
 
     # @return [Preservation::Client::Objects] an instance of the `Client::Objects` class
     def objects
-      @objects ||= Objects.new(connection: connection, api_version: DEFAULT_API_VERSION)
+      @objects ||= Objects.new(connection: connection, streaming_connection: streaming_connection,
+                               retry_max: retry_max, retry_interval: retry_interval,
+                               api_version: DEFAULT_API_VERSION)
     end
 
     # @return [Preservation::Client::Catalog] an instance of the `Client::Catalog` class
@@ -71,13 +77,19 @@ module Preservation
       # @param [String] url the endpoint URL
       # @param [String] token a bearer token for HTTP authentication
       # @param [Integer] read_timeout the value in seconds of the read timeout
-      def configure(url:, token:, read_timeout: DEFAULT_TIMEOUT)
+      # @param [Integer] retry_max number of retry attempts for GET requests
+      # @param [Float] retry_interval base delay in seconds between retries (exponential backoff)
+      def configure(url:, token:, read_timeout: DEFAULT_TIMEOUT,
+                    retry_max: DEFAULT_RETRY_MAX, retry_interval: DEFAULT_RETRY_INTERVAL)
         instance.url = url
         instance.token = token
         instance.read_timeout = read_timeout
+        instance.retry_max = retry_max
+        instance.retry_interval = retry_interval
 
-        # Force connection to be re-established when `.configure` is called
+        # Force connections to be re-established when `.configure` is called
         instance.connection = nil
+        instance.streaming_connection = nil
 
         self
       end
@@ -85,7 +97,7 @@ module Preservation
       delegate :objects, :update, to: :instance
     end
 
-    attr_writer :connection, :read_timeout, :token, :url
+    attr_writer :connection, :read_timeout, :retry_interval, :retry_max, :streaming_connection, :token, :url
 
     delegate :update, to: :catalog
 
@@ -103,11 +115,35 @@ module Preservation
       @read_timeout || raise(Error, 'read timeout has not been configured')
     end
 
+    def retry_max
+      @retry_max || raise(Error, 'retry_max has not been configured')
+    end
+
+    def retry_interval
+      @retry_interval || raise(Error, 'retry_interval has not been configured')
+    end
+
     def connection
-      @connection ||= Faraday.new(url, request: { read_timeout: read_timeout }) do |builder|
+      @connection ||= build_connection(with_retry: true)
+    end
+
+    def streaming_connection
+      @streaming_connection ||= build_connection(with_retry: false)
+    end
+
+    def build_connection(with_retry: true) # rubocop:disable Metrics/AbcSize
+      Faraday.new(url, request: { read_timeout: read_timeout }) do |builder|
         builder.use ErrorFaradayMiddleware
+        if with_retry
+          builder.request :retry, max: retry_max,
+                                  interval: retry_interval,
+                                  backoff_factor: RETRY_BACKOFF_FACTOR,
+                                  methods: [:get],
+                                  exceptions: Faraday::Retry::Middleware::DEFAULT_EXCEPTIONS +
+                                              [Faraday::ConnectionFailed, Faraday::SSLError, Faraday::ServerError]
+        end
         builder.use Faraday::Request::UrlEncoded
-        builder.use Faraday::Response::RaiseError # raise exceptions on 40x, 50x responses
+        builder.use Faraday::Response::RaiseError
         builder.adapter Faraday.default_adapter
         builder.headers[:user_agent] = user_agent
         builder.headers[TOKEN_HEADER] = "Bearer #{token}"

data/preservation-client.gemspec

@@ -31,6 +31,7 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency 'activesupport', '>= 4.2'
   spec.add_dependency 'faraday', '~> 2.0'
+  spec.add_dependency 'faraday-retry', '~> 2.0'
   spec.add_dependency 'moab-versioning', '>= 5.0.0', '< 7'
   spec.add_dependency 'zeitwerk', '~> 2.1'
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: preservation-client
 version: !ruby/object:Gem::Version
-  version: 7.4.0
+  version: 8.1.0
 platform: ruby
 authors:
 - Naomi Dushay
 bindir: exe
 cert_chain: []
-date: 2026-05-18 00:00:00.000000000 Z
+date: 2026-07-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -37,6 +37,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: moab-versioning
   requirement: !ruby/object:Gem::Requirement