aws-sdk-s3 1.176.1 → 1.208.0

data/lib/aws-sdk-s3/object_version.rb

@@ -62,6 +62,18 @@ module Aws::S3
       data[:checksum_algorithm]
     end
 
+    # The checksum type that is used to calculate the object’s checksum
+    # value. For more information, see [Checking object integrity][1] in the
+    # *Amazon S3 User Guide*.
+    #
+    #
+    #
+    # [1]: https://docs.aws.amazon.com/AmazonS3/latest/userguide/checking-object-integrity.html
+    # @return [String]
+    def checksum_type
+      data[:checksum_type]
+    end
+
     # Size in bytes of the object.
     # @return [Integer]
     def size
@@ -300,21 +312,19 @@ module Aws::S3
     #   you provide does not match the actual owner of the bucket, the request
     #   fails with the HTTP status code `403 Forbidden` (access denied).
     # @option options [String] :if_match
-    #   The `If-Match` header field makes the request method conditional on
-    #   ETags. If the ETag value does not match, the operation returns a `412
-    #   Precondition Failed` error. If the ETag matches or if the object
-    #   doesn't exist, the operation will return a `204 Success (No Content)
-    #   response`.
-    #
-    #   For more information about conditional requests, see [RFC 7232][1].
+    #   Deletes the object if the ETag (entity tag) value provided during the
+    #   delete operation matches the ETag of the object in S3. If the ETag
+    #   values do not match, the operation returns a `412 Precondition Failed`
+    #   error.
     #
-    #   <note markdown="1"> This functionality is only supported for directory buckets.
+    #   Expects the ETag value as a string. `If-Match` does accept a string
+    #   value of an '*' (asterisk) character to denote a match of any ETag.
     #
-    #    </note>
+    #   For more information about conditional requests, see [RFC 7232][1].
     #
     #
     #
-    #   [1]: https://docs.aws.amazon.com/https:/tools.ietf.org/html/rfc7232
+    #   [1]: https://tools.ietf.org/html/rfc7232
     # @option options [Time,DateTime,Date,Integer,String] :if_match_last_modified_time
     #   If present, the object is deleted only if its modification times
     #   matches the provided `Timestamp`. If the `Timestamp` values do not
@@ -566,15 +576,6 @@ module Aws::S3
     #   fails with the HTTP status code `403 Forbidden` (access denied).
     # @option options [String] :checksum_mode
     #   To retrieve the checksum, this mode must be enabled.
-    #
-    #   **General purpose buckets** - In addition, if you enable checksum mode
-    #   and the object is uploaded with a [checksum][1] and encrypted with an
-    #   Key Management Service (KMS) key, you must have permission to use the
-    #   `kms:Decrypt` action to retrieve the checksum.
-    #
-    #
-    #
-    #   [1]: https://docs.aws.amazon.com/AmazonS3/latest/API/API_Checksum.html
     # @return [Types::GetObjectOutput]
     def get(options = {}, &block)
       options = options.merge(
@@ -848,7 +849,7 @@ module Aws::S3
       #     request_payer: "requester", # accepts requester
       #     bypass_governance_retention: false,
       #     expected_bucket_owner: "AccountId",
-      #     checksum_algorithm: "CRC32", # accepts CRC32, CRC32C, SHA1, SHA256
+      #     checksum_algorithm: "CRC32", # accepts CRC32, CRC32C, SHA1, SHA256, CRC64NVME
       #   })
       # @param options ({})
       # @option options [String] :mfa
@@ -916,6 +917,8 @@ module Aws::S3
       #
       #   * `CRC32C`
       #
+      #   * `CRC64NVME`
+      #
       #   * `SHA1`
       #
       #   * `SHA256`
@@ -925,9 +928,8 @@ module Aws::S3
       #
       #   If the individual checksum value you provide through
       #   `x-amz-checksum-algorithm ` doesn't match the checksum algorithm you
-      #   set through `x-amz-sdk-checksum-algorithm`, Amazon S3 ignores any
-      #   provided `ChecksumAlgorithm` parameter and uses the checksum algorithm
-      #   that matches the provided value in `x-amz-checksum-algorithm `.
+      #   set through `x-amz-sdk-checksum-algorithm`, Amazon S3 fails the
+      #   request with a `BadDigest` error.
       #
       #   If you provide an individual checksum, Amazon S3 ignores any provided
       #   `ChecksumAlgorithm` parameter.

data/lib/aws-sdk-s3/plugins/checksum_algorithm.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Aws
+  module S3
+    module Plugins
+      # @api private
+      class ChecksumAlgorithm < Seahorse::Client::Plugin
+
+        # S3 GetObject results for whole Multipart Objects contain a checksum
+        # that cannot be validated. These should be skipped by the
+        # ChecksumAlgorithm plugin.
+        class SkipWholeMultipartGetChecksumsHandler < Seahorse::Client::Handler
+          def call(context)
+            context[:http_checksum] ||= {}
+            context[:http_checksum][:skip_on_suffix] = true
+
+            @handler.call(context)
+          end
+        end
+
+        def add_handlers(handlers, _config)
+          handlers.add(
+            SkipWholeMultipartGetChecksumsHandler,
+            step: :initialize,
+            operations: [:get_object]
+          )
+        end
+      end
+    end
+  end
+end

data/lib/aws-sdk-s3/plugins/endpoints.rb

@@ -25,7 +25,7 @@ The endpoint provider used to resolve endpoints. Any object that responds to
 
       option(
         :disable_s3_express_session_auth,
-        doc_type: 'Boolean',
+        doc_type: 'boolean',
         docstring: <<~DOCS) do |cfg|
 Parameter to indicate whether S3Express session auth should be disabled
         DOCS

data/lib/aws-sdk-s3/plugins/express_session_auth.rb

@@ -29,24 +29,17 @@ for different buckets.
         # @api private
         class Handler < Seahorse::Client::Handler
           def call(context)
-            if (props = context[:endpoint_properties])
-              # S3 Express endpoint - turn off md5 and enable crc32 default
-              if props['backend'] == 'S3Express'
-                if context.operation_name == :put_object || checksum_required?(context)
-                  context[:default_request_checksum_algorithm] = 'CRC32'
-                end
-                context[:s3_express_endpoint] = true
-              end
+            context[:s3_express_endpoint] = true if s3_express_endpoint?(context)
 
-              # if s3 express auth, use new credentials and sign additional header
-              if context[:auth_scheme]['name'] == 'sigv4-s3express' &&
-                 !context.config.disable_s3_express_session_auth
-                bucket = context.params[:bucket]
-                credentials_provider = context.config.express_credentials_provider
-                credentials = credentials_provider.express_credentials_for(bucket)
-                context[:sigv4_credentials] = credentials # Sign will use this
-              end
+            # if s3 express auth, use new credentials and sign additional header
+            if context[:auth_scheme]['name'] == 'sigv4-s3express' &&
+               !context.config.disable_s3_express_session_auth
+              bucket = context.params[:bucket]
+              credentials_provider = context.config.express_credentials_provider
+              credentials = credentials_provider.express_credentials_for(bucket)
+              context[:sigv4_credentials] = credentials # Sign will use this
             end
+
             with_metric(credentials) { @handler.call(context) }
           end
 
@@ -58,10 +51,8 @@ for different buckets.
             Aws::Plugins::UserAgent.metric('S3_EXPRESS_BUCKET', &block)
           end
 
-          def checksum_required?(context)
-            context.operation.http_checksum_required ||
-              (context.operation.http_checksum &&
-                context.operation.http_checksum['requestChecksumRequired'])
+          def s3_express_endpoint?(context)
+            context[:endpoint_properties]['backend'] == 'S3Express'
           end
         end
 

data/lib/aws-sdk-s3/plugins/md5s.rb

@@ -6,81 +6,20 @@ module Aws
   module S3
     module Plugins
       # @api private
-      # This plugin is effectively deprecated in favor of modeled
+      # This plugin is deprecated in favor of modeled
       # httpChecksumRequired traits.
       class Md5s < Seahorse::Client::Plugin
-        # These operations allow Content MD5 but are not required by
-        # httpChecksumRequired. This list should not grow.
-        OPTIONAL_OPERATIONS = [
-          :put_object,
-          :upload_part
-        ]
-
-        # @api private
-        class Handler < Seahorse::Client::Handler
-
-          CHUNK_SIZE = 1 * 1024 * 1024 # one MB
-
-          def call(context)
-            if !context[:checksum_algorithms] && # skip in favor of flexible checksum
-               !context[:s3_express_endpoint] # s3 express endpoints do not support md5
-              body = context.http_request.body
-              if body.respond_to?(:size) && body.size > 0
-                context.http_request.headers['Content-Md5'] ||= md5(body)
-              end
-            end
-            @handler.call(context)
-          end
-
-          private
-
-          # @param [File, Tempfile, IO#read, String] value
-          # @return [String<MD5>]
-          def md5(value)
-            if (File === value || Tempfile === value) && !value.path.nil? && File.exist?(value.path)
-              OpenSSL::Digest::MD5.file(value).base64digest
-            elsif value.respond_to?(:read)
-              md5 = OpenSSL::Digest::MD5.new
-              update_in_chunks(md5, value)
-              md5.base64digest
-            else
-              OpenSSL::Digest::MD5.digest(value).base64digest
-            end
-          end
-
-          def update_in_chunks(digest, io)
-            loop do
-              chunk = io.read(CHUNK_SIZE)
-              break unless chunk
-              digest.update(chunk)
-            end
-            io.rewind
-          end
-
-        end
-
         option(:compute_checksums,
-          default: true,
-          doc_type: 'Boolean',
-          docstring: <<-DOCS)
-When `true` a MD5 checksum will be computed and sent in the Content Md5
-header for :put_object and :upload_part. When `false`, MD5 checksums
-will not be computed for these operations. Checksums are still computed
-for operations requiring them. Checksum errors returned by Amazon S3 are
-automatically retried up to `:retry_limit` times.
-          DOCS
-
-        def add_handlers(handlers, config)
-          if config.compute_checksums
-            # priority set low to ensure md5 is computed AFTER the request is
-            # built but before it is signed
-            handlers.add(
-              Handler,
-              priority: 10, step: :build, operations: OPTIONAL_OPERATIONS
-            )
-          end
+               default: true,
+               doc_type: 'Boolean',
+               docstring: <<~DOCS)
+                 This option is deprecated. Please use `:request_checksum_calculation` instead.
+                 When `false`, `request_checksum_calculation` is overridden to `when_required`.
+               DOCS
+
+        def after_initialize(client)
+          client.config.request_checksum_calculation = 'when_required' unless client.config.compute_checksums
         end
-
       end
     end
   end

data/lib/aws-sdk-s3/plugins/streaming_retry.rb

@@ -62,18 +62,16 @@ module Aws
         class Handler < Seahorse::Client::Handler
 
           def call(context)
-            target = context.params[:response_target] || context[:response_target]
-
             # retry is only supported when range is NOT set on the initial request
-            if supported_target?(target) && !context.params[:range]
-              add_event_listeners(context, target)
+            if supported_target?(context) && !context.params[:range]
+              add_event_listeners(context)
             end
             @handler.call(context)
           end
 
           private
 
-          def add_event_listeners(context, target)
+          def add_event_listeners(context)
             context.http_response.on_headers(200..299) do
               case context.http_response.body
               when Seahorse::Client::BlockIO then
@@ -123,8 +121,8 @@ module Aws
               context.http_response.body.is_a?(RetryableManagedFile)
           end
 
-          def supported_target?(target)
-            case target
+          def supported_target?(context)
+            case context[:response_target]
             when Proc, String, Pathname then true
             else false
             end

data/lib/aws-sdk-s3/plugins/url_encoded_keys.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 require 'uri'
-require 'cgi'
+require "cgi/escape"
+require "cgi/util" if RUBY_VERSION < "3.5"
 
 module Aws
   module S3

data/lib/aws-sdk-s3/presigner.rb

@@ -193,15 +193,14 @@ module Aws
         req, expires_in, secure, time, unsigned_headers, hoist = true
       )
         x_amz_headers = {}
-
         http_req = req.context.http_request
-
-        req.handlers.remove(Aws::S3::Plugins::S3Signer::LegacyHandler)
-        req.handlers.remove(Aws::Plugins::Sign::Handler)
         req.handlers.remove(Seahorse::Client::Plugins::ContentLength::Handler)
         req.handlers.remove(Aws::Rest::ContentTypeHandler)
+        req.handlers.remove(Aws::Plugins::ChecksumAlgorithm::OptionHandler)
+        req.handlers.remove(Aws::Plugins::ChecksumAlgorithm::ChecksumHandler)
         req.handlers.remove(Aws::Plugins::InvocationId::Handler)
-
+        req.handlers.remove(Aws::Plugins::Sign::Handler)
+        req.handlers.remove(Aws::S3::Plugins::S3Signer::LegacyHandler)
         req.handle(step: :send) do |context|
           # if an endpoint was not provided, force secure or insecure
           if context.config.regional_endpoint

data/lib/aws-sdk-s3/resource.rb

@@ -41,7 +41,7 @@ module Aws::S3
     #     acl: "private", # accepts private, public-read, public-read-write, authenticated-read
     #     bucket: "BucketName", # required
     #     create_bucket_configuration: {
-    #       location_constraint: "af-south-1", # accepts af-south-1, ap-east-1, ap-northeast-1, ap-northeast-2, ap-northeast-3, ap-south-1, ap-south-2, ap-southeast-1, ap-southeast-2, ap-southeast-3, ca-central-1, cn-north-1, cn-northwest-1, EU, eu-central-1, eu-north-1, eu-south-1, eu-south-2, eu-west-1, eu-west-2, eu-west-3, me-south-1, sa-east-1, us-east-2, us-gov-east-1, us-gov-west-1, us-west-1, us-west-2
+    #       location_constraint: "af-south-1", # accepts af-south-1, ap-east-1, ap-northeast-1, ap-northeast-2, ap-northeast-3, ap-south-1, ap-south-2, ap-southeast-1, ap-southeast-2, ap-southeast-3, ap-southeast-4, ap-southeast-5, ca-central-1, cn-north-1, cn-northwest-1, EU, eu-central-1, eu-central-2, eu-north-1, eu-south-1, eu-south-2, eu-west-1, eu-west-2, eu-west-3, il-central-1, me-central-1, me-south-1, sa-east-1, us-east-2, us-gov-east-1, us-gov-west-1, us-west-1, us-west-2
     #       location: {
     #         type: "AvailabilityZone", # accepts AvailabilityZone, LocalZone
     #         name: "LocationNameAsString",
@@ -50,6 +50,12 @@ module Aws::S3
     #         data_redundancy: "SingleAvailabilityZone", # accepts SingleAvailabilityZone, SingleLocalZone
     #         type: "Directory", # accepts Directory
     #       },
+    #       tags: [
+    #         {
+    #           key: "ObjectKey", # required
+    #           value: "Value", # required
+    #         },
+    #       ],
     #     },
     #     grant_full_control: "GrantFullControl",
     #     grant_read: "GrantRead",

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

@@ -0,0 +1,303 @@
+# frozen_string_literal: true
+
+module Aws
+  module S3
+    # A high-level S3 transfer utility that provides enhanced upload and download capabilities with automatic
+    # multipart handling, progress tracking, and handling of large files. The following features are supported:
+    #
+    # * upload a file with multipart upload
+    # * upload a stream with multipart upload
+    # * download a S3 object with multipart download
+    # * track transfer progress by using progress listener
+    #
+    # ## Executor Management
+    # TransferManager uses executors to handle concurrent operations during multipart transfers. You can control
+    # concurrency behavior by providing a custom executor or relying on the default executor management.
+    #
+    # ### Default Behavior
+    # When no `:executor` is provided, TransferManager creates a new DefaultExecutor for each individual
+    # operation (`download_file`, `upload_file`, etc.) and automatically shuts it down when that operation completes.
+    # Each operation gets its own isolated thread pool with the specified `:thread_count` (default 10 threads).
+    #
+    # ### Custom Executor
+    # You can provide your own executor (e.g., `Concurrent::ThreadPoolExecutor`) for fine-grained control over thread
+    # pools and resource management. When using a custom executor, you are responsible for shutting it down
+    # when finished. The executor may be reused across multiple TransferManager operations.
+    #
+    # Custom executors must implement the same interface as DefaultExecutor.
+    #
+    # **Required methods:**
+    #
+    #   * `post(*args, &block)` - Execute a task with given arguments and block
+    #   * `kill` - Immediately terminate all running tasks
+    #
+    # **Optional methods:**
+    #
+    #   * `shutdown(timeout = nil)` - Gracefully shutdown the executor with optional timeout
+    #
+    # @example Using default executor (automatic creation and shutdown)
+    #     tm = TransferManager.new # No executor provided
+    #     # DefaultExecutor created, used, and shutdown automatically
+    #     tm.download_file('/path/to/file', bucket: 'bucket', key: 'key')
+    #
+    # @example Using custom executor (manual shutdown required)
+    #     require 'concurrent-ruby'
+    #
+    #     executor = Concurrent::ThreadPoolExecutor.new(max_threads: 5)
+    #     tm = TransferManager.new(executor: executor)
+    #     tm.download_file('/path/to/file1', bucket: 'bucket', key: 'key1')
+    #     executor.shutdown # You must shutdown custom executors
+    #
+    class TransferManager
+
+      # @param [Hash] options
+      # @option options [S3::Client] :client (S3::Client.new)
+      #   The S3 client to use for {TransferManager} operations. If not provided, a new default client
+      #   will be created automatically.
+      # @option options [Object] :executor
+      #   The executor to use for multipart operations. Must implement the same interface as {DefaultExecutor}.
+      #   If not provided, a new {DefaultExecutor} will be created automatically for each operation and
+      #   shutdown after completion. When provided a custom executor, it will be reused across operations, and
+      #   you are responsible for shutting it down when finished.
+      def initialize(options = {})
+        @client = options[:client] || Client.new
+        @executor = options[:executor]
+      end
+
+      # @return [S3::Client]
+      attr_reader :client
+
+      # @return [Object]
+      attr_reader :executor
+
+      # Downloads a file in S3 to a path on disk.
+      #
+      #     # small files (< 5MB) are downloaded in a single API call
+      #     tm = TransferManager.new
+      #     tm.download_file('/path/to/file', bucket: 'bucket', key: 'key')
+      #
+      # Files larger than 5MB are downloaded using multipart method:
+      #
+      #     # large files are split into parts and the parts are downloaded in parallel
+      #     tm.download_file('/path/to/large_file', bucket: 'bucket', key: 'key')
+      #
+      # You can provide a callback to monitor progress of the download:
+      #
+      #     # bytes and part_sizes are each an array with 1 entry per part
+      #     # part_sizes may not be known until the first bytes are retrieved
+      #     progress = proc do |bytes, part_sizes, file_size|
+      #       bytes.map.with_index do |b, i|
+      #         puts "Part #{i + 1}: #{b} / #{part_sizes[i]}".join(' ') + "Total: #{100.0 * bytes.sum / file_size}%"
+      #       end
+      #     end
+      #     tm.download_file('/path/to/file', bucket: 'bucket', key: 'key', progress_callback: progress)
+      #
+      # @param [String, Pathname, File, Tempfile] destination
+      #   Where to download the file to. This can either be a String or Pathname to the file, an open File object,
+      #   or an open Tempfile object. If you pass an open File or Tempfile object, then you are responsible for
+      #   closing it after the download completes. Download behavior varies by destination type:
+      #
+      #   * **String/Pathname paths**: Downloads to a temporary file first, then atomically moves to the final
+      #    destination. This prevents corruption of any existing file if the download fails.
+      #   * **File/Tempfile objects**: Downloads directly to the file object without using temporary files.
+      #    You are responsible for managing the file object's state and closing it after the download completes.
+      #    If the download fails, the file object may contain partial data.
+      #
+      # @param [String] bucket
+      #   The name of the S3 bucket to upload to.
+      #
+      # @param [String] key
+      #   The object key name in S3 bucket.
+      #
+      # @param [Hash] options
+      #   Additional options for {Client#get_object} and #{Client#head_object} may be provided.
+      #
+      # @option options [String] :mode ("auto") `"auto"`, `"single_request"` or `"get_range"`
+      #
+      #  * `"auto"` mode is enabled by default, which performs `multipart_download`
+      #  * `"single_request`" mode forces only 1 GET request is made in download
+      #  * `"get_range"` mode requires `:chunk_size` parameter to configured in customizing each range size
+      #
+      # @option options [Integer] :chunk_size required in `"get_range"` mode.
+      #
+      # @option options [Integer] :thread_count (10) Customize threads used in the multipart download.
+      #   Only used when no custom executor is provided (creates {DefaultExecutor} with given thread count).
+      #
+      # @option options [String] :checksum_mode ("ENABLED")
+      #   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
+      #   response.  For multipart downloads, this will be called for each part that is downloaded and validated.
+      #
+      # @option options [Proc] :progress_callback
+      #   A Proc that will be called when each chunk of the download is received. It will be invoked with
+      #   `bytes_read`, `part_sizes`, `file_size`. When the object is downloaded as parts (rather than by ranges),
+      #   the `part_sizes` will not be known ahead of time and will be `nil` in the callback until the first bytes
+      #   in the part are received.
+      #
+      # @raise [MultipartDownloadError] Raised when an object validation fails outside of service errors.
+      #
+      # @return [Boolean] Returns `true` when the file is downloaded without any errors.
+      #
+      # @see Client#get_object
+      # @see Client#head_object
+      def download_file(destination, bucket:, key:, **options)
+        download_opts = options.merge(bucket: bucket, key: key)
+        executor = @executor || DefaultExecutor.new(max_threads: download_opts.delete(:thread_count))
+        downloader = FileDownloader.new(client: @client, executor: executor)
+        downloader.download(destination, download_opts)
+        executor.shutdown unless @executor
+        true
+      end
+
+      # Uploads a file from disk to S3.
+      #
+      #     # a small file are uploaded with PutObject API
+      #     tm = TransferManager.new
+      #     tm.upload_file('/path/to/small_file', bucket: 'bucket', key: 'key')
+      #
+      # Files larger than or equal to `:multipart_threshold` are uploaded using multipart upload APIs.
+      #
+      #     # large files are automatically split into parts and the parts are uploaded in parallel
+      #     tm.upload_file('/path/to/large_file', bucket: 'bucket', key: 'key')
+      #
+      # The response of the S3 upload API is yielded if a block given.
+      #
+      #     # API response will have etag value of the file
+      #     tm.upload_file('/path/to/file', bucket: 'bucket', key: 'key') do |response|
+      #       etag = response.etag
+      #     end
+      #
+      # You can provide a callback to monitor progress of the upload:
+      #
+      #     # bytes and totals are each an array with 1 entry per part
+      #     progress = proc do |bytes, totals|
+      #       bytes.map.with_index do |b, i|
+      #           puts "Part #{i + 1}: #{b} / #{totals[i]} " + "Total: #{100.0 * bytes.sum / totals.sum}%"
+      #       end
+      #     end
+      #     tm.upload_file('/path/to/file', bucket: 'bucket', key: 'key', progress_callback: progress)
+      #
+      # @param [String, Pathname, File, Tempfile] source
+      #   A file on the local file system that will be uploaded. This can either be a `String` or `Pathname` to the
+      #   file, an open `File` object, or an open `Tempfile` object. If you pass an open `File` or `Tempfile` object,
+      #   then you are responsible for closing it after the upload completes. When using an open Tempfile, rewind it
+      #   before uploading or else the object will be empty.
+      #
+      # @param [String] bucket
+      #   The name of the S3 bucket to upload to.
+      #
+      # @param [String] key
+      #   The object key name for the uploaded file.
+      #
+      # @param [Hash] options
+      #   Additional options for {Client#put_object} when file sizes below the multipart threshold.
+      #   For files larger than the multipart threshold, options for {Client#create_multipart_upload},
+      #   {Client#complete_multipart_upload}, and {Client#upload_part} can be provided.
+      #
+      # @option options [Integer] :multipart_threshold (104857600)
+      #   Files larger han or equal to `:multipart_threshold` are uploaded using the S3 multipart upload APIs.
+      #   Default threshold is `100MB`.
+      #
+      # @option options [Integer] :thread_count (10) Customize threads used in the multipart upload.
+      #   Only used when no custom executor is provided (creates {DefaultExecutor} with the given thread count).
+      #
+      # @option options [Proc] :progress_callback (nil)
+      #   A Proc that will be called when each chunk of the upload is sent.
+      #   It will be invoked with `[bytes_read]` and  `[total_sizes]`.
+      #
+      # @raise [MultipartUploadError] If a file is being uploaded in parts, and the upload can not be completed,
+      #   then the upload is aborted and this error is raised.  The raised error has a `#errors` method that
+      #   returns the failures that caused the upload to be aborted.
+      #
+      # @return [Boolean] Returns `true` when the file is uploaded without any errors.
+      #
+      # @see Client#put_object
+      # @see Client#create_multipart_upload
+      # @see Client#complete_multipart_upload
+      # @see Client#upload_part
+      def upload_file(source, bucket:, key:, **options)
+        upload_opts = options.merge(bucket: bucket, key: key)
+        executor = @executor || DefaultExecutor.new(max_threads: upload_opts.delete(:thread_count))
+        uploader = FileUploader.new(
+          multipart_threshold: upload_opts.delete(:multipart_threshold),
+          client: @client,
+          executor: executor
+        )
+        response = uploader.upload(source, upload_opts)
+        yield response if block_given?
+        executor.shutdown unless @executor
+        true
+      end
+
+      # Uploads a stream in a streaming fashion to S3.
+      #
+      # Passed chunks automatically split into multipart upload parts and the parts are uploaded in parallel.
+      # This allows for streaming uploads that never touch the disk.
+      #
+      # **Note**: There are known issues in JRuby until jruby-9.1.15.0, so avoid using this with older JRuby versions.
+      #
+      # @example Streaming chunks of data
+      #     tm = TransferManager.new
+      #     tm.upload_stream(bucket: 'bucket', key: 'key') do |write_stream|
+      #       10.times { write_stream << 'foo' }
+      #     end
+      # @example Streaming chunks of data
+      #     tm.upload_stream(bucket: 'bucket', key: 'key') do |write_stream|
+      #       IO.copy_stream(IO.popen('ls'), write_stream)
+      #     end
+      # @example Streaming chunks of data
+      #     tm.upload_stream(bucket: 'bucket', key: 'key') do |write_stream|
+      #       IO.copy_stream(STDIN, write_stream)
+      #     end
+      #
+      # @param [String] bucket
+      #   The name of the S3 bucket to upload to.
+      #
+      # @param [String] key
+      #   The object key name for the uploaded file.
+      #
+      # @param [Hash] options
+      #   Additional options for {Client#create_multipart_upload}, {Client#complete_multipart_upload}, and
+      #   {Client#upload_part} can be provided.
+      #
+      # @option options [Integer] :thread_count (10)
+      #   The number of parallel multipart uploads. Only used when no custom executor is provided (creates
+      #   {DefaultExecutor} with the given thread count). An additional thread is used internally for task coordination.
+      #
+      # @option options [Boolean] :tempfile (false)
+      #   Normally read data is stored in memory when building the parts in order to complete the underlying
+      #   multipart upload. By passing `:tempfile => true`, the data read will be temporarily stored on disk reducing
+      #   the memory footprint vastly.
+      #
+      # @option options [Integer] :part_size (5242880)
+      #   Define how big each part size but the last should be. Default `:part_size` is `5 * 1024 * 1024`.
+      #
+      # @raise [MultipartUploadError] If an object is being uploaded in parts, and the upload can not be completed,
+      #   then the upload is aborted and this error is raised. The raised error has a `#errors` method that returns
+      #   the failures that caused the upload to be aborted.
+      #
+      # @return [Boolean] Returns `true` when the object is uploaded without any errors.
+      #
+      # @see Client#create_multipart_upload
+      # @see Client#complete_multipart_upload
+      # @see Client#upload_part
+      def upload_stream(bucket:, key:, **options, &block)
+        upload_opts = options.merge(bucket: bucket, key: key)
+        executor = @executor || DefaultExecutor.new(max_threads: upload_opts.delete(:thread_count))
+        uploader = MultipartStreamUploader.new(
+          client: @client,
+          executor: executor,
+          tempfile: upload_opts.delete(:tempfile),
+          part_size: upload_opts.delete(:part_size)
+        )
+        uploader.upload(upload_opts, &block)
+        executor.shutdown unless @executor
+        true
+      end
+    end
+  end
+end