aws-sdk-s3 1.30.0 → 1.114.0

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

@@ -1,11 +1,14 @@
+# frozen_string_literal: true
+
 # WARNING ABOUT GENERATED CODE
 #
 # This file is generated. See the contributing guide for more information:
-# https://github.com/aws/aws-sdk-ruby/blob/master/CONTRIBUTING.md
+# https://github.com/aws/aws-sdk-ruby/blob/version-3/CONTRIBUTING.md
 #
 # WARNING ABOUT GENERATED CODE
 
 module Aws::S3
+
   class ObjectVersion
 
     extend Aws::Deprecations
@@ -27,6 +30,7 @@ module Aws::S3
       @id = extract_id(args, options)
       @data = options.delete(:data)
       @client = options.delete(:client) || Client.new(options)
+      @waiter_block_warned = false
     end
 
     # @!group Read-Only Attributes
@@ -46,11 +50,18 @@ module Aws::S3
       @id
     end
 
+    # The entity tag is an MD5 hash of that version of the object.
     # @return [String]
     def etag
       data[:etag]
     end
 
+    # The algorithm that was used to create a checksum of the object.
+    # @return [Array<String>]
+    def checksum_algorithm
+      data[:checksum_algorithm]
+    end
+
     # Size in bytes of the object.
     # @return [Integer]
     def size
@@ -88,6 +99,7 @@ module Aws::S3
       data[:last_modified]
     end
 
+    # Specifies the owner of the object.
     # @return [Types::Owner]
     def owner
       data[:owner]
@@ -128,7 +140,8 @@ module Aws::S3
     # Waiter polls an API operation until a resource enters a desired
     # state.
     #
-    # @note The waiting operation is performed on a copy. The original resource remains unchanged
+    # @note The waiting operation is performed on a copy. The original resource
+    #   remains unchanged.
     #
     # ## Basic Usage
     #
@@ -141,13 +154,15 @@ module Aws::S3
     #
     # ## Example
     #
-    #     instance.wait_until(max_attempts:10, delay:5) {|instance| instance.state.name == 'running' }
+    #     instance.wait_until(max_attempts:10, delay:5) do |instance|
+    #       instance.state.name == 'running'
+    #     end
     #
     # ## Configuration
     #
     # You can configure the maximum number of polling attempts, and the
-    # delay (in seconds) between each polling attempt. The waiting condition is set
-    # by passing a block to {#wait_until}:
+    # delay (in seconds) between each polling attempt. The waiting condition is
+    # set by passing a block to {#wait_until}:
     #
     #     # poll for ~25 seconds
     #     resource.wait_until(max_attempts:5,delay:5) {|resource|...}
@@ -178,17 +193,16 @@ module Aws::S3
     #       # resource did not enter the desired state in time
     #     end
     #
+    # @yieldparam [Resource] resource to be used in the waiting condition.
     #
-    # @yield param [Resource] resource to be used in the waiting condition
-    #
-    # @raise [Aws::Waiters::Errors::FailureStateError] Raised when the waiter terminates
-    #   because the waiter has entered a state that it will not transition
-    #   out of, preventing success.
+    # @raise [Aws::Waiters::Errors::FailureStateError] Raised when the waiter
+    #   terminates because the waiter has entered a state that it will not
+    #   transition out of, preventing success.
     #
     #   yet successful.
     #
-    # @raise [Aws::Waiters::Errors::UnexpectedError] Raised when an error is encountered
-    #   while polling for a resource that is not expected.
+    # @raise [Aws::Waiters::Errors::UnexpectedError] Raised when an error is
+    #   encountered while polling for a resource that is not expected.
     #
     # @raise [NotImplementedError] Raised when the resource does not
     #
@@ -226,20 +240,32 @@ module Aws::S3
     #     mfa: "MFA",
     #     request_payer: "requester", # accepts requester
     #     bypass_governance_retention: false,
+    #     expected_bucket_owner: "AccountId",
     #   })
     # @param [Hash] options ({})
     # @option options [String] :mfa
     #   The concatenation of the authentication device's serial number, a
     #   space, and the value that is displayed on your authentication device.
+    #   Required to permanently delete a versioned object if versioning is
+    #   configured with MFA delete enabled.
     # @option options [String] :request_payer
-    #   Confirms that the requester knows that she or he will be charged for
-    #   the request. Bucket owners need not specify this parameter in their
-    #   requests. Documentation on downloading objects from requester pays
-    #   buckets can be found at
-    #   http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
+    #   Confirms that the requester knows that they will be charged for the
+    #   request. Bucket owners need not specify this parameter in their
+    #   requests. For information about downloading objects from Requester
+    #   Pays buckets, see [Downloading Objects in Requester Pays Buckets][1]
+    #   in the *Amazon S3 User Guide*.
+    #
+    #
+    #
+    #   [1]: https://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
     # @option options [Boolean] :bypass_governance_retention
     #   Indicates whether S3 Object Lock should bypass Governance-mode
-    #   restrictions to process this operation.
+    #   restrictions to process this operation. To use this header, you must
+    #   have the `s3:BypassGovernanceRetention` permission.
+    # @option options [String] :expected_bucket_owner
+    #   The account ID of the expected bucket owner. If the bucket is owned by
+    #   a different account, the request fails with the HTTP status code `403
+    #   Forbidden` (access denied).
     # @return [Types::DeleteObjectOutput]
     def delete(options = {})
       options = options.merge(
@@ -270,60 +296,81 @@ module Aws::S3
     #     sse_customer_key_md5: "SSECustomerKeyMD5",
     #     request_payer: "requester", # accepts requester
     #     part_number: 1,
+    #     expected_bucket_owner: "AccountId",
+    #     checksum_mode: "ENABLED", # accepts ENABLED
     #   })
     # @param [Hash] options ({})
     # @option options [String] :if_match
     #   Return the object only if its entity tag (ETag) is the same as the one
-    #   specified, otherwise return a 412 (precondition failed).
+    #   specified; otherwise, return a 412 (precondition failed) error.
     # @option options [Time,DateTime,Date,Integer,String] :if_modified_since
     #   Return the object only if it has been modified since the specified
-    #   time, otherwise return a 304 (not modified).
+    #   time; otherwise, return a 304 (not modified) error.
     # @option options [String] :if_none_match
     #   Return the object only if its entity tag (ETag) is different from the
-    #   one specified, otherwise return a 304 (not modified).
+    #   one specified; otherwise, return a 304 (not modified) error.
     # @option options [Time,DateTime,Date,Integer,String] :if_unmodified_since
     #   Return the object only if it has not been modified since the specified
-    #   time, otherwise return a 412 (precondition failed).
+    #   time; otherwise, return a 412 (precondition failed) error.
     # @option options [String] :range
     #   Downloads the specified range bytes of an object. For more information
-    #   about the HTTP Range header, go to
-    #   http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35.
+    #   about the HTTP Range header, see
+    #   [https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35][1].
+    #
+    #   <note markdown="1"> Amazon S3 doesn't support retrieving multiple ranges of data per
+    #   `GET` request.
+    #
+    #    </note>
+    #
+    #
+    #
+    #   [1]: https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35
     # @option options [String] :response_cache_control
-    #   Sets the Cache-Control header of the response.
+    #   Sets the `Cache-Control` header of the response.
     # @option options [String] :response_content_disposition
-    #   Sets the Content-Disposition header of the response
+    #   Sets the `Content-Disposition` header of the response
     # @option options [String] :response_content_encoding
-    #   Sets the Content-Encoding header of the response.
+    #   Sets the `Content-Encoding` header of the response.
     # @option options [String] :response_content_language
-    #   Sets the Content-Language header of the response.
+    #   Sets the `Content-Language` header of the response.
     # @option options [String] :response_content_type
-    #   Sets the Content-Type header of the response.
+    #   Sets the `Content-Type` header of the response.
     # @option options [Time,DateTime,Date,Integer,String] :response_expires
-    #   Sets the Expires header of the response.
+    #   Sets the `Expires` header of the response.
     # @option options [String] :sse_customer_algorithm
-    #   Specifies the algorithm to use to when encrypting the object (e.g.,
-    #   AES256).
+    #   Specifies the algorithm to use to when decrypting the object (for
+    #   example, AES256).
     # @option options [String] :sse_customer_key
-    #   Specifies the customer-provided encryption key for Amazon S3 to use in
-    #   encrypting data. This value is used to store the object and then it is
-    #   discarded; Amazon does not store the encryption key. The key must be
-    #   appropriate for use with the algorithm specified in the
-    #   x-amz-server-side​-encryption​-customer-algorithm header.
+    #   Specifies the customer-provided encryption key for Amazon S3 used to
+    #   encrypt the data. This value is used to decrypt the object when
+    #   recovering it and must match the one used when storing the data. The
+    #   key must be appropriate for use with the algorithm specified in the
+    #   `x-amz-server-side-encryption-customer-algorithm` header.
     # @option options [String] :sse_customer_key_md5
     #   Specifies the 128-bit MD5 digest of the encryption key according to
     #   RFC 1321. Amazon S3 uses this header for a message integrity check to
-    #   ensure the encryption key was transmitted without error.
+    #   ensure that the encryption key was transmitted without error.
     # @option options [String] :request_payer
-    #   Confirms that the requester knows that she or he will be charged for
-    #   the request. Bucket owners need not specify this parameter in their
-    #   requests. Documentation on downloading objects from requester pays
-    #   buckets can be found at
-    #   http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
+    #   Confirms that the requester knows that they will be charged for the
+    #   request. Bucket owners need not specify this parameter in their
+    #   requests. For information about downloading objects from Requester
+    #   Pays buckets, see [Downloading Objects in Requester Pays Buckets][1]
+    #   in the *Amazon S3 User Guide*.
+    #
+    #
+    #
+    #   [1]: https://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
     # @option options [Integer] :part_number
     #   Part number of the object being read. This is a positive integer
     #   between 1 and 10,000. Effectively performs a 'ranged' GET request
     #   for the part specified. Useful for downloading just a part of an
     #   object.
+    # @option options [String] :expected_bucket_owner
+    #   The account ID of the expected bucket owner. If the bucket is owned by
+    #   a different account, the request fails with the HTTP status code `403
+    #   Forbidden` (access denied).
+    # @option options [String] :checksum_mode
+    #   To retrieve the checksum, this mode must be enabled.
     # @return [Types::GetObjectOutput]
     def get(options = {}, &block)
       options = options.merge(
@@ -348,48 +395,64 @@ module Aws::S3
     #     sse_customer_key_md5: "SSECustomerKeyMD5",
     #     request_payer: "requester", # accepts requester
     #     part_number: 1,
+    #     expected_bucket_owner: "AccountId",
+    #     checksum_mode: "ENABLED", # accepts ENABLED
     #   })
     # @param [Hash] options ({})
     # @option options [String] :if_match
     #   Return the object only if its entity tag (ETag) is the same as the one
-    #   specified, otherwise return a 412 (precondition failed).
+    #   specified; otherwise, return a 412 (precondition failed) error.
     # @option options [Time,DateTime,Date,Integer,String] :if_modified_since
     #   Return the object only if it has been modified since the specified
-    #   time, otherwise return a 304 (not modified).
+    #   time; otherwise, return a 304 (not modified) error.
     # @option options [String] :if_none_match
     #   Return the object only if its entity tag (ETag) is different from the
-    #   one specified, otherwise return a 304 (not modified).
+    #   one specified; otherwise, return a 304 (not modified) error.
     # @option options [Time,DateTime,Date,Integer,String] :if_unmodified_since
     #   Return the object only if it has not been modified since the specified
-    #   time, otherwise return a 412 (precondition failed).
+    #   time; otherwise, return a 412 (precondition failed) error.
     # @option options [String] :range
-    #   Downloads the specified range bytes of an object. For more information
-    #   about the HTTP Range header, go to
-    #   http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35.
+    #   Because `HeadObject` returns only the metadata for an object, this
+    #   parameter has no effect.
     # @option options [String] :sse_customer_algorithm
-    #   Specifies the algorithm to use to when encrypting the object (e.g.,
-    #   AES256).
+    #   Specifies the algorithm to use to when encrypting the object (for
+    #   example, AES256).
     # @option options [String] :sse_customer_key
     #   Specifies the customer-provided encryption key for Amazon S3 to use in
     #   encrypting data. This value is used to store the object and then it is
-    #   discarded; Amazon does not store the encryption key. The key must be
-    #   appropriate for use with the algorithm specified in the
-    #   x-amz-server-side​-encryption​-customer-algorithm header.
+    #   discarded; Amazon S3 does not store the encryption key. The key must
+    #   be appropriate for use with the algorithm specified in the
+    #   `x-amz-server-side-encryption-customer-algorithm` header.
     # @option options [String] :sse_customer_key_md5
     #   Specifies the 128-bit MD5 digest of the encryption key according to
     #   RFC 1321. Amazon S3 uses this header for a message integrity check to
-    #   ensure the encryption key was transmitted without error.
+    #   ensure that the encryption key was transmitted without error.
     # @option options [String] :request_payer
-    #   Confirms that the requester knows that she or he will be charged for
-    #   the request. Bucket owners need not specify this parameter in their
-    #   requests. Documentation on downloading objects from requester pays
-    #   buckets can be found at
-    #   http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
+    #   Confirms that the requester knows that they will be charged for the
+    #   request. Bucket owners need not specify this parameter in their
+    #   requests. For information about downloading objects from Requester
+    #   Pays buckets, see [Downloading Objects in Requester Pays Buckets][1]
+    #   in the *Amazon S3 User Guide*.
+    #
+    #
+    #
+    #   [1]: https://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
     # @option options [Integer] :part_number
     #   Part number of the object being read. This is a positive integer
     #   between 1 and 10,000. Effectively performs a 'ranged' HEAD request
     #   for the part specified. Useful querying about the size of the part and
     #   the number of parts in this object.
+    # @option options [String] :expected_bucket_owner
+    #   The account ID of the expected bucket owner. If the bucket is owned by
+    #   a different account, the request fails with the HTTP status code `403
+    #   Forbidden` (access denied).
+    # @option options [String] :checksum_mode
+    #   To retrieve the checksum, this parameter must be enabled.
+    #
+    #   In addition, if you enable `ChecksumMode` and the object is encrypted
+    #   with Amazon Web Services Key Management Service (Amazon Web Services
+    #   KMS), you must have permission to use the `kms:Decrypt` action for the
+    #   request to succeed.
     # @return [Types::HeadObjectOutput]
     def head(options = {})
       options = options.merge(
@@ -468,21 +531,51 @@ module Aws::S3
       #     mfa: "MFA",
       #     request_payer: "requester", # accepts requester
       #     bypass_governance_retention: false,
+      #     expected_bucket_owner: "AccountId",
+      #     checksum_algorithm: "CRC32", # accepts CRC32, CRC32C, SHA1, SHA256
       #   })
       # @param options ({})
       # @option options [String] :mfa
       #   The concatenation of the authentication device's serial number, a
       #   space, and the value that is displayed on your authentication device.
+      #   Required to permanently delete a versioned object if versioning is
+      #   configured with MFA delete enabled.
       # @option options [String] :request_payer
-      #   Confirms that the requester knows that she or he will be charged for
-      #   the request. Bucket owners need not specify this parameter in their
-      #   requests. Documentation on downloading objects from requester pays
-      #   buckets can be found at
-      #   http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
+      #   Confirms that the requester knows that they will be charged for the
+      #   request. Bucket owners need not specify this parameter in their
+      #   requests. For information about downloading objects from Requester
+      #   Pays buckets, see [Downloading Objects in Requester Pays Buckets][1]
+      #   in the *Amazon S3 User Guide*.
+      #
+      #
+      #
+      #   [1]: https://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
       # @option options [Boolean] :bypass_governance_retention
       #   Specifies whether you want to delete this object even if it has a
-      #   Governance-type Object Lock in place. You must have sufficient
-      #   permissions to perform this operation.
+      #   Governance-type Object Lock in place. To use this header, you must
+      #   have the `s3:BypassGovernanceRetention` permission.
+      # @option options [String] :expected_bucket_owner
+      #   The account ID of the expected bucket owner. If the bucket is owned by
+      #   a different account, the request fails with the HTTP status code `403
+      #   Forbidden` (access denied).
+      # @option options [String] :checksum_algorithm
+      #   Indicates the algorithm used to create the checksum for the object
+      #   when using the SDK. This header will not provide any additional
+      #   functionality if not using the SDK. When sending this header, there
+      #   must be a corresponding `x-amz-checksum` or `x-amz-trailer` header
+      #   sent. Otherwise, Amazon S3 fails the request with the HTTP status code
+      #   `400 Bad Request`. For more information, see [Checking object
+      #   integrity][1] in the *Amazon S3 User Guide*.
+      #
+      #   If you provide an individual checksum, Amazon S3 ignores any provided
+      #   `ChecksumAlgorithm` parameter.
+      #
+      #   This checksum algorithm must be the same for all parts and it match
+      #   the checksum value supplied in the `CreateMultipartUpload` request.
+      #
+      #
+      #
+      #   [1]: https://docs.aws.amazon.com/AmazonS3/latest/userguide/checking-object-integrity.html
       # @return [void]
       def batch_delete!(options = {})
         batch_enum.each do |batch|

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

@@ -1,36 +1,57 @@
+# frozen_string_literal: true
+
 module Aws
   module S3
     module Plugins
-
       # Provides support for using `Aws::S3::Client` with Amazon S3 Transfer
       # Acceleration.
       #
       # Go here for more information about transfer acceleration:
       # [http://docs.aws.amazon.com/AmazonS3/latest/dev/transfer-acceleration.html](http://docs.aws.amazon.com/AmazonS3/latest/dev/transfer-acceleration.html)
       class Accelerate < Seahorse::Client::Plugin
-
-        option(:use_accelerate_endpoint,
+        option(
+          :use_accelerate_endpoint,
           default: false,
           doc_type: 'Boolean',
           docstring: <<-DOCS)
 When set to `true`, accelerated bucket endpoints will be used
 for all object operations. You must first enable accelerate for
-each bucket.  [Go here for more information](http://docs.aws.amazon.com/AmazonS3/latest/dev/transfer-acceleration.html).
+each bucket. [Go here for more information](http://docs.aws.amazon.com/AmazonS3/latest/dev/transfer-acceleration.html).
           DOCS
 
         def add_handlers(handlers, config)
           operations = config.api.operation_names - [
-            :create_bucket, :list_buckets, :delete_bucket,
+            :create_bucket, :list_buckets, :delete_bucket
           ]
-          handlers.add(OptionHandler, step: :initialize, operations: operations)
-          handlers.add(AccelerateHandler, step: :build, priority: 0, operations: operations)
+          # Need 2 handlers so that the context can be set for other plugins
+          # and to remove :use_accelerate_endpoint from the params.
+          handlers.add(
+            OptionHandler, step: :initialize, operations: operations
+          )
+          handlers.add(
+            AccelerateHandler, step: :build, priority: 11, operations: operations
+          )
         end
 
         # @api private
         class OptionHandler < Seahorse::Client::Handler
           def call(context)
-            accelerate = context.params.delete(:use_accelerate_endpoint)
+            # Support client configuration and per-operation configuration
+            if context.params.is_a?(Hash)
+              accelerate = context.params.delete(:use_accelerate_endpoint)
+            end
             accelerate = context.config.use_accelerate_endpoint if accelerate.nil?
+            # Raise if :endpoint and accelerate are both provided
+            if accelerate && !context.config.regional_endpoint
+              raise ArgumentError,
+                    'Cannot use both :use_accelerate_endpoint and :endpoint'
+            end
+            # Raise if :use_fips_endpoint and accelerate are both provided
+            if accelerate && context.config.use_fips_endpoint
+              raise ArgumentError,
+                    'Cannot use both :use_accelerate_endpoint and '\
+                    ':use_fips_endpoint'
+            end
             context[:use_accelerate_endpoint] = accelerate
             @handler.call(context)
           end
@@ -38,39 +59,24 @@ each bucket.  [Go here for more information](http://docs.aws.amazon.com/AmazonS3
 
         # @api private
         class AccelerateHandler < Seahorse::Client::Handler
-
           def call(context)
-            if context[:use_accelerate_endpoint]
-              if context[:use_dualstack_endpoint]
-                use_combined_accelerate_dualstack_endpoint(context)
-              else
-                use_accelerate_endpoint(context)
-              end
+            if context.config.regional_endpoint && context[:use_accelerate_endpoint]
+              dualstack = !!context[:use_dualstack_endpoint]
+              use_accelerate_endpoint(context, dualstack)
             end
             @handler.call(context)
           end
 
           private
 
-          def use_accelerate_endpoint(context)
+          def use_accelerate_endpoint(context, dualstack)
             bucket_name = context.params[:bucket]
             validate_bucket_name!(bucket_name)
             endpoint = URI.parse(context.http_request.endpoint.to_s)
             endpoint.scheme = 'https'
             endpoint.port = 443
-            endpoint.host = "#{bucket_name}.s3-accelerate.amazonaws.com"
-            context.http_request.endpoint = endpoint.to_s
-            # s3 accelerate endpoint doesn't work with 'expect' header
-            context.http_request.headers.delete('expect')
-          end
-
-          def use_combined_accelerate_dualstack_endpoint(context)
-            bucket_name = context.params[:bucket]
-            validate_bucket_name!(bucket_name)
-            endpoint = URI.parse(context.http_request.endpoint.to_s)
-            endpoint.scheme = 'https'
-            endpoint.port = 443
-            endpoint.host = "#{bucket_name}.s3-accelerate.dualstack.amazonaws.com"
+            endpoint.host = "#{bucket_name}.s3-accelerate"\
+                            "#{'.dualstack' if dualstack}.amazonaws.com"
             context.http_request.endpoint = endpoint.to_s
             # s3 accelerate endpoint doesn't work with 'expect' header
             context.http_request.headers.delete('expect')
@@ -78,17 +84,11 @@ each bucket.  [Go here for more information](http://docs.aws.amazon.com/AmazonS3
 
           def validate_bucket_name!(bucket_name)
             unless BucketDns.dns_compatible?(bucket_name, _ssl = true)
-              msg = "unable to use `accelerate: true` on buckets with "
-              msg << "non-DNS compatible names"
-              raise ArgumentError, msg
-            end
-            if bucket_name.include?('.')
-              msg = "unable to use `accelerate: true` on buckets with dots"
-              msg << "in their name: #{bucket_name.inspect}"
-              raise ArgumentError, msg
+              raise ArgumentError,
+                    'Unable to use `use_accelerate_endpoint: true` on buckets '\
+                    'with non-DNS compatible names.'
             end
           end
-
         end
       end
     end