NAME

Net::Amazon::S3::Features - Features available in Net::Amazon::S3
VERSION

version 0.99
AUTHOR

Branislav Zahradník <barney@cpan.org>
COPYRIGHT AND LICENSE

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
API COMPARISON

Net::Amazon::S3 supports two APIs with different feature support.
This document describes current behaviour.
Error reporting

Default error reporting method.
set S3 err: Operation returns expression evaluated as false and "err" with "errstr" are populated from response content
See Net::Amazon::S3::Error::Handler::Status, Net::Amazon::S3::Error::Handler::Legacy
set network error: Populates S3 err with "network_error" constant and S3 errstr with http status line (eg: "404 Not Found") and throws.
See Net::Amazon::S3::Error::Handler::Legacy
confess: Operation throws using "confess"
See Net::Amazon::S3::Error::Handler::Confess
Feature support

For details see corresponding "api-operation" / "client-operation" test file
List of "Amazon S3 Operations" <https://docs.aws.amazon.com/AmazonS3/latest/API/API_Operations_Amazon_Simple_Storage_Service.html>
 |-------------------------+---------------------------------+-----------------------------------|
 | operation               | Net::Amazon::S3 (API)           | Net::Amazon::S3::Client           |
 |-------------------------+---------------------------------+-----------------------------------|
 | AbortMultipartUpload    | ❌                              | object->abort_multipart_upload    |
 | returns                 | ❌                              | http response                     |
 | errors                  | ❌                              | confess                           |
 |-------------------------+---------------------------------+-----------------------------------|
 | CompleteMultipartUpload | ❌                              | object->complete_multipart_upload |
 | returns                 | ❌                              | http response                     |
 | errors                  | ❌                              | confess                           |
 |-------------------------+---------------------------------+-----------------------------------|
 | CreateBucket            | s3->add_bucket                  | client->create_bucket             |
 | - with region           | ✅                              | ✅                                |
 | returns                 | Bucket instance                 | Bucket instance                   |
 | errors                  | set S3 err                      | confess                           |
 |-------------------------+---------------------------------+-----------------------------------|
 | CreateMultipartUpload   | ❌                              | object->initiate_multipart_upload |
 | returns                 | ❌                              | http response                     |
 | errors                  | ❌                              | confess                           |
 |-------------------------+---------------------------------+-----------------------------------|
 | DeleteBucket            | s3->delete_bucket               | bucket->delete                    |
 | returns                 | boolean                         | boolean                           |
 | errors                  | set S3 err                      | confess                           |
 |-------------------------+---------------------------------+-----------------------------------|
 | DeleteBucketTagging     | bucket->delete_tags             | bucket->delete_tags               |
 | returns                 | boolean                         | boolean                           |
 | errors                  | set S3 err                      | confess                           |
 |-------------------------+---------------------------------+-----------------------------------|
 | DeleteObject            | bucket->delete_key              | bucket->object->delete            |
 | returns                 | boolean                         | boolean                           |
 | errors                  | set S3 err                      | confess                           |
 |-------------------------+---------------------------------+-----------------------------------|
 | DeleteObjects           | bucket->delete_multi_object     | bucket->delete_multi_object       |
 | - auto chunks           | ✅                              | ✅                                |
 | returns                 | boolean                         | HTTP::Response object             |
 | errors                  | set S3 err                      | confess                           |
 |-------------------------+---------------------------------+-----------------------------------|
 | DeleteObjectTagging     | bucket->delete_tags             | bucket->object->delete_tags       |
 | returns                 | boolean                         | boolean                           |
 | errors                  | set S3 err                      | confess                           |
 |-------------------------+---------------------------------+-----------------------------------|
 | GetBucketAcl            | bucket->get_acl                 | bucket->acl                       |
 | returns                 | response body (XML)             | response body (XML)               |
 |                         | (undef on Not Found)            |                                   |
 | errors                  | set network error               | confess                           |
 |                         | (none on Not Found)             |                                   |
 |-------------------------+---------------------------------+-----------------------------------|
 | GetBucketLocation       | bucket->get_location_constraint | bucket->get_location_constraint   |
 | returns                 | location (Str)                  | location (Str)                    |
 | errors                  | set S3 err                      | confess                           |
 |-------------------------+---------------------------------+-----------------------------------|
 | GetObject               | bucket->get_key                 | bucket->object->get               |
 | - into file             | ✅, bucket->get_key_filename    | ✅, bucket->object->get_filename  |
 | - into callback         | ❌                              | ✅, bucket->object->get_callback  |
 | returns                 | struct with value               | value                             |
 |                         | (undef on Not Found)            |                                   |
 | errors                  | set network error               | confess                           |
 |                         | (none on Not Found)             |                                   |
 |-------------------------+---------------------------------+-----------------------------------|
 | GetObjectAcl            | bucket->get_acl                 | ❌                                |
 | returns                 | response body (XML)             | ❌                                |
 |                         | (undef on Not Found)            | ❌                                |
 | errors                  | set network error               | ❌                                |
 |                         | (none on Not Found)             | ❌                                |
 |-------------------------+---------------------------------+-----------------------------------|
 | ListBuckets             | s3->buckets                     | client->buckets                   |
 | returns                 | Bucket instances in struct      | Bucket instances (list)           |
 | errors                  | set S3 err                      | confess                           |
 |-------------------------+---------------------------------+-----------------------------------|
 | ListObjects             | s3->list_bucket                 | bucket->list                      |
 | - common prefixes       | ✅                              | ❌                                |
 | - list all              | ✅, s3->list_bucket_all         | ✅                                |
 | returns                 | struct with list                | iterator (Object list)            |
 | errors                  | set S3 err                      | confess during iteration          |
 |-------------------------+---------------------------------+-----------------------------------|
 | ListObjectsV2           | ❌                              | ❌                                |
 |-------------------------+---------------------------------+-----------------------------------|
 | ListParts               | ❌                              | ❌                                |
 |-------------------------+---------------------------------+-----------------------------------|
 | PutBucketAcl            | bucket->set_acl                 | bucket->set_acl                   |
 | - with canned acl       | ✅, as acl                      | ✅, as acl                        |
 | - with explicit acl     | ✅, as acl                      | ✅, as acl                        |
 | - with xml acl          | ✅, as acl_xml                  | ✅, as acl_xml                    |
 | returns                 | boolean                         | boolean                           |
 | errors                  | set S3 err                      | confess                           |
 |-------------------------+---------------------------------+-----------------------------------|
 | PutBucketTagging        | bucket->add_tags                | bucket->add_tags                  |
 | - with canned acl       | ✅, as acl                      | ✅, as acl                        |
 | - with explicit acl     | ✅, as acl                      | ✅, as acl                        |
 | - with xml acl          | ✅, as acl_xml                  | ✅, as acl_xml                    |
 | returns                 | boolean                         | boolean                           |
 | errors                  | set S3 err                      | confess                           |
 |-------------------------+---------------------------------+-----------------------------------|
 | PutObject               | bucket->add_key                 | bucket->object->put               |
 | returns                 | boolean                         | empty string                      |
 | errors                  | set S3 err                      | confess                           |
 |-------------------------+---------------------------------+-----------------------------------|
 | PutObjectAcl            | bucket->set_acl                 | object->set_acl                   |
 | - with canned acl       | ✅, as acl                      | ✅, as acl                        |
 | - with explicit acl     | ✅, as acl                      | ✅, as acl                        |
 | - with xml acl          | ✅, as acl_xml                  | ✅, as acl_xml                    |
 | returns                 | boolean                         | boolean                           |
 | errors                  | set S3 err                      | confess                           |
 |-------------------------+---------------------------------+-----------------------------------|
 | PutObjectTagging        | bucket->add_tags                | bucket->object->add_tags          |
 | - with canned acl       | ✅, as acl                      | ✅, as acl                        |
 | - with explicit acl     | ✅, as acl                      | ✅, as acl                        |
 | - with xml acl          | ✅, as acl_xml                  | ✅, as acl_xml                    |
 | returns                 | boolean                         | boolean                           |
 | errors                  | set S3 err                      | confess                           |
 |-------------------------+---------------------------------+-----------------------------------|
 | RestoreObject           | ❌                              | bucket->object->restore           |
 | returns                 | ❌                              | http response                     |
 | errors                  | ❌                              | confess                           |
 |-------------------------+---------------------------------+-----------------------------------|
 | UploadPart              | ❌                              | bucket->object->put_part          |
 | - from value            | ❌                              | ✅                                |
 | - from file             | ❌                              | ❌                                |
 | - from file chunk       | ❌                              | ❌                                |
 | returns                 | ❌                              | http response                     |
 | errors                  | ❌                              | confess                           |
 |-------------------------+---------------------------------+-----------------------------------|
 | object-copy             | bucket->copy_key                | ❌                                |
 | returns                 | boolean                         | ❌                                |
 | errors                  | set S3 err                      | ❌                                |
 |-------------------------+---------------------------------+-----------------------------------|
 | object-head             |                                 | ❌                                |
 | returns                 | boolean                         | ❌                                |
 | errors                  | set S3 err                      | ❌                                |
 |-------------------------+---------------------------------+-----------------------------------|
TODO plan (asorted, without time-plan)

unify features: Both APIs should support same set of operations
support all AWS S3 operations and x-amz-* headers: https://docs.aws.amazon.com/AmazonS3/latest/API/Welcome.html
add async API (AnyEvent / IO::Async)