preservation-client 7.3.0 → 7.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 164a8df77b290866471041f9da4a8cd1950e54e3caf5df094e4201c997b6c1c7
-  data.tar.gz: 93d3fd16f175e7ecdee4538b917698c1be483c9d8233b6d8b1a79306b4be3567
+  metadata.gz: 4d817dbb112d807e3b070711015fef2a49f7b750152a2295be3035ae50656ee6
+  data.tar.gz: d68da61d268e666137004c72ce3418d9a3e46694e82007dc540819b1456baa35
 SHA512:
-  metadata.gz: ad80fe3e37727f57c9e28ab83cac8f058013a9764cce950ab46a535eac845cffd7a5e9b6fcb8149849d87810d319aed4305a1661f9ad29760c5d2d47f4b7d56f
-  data.tar.gz: c7e0a0cef3816863d13b3019ccd21f9465e07236a14f058cf748ddfaa19a51f08b3d0f39fb7a3024025495d961b16bd85400e2566ad03b09efc4b52b3ebaee11
+  metadata.gz: 1a10922191104b4055c087b00209e4fe8c03608fa821349e3c50d2f8ec14e403c072d6347efdf038d854f517254511906bcf6ed688d89d073fa3daa072960f03
+  data.tar.gz: 87a123f701eca1f7e7791c42684aa291e0801a1a9d29c26ea08f683cae8f696e02d2d6535cf2b199e240defd885d298ddbcbae490024728cdebbbf07832c09af

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,7 +1,7 @@
 PATH
   remote: .
   specs:
-    preservation-client (7.3.0)
+    preservation-client (7.4.0)
       activesupport (>= 4.2)
       faraday (~> 2.0)
       moab-versioning (>= 5.0.0, < 7)

data/README.md

@@ -87,6 +87,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,16 @@
 # 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
       # @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 +63,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_retries - number of retry attempts after the initial attempt
+      # @param [Float] delay_seconds - base delay for 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
+          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 +137,71 @@ 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_retries:, delay_seconds:)
+        attempt = 0
+
+        begin
+          yield
+        rescue StandardError => e
+          raise if !retryable_error?(e) || attempt >= max_retries
+
+          sleep_seconds = delay_seconds.to_f * (attempt + 1)
+          sleep(sleep_seconds) unless sleep_seconds.nil?
+          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 = '7.4.0'
   end
 end

data/lib/preservation/client/versioned_api_service.rb

@@ -47,7 +47,7 @@ module Preservation
             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 +103,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

@@ -15,7 +15,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 +42,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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: preservation-client
 version: !ruby/object:Gem::Version
-  version: 7.3.0
+  version: 7.4.0
 platform: ruby
 authors:
 - Naomi Dushay