# PODNAME:Net::Amazon::S3::Features
# ABSTRACT: Features available in Net::Amazon::S3
=pod
=encoding UTF-8
=head1 NAME
Net::Amazon::S3::Features - Features available in Net::Amazon::S3
=head1 VERSION
version 0.991
=head1 AUTHOR
Branislav Zahradník <barney@cpan.org>
=head1 COPYRIGHT AND LICENSE
This software is copyright (c) 2022 by Amazon Digital Services, Leon Brocard, Brad Fitzpatrick, Pedro Figueiredo, Rusty Conover, Branislav Zahradník.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
=cut
__DATA__
=pod
=encoding utf8
=head1 API COMPARISON
Net::Amazon::S3 supports two APIs with different feature support.
This document describes current behaviour.
=head2 Error reporting
Default error reporting method.
=over
=item set S3 err
Operation returns expression evaluated as false
and C<< err >> with C<< errstr >> are populated from response content
See L<Net::Amazon::S3::Error::Handler::Status>, L<Net::Amazon::S3::Error::Handler::Legacy>
=item set network error
Populates S3 err with C<< network_error >> constant and S3 errstr
with http status line (eg: C<< 404 Not Found >>) and throws.
See L<Net::Amazon::S3::Error::Handler::Legacy>
=item confess
Operation throws using C<< confess >>
See L<Net::Amazon::S3::Error::Handler::Confess>
=back
=head2 Feature support
For details see corresponding C<< api-operation >> / C<< client-operation >> test file
List of L<"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 | ❌ |
|-------------------------+---------------------------------+-----------------------------------|
=head2 TODO plan (asorted, without time-plan)
=over
=item unify features
Both APIs should support same set of operations
=item support all AWS S3 operations and x-amz-* headers
https://docs.aws.amazon.com/AmazonS3/latest/API/Welcome.html
=item add async API (AnyEvent / IO::Async)
=back