Amazon-S3
view release on metacpan or search on metacpan
Mon Aug 1 15:44:04 2022 Rob Lauer <rlauer6@comcast.net>
[0.55 - bucket region]:
* requires: latest version of most modules
* src/main/perl/lib/Amazon/S3.pm.in
- pod tweaks, corrections
- don't specify a minimum version of perl
(new): set default region to 'us-east-1', again
(get_bucket_location): $bucket, not $self
(buckets)
- verify region option
- pass hash of options and region to _send_request
(add_bucket)
- do not add region constraint if us-east-1
- refactored, send region to _send_request_expect_nothing
(delete_bucket): likewise refactored
(list_bucket): likewise refactored
(_make_request): use region() method of signer
(_do_http): debug statements, set last_reponse, reset_errors
(_do_http_no_redirect): likewise
(_send_request_expect_nothing): likewise
- accept hash argument
- debug statements
- croak if redirect, but no Location
(error): new
(reset_errors): new
(_remember_error): set error
* src/main/perl/lib/Amazon/S3/Bucket.pm.in
- pod tweaks, corrections
(new)
- + logger attribute
- + verify_region attribute, verify region if true
(_uri): remove leading '/'
(add_key): correct region if 301 response
(upload_multipart_object): debug messages
(upload_part_of_multipart_upload): likewise
(complete_multipart_upload): likewise
(get_key): remove redundant debug message
(delete_key): pass region to _send_request_expect_nothing
(set_acl): likewise
* src/main/perl/t/01-api.t: do not bailout on early tests
(error): new
Use your Access Key ID as the value of the AWSAccessKeyId parameter
in requests you send to Amazon Web Services (when required). Your
Access Key ID identifies you as the party responsible for the
request.
- aws\_secret\_access\_key
Since your Access Key ID is not encrypted in requests to AWS, it
could be discovered and used by anyone. Services that are not free
require you to provide additional information, a request signature,
to verify that a request containing your unique Access Key ID could
only have come from you.
**DO NOT INCLUDE THIS IN SCRIPTS OR APPLICATIONS YOU
DISTRIBUTE. YOU'LL BE SORRY.**
_Consider using a credential class as described above to provide
credentials, otherwise this class will store your credentials for
signing the requests. If you dump this object to logs your credentials
could be discovered._
In this case, both the `Amazon::S3` class and the
[Net::Amazon::Signature::V4](https://metacpan.org/pod/Net%3A%3AAmazon%3A%3ASignature%3A%3AV4) have your credentials. Caveat Emptor.
See also [Amazon::Credentials](https://metacpan.org/pod/Amazon%3A%3ACredentials) for more information about safely
storing your credentials and preventing exfiltration.
## region
Sets the region for the API calls. This will also be the
default when instantiating the bucket object unless you pass the
region parameter in the `bucket` method or use the `verify_region`
flag that will _always_ verify the region of the bucket using the
`get_location_constraint` method.
default: us-east-1
## buckets
buckets([verify-region])
- verify-region (optional)
`verify-region` is a boolean value that indicates if the
bucket's region should be verified when the bucket object is
instantiated.
If set to true, this method will call the `bucket` method with
`verify_region` set to true causing the constructor to call the
`get_location_constraint` for each bucket to set the bucket's
region. This will cause a significant decrease in the peformance of
the `buckets()` method. Setting the region for each bucket is
necessary since API operations on buckets require the region of the
bucket when signing API requests. If all of your buckets are in the
same region and you have passed a region parameter to your S3 object,
then that region will be used when calling the constructor of your
bucket objects.
default: false
- region
The region the bucket is to be created in.
Returns a [Amazon::S3::Bucket](https://metacpan.org/pod/Amazon%3A%3AS3%3A%3ABucket) object on success or `undef` on failure.
## bucket
bucket(bucket, [region])
bucket({ bucket => bucket-name, verify_region => boolean, region => region });
Takes a scalar argument or refernce to a hash of arguments.
You can pass the region or set `verify_region` indicating that
you want the bucket constructor to detemine the bucket region.
If you do not pass the region or set the `verify_region` value, the
region will be set to the default region set in your `Amazon::S3`
object.
See [Amazon::S3::Bucket](https://metacpan.org/pod/Amazon%3A%3AS3%3A%3ABucket) for a complete description of the `bucket`
method.
## delete\_bucket
Takes either a [Amazon::S3::Bucket](https://metacpan.org/pod/Amazon%3A%3AS3%3A%3ABucket) object or a reference to a hash
containing:
lib/Amazon/S3.pm view on Meta::CPAN
$self->host( sprintf 's3.%s.amazonaws.com', $self->_region );
}
}
return $self->_region;
}
########################################################################
sub buckets {
########################################################################
my ( $self, $verify_region ) = @_;
# The "default" region for Amazon is us-east-1
# This is the region to set it to for listing buckets
# You may need to reset the signer's endpoint to 'us-east-1'
# temporarily cache signer
my $region = $self->_region;
my $bucket_list;
$self->reset_signer_region($DEFAULT_REGION); # default region for buckets op
lib/Amazon/S3.pm view on Meta::CPAN
$buckets = [$buckets];
}
foreach my $node ( @{$buckets} ) {
push @buckets,
Amazon::S3::Bucket->new(
{ bucket => $node->{Name},
creation_date => $node->{CreationDate},
account => $self,
buffer_size => $self->buffer_size,
verify_region => $verify_region // $FALSE,
},
);
}
}
$self->reset_signer_region($region); # restore original region
$bucket_list = {
owner_id => $owner_id,
lib/Amazon/S3.pm view on Meta::CPAN
my $bucket_obj = $retval ? $self->bucket($bucket) : undef;
return $bucket_obj;
}
########################################################################
sub bucket {
########################################################################
my ( $self, @args ) = @_;
my ( $bucketname, $region, $verify_region );
if ( ref $args[0] && reftype( $args[0] ) eq 'HASH' ) {
( $bucketname, $region, $verify_region )
= @{ $args[0] }{qw(bucket region verify_region)};
}
else {
( $bucketname, $region ) = @args;
}
# only set to default region if a region wasn't passed or region
# verification not requested
if ( !$region && !$verify_region ) {
$region = $self->region;
}
return Amazon::S3::Bucket->new(
{ bucket => $bucketname,
account => $self,
region => $region,
verify_region => $verify_region,
},
);
}
########################################################################
sub delete_bucket {
########################################################################
my ( $self, $conf ) = @_;
my $bucket;
lib/Amazon/S3.pm view on Meta::CPAN
my $request
= HTTP::Request->new( 'GET', 'https://' . $bucket . $DOT . $self->host );
$self->{'signer'}->sign($request);
# We have to turn off our special retry since this will deliberately trigger that code
$self->turn_off_special_retry();
# If the bucket name has a period in it, the certificate validation
# will fail since it will expect a certificate for a subdomain.
# Setting it to verify against the expected host guards against
# that while still being secure since we will have verified
# the response as coming from the expected server.
$self->ua->ssl_opts( SSL_verifycn_name => $self->host );
my $response = $self->_do_http($request);
# Turn this off, since all other requests have the bucket after
# the host in the URL, and the host may change depending on the region
$self->ua->ssl_opts( SSL_verifycn_name => undef );
$self->turn_on_special_retry();
# If No error, then nothing to do
return $TRUE
if $response->is_success();
# If the error is due to the wrong region, then we will get
# back a block of XML with the details
if ( $response->content_type eq 'application/xml' and $response->content ) {
lib/Amazon/S3.pm view on Meta::CPAN
Use your Access Key ID as the value of the AWSAccessKeyId parameter
in requests you send to Amazon Web Services (when required). Your
Access Key ID identifies you as the party responsible for the
request.
=item aws_secret_access_key
Since your Access Key ID is not encrypted in requests to AWS, it
could be discovered and used by anyone. Services that are not free
require you to provide additional information, a request signature,
to verify that a request containing your unique Access Key ID could
only have come from you.
B<DO NOT INCLUDE THIS IN SCRIPTS OR APPLICATIONS YOU
DISTRIBUTE. YOU'LL BE SORRY.>
I<Consider using a credential class as described above to provide
credentials, otherwise this class will store your credentials for
signing the requests. If you dump this object to logs your credentials
could be discovered.>
lib/Amazon/S3.pm view on Meta::CPAN
See also L<Amazon::Credentials> for more information about safely
storing your credentials and preventing exfiltration.
=back
=head2 region
Sets the region for the API calls. This will also be the
default when instantiating the bucket object unless you pass the
region parameter in the C<bucket> method or use the C<verify_region>
flag that will I<always> verify the region of the bucket using the
C<get_location_constraint> method.
default: us-east-1
=head2 buckets
buckets([verify-region])
=over
=item verify-region (optional)
C<verify-region> is a boolean value that indicates if the
bucket's region should be verified when the bucket object is
instantiated.
If set to true, this method will call the C<bucket> method with
C<verify_region> set to true causing the constructor to call the
C<get_location_constraint> for each bucket to set the bucket's
region. This will cause a significant decrease in the peformance of
the C<buckets()> method. Setting the region for each bucket is
necessary since API operations on buckets require the region of the
bucket when signing API requests. If all of your buckets are in the
same region and you have passed a region parameter to your S3 object,
then that region will be used when calling the constructor of your
bucket objects.
default: false
lib/Amazon/S3.pm view on Meta::CPAN
The region the bucket is to be created in.
=back
Returns a L<Amazon::S3::Bucket> object on success or C<undef> on failure.
=head2 bucket
bucket(bucket, [region])
bucket({ bucket => bucket-name, verify_region => boolean, region => region });
Takes a scalar argument or refernce to a hash of arguments.
You can pass the region or set C<verify_region> indicating that
you want the bucket constructor to detemine the bucket region.
If you do not pass the region or set the C<verify_region> value, the
region will be set to the default region set in your C<Amazon::S3>
object.
See L<Amazon::S3::Bucket> for a complete description of the C<bucket>
method.
=head2 delete_bucket
Takes either a L<Amazon::S3::Bucket> object or a reference to a hash
containing:
lib/Amazon/S3/Bucket.pm view on Meta::CPAN
our $VERSION = '0.65'; ## no critic (RequireInterpolation)
__PACKAGE__->mk_accessors(
qw(
bucket
creation_date
account
buffer_size
region
logger
verify_region
),
);
########################################################################
sub new {
########################################################################
my ( $class, @args ) = @_;
my %options = ref $args[0] ? %{ $args[0] } : @args;
$options{buffer_size} ||= $DEFAULT_BUFFER_SIZE;
lib/Amazon/S3/Bucket.pm view on Meta::CPAN
if !$self->bucket;
croak 'no account'
if !$self->account;
if ( !$self->logger ) {
$self->logger( $self->account->get_logger );
}
# now each bucket maintains its own region
if ( !$self->region && $self->verify_region ) {
my $region;
if ( !$self->account->err ) {
$region = $self->get_location_constraint() // 'us-east-1';
}
$self->logger->debug( sprintf "bucket: %s region: %s\n",
$self->bucket, ( $region // $EMPTY ) );
$self->region($region);
lib/Amazon/S3/Bucket.pm view on Meta::CPAN
$etag =~ s/"$//xsm;
}
$retval = {
content_length => $response->content_length || 0,
content_type => $response->content_type,
etag => $etag,
value => $response->content,
};
# Validate against data corruption by verifying the MD5
if ( $method eq 'GET' ) {
my $md5
= ( $filename and -f $filename )
? file_md5_hex($filename)
: md5_hex( $retval->{value} );
# Some S3-compatible providers return an all-caps MD5 value in the
# etag so it should be lc'd for comparison.
croak "Computed and Response MD5's do not match: $md5 : $etag"
if $md5 ne lc $etag;
lib/Amazon/S3/Bucket.pm view on Meta::CPAN
bucket is associated with.
=item buffer_size
The buffer size used for reading and writing objects to S3.
default: 4K
=item region
If no region is set and C<verify_region> is set to true, the region of
the bucket will be determined by calling the
C<get_location_constraint> method. Note that this will decrease
performance of the constructor. If you know the region or are
operating in only 1 region, set the region in the C<account> object
(C<Amazon::S3>).
=item logger
Sets the logger. The logger should be a blessed reference capable of
providing at least a C<debug> and C<trace> method for recording log
messages. If no logger object is passed the C<account> object's logger
object will be used.
=item verify_region
Indicates that the bucket's region should be determined by calling the
C<get_location_constraint> method.
default: false
=back
I<NOTE:> This method does not check if a bucket actually exists unless
you set C<verify_region> to true. If the bucket does not exist,
the constructor will set the region to the default region specified by
the L<Amazon::S3> object (C<account>) that you passed.
Typically a developer will not call this method directly,
but work through the interface in L<S3::Amazon> that will
handle their creation.
=head2 add_key
add_key( key, value, configuration)
( run in 0.521 second using v1.01-cache-2.11-cpan-5467b0d2c73 )