0.66 - refactoring, Amazon::S3::BucketV2

ChangeLog

@@ -1,9 +1,64 @@
 Thu Nov 30 13:56:08 2023  Rob Lauer  <[email protected]>
 
-	[0.66 - unreleased]:
+	[0.66]:
 	* VERSION: bump
+	* NEWS.md: updated
+	* README.md: generated
 	* src/main/perl/lib/Amazon/S3.pm.in: pod updates
 	* README.md: generated
+	* src/main/perl/lib/Amazon/S3/BucketV2.pm.in: new
+	* src/main/perl/lib/Amazon/S3/Util.pm.in: new
+	* src/main/perl/lib/Makefile.am: add above to build
+	* src/main/perl/lib/Amazon/S3.pm.in
+	- refactoring
+	- updated pod
+	(add_bucket): allow additional headers
+	(delete_bucket): likewise
+	(list_bucket)
+	- likewise
+	- allow query parameters
+	(_validate_acl_short): refactored
+	(_make_request): refactored
+	(adjust_region): refactored
+	(_do_http): refactored
+	(_send_request_expect_nothing): refactored
+	(_send_request_expect_nothing_probed): refactored
+	(_remember_errors): refactored
+	(_add_auth_header): refactored
+	(_merge_meta): refactored
+	(_encode): refactored
+	* src/main/perl/lib/Amazon/S3/Bucket.pm.in
+	- refactored
+	(new): refactored
+	(_uri): refactored
+	(add_key): allow for additional headers
+	(upload_mulipart_object)
+	- refactored
+	- allow additional headers
+	(initiate_multipart_upload): likewise
+	(upload_part_of_multipart_upload): likewise
+	(make_xml_document_simple): replaced with _create_multipart_upload_request()
+	(get_key): call _get_key() now
+	(_get_key)
+	- renamed from get_key()
+	- allow additional headers
+	(copy_object): refactored
+	(delete_keys)
+	- refactored
+	- allow additional headers
+	* src/main/perl/lib/Amazon/S3/Constants.pm.in
+	- + $AWS_METADATA_BASE_URL
+	- + markers for ListObjectVersions
+	* src/main/perl/t/01-api.t
+	- create private bucket first, then delete public access block
+	(list_all)
+	- refactored
+	- allow additional headers
+	(get_acl)
+	- refactored
+	- allow additional headers
+	(get_location_constraint): refactored
+	(_create_multipart_upload_request): new
 
 Tue Nov 28 17:42:44 2023  Rob Lauer  <[email protected]>
 

NEWS.md

@@ -7,6 +7,37 @@ previous versions.  If critical bugs are found in any of the software,
 notice of such bugs and the versions in which they were fixed will be
 noted here, as well.
 
+# perl-Amazon-S3 2.00 (2023-12-13)
+
+> This version introduces several new methods. Much of the legacy code has
+> been refactored for clarity and to reduce duplication.  A new set of
+> S3 methods have been implemented in `Amazon::S3::V2`. Some of
+> the new methods duplicate existing functionality but are now
+> implemented with interfaces that are more aligned with the actual
+> AWS API documentation. The new methods in `Amazon::S3::V2` are named
+> after the documented API. Not all API actions have been implemented yet.
+>
+> Additionally, many of the existing methods have been modified slightly to allow
+> for specifying object versions or to allow for setting additional
+> headers which were previously ignored.
+>
+> See the documentation for `Amazon::S3`, `Amazon::S3::Bucket` and
+> `Amazon::S3::V2` for more details.
+
+# perl-Amazon-S3 0.66 (2023-12-09)
+
+> This version introduces new methods for handling object versions.
+
+## Enhancements
+
+* `Amazon::S3::Bucket`
+  * `delete_key()` now accepts an optional version identifier
+  * `get_bucket_versioning()` - returns status of bucket versioning
+  * `put_bucket_versioning()` - sets the status of bucket versioning
+
+* `Amazon:S3`
+  * `list_object_versions()` - method that returns version metadata
+
 # perl-Amazon-S3 0.65 (2023-11-28)
 
 > This version fixes a bug when getting credentials from the the

README.md

@@ -78,11 +78,34 @@ implementations of:
 - ListObjectsV2
 - CopyObject
 - DeleteObjects
+- ListObjectVersions
 
 Additionally, this module now implements Signature Version 4 signing,
 unit tests have been updated and more documentation has been added or
 corrected. Credentials are encrypted if you have encryption modules installed.
 
+_NEW!_
+
+The `Amazon::S3` modules have been heavily refactored over the last
+year to increase maintainability and to add new features. New features include:
+
+- Addition of version parameter for some methods that can accept
+an object version.
+    - delete\_key
+    - delete\_keys
+    - set\_acl
+- Methods that accept a hash reference can now accept a
+`headers` object that contains any additional headers you might want
+to send with a request. Some of the methods that now allow you to pass
+a header object include:
+    - add\_bucket
+    - add\_key
+    - get\_key
+    - delete\_bucket
+    - list\_bucket
+    - list\_object\_versions
+    - upload\_multipart\_object
+
 ## Comparison to Other Perl S3 Modules
 
 Other implementations for accessing Amazon's S3 service include
@@ -445,8 +468,16 @@ buckets owned by the accout or (see below) or `undef` on error.
 
     add_bucket(bucket-configuration)
 
-`bucket-configuration` is a reference to a hash with bucket configuration
-parameters.
+`bucket-configuration` is a reference to a hash with bucket
+configuration parameters.
+
+_Note that since April of 2023, new buckets are created that block
+public access by default. If you attempt to set an ACL with public
+permissions the create operation will fail. To create a public bucket
+you must first create the bucket with private permissions, remove the
+public block and subsequently apply public permissions._
+
+See ["delete\_public\_access\_block"](#delete_public_access_block).
 
 - bucket
 
@@ -456,13 +487,23 @@ parameters.
 
 - acl\_short (optional)
 
-    See the set\_acl subroutine for documenation on the acl\_short options
+    See the set\_acl subroutine for documenation on the acl\_short
+    options. Note that starting in April of 2023 new buckets are
+    configured to automatically block public access. Trying to create a
+    bucket with public permissions will fail. In order to create a public
+    bucket you must first create a private bucket, then call the
+    DeletePublicAccessBlock API. You can then set public permissions for
+    your bucket using ACLs or a bucket policy.
 
 - location\_constraint
 - region
 
     The region the bucket is to be created in.
 
+- headers
+
+    Additional headers to send with request.
+
 Returns a [Amazon::S3::Bucket](https://metacpan.org/pod/Amazon%3A%3AS3%3A%3ABucket) object on success or `undef` on failure.
 
 ## bucket
@@ -512,6 +553,12 @@ Note from the [Amazon's documentation](https://docs.aws.amazon.com/AmazonS3/late
 > of a deleted bucket**. If you want to use the same bucket name, we
 > recommend that you don't delete the bucket.
 
+## delete\_public\_access\_block
+
+    delete_public_access_block(bucket-obj)
+
+Removes the public access block flag for the bucket.
+
 ## dns\_bucket\_names
 
 Set or get a boolean that indicates whether to use DNS bucket
@@ -722,6 +769,75 @@ Takes the same arguments as `list_bucket`.
 
 _You are encouraged to use the newer `list_bucket_all_v2` method._
 
+## list\_object\_versions
+
+    list_object_versions( args ) 
+
+Returns metadata about all versions of the objects in a bucket. You
+can also use request parameters as selection criteria to return
+metadata about a subset of all the object versions.
+
+This method will only return the raw result set and does not perform
+pagination or unravel common prefixes as do other methods like
+`list_bucket`. This may change in the future.
+
+See [https://docs.aws.amazon.com/AmazonS3/latest/API/API\_ListObjectVersions.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectVersions.html)
+for more information about the request parameters and the result body.
+
+`args` is hash reference containing the following parameters:
+
+- bucket
+
+    Name of the bucket. This method is not vailable for directory buckets.
+
+- headers
+
+    Optional headers. See
+    [https://docs.aws.amazon.com/AmazonS3/latest/API/API\_ListObjectVersions.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectVersions.html)
+    for more details regarding optional headers.
+
+- delimiter
+
+    A delimiter is a character that you specify to group keys. All keys
+    that contain the same string between the prefix and the first
+    occurrence of the delimiter are grouped under a single result element
+    in CommonPrefixes. These groups are counted as one result against the
+    max-keys limitation. These keys are not returned elsewhere in the
+    response.
+
+- encoding-type     
+
+    Requests Amazon S3 to encode the object keys in the response and
+    specifies the encoding method to use.
+
+- key-marker        
+
+    Specifies the key to start with when listing objects in a bucket.
+
+- max-keys          
+
+    Sets the maximum number of keys returned in the response. By default,
+    the action returns up to 1,000 key names. The response might contain
+    fewer keys but will never contain more. If additional keys satisfy the
+    search criteria, but were not returned because max-keys was exceeded,
+    the response contains <isTruncated>true</isTruncated>. To return the
+    additional keys, see key-marker and version-id-marker.
+
+    default: 1000
+
+- prefix            
+
+    Use this parameter to select only those keys that begin with the
+    specified prefix. You can use prefixes to separate a bucket into
+    different groupings of keys. (You can think of using prefix to make
+    groups in the same way that you'd use a folder in a file system.) You
+    can use prefix with delimiter to roll up numerous objects into a
+    single result under CommonPrefixes.
+
+- version-id-marker 
+
+    Specifies the object version you want to start listing from.
+
 ## err
 
 The S3 error code for the last error encountered.
@@ -797,7 +913,7 @@ For more on testing this module see
     can override this behavior by setting `AWS_S3_DNS_BUCKET_NAMES` to any
     value.
 
-- AWS\_S3\_DSN\_BUCKET\_NAMES
+- AWS\_S3\_DNS\_BUCKET\_NAMES
 
     Set this to any value to override the default behavior of disabling
     DNS bucket names during testing.

VERSION

@@ -1 +1 @@
- 0.66
+0.66