Fix :checksum_mode param in S3::FileDownloader

gems/aws-sdk-s3/CHANGELOG.md

@@ -1,6 +1,8 @@
 Unreleased Changes
 ------------------
 
+* Issue - Deprecated `:checksum_mode` parameter in `FileDownloader#download`. When set to "DISABLED", a deprecation warning is issued and the parameter is ignored. Use `:response_checksum_validation` on the S3 client instead to control checksum validation behavior.
+
 1.203.0 (2025-11-05)
 ------------------
 

gems/aws-sdk-s3/lib/aws-sdk-s3/customizations/object.rb

@@ -518,10 +518,9 @@ def upload_file(source, options = {})
       # @option options [Integer] :thread_count (10) Customize threads used in the multipart download.
       #
       # @option options [String] :checksum_mode ("ENABLED")
-      #   When `"ENABLED"` and the object has a stored checksum, it will be used to validate the download and will
-      #   raise an `Aws::Errors::ChecksumError` if checksum validation fails. You may provide a `on_checksum_validated`
-      #   callback if you need to verify that validation occurred and which algorithm was used.
-      #   To disable checksum validation, set `checksum_mode` to `"DISABLED"`.
+      #   This option is deprecated. Use `:response_checksum_validation` on your S3 client instead.
+      #   To disable checksum validation, set `response_checksum_validation: 'when_required'`
+      #   when creating your S3 client.
       #
       # @option options [Callable] :on_checksum_validated
       #   Called each time a request's checksum is validated with the checksum algorithm and the

gems/aws-sdk-s3/lib/aws-sdk-s3/file_downloader.rb

@@ -90,12 +90,29 @@ def download_with_executor(part_list, total_size, opts)
         raise error unless error.nil?
       end
 
+      def handle_checksum_mode_option(option_key, opts)
+        return false unless option_key == :checksum_mode && opts[:checksum_mode] == 'DISABLED'
+
+        msg = ':checksum_mode option is deprecated. Checksums will be validated by default. ' \
+          'To disable checksum validation, set :response_checksum_validation to "when_required" on your S3 client.'
+        warn(msg)
+        true
+      end
+
       def get_opts(opts)
-        GET_OPTIONS.each_with_object({}) { |k, h| h[k] = opts[k] if opts.key?(k) }
+        GET_OPTIONS.each_with_object({}) do |k, h|
+          next if k == :checksum_mode
+
+          h[k] = opts[k] if opts.key?(k)
+        end
       end
 
       def head_opts(opts)
-        HEAD_OPTIONS.each_with_object({}) { |k, h| h[k] = opts[k] if opts.key?(k) }
+        HEAD_OPTIONS.each_with_object({}) do |k, h|
+          next if handle_checksum_mode_option(k, opts)
+
+          h[k] = opts[k] if opts.key?(k)
+        end
       end
 
       def compute_chunk(chunk_size, file_size)

gems/aws-sdk-s3/lib/aws-sdk-s3/transfer_manager.rb

@@ -124,10 +124,9 @@ def initialize(options = {})
       #   Only used when no custom executor is provided (creates {DefaultExecutor} with given thread count).
       #
       # @option options [String] :checksum_mode ("ENABLED")
-      #   When `"ENABLED"` and the object has a stored checksum, it will be used to validate the download and will
-      #   raise an `Aws::Errors::ChecksumError` if checksum validation fails. You may provide a `on_checksum_validated`
-      #   callback if you need to verify that validation occurred and which algorithm was used.
-      #   To disable checksum validation, set `checksum_mode` to `"DISABLED"`.
+      #   This option is deprecated. Use `:response_checksum_validation` on your S3 client instead.
+      #   To disable checksum validation, set `response_checksum_validation: 'when_required'`
+      #   when creating your S3 client.
       #
       # @option options [Callable] :on_checksum_validated
       #   Called each time a request's checksum is validated with the checksum algorithm and the

gems/aws-sdk-s3/spec/file_downloader_spec.rb

@@ -121,16 +121,8 @@ module S3
           expect(callback_data[:called]).to eq(4)
         end
 
-        it 'supports disabling checksum_mode' do
-          client.stub_responses(:head_object, lambda { |context|
-            expect(context.params[:checksum_mode]).to eq('DISABLED')
-            { content_length: one_meg, parts_count: nil }
-          })
-          client.stub_responses(:get_object, lambda { |context|
-            expect(context.params[:checksum_mode]).to eq('DISABLED')
-            { body: 'body' }
-          })
-
+        it 'warns when :checksum_mode is set to DISABLED' do
+          expect(subject).to receive(:warn).with(/checksum_mode option is deprecated/)
           subject.download(path, single_params.merge(checksum_mode: 'DISABLED'))
         end