File Coverage

blib/lib/Net/Amazon/S3.pm
Criterion Covered Total %
statement 227 242 93.8
branch 28 36 77.7
condition 2 6 33.3
subroutine 59 59 100.0
pod 6 11 54.5
total 322 354 90.9


line stmt bran cond sub pod time code
1             package Net::Amazon::S3;
2             # ABSTRACT: Use the Amazon S3 - Simple Storage Service
3             $Net::Amazon::S3::VERSION = '0.98';
4 96     96   1070552 use Moose 0.85;
  96         28785541  
  96         911  
5 96     96   691185 use MooseX::StrictConstructor 0.16;
  96         1592421  
  96         636  
6              
7 96     96   745565 use Carp;
  96         248  
  96         6938  
8 96     96   58026 use Digest::HMAC_SHA1;
  96         510599  
  96         4184  
9 96     96   1719 use Safe::Isa ();
  96         1293  
  96         1885  
10              
11 96     96   57827 use Net::Amazon::S3::Bucket;
  96         475  
  96         5901  
12 96     96   43007 use Net::Amazon::S3::Client;
  96         321  
  96         3625  
13 96     96   59068 use Net::Amazon::S3::Client::Bucket;
  96         430  
  96         4857  
14 96     96   73699 use Net::Amazon::S3::Client::Object;
  96         511  
  96         5169  
15 96     96   64998 use Net::Amazon::S3::Error::Handler::Legacy;
  96         397  
  96         4403  
16 96     96   53653 use Net::Amazon::S3::HTTPRequest;
  96         466  
  96         5193  
17 96     96   62930 use Net::Amazon::S3::Request;
  96         440  
  96         4489  
18 96     96   60649 use Net::Amazon::S3::Response;
  96         486  
  96         5280  
19 96     96   60124 use Net::Amazon::S3::Operation::Bucket::Acl::Fetch;
  96         473  
  96         5207  
20 96     96   53468 use Net::Amazon::S3::Operation::Bucket::Acl::Set;
  96         428  
  96         4775  
21 96     96   50039 use Net::Amazon::S3::Operation::Bucket::Create;
  96         478  
  96         4796  
22 96     96   49642 use Net::Amazon::S3::Operation::Bucket::Delete;
  96         572  
  96         4921  
23 96     96   50422 use Net::Amazon::S3::Operation::Bucket::Location;
  96         383  
  96         4440  
24 96     96   51914 use Net::Amazon::S3::Operation::Bucket::Tags::Add;
  96         403  
  96         4912  
25 96     96   52417 use Net::Amazon::S3::Operation::Bucket::Tags::Delete;
  96         460  
  96         4705  
26 96     96   50776 use Net::Amazon::S3::Operation::Buckets::List;
  96         386  
  96         4319  
27 96     96   55458 use Net::Amazon::S3::Operation::Object::Acl::Fetch;
  96         421  
  96         4713  
28 96     96   52751 use Net::Amazon::S3::Operation::Object::Acl::Set;
  96         409  
  96         4748  
29 96     96   51681 use Net::Amazon::S3::Operation::Object::Add;
  96         465  
  96         4938  
30 96     96   51871 use Net::Amazon::S3::Operation::Object::Delete;
  96         407  
  96         4793  
31 96     96   51176 use Net::Amazon::S3::Operation::Object::Fetch;
  96         428  
  96         4788  
32 96     96   51080 use Net::Amazon::S3::Operation::Object::Head;
  96         428  
  96         4710  
33 96     96   50346 use Net::Amazon::S3::Operation::Object::Restore;
  96         437  
  96         4903  
34 96     96   53680 use Net::Amazon::S3::Operation::Object::Tags::Add;
  96         471  
  96         5002  
35 96     96   51712 use Net::Amazon::S3::Operation::Object::Tags::Delete;
  96         431  
  96         4791  
36 96     96   52851 use Net::Amazon::S3::Operation::Object::Upload::Abort;
  96         432  
  96         5083  
37 96     96   53214 use Net::Amazon::S3::Operation::Object::Upload::Complete;
  96         490  
  96         4972  
38 96     96   54578 use Net::Amazon::S3::Operation::Object::Upload::Create;
  96         455  
  96         4797  
39 96     96   54220 use Net::Amazon::S3::Operation::Object::Upload::Part;
  96         436  
  96         5092  
40 96     96   55241 use Net::Amazon::S3::Operation::Object::Upload::Parts;
  96         434  
  96         4929  
41 96     96   52692 use Net::Amazon::S3::Operation::Objects::Delete;
  96         448  
  96         4911  
42 96     96   52297 use Net::Amazon::S3::Operation::Objects::List;
  96         432  
  96         4610  
43 96     96   2707 use Net::Amazon::S3::Signature::V2;
  96         268  
  96         2726  
44 96     96   53125 use Net::Amazon::S3::Signature::V4;
  96         432  
  96         5291  
45 96     96   95130 use Net::Amazon::S3::Utils;
  96         333  
  96         3844  
46 96     96   45345 use Net::Amazon::S3::Vendor;
  96         414  
  96         4449  
47 96     96   58480 use Net::Amazon::S3::Vendor::Amazon;
  96         399  
  96         4502  
48 96     96   60635 use LWP::UserAgent::Determined;
  96         55827  
  96         3566  
49 96     96   821 use URI::Escape qw(uri_escape_utf8);
  96         242  
  96         193912  
50              
51             my $AMAZON_S3_HOST = 's3.amazonaws.com';
52              
53             has authorization_context => (
54             is => 'ro',
55             isa => 'Net::Amazon::S3::Authorization',
56             required => 0,
57              
58             handles => {
59             aws_access_key_id => 'aws_access_key_id',
60             aws_secret_access_key => 'aws_secret_access_key',
61             aws_session_token => 'aws_session_token',
62             },
63             );
64              
65             has vendor => (
66             is => 'ro',
67             isa => 'Net::Amazon::S3::Vendor',
68             required => 1,
69              
70             handles => {
71             authorization_method => 'authorization_method',
72             host => 'host',
73             secure => 'use_https',
74             use_virtual_host => 'use_virtual_host',
75             },
76             );
77              
78             has 'timeout' => ( is => 'ro', isa => 'Num', required => 0, default => 30 );
79             has 'retry' => ( is => 'ro', isa => 'Bool', required => 0, default => 0 );
80             has 'ua' => ( is => 'rw', isa => 'LWP::UserAgent', required => 0 );
81             has 'err' => ( is => 'rw', isa => 'Maybe[Str]', required => 0 );
82             has 'errstr' => ( is => 'rw', isa => 'Maybe[Str]', required => 0 );
83             has keep_alive_cache_size => ( is => 'ro', isa => 'Int', required => 0, default => 10 );
84              
85             has error_handler_class => (
86             is => 'ro',
87             lazy => 1,
88             default => 'Net::Amazon::S3::Error::Handler::Legacy',
89             );
90              
91             has error_handler => (
92             is => 'ro',
93             lazy => 1,
94             default => sub { $_[0]->error_handler_class->new (s3 => $_[0]) },
95             );
96              
97             has bucket_class => (
98             is => 'ro',
99             init_arg => undef,
100             lazy => 1,
101             default => 'Net::Amazon::S3::Bucket',
102             );
103              
104             sub _build_arg_authorization_context {
105 408     408   1094 my ($args) = @_;
106              
107 408         1208 my $aws_access_key_id = delete $args->{aws_access_key_id};
108 408         1064 my $aws_secret_access_key = delete $args->{aws_secret_access_key};
109 408         1082 my $use_iam_role = delete $args->{use_iam_role};
110 408         951 my $aws_session_token = delete $args->{aws_session_token};
111              
112 408 50       1471 if ($args->{authorization_context}) {
113 0         0 return $args->{authorization_context};
114             }
115              
116 408 100 66     2298 if ($use_iam_role || $aws_session_token) {
117 1         591 require Net::Amazon::S3::Authorization::IAM;
118              
119 1         16 return Net::Amazon::S3::Authorization::IAM->new (
120             aws_access_key_id => $aws_access_key_id,
121             aws_secret_access_key => $aws_secret_access_key,
122             aws_session_token => $aws_session_token,
123             )
124             }
125              
126 407         50313 require Net::Amazon::S3::Authorization::Basic;
127              
128 407         3372 return Net::Amazon::S3::Authorization::Basic->new (
129             aws_access_key_id => $aws_access_key_id,
130             aws_secret_access_key => $aws_secret_access_key,
131             );
132             }
133              
134             sub _build_arg_vendor {
135 408     408   1213 my ($args) = @_;
136              
137             my %backward =
138 1267         3541 map { $_ => delete $args->{$_} }
139 408         1160 grep { exists $args->{$_} }
  1632         3699  
140             qw[ host secure use_virtual_host authorization_method ]
141             ;
142              
143             return $args->{vendor}
144 408 100       2019 if $args->{vendor};
145              
146             $backward{host} = $AMAZON_S3_HOST
147 406 100       1832 unless exists $backward{host};
148              
149             $backward{use_https} = delete $backward{secure}
150 406 100       1649 if exists $backward{secure};
151              
152 406 100       1760 my $vendor_class = $backward{host} eq $AMAZON_S3_HOST
153             ? 'Net::Amazon::S3::Vendor::Amazon'
154             : 'Net::Amazon::S3::Vendor'
155             ;
156              
157 406         4005 return $vendor_class->new (%backward);
158             }
159              
160             around BUILDARGS => sub {
161             my ($orig, $class) = (shift, shift);
162             my $args = $class->$orig (@_);
163              
164             # support compat authorization arguments
165             $args->{authorization_context} = _build_arg_authorization_context $args;
166             $args->{vendor} = _build_arg_vendor $args;
167              
168             $args;
169             };
170              
171              
172             sub BUILD {
173 408     408 0 1022 my $self = shift;
174              
175 408         816 my $ua;
176 408 50       12625 if ( $self->retry ) {
177 0         0 $ua = LWP::UserAgent::Determined->new(
178             keep_alive => $self->keep_alive_cache_size,
179             requests_redirectable => [qw(GET HEAD DELETE PUT POST)],
180             );
181 0         0 $ua->timing('1,2,4,8,16,32');
182             } else {
183 408         11894 $ua = LWP::UserAgent->new(
184             keep_alive => $self->keep_alive_cache_size,
185             requests_redirectable => [qw(GET HEAD DELETE PUT POST)],
186             );
187             }
188              
189 408         602574 $ua->timeout( $self->timeout );
190 408         8610 $ua->env_proxy;
191              
192 408         519681 $self->ua($ua);
193             }
194              
195             sub buckets {
196 5     5 1 22 my ($self, %args) = @_;
197              
198 5         21 my $response = $self->_perform_operation (
199             'Net::Amazon::S3::Operation::Buckets::List',
200             %args,
201             );
202              
203 4 100       19 return unless $response->is_success;
204              
205 2         40 my $owner_id = $response->owner_id;;
206 2         7 my $owner_displayname = $response->owner_displayname;
207              
208 2         3 my @buckets;
209 2         5 foreach my $bucket ($response->buckets) {
210             push @buckets, $self->bucket_class->new (
211             account => $self,
212             bucket => $bucket->{name},
213             creation_date => $bucket->{creation_date},
214 4         94 );
215              
216             }
217              
218             return +{
219 2         15 owner_id => $owner_id,
220             owner_displayname => $owner_displayname,
221             buckets => \@buckets,
222             };
223             }
224              
225             sub add_bucket {
226 27     27 1 65 my $self = shift;
227 27         208 my %args = Net::Amazon::S3::Utils->parse_arguments_with_bucket (\@_);
228              
229 27         157 my $response = $self->_perform_operation (
230             'Net::Amazon::S3::Operation::Bucket::Create',
231              
232             %args,
233             );
234              
235 11 100       292 return unless $response->is_success;
236              
237 7         178 return $self->bucket ($args{bucket});
238             }
239              
240             sub bucket {
241 146     146 1 2294 my ( $self, $bucket ) = @_;
242              
243 146 100       5207 return $bucket if $bucket->$Safe::Isa::_isa ($self->bucket_class);
244              
245 145         5165 return $self->bucket_class->new(
246             { bucket => $bucket, account => $self } );
247             }
248              
249             sub delete_bucket {
250 9     9 1 20 my $self = shift;
251 9         83 my %args = Net::Amazon::S3::Utils->parse_arguments_with_bucket (\@_);
252              
253             croak 'must specify bucket'
254 9 50       41 unless defined $args{bucket};
255              
256 9         43 my $response = $self->_perform_operation (
257             'Net::Amazon::S3::Operation::Bucket::Delete',
258             %args,
259             );
260              
261 5 100       40 return unless $response->is_success;
262              
263 1         29 return 1;
264             }
265              
266             sub list_bucket {
267 16     16 1 40 my $self = shift;
268 16         111 my %args = Net::Amazon::S3::Utils->parse_arguments_with_bucket (\@_);
269              
270 16         105 my $response = $self->_perform_operation (
271             'Net::Amazon::S3::Operation::Objects::List',
272             %args,
273             );
274              
275 8 100       56 return unless $response->is_success;
276              
277 5         128 my $return = {
278             bucket => $response->bucket,
279             prefix => $response->prefix,
280             marker => $response->marker,
281             next_marker => $response->next_marker,
282             max_keys => $response->max_keys,
283             is_truncated => $response->is_truncated,
284             };
285              
286 5         16 my @keys;
287 5         20 foreach my $node ($response->contents) {
288             push @keys, {
289             key => $node->{key},
290             last_modified => $node->{last_modified},
291             etag => $node->{etag},
292             size => $node->{size},
293             storage_class => $node->{storage_class},
294             owner_id => $node->{owner}{id},
295             owner_displayname => $node->{owner}{displayname},
296 7         66 };
297             }
298 5         20 $return->{keys} = \@keys;
299              
300 5 100       17 if ( $args{delimiter} ) {
301 2         9 $return->{common_prefixes} = [ $response->common_prefixes ];
302             }
303              
304 5         26 return $return;
305             }
306              
307             sub list_bucket_all {
308 4     4 1 10 my $self = shift;
309 4         17 my %args = Net::Amazon::S3::Utils->parse_arguments_with_bucket (\@_);
310              
311 4         16 my $bucket = $args{bucket};
312 4 50       13 croak 'must specify bucket' unless $bucket;
313              
314 4         16 my $response = $self->list_bucket (%args);
315 0 0       0 return $response unless $response->{is_truncated};
316 0         0 my $all = $response;
317              
318 0         0 while (1) {
319             my $next_marker = $response->{next_marker}
320 0   0     0 || $response->{keys}->[-1]->{key};
321 0         0 $response = $self->list_bucket (
322             %args,
323             marker => $next_marker,
324             );
325 0         0 push @{ $all->{keys} }, @{ $response->{keys} };
  0         0  
  0         0  
326 0 0       0 last unless $response->{is_truncated};
327             }
328              
329 0         0 delete $all->{is_truncated};
330 0         0 delete $all->{next_marker};
331 0         0 return $all;
332             }
333              
334             # compat wrapper; deprecated as of 2005-03-23
335             sub add_key {
336 2     2 0 4 my $self = shift;
337 2         10 my %args = Net::Amazon::S3::Utils->parse_arguments_with_bucket_and_object (\@_);
338              
339 2         11 my $bucket = $self->bucket (delete $args{bucket});
340 2         11 return $bucket->add_key (%args);
341             }
342              
343             # compat wrapper; deprecated as of 2005-03-23
344             sub get_key {
345 2     2 0 5 my $self = shift;
346 2         20 my %args = Net::Amazon::S3::Utils->parse_arguments_with_bucket_and_object (\@_);
347              
348 2         13 my $bucket = $self->bucket (delete $args{bucket});
349 2         12 return $bucket->get_key (%args);
350             }
351              
352             # compat wrapper; deprecated as of 2005-03-23
353             sub head_key {
354 1     1 0 4 my ( $self, $conf ) = @_;
355 1         4 my $bucket = $self->bucket (delete $conf->{bucket});
356 1         6 return $bucket->head_key( $conf->{key} );
357             }
358              
359             # compat wrapper; deprecated as of 2005-03-23
360             sub delete_key {
361 2     2 0 6 my $self = shift;
362 2         11 my %args = Net::Amazon::S3::Utils->parse_arguments_with_bucket_and_object (\@_);
363              
364 2         11 my $bucket = $self->bucket (delete $args{bucket});
365 2         10 return $bucket->delete_key (%args);
366             }
367              
368             sub _perform_operation {
369 203     203   1018 my ($self, $operation, %params) = @_;
370              
371 203         610 my $error_handler = delete $params{error_handler};
372 203 100       3773 $error_handler = $self->error_handler unless defined $error_handler;
373              
374 203         710 my $request_class = $operation . '::Request';
375 203         510 my $response_class = $operation . '::Response';
376 203         541 my $filename = delete $params{filename};
377              
378 203         9722 my $request = $request_class->new (s3 => $self, %params);
379 203         5969 my $http_response = $self->ua->request ($request->http_request, $filename);
380 203         172699 my $response = $response_class->new (http_response => $http_response);
381              
382 203         216454 $error_handler->handle_error ($response);
383              
384 135         5862 return $response;
385             }
386              
387             sub _urlencode {
388 387     387   944 my ( $self, $unencoded ) = @_;
389 387         1488 return uri_escape_utf8( $unencoded, '^A-Za-z0-9_\-\.' );
390             }
391              
392             __PACKAGE__->meta->make_immutable;
393              
394             1;
395              
396             __END__
397              
398             =pod
399              
400             =encoding UTF-8
401              
402             =head1 NAME
403              
404             Net::Amazon::S3 - Use the Amazon S3 - Simple Storage Service
405              
406             =head1 VERSION
407              
408             version 0.98
409              
410             =head1 SYNOPSIS
411              
412             use Net::Amazon::S3;
413             use Net::Amazon::S3::Authorization::Basic;
414             use Net::Amazon::S3::Authorization::IAM;
415             my $aws_access_key_id = 'fill me in';
416             my $aws_secret_access_key = 'fill me in too';
417              
418             my $s3 = Net::Amazon::S3->new (
419             authorization_context => Net::Amazon::S3::Authorization::Basic->new (
420             aws_access_key_id => $aws_access_key_id,
421             aws_secret_access_key => $aws_secret_access_key,
422             ),
423             retry => 1,
424             );
425              
426             # or use an IAM role.
427             my $s3 = Net::Amazon::S3->new (
428             authorization_context => Net::Amazon::S3::Authorization::IAM->new (
429             aws_access_key_id => $aws_access_key_id,
430             aws_secret_access_key => $aws_secret_access_key,
431             ),
432             retry => 1,
433             );
434              
435             # a bucket is a globally-unique directory
436             # list all buckets that i own
437             my $response = $s3->buckets;
438             foreach my $bucket ( @{ $response->{buckets} } ) {
439             print "You have a bucket: " . $bucket->bucket . "\n";
440             }
441              
442             # create a new bucket
443             my $bucketname = 'acmes_photo_backups';
444             my $bucket = $s3->add_bucket( { bucket => $bucketname } )
445             or die $s3->err . ": " . $s3->errstr;
446              
447             # or use an existing bucket
448             $bucket = $s3->bucket($bucketname);
449              
450             # store a file in the bucket
451             $bucket->add_key_filename( '1.JPG', 'DSC06256.JPG',
452             { content_type => 'image/jpeg', },
453             ) or die $s3->err . ": " . $s3->errstr;
454              
455             # store a value in the bucket
456             $bucket->add_key( 'reminder.txt', 'this is where my photos are backed up' )
457             or die $s3->err . ": " . $s3->errstr;
458              
459             # list files in the bucket
460             $response = $bucket->list_all
461             or die $s3->err . ": " . $s3->errstr;
462             foreach my $key ( @{ $response->{keys} } ) {
463             my $key_name = $key->{key};
464             my $key_size = $key->{size};
465             print "Bucket contains key '$key_name' of size $key_size\n";
466             }
467              
468             # fetch file from the bucket
469             $response = $bucket->get_key_filename( '1.JPG', 'GET', 'backup.jpg' )
470             or die $s3->err . ": " . $s3->errstr;
471              
472             # fetch value from the bucket
473             $response = $bucket->get_key('reminder.txt')
474             or die $s3->err . ": " . $s3->errstr;
475             print "reminder.txt:\n";
476             print " content length: " . $response->{content_length} . "\n";
477             print " content type: " . $response->{content_type} . "\n";
478             print " etag: " . $response->{content_type} . "\n";
479             print " content: " . $response->{value} . "\n";
480              
481             # delete keys
482             $bucket->delete_key('reminder.txt') or die $s3->err . ": " . $s3->errstr;
483             $bucket->delete_key('1.JPG') or die $s3->err . ": " . $s3->errstr;
484              
485             # and finally delete the bucket
486             $bucket->delete_bucket or die $s3->err . ": " . $s3->errstr;
487              
488             =head1 DESCRIPTION
489              
490             This module provides a Perlish interface to Amazon S3. From the
491             developer blurb: "Amazon S3 is storage for the Internet. It is
492             designed to make web-scale computing easier for developers. Amazon S3
493             provides a simple web services interface that can be used to store and
494             retrieve any amount of data, at any time, from anywhere on the web. It
495             gives any developer access to the same highly scalable, reliable,
496             fast, inexpensive data storage infrastructure that Amazon uses to run
497             its own global network of web sites. The service aims to maximize
498             benefits of scale and to pass those benefits on to developers".
499              
500             To find out more about S3, please visit: http://s3.amazonaws.com/
501              
502             To use this module you will need to sign up to Amazon Web Services and
503             provide an "Access Key ID" and " Secret Access Key". If you use this
504             module, you will incurr costs as specified by Amazon. Please check the
505             costs. If you use this module with your Access Key ID and Secret
506             Access Key you must be responsible for these costs.
507              
508             I highly recommend reading all about S3, but in a nutshell data is
509             stored in values. Values are referenced by keys, and keys are stored
510             in buckets. Bucket names are global.
511              
512             Note: This is the legacy interface, please check out
513             L<Net::Amazon::S3::Client> instead.
514              
515             Development of this code happens here: https://github.com/rustyconover/net-amazon-s3
516              
517             =head2 Bucket names with dots, HTTPS, and Signature V4
518              
519             At the moment Amazon S3 doesn't play well with HTTPS and virtual bucket hosts
520             if bucket name contains dots.
521              
522             Due the current implementation of Signature V4 handling you should use workaround
523             consisting of usage of region hostnames
524              
525             my $bucket_region = $global_s3->bucket ($bucket)->_head_region;
526              
527             my $region_s3 = Net::Amazon:S3->new (
528             ...,
529             vendor => Net::Amazon::S3::Vendor::Amazon->new (
530             host => "s3-$bucket_region.amazonaws.com",
531             use_virtual_host => 0,
532             ),
533             );
534              
535             my $bucket = $region_s3->bucket ($bucket);
536              
537             And use bucket instance / region s3 connection.
538              
539             =head1 METHODS
540              
541             =head2 new
542              
543             Create a new S3 client object. Takes some arguments:
544              
545             =over
546              
547             =item authorization_context
548              
549             Class that provides authorization informations.
550              
551             See one of available implementations for more
552              
553             =over
554              
555             =item L<Net::Amazon::S3::Authorization::Basic>
556              
557             =item L<Net::Amazon::S3::Authorization::IAM>
558              
559             =back
560              
561             =item vendor
562              
563             Instance of L<Net::Amazon::S3::Vendor> holding vendor specific deviations.
564              
565             S3 became widely used object storage protocol with many vendors providing
566             different feature sets and different compatibility level.
567              
568             One common difference is bucket's HEAD request to determine its region.
569              
570             To maintain currently known differences along with any differencies that
571             may rise in feature it's better to hold vendor specification in dedicated
572             classes. This also allows users to build their own fine-tuned vendor classes.
573              
574             =over
575              
576             =item L<Net::Amazon::S3::Vendor::Amazon>
577              
578             =item L<Net::Amazon::S3::Vendor::Generic>
579              
580             =back
581              
582             =item aws_access_key_id
583              
584             Deprecated.
585              
586             When used it's used to create authorization context.
587              
588             Use your Access Key ID as the value of the AWSAccessKeyId parameter
589             in requests you send to Amazon Web Services (when required). Your
590             Access Key ID identifies you as the party responsible for the
591             request.
592              
593             =item aws_secret_access_key
594              
595             Deprecated.
596              
597             When used it's used to create authorization context.
598              
599             Since your Access Key ID is not encrypted in requests to AWS, it
600             could be discovered and used by anyone. Services that are not free
601             require you to provide additional information, a request signature,
602             to verify that a request containing your unique Access Key ID could
603             only have come from you.
604              
605             DO NOT INCLUDE THIS IN SCRIPTS OR APPLICATIONS YOU DISTRIBUTE. YOU'LL BE SORRY
606              
607             =item aws_session_token
608              
609             Deprecated.
610              
611             When used it's used to create authorization context.
612              
613             If you are using temporary credentials provided by the AWS Security Token
614             Service, set the token here, and it will be added to the request in order to
615             authenticate it.
616              
617             =item use_iam_role
618              
619             Deprecated.
620              
621             When used it's used to create authorization context.
622              
623             If you'd like to use IAM provided temporary credentials, pass this option
624             with a true value.
625              
626             =item secure
627              
628             Deprecated.
629              
630             Set this to C<0> if you don't want to use SSL-encrypted connections when talking
631             to S3. Defaults to C<1>.
632              
633             To use SSL-encrypted connections, LWP::Protocol::https is required.
634              
635             See L<#vendor> and L<Net::Amazon::S3::Vendor>.
636              
637             =item keep_alive_cache_size
638              
639             Set this to C<0> to disable Keep-Alives. Default is C<10>.
640              
641             =item timeout
642              
643             How many seconds should your script wait before bailing on a request to S3? Defaults
644             to 30.
645              
646             =item retry
647              
648             If this library should retry upon errors. This option is recommended.
649             This uses exponential backoff with retries after 1, 2, 4, 8, 16, 32 seconds,
650             as recommended by Amazon. Defaults to off.
651              
652             =item host
653              
654             Deprecated.
655              
656             The S3 host endpoint to use. Defaults to 's3.amazonaws.com'. This allows
657             you to connect to any S3-compatible host.
658              
659             See L<#vendor> and L<Net::Amazon::S3::Vendor>.
660              
661             =item use_virtual_host
662              
663             Deprecated.
664              
665             Use the virtual host method ('bucketname.s3.amazonaws.com') instead of specifying the
666             bucket at the first part of the path. This is particularly useful if you want to access
667             buckets not located in the US-Standard region (such as EU, Asia Pacific or South America).
668             See L<http://docs.aws.amazon.com/AmazonS3/latest/dev/VirtualHosting.html> for the pros and cons.
669              
670             See L<#vendor> and L<Net::Amazon::S3::Vendor>.
671              
672             =item authorization_method
673              
674             Deprecated.
675              
676             Authorization implementation package name.
677              
678             This library provides L<< Net::Amazon::S3::Signature::V2 >> and L<< Net::Amazon::S3::Signature::V4 >>
679              
680             Default is Signature 4 if host is C<< s3.amazonaws.com >>, Signature 2 otherwise
681              
682             See L<#vendor> and L<Net::Amazon::S3::Vendor>.
683              
684             =item error_handler_class
685              
686             Error handler class name (package name), see L<< Net::Amazon::S3::Error::Handler >>
687             for more.
688              
689             Default: L<< Net::Amazon::S3::Error::Handler::Legacy >>
690              
691             =item error_handler
692              
693             Instance of error handler class.
694              
695             =back
696              
697             =head3 Notes
698              
699             When using L<Net::Amazon::S3> in child processes using fork (such as in
700             combination with the excellent L<Parallel::ForkManager>) you should create the
701             S3 object in each child, use a fresh LWP::UserAgent in each child, or disable
702             the L<LWP::ConnCache> in the parent:
703              
704             $s3->ua( LWP::UserAgent->new(
705             keep_alive => 0, requests_redirectable => [qw'GET HEAD DELETE PUT POST'] );
706              
707             =head2 buckets
708              
709             Returns undef on error, else hashref of results
710              
711             =head2 add_bucket
712              
713             # Create new bucket with default location
714             my $bucket = $s3->add_bucket ('new-bucket');
715              
716             # Create new bucket in another location
717             my $bucket = $s3->add_bucket ('new-bucket', location_constraint => 'eu-west-1');
718             my $bucket = $s3->add_bucket ('new-bucket', { location_constraint => 'eu-west-1' });
719             my $bucket = $s3->add_bucket (bucket => 'new-bucket', location_constraint => 'eu-west-1');
720             my $bucket = $s3->add_bucket ({ bucket => 'new-bucket', location_constraint => 'eu-west-1' });
721              
722             Method creates and returns new bucket.
723              
724             In case of error it reports it and returns C<undef> (refer L</"ERROR HANDLING">).
725              
726             Recognized positional arguments (refer L</"CALLING CONVENTION">)
727              
728             =over
729              
730             =item bucket
731              
732             Required, recognized as positional.
733              
734             The name of the bucket you want to add.
735              
736             =back
737              
738             Recognized optional arguments
739              
740             =over
741              
742             =item acl
743              
744             acl => 'private'
745             acl => Net::Amazon::S3::ACL::Canned->PRIVATE
746             acl => Net::Amazon::S3::ACL::Set->grant_read (email => 'foo@bar.baz')
747              
748             I<Available since v0.94>
749              
750             Set ACL to the newly created bucket. Refer L<Net::Amazon::S3::ACL> for possibilities.
751              
752             =item acl_short (deprecated)
753              
754             I<Deprecated since v0.94>
755              
756             When specified its value is used to populate C<acl> argument (unless it exists).
757              
758             =item location_constraint
759              
760             Optional.
761              
762             Sets the location constraint of the new bucket. If left unspecified, the
763             default S3 datacenter location will be used.
764              
765             This library recognizes regions according Amazon S3 documentation
766              
767             =over
768              
769             =item →
770              
771             L<https://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region>
772              
773             =item →
774              
775             L<https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateBucket.html#API_CreateBucket_RequestSyntax>
776              
777             =back
778              
779             =back
780              
781             Provides operation L<CreateBucket|https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateBucket.html>.
782              
783             =head2 bucket BUCKET
784              
785             Takes a scalar argument, the name of the bucket you're creating
786              
787             Returns an (unverified) bucket object from an account. Does no network access.
788              
789             =head2 delete_bucket
790              
791             $s3->delete_bucket ($bucket);
792             $s3->delete_bucket (bucket => $bucket);
793              
794             Deletes bucket from account.
795              
796             Returns C<true> if the bucket is successfully deleted.
797              
798             Returns C<false> and reports an error otherwise (refer L</"ERROR HANDLING">)
799              
800             Positional arguments (refer L</"CALLING CONVENTION">)
801              
802             =over
803              
804             =item bucket
805              
806             Required.
807              
808             The name of the bucket or L<Net::Amazon::S3::Bucket> instance you want to delete.
809              
810             =back
811              
812             Provides operation L<"DeleteBucket"|https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteBucket.html>
813              
814             =head2 list_bucket
815              
816             List all keys in this bucket.
817              
818             Takes a hashref of arguments:
819              
820             MANDATORY
821              
822             =over
823              
824             =item bucket
825              
826             The name of the bucket you want to list keys on
827              
828             =back
829              
830             OPTIONAL
831              
832             =over
833              
834             =item prefix
835              
836             Restricts the response to only contain results that begin with the
837             specified prefix. If you omit this optional argument, the value of
838             prefix for your query will be the empty string. In other words, the
839             results will be not be restricted by prefix.
840              
841             =item delimiter
842              
843             If this optional, Unicode string parameter is included with your
844             request, then keys that contain the same string between the prefix
845             and the first occurrence of the delimiter will be rolled up into a
846             single result element in the CommonPrefixes collection. These
847             rolled-up keys are not returned elsewhere in the response. For
848             example, with prefix="USA/" and delimiter="/", the matching keys
849             "USA/Oregon/Salem" and "USA/Oregon/Portland" would be summarized
850             in the response as a single "USA/Oregon" element in the CommonPrefixes
851             collection. If an otherwise matching key does not contain the
852             delimiter after the prefix, it appears in the Contents collection.
853              
854             Each element in the CommonPrefixes collection counts as one against
855             the MaxKeys limit. The rolled-up keys represented by each CommonPrefixes
856             element do not. If the Delimiter parameter is not present in your
857             request, keys in the result set will not be rolled-up and neither
858             the CommonPrefixes collection nor the NextMarker element will be
859             present in the response.
860              
861             =item max-keys
862              
863             This optional argument limits the number of results returned in
864             response to your query. Amazon S3 will return no more than this
865             number of results, but possibly less. Even if max-keys is not
866             specified, Amazon S3 will limit the number of results in the response.
867             Check the IsTruncated flag to see if your results are incomplete.
868             If so, use the Marker parameter to request the next page of results.
869             For the purpose of counting max-keys, a 'result' is either a key
870             in the 'Contents' collection, or a delimited prefix in the
871             'CommonPrefixes' collection. So for delimiter requests, max-keys
872             limits the total number of list results, not just the number of
873             keys.
874              
875             =item marker
876              
877             This optional parameter enables pagination of large result sets.
878             C<marker> specifies where in the result set to resume listing. It
879             restricts the response to only contain results that occur alphabetically
880             after the value of marker. To retrieve the next page of results,
881             use the last key from the current page of results as the marker in
882             your next request.
883              
884             See also C<next_marker>, below.
885              
886             If C<marker> is omitted,the first page of results is returned.
887              
888             =back
889              
890             Returns undef on error and a hashref of data on success:
891              
892             The hashref looks like this:
893              
894             {
895             bucket => $bucket_name,
896             prefix => $bucket_prefix,
897             common_prefixes => [$prefix1,$prefix2,...]
898             marker => $bucket_marker,
899             next_marker => $bucket_next_available_marker,
900             max_keys => $bucket_max_keys,
901             is_truncated => $bucket_is_truncated_boolean
902             keys => [$key1,$key2,...]
903             }
904              
905             Explanation of bits of that:
906              
907             =over
908              
909             =item common_prefixes
910              
911             If list_bucket was requested with a delimiter, common_prefixes will
912             contain a list of prefixes matching that delimiter. Drill down into
913             these prefixes by making another request with the prefix parameter.
914              
915             =item is_truncated
916              
917             B flag that indicates whether or not all results of your query were
918             returned in this response. If your results were truncated, you can
919             make a follow-up paginated request using the Marker parameter to
920             retrieve the rest of the results.
921              
922             =item next_marker
923              
924             A convenience element, useful when paginating with delimiters. The
925             value of C<next_marker>, if present, is the largest (alphabetically)
926             of all key names and all CommonPrefixes prefixes in the response.
927             If the C<is_truncated> flag is set, request the next page of results
928             by setting C<marker> to the value of C<next_marker>. This element
929             is only present in the response if the C<delimiter> parameter was
930             sent with the request.
931              
932             =back
933              
934             Each key is a hashref that looks like this:
935              
936             {
937             key => $key,
938             last_modified => $last_mod_date,
939             etag => $etag, # An MD5 sum of the stored content.
940             size => $size, # Bytes
941             storage_class => $storage_class # Doc?
942             owner_id => $owner_id,
943             owner_displayname => $owner_name
944             }
945              
946             =head2 list_bucket_all
947              
948             List all keys in this bucket without having to worry about
949             'marker'. This is a convenience method, but may make multiple requests
950             to S3 under the hood.
951              
952             Takes the same arguments as list_bucket.
953              
954             =head2 _perform_operation
955              
956             my $response = $s3->_perform_operation ('Operation' => (
957             # ... operation request parameters
958             ));
959              
960             Internal operation implementation method, takes request construction parameters,
961             performs necessary HTTP requests(s) and returns Response instance.
962              
963             Method takes same named parameters as realted Request class.
964              
965             Method provides available contextual parameters by default (eg s3, bucket)
966              
967             Method invokes contextual error handler.
968              
969             =head1 CALLING CONVENTION
970              
971             I<Available since v0.97> - calling convention extentend
972              
973             In order to make method calls somehow consistent, backward compatible,
974             and extendable, API's methods support multiple ways how to provide their arguments
975              
976             =over
977              
978             =item plain named arguments (preferred)
979              
980             method (named => 'argument', another => 'argument');
981              
982             =item trailing configuration hash
983              
984             method ({ named => 'argument', another => 'argument' });
985             method (positional, { named => 'argument', another => 'argument' } );
986              
987             Last argument of every method can be configuration hash, treated as additional
988             named arguments. Can be combined with named arguments.
989              
990             =item positional arguments with optional named arguments
991              
992             method (positional, named => 'argument', another => 'argument');
993             method (positional, { named => 'argument', another => 'argument' } );
994              
995             For methods supporting mandatory positional arguments additional named
996             arguments and/or configuration hash is supported.
997              
998             Named arguments or configuration hash can specify value of positional
999             arguments as well removing it from list of required positional arguments
1000             for given call (see example)
1001              
1002             $s3->bucket->add_key ('key', 'value', acl => $acl);
1003             $s3->bucket->add_key ('value', key => 'key', acl => $acl);
1004             $s3->bucket->add_key (key => 'key', value => 'value', acl => $acl);
1005              
1006             =back
1007              
1008             =head1 ERROR HANDLING
1009              
1010             L<Net::Amazon::S3> supports pluggable error handling via
1011             L<Net::Amazon::S3::Error::Handler>.
1012              
1013             When response ends up with an error, every method reports it, and in case it
1014             receives control back (no exception), it returns C<undef>.
1015              
1016             Default error handling for L<Net::Amazon::S3> is L<Net::Amazon::S3::Error::Handler::Legacy>
1017             which (mostly) sets C<err> and C<errstr>.
1018              
1019             =head1 LICENSE
1020              
1021             This module contains code modified from Amazon that contains the
1022             following notice:
1023              
1024             # This software code is made available "AS IS" without warranties of any
1025             # kind. You may copy, display, modify and redistribute the software
1026             # code either by itself or as incorporated into your code; provided that
1027             # you do not remove any proprietary notices. Your use of this software
1028             # code is at your own risk and you waive any claim against Amazon
1029             # Digital Services, Inc. or its affiliates with respect to your use of
1030             # this software code. (c) 2006 Amazon Digital Services, Inc. or its
1031             # affiliates.
1032              
1033             =head1 TESTING
1034              
1035             Testing S3 is a tricky thing. Amazon wants to charge you a bit of
1036             money each time you use their service. And yes, testing counts as using.
1037             Because of this, the application's test suite skips anything approaching
1038             a real test unless you set these three environment variables:
1039              
1040             =over
1041              
1042             =item AMAZON_S3_EXPENSIVE_TESTS
1043              
1044             Doesn't matter what you set it to. Just has to be set
1045              
1046             =item AWS_ACCESS_KEY_ID
1047              
1048             Your AWS access key
1049              
1050             =item AWS_ACCESS_KEY_SECRET
1051              
1052             Your AWS sekkr1t passkey. Be forewarned that setting this environment variable
1053             on a shared system might leak that information to another user. Be careful.
1054              
1055             =back
1056              
1057             =head1 AUTHOR
1058              
1059             Leon Brocard <acme@astray.com> and unknown Amazon Digital Services programmers.
1060              
1061             Brad Fitzpatrick <brad@danga.com> - return values, Bucket object
1062              
1063             Pedro Figueiredo <me@pedrofigueiredo.org> - since 0.54
1064              
1065             Branislav Zahradník <barney@cpan.org> - since v0.81
1066              
1067             =head1 SEE ALSO
1068              
1069             L<Net::Amazon::S3::Bucket>
1070              
1071             =head1 AUTHOR
1072              
1073             Branislav Zahradník <barney@cpan.org>
1074              
1075             =head1 COPYRIGHT AND LICENSE
1076              
1077             This software is copyright (c) 2021 by Amazon Digital Services, Leon Brocard, Brad Fitzpatrick, Pedro Figueiredo, Rusty Conover, Branislav Zahradník.
1078              
1079             This is free software; you can redistribute it and/or modify it under
1080             the same terms as the Perl 5 programming language system itself.
1081              
1082             =cut