preservation-client 7.3.0 → 8.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 164a8df77b290866471041f9da4a8cd1950e54e3caf5df094e4201c997b6c1c7
-  data.tar.gz: 93d3fd16f175e7ecdee4538b917698c1be483c9d8233b6d8b1a79306b4be3567
+  metadata.gz: c187f939eb6d782795bb422308b7417f024db4c4e9d4d36e0685d7060c4150a0
+  data.tar.gz: 9c3f855e31677b447712ba3c35d67e0ab1127b83a469fc17664be82ac0b28f70
 SHA512:
-  metadata.gz: ad80fe3e37727f57c9e28ab83cac8f058013a9764cce950ab46a535eac845cffd7a5e9b6fcb8149849d87810d319aed4305a1661f9ad29760c5d2d47f4b7d56f
-  data.tar.gz: c7e0a0cef3816863d13b3019ccd21f9465e07236a14f058cf748ddfaa19a51f08b3d0f39fb7a3024025495d961b16bd85400e2566ad03b09efc4b52b3ebaee11
+  metadata.gz: 9800102447b72c245667cd69cc90c97878a11a28663cb56012d21678355cc4e4e90dccc6e98a8481cab53ec64507e66a5968ef63d01b083b10959e79424bb54b
+  data.tar.gz: ab270e3e62cba84ed0e560b63ab392fd48c07854b35f37abb0e0251d471d78e48df5a7cf3d8a78fb93c06a7450ea1656d99624ac1ff283e799a5f18e410c7dec

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/.rubocop.yml

@@ -45,7 +45,7 @@ RSpec/ExampleLength:
 
 # most tests should test a single thing
 RSpec/MultipleExpectations:
-  Max: 5 # default 1
+  Enabled: false
 
 RSpec/MultipleMemoizedHelpers:
   Enabled: false

data/Gemfile.lock

@@ -1,9 +1,10 @@
 PATH
   remote: .
   specs:
-    preservation-client (7.3.0)
+    preservation-client (8.0.0)
       activesupport (>= 4.2)
       faraday (~> 2.0)
+      faraday-retry (~> 2.0)
       moab-versioning (>= 5.0.0, < 7)
       zeitwerk (~> 2.1)
 
@@ -31,7 +32,7 @@ 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
@@ -40,17 +41,19 @@ GEM
     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)
+    json (2.20.0)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
     logger (1.7.0)
@@ -65,11 +68,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 +109,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.0)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -123,9 +126,10 @@ GEM
     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)
@@ -144,7 +148,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'
@@ -87,6 +92,27 @@ Note that the preservation service is behind a firewall.
     - `client.objects.metadata(druid: 'oo000oo0000', filepath: 'identityMetadata.xml', version: '8')` - returns contents of identityMetadata.xml in version 8 of Moab object
 - `client.objects.signature_catalog('oo000oo0000')` - returns latest Moab::SignatureCatalog from Moab
 
+### Download content files safely to disk
+
+- `client.objects.content_to_file(...)` streams content to a tempfile in the destination directory, verifies integrity when requested, and atomically replaces the destination on success.
+
+```ruby
+client.objects.content_to_file(
+  druid: 'oo000oo0000',
+  filepath: 'my_file.pdf',
+  destination_filepath: '/tmp/my_file.pdf',
+  version: '1',
+  expected_md5: 'ffc0cc90e4215e0a3d822b04a8eab980'
+)
+```
+
+Behavior notes:
+
+- Retries transient failures (`ConnectionFailedError`, HTTP 5xx).
+- Does not retry other errors or integrity failures.
+- Raises `Preservation::Client::IntegrityError` on MD5 mismatch.
+- Removes temp files on success and failure and never promotes partial downloads to the destination path.
+
 ### 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

data/lib/preservation/client/objects.rb

@@ -1,13 +1,22 @@
 # frozen_string_literal: true
 
+require 'digest'
+require 'fileutils'
 require 'moab'
+require 'tempfile'
 
 # NOTE:  this class makes use of data structures from moab-versioning gem,
 #  but it does NOT directly access any preservation storage roots
 module Preservation
   class Client
     # API calls that are about Preserved Objects
-    class Objects < VersionedApiService
+    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:)
@@ -60,6 +69,36 @@ module Preservation
         file(druid, 'content', filepath, version, on_data: on_data)
       end
 
+      # retrieve a content file from a Moab object and write it to destination atomically
+      # @param [String] druid - with or without prefix: 'druid:ab123cd4567' OR 'ab123cd4567'
+      # @param [String] filepath - the path of the file relative to the moab content directory
+      # @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 - 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: nil, interval: nil)
+        with_retries(max: max || @retry_max, interval: interval || @retry_interval) do
+          temp_filepath = nil
+
+          begin
+            temp_filepath = download_to_tempfile(druid: druid, filepath: filepath,
+                                                 destination_filepath: destination_filepath,
+                                                 version: version)
+            verify_md5!(filepath: temp_filepath, expected_md5: expected_md5) if expected_md5
+
+            File.rename(temp_filepath, destination_filepath)
+            temp_filepath = nil
+          ensure
+            cleanup_tempfile(temp_filepath)
+          end
+        end
+      end
+
       # retrieve a manifest file from a Moab object
       # @param [String] druid - with or without prefix: 'druid:ab123cd4567' OR 'ab123cd4567'
       # @param [String] filepath - the path of the file relative to the moab manifest directory
@@ -104,6 +143,70 @@ module Preservation
       def file(druid, category, filepath, version, on_data: nil)
         get("objects/#{druid}/file", { category: category, filepath: filepath, version: version }, on_data: on_data)
       end
+
+      def with_retries(max:, interval:)
+        attempt = 0
+
+        begin
+          yield
+        rescue StandardError => e
+          raise if !retryable_error?(e) || attempt >= max
+
+          sleep(interval.to_f * (Client::RETRY_BACKOFF_FACTOR**attempt))
+          attempt += 1
+          retry
+        end
+      end
+
+      def download_to_tempfile(druid:, filepath:, destination_filepath:, version: nil)
+        destination_dir = File.dirname(destination_filepath)
+        FileUtils.mkdir_p(destination_dir)
+
+        tempfile = Tempfile.create(['preservation-client-', '.tmp'], destination_dir)
+        tempfile.binmode
+        temp_filepath = tempfile.path
+
+        begin
+          content(druid: druid, filepath: filepath, version: version,
+                  on_data: proc do |chunk, _size, _env|
+                    tempfile.write(chunk)
+                  end)
+          tempfile.flush
+          tempfile.fsync
+        rescue StandardError
+          cleanup_tempfile(temp_filepath)
+          raise
+        ensure
+          tempfile.close
+        end
+
+        temp_filepath
+      end
+
+      def verify_md5!(filepath:, expected_md5:)
+        actual_md5 = Digest::MD5.file(filepath).hexdigest
+        return if actual_md5.casecmp?(expected_md5)
+
+        raise IntegrityError,
+              "Downloaded file md5 mismatch for #{filepath}: expected #{expected_md5}, got #{actual_md5}"
+      end
+
+      def retryable_error?(error)
+        return true if error.is_a?(ConnectionFailedError)
+
+        return true if error.is_a?(Error) && (500..599).cover?(error.status)
+
+        false
+      end
+
+      def cleanup_tempfile(path)
+        return if path.nil?
+        return unless File.exist?(path)
+
+        File.delete(path)
+      rescue Errno::ENOENT
+        nil
+      end
     end
   end
 end

data/lib/preservation/client/version.rb

@@ -2,6 +2,6 @@
 
 module Preservation
   class Client
-    VERSION = '7.3.0'
+    VERSION = '8.0.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,12 +43,12 @@ 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} " \
                        "got #{env.status} from Preservation at #{req_url}"
-              raise http_exception_class(env.status), errmsg
+              raise http_exception_class(env.status).new(errmsg, status: env.status)
             end
             on_data.call(chunk, size, env)
           end
@@ -103,7 +104,7 @@ module Preservation
       rescue Faraday::Error => e
         errmsg = "Preservation::Client.#{caller_locations.first.label} " \
                  "got #{e.response[:status]} from Preservation at #{req_url}: #{e.response[:body]}"
-        raise http_exception_class(e.response[:status]), errmsg
+        raise http_exception_class(e.response[:status]).new(errmsg, status: e.response[:status])
       end
 
       # @param status_code [Integer] the HTTP status code to translate to an exception class

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'
 
@@ -15,7 +16,15 @@ loader.setup
 module Preservation
   # REST API client wrapper for PreservationCatalog with error handling
   class Client
-    class Error < StandardError; end
+    # Base error class for preservation-client errors
+    class Error < StandardError
+      attr_reader :status
+
+      def initialize(message = nil, status: nil)
+        super(message)
+        @status = status
+      end
+    end
 
     # Error raised when server returns 404 Not Found
     class NotFoundError < Error; end
@@ -34,6 +43,9 @@ module Preservation
     # timeouts
     class ConnectionFailedError < Error; end
 
+    # Error raised when downloaded file integrity verification fails
+    class IntegrityError < Error; end
+
     Object = Struct.new('Object', :druid, :current_version, :ok_on_local_storage) do
       def ok_on_local_storage?
         ok_on_local_storage
@@ -42,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
@@ -60,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
@@ -74,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
 
@@ -92,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.3.0
+  version: 8.0.0
 platform: ruby
 authors:
 - Naomi Dushay
 bindir: exe
 cert_chain: []
-date: 2026-05-18 00:00:00.000000000 Z
+date: 2026-06-29 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