Amazon-S3

 view release on metacpan or  search on metacpan

lib/Amazon/S3.pm  view on Meta::CPAN

package Amazon::S3;

use strict;
use warnings;

use Amazon::S3::Bucket;
use Amazon::S3::BucketV2;
use Amazon::S3::Constants qw(:all);

use Amazon::S3::Util qw(
  set_md5_header
  urlencode
  get_parameters
  create_xml_request
  create_api_uri
  create_query_string
);

use Amazon::S3::Logger;
use Amazon::S3::Signature::V4;

use Carp;
use Data::Dumper;
use Digest::HMAC_SHA1;
use Digest::MD5 qw(md5_hex);
use English qw(-no_match_vars);
use HTTP::Date;
use LWP::UserAgent::Determined;
use List::Util qw( any pairs none );
use MIME::Base64 qw(encode_base64 decode_base64);
use Module::Load;
use Scalar::Util qw( reftype blessed );
use URI;
use XML::Simple;

use parent qw(Class::Accessor::Fast Exporter);

__PACKAGE__->mk_accessors(
  qw(
    aws_access_key_id
    aws_secret_access_key
    token
    buffer_size
    cache_signer
    checksum_types
    checksum_algorithm
    credentials
    dns_bucket_names
    digest
    endpoint_url
    err
    errstr
    error
    express
    host
    last_request
    last_response
    logger
    log_level
    raise_error
    retry
    _region
    secure
    _signer
    timeout
    ua
    verify_checksums
  ),
);

our $VERSION = '2.1.4'; ## no critic (RequireInterpolation)

our @EXPORT_OK = qw(is_domain_bucket);

########################################################################
sub new {
########################################################################
  my ( $class, @args ) = @_;

  my %options = ref $args[0] ? %{ $args[0] } : @args;

  $options{timeout}            //= $DEFAULT_TIMEOUT;
  $options{cache_signer}       //= $FALSE;
  $options{retry}              //= $FALSE;
  $options{express}            //= $FALSE;
  $options{verify_checksums}   //= $TRUE;
  $options{checksum_algorithm} //= 'crc64nvme';
  $options{raise_error}        //= $FALSE;

  croak "ERROR: pass endpoint_url or host but not both\n"
    if $options{endpoint_url} && $options{host};

  if ( my $endpoint_url = $options{endpoint_url} ) {
    @options{qw(secure host)} = _parse_endpoint($endpoint_url);
  }
  elsif ( $options{host} ) {
    if ( $options{host} =~ m{\Ahttps?://}xsm ) {
      warn "host containing a URL is deprecated; use endpoint_url instead\n";

      @options{qw(secure host)} = _parse_endpoint( $options{host} );
    }
    else {
      $options{secure} //= $TRUE;
    }
  }
  else {
    $options{secure} = $TRUE;
    $options{host}   = $DEFAULT_HOST;
  }

  $options{dns_bucket_names} //= $TRUE;

  croak sprintf "ERROR: invalid checksum_algorithm: '%s'\nMust be one of: %s\n", $options{checksum_algorithm}, join q{,},
    @AWS_CHECKSUM_TYPES
    if none { $options{checksum_algorithm} eq $_ } @AWS_CHECKSUM_TYPES;

  $options{_region} = delete $options{region};
  $options{_signer} = delete $options{signer};

  # convenience for level => 'debug' & for consistency with
  # Amazon::Credentials only do this if we are using internal logger,
  # call should NOT use debug flag but rather use their own logger's
  # level to turn on higher levels of logging...

  if ( !$options{logger} ) {
    if ( delete $options{debug} ) {
      $options{level} = 'debug';
    }

    $options{log_level} = delete $options{level};
    $options{log_level} //= $DEFAULT_LOG_LEVEL;

    $options{logger}
      = Amazon::S3::Logger->new( log_level => $options{log_level} );
  }

  my $self = $class->SUPER::new( \%options );

  # setup logger internal logging

  $self->get_logger->debug(
    sub {
      my %safe_options = %options;

      if ( $safe_options{aws_secret_access_key} ) {
        $safe_options{aws_secret_access_key} = '****';
        $safe_options{aws_access_key_id}     = '****';
      }

      return Dumper( [ options => \%safe_options ] );
    },
  );

  if ( !$self->credentials ) {

    croak 'No aws_access_key_id'
      if !$self->aws_access_key_id;

    croak 'No aws_secret_access_key'
      if !$self->aws_secret_access_key;

    # encrypt credentials
    $self->aws_access_key_id( _encrypt( $self->aws_access_key_id ) );
    $self->aws_secret_access_key( _encrypt( $self->aws_secret_access_key ) );
    $self->token( _encrypt( $self->token ) );
  }

  my $ua;

  if ( $self->retry ) {
    $ua = LWP::UserAgent::Determined->new(
      keep_alive            => $KEEP_ALIVE_CACHESIZE,
      requests_redirectable => [qw(GET HEAD DELETE)],
    );

    $ua->timing( join $COMMA, map { 2**$_ } 0 .. $MAX_RETRIES );
  }
  else {
    $ua = LWP::UserAgent->new(
      keep_alive            => $KEEP_ALIVE_CACHESIZE,
      requests_redirectable => [qw(GET HEAD DELETE)],
    );
  }

  $ua->timeout( $self->timeout );
  $ua->env_proxy;
  $self->ua($ua);

  $self->region( $self->_region // $DEFAULT_REGION );

  if ( !$self->_signer && $self->cache_signer ) {
    $self->_signer( $self->signer );
  }

  if ( $self->express ) {
    $self->use_express_one_zone();
  }

  $self->turn_on_special_retry();

  $self->_init_checksum_types;

  return $self;
}

########################################################################
sub _parse_endpoint {
########################################################################
  my ($endpoint_url) = @_;

  my $uri = URI->new($endpoint_url);

  my $scheme = $uri->scheme;

  croak "ERROR: endpoint_url must include a host\n"
    if !defined $uri->host || !length $uri->host;

  croak "ERROR: endpoint_url must use http or https\n"
    if !defined $scheme || ( $scheme ne 'http' && $scheme ne 'https' );

  croak "ERROR: endpoint_url must not contain a query or fragment\n"
    if defined $uri->query || defined $uri->fragment;

  croak "ERROR: endpoint_url must not contain a path\n"
    if $uri->path && $uri->path ne $SLASH;

  my $secure = $scheme eq 'https' ? $TRUE : $FALSE;
  my $host   = $uri->host_port;

  return ( $secure, $host );
}

########################################################################
sub _init_checksum_types {
########################################################################
  my ($self) = @_;

  my %checksum_types;
  $self->checksum_types( \%checksum_types );

  foreach my $algorithm (@AWS_CHECKSUM_TYPES) {
    next
      if !exists $CHECKSUM_TYPES{$algorithm};

    my $checksum_type = $CHECKSUM_TYPES{$algorithm};
    my $module        = $checksum_type->{module};

    my $loaded = eval {
      load $module;
      return $TRUE;
    };

    next
      if !$loaded;

    # since our module has already been loaded we only need the code
    # ref to the implementation
    $checksum_types{$algorithm} = $checksum_type->{digest};
  }

  return $self;
}

########################################################################
sub use_express_one_zone {
########################################################################
  my ($self) = @_;

  my $express = $self->express;

  $self->express($TRUE);

  $self->host( sprintf 's3express-control.%s.amazonaws.com', $self->region );
  $self->secure($TRUE);
  $self->dns_bucket_names($FALSE);

  return $express;
}

########################################################################
{
  my $encryption_key;

########################################################################

lib/Amazon/S3.pm  view on Meta::CPAN

sub get_token {
########################################################################
  my ($self) = @_;

  return _decrypt( $self->token );
}

########################################################################
sub turn_on_special_retry {
########################################################################
  my ($self) = @_;

  return
    if !$self->retry;

  # In the field we are seeing issue of Amazon returning with a 400
  # code in the case of timeout.  From AWS S3 logs: REST.PUT.PART
  # Backups/2017-05-04/<account>.tar.gz "PUT
  # /Backups<path>?partNumber=27&uploadId=<id> - HTTP/1.1" 400
  # RequestTimeout 360 20971520 20478 - "-" "libwww-perl/6.15"
  my $http_codes_hr = $self->ua->codes_to_determinate();
  $http_codes_hr->{$HTTP_BAD_REQUEST} = $TRUE;

  return;
}

########################################################################
sub turn_off_special_retry {
########################################################################
  my ($self) = @_;

  return
    if !$self->retry;

  # In the field we are seeing issue with Amazon returning a 400
  # code in the case of timeout.  From AWS S3 logs: REST.PUT.PART
  # Backups/2017-05-04/<account>.tar.gz "PUT
  # /Backups<path>?partNumber=27&uploadId=<id> - HTTP/1.1" 400
  # RequestTimeout 360 20971520 20478 - "-" "libwww-perl/6.15"
  my $http_codes_hr = $self->ua->codes_to_determinate();
  delete $http_codes_hr->{$HTTP_BAD_REQUEST};

  return;
}

########################################################################
sub region {
########################################################################
  my ( $self, @args ) = @_;

  if (@args) {
    $self->_region( $args[0] );
  }

  $self->get_logger->debug( sub { return 'region: ' . ( $self->_region // $EMPTY ) } );

  if ( $self->_region ) {
    my $host = $self->host;
    $self->get_logger->debug( sub { return 'host: ' . $self->host } );

    # only add region if host was not populated from endpoint_url
    if ( !$self->endpoint_url && $host =~ /\As3[.](.*)?amazonaws/xsm ) {
      $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

  my $r = $self->send_request(
    { method  => 'GET',
      path    => $EMPTY,
      headers => {},
      region  => $DEFAULT_REGION,
    },
  );

  return $bucket_list
    if !$r || $self->errstr;

  my $owner_id          = $r->{Owner}{ID};
  my $owner_displayname = $r->{Owner}{DisplayName};

  my @buckets;

  if ( ref $r->{Buckets} ) {
    my $buckets = $r->{Buckets}{Bucket};

    if ( !ref $buckets || reftype($buckets) ne 'ARRAY' ) {
      $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,
    owner_displayname => $owner_displayname,
    buckets           => \@buckets,
  };

  return $bucket_list;
}

########################################################################
sub reset_signer_region {
########################################################################
  my ( $self, $region ) = @_;

lib/Amazon/S3.pm  view on Meta::CPAN

  my $url = sprintf '%s://%s/%s', $protocol, $host, $path;

  #  if ( $path =~ m{\A([^/?]+)([^?]+)(.*)}xsm
  if ( $path =~ /\A([^\/?]+)([^?]+)(.*)/xsm
    && $self->dns_bucket_names
    && is_domain_bucket($1) ) {

    my $bucket = $1;
    $path = $2;

    my $query_string = $3;

    $self->logger->debug(
      sub {
        return Dumper(
          [ bucket       => $bucket,
            path         => $path,
            query_string => $query_string,
          ]
        );
      }
    );

    if ( $host =~ /([^:]+):([^:]\d+)$/xsm ) {

      my $port;

      $url = eval {
        $port = $2;
        $host = $1;

        my $uri = URI->new;

        $uri->scheme('http');
        $uri->host("$bucket.$host");
        $uri->port($port);
        $uri->path($path);

        return $uri . $query_string;
      };

      die sprintf
        "error creating uri for bucket: [%s], host: [%s], path: [%s], port: [%s]\n%s",
        $bucket, $host, $path, $port, $EVAL_ERROR

        if !$url || $EVAL_ERROR;
    }
    else {
      $url = sprintf '%s://%s.%s%s%s', $protocol, $bucket, $host, $path, $query_string;
    }
  }

  my $request = HTTP::Request->new( $method, $url, $http_headers );

  $self->last_request($request);

  if ($data) {
    $request->content($data);
  }

  $self->signer->region($region);  # always set regional endpoint for signing

  $self->signer->sign($request);

  return $request;
}

########################################################################
sub send_request {
########################################################################
  my ( $self, @args ) = @_;

  my $logger = $self->get_logger;

  $logger->trace(
    sub {
      return Dumper( [ args => \@args ] );
    },
  );

  my $keep_root = $FALSE;

  my $request = eval {
    return $args[0]
      if ref( $args[0] ) =~ /HTTP::Request/xsm;

    return {@args}
      if @args > 1 && !@args % 2;

    return $args[0]
      if ref $args[0];

    croak 'invalid argument to send_request';
  };

  if ( ref($request) !~ /HTTP::Request/xsm ) {
    $keep_root = delete $request->{keep_root};

    $request = $self->_make_request($request);
  }

  my $response = $self->_do_http($request);

  $self->last_response($response);

  $logger->debug(
    sub {
      return Dumper( [ response => $response ] );
    }
  );

  return $self->_decode_response( $response, $keep_root );
}

########################################################################
sub is_json_response {
########################################################################
  my ($rsp) = @_;

  return $FALSE
    if !$rsp->content;

lib/Amazon/S3.pm  view on Meta::CPAN

sub is_xml_response {
########################################################################
  my ($rsp) = @_;

  return $FALSE
    if !$rsp->content;

  return $TRUE
    if $rsp->content_type eq 'application/xml';

  return $TRUE
    if $rsp->content =~ /\A\s*<[?]xml/xsm;

  return $FALSE;
}

#
# This is the necessary to find the region for a specific bucket
# and set the signer object to use that region when signing requests
########################################################################
sub adjust_region {
########################################################################
  my ( $self, $bucket, $called_from_redirect ) = @_;

  my $url = sprintf 'https://%s.%s', $bucket, $self->host;

  my $request = HTTP::Request->new( GET => $url );

  $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
  return $FALSE
    if !is_xml_response($response);

  my $error_hash = $self->_xpc_of_content( $response->content );

  my ( $endpoint, $code, $region, $message )
    = @{$error_hash}{qw(Endpoint Code Region Message)};

  my $condition = eval {
    return 'PermanentRedirect'
      if $code eq 'PermanentRedirect' && $endpoint;

    return 'AuthorizationHeaderMalformed'
      if $code eq 'AuthorizationHeaderMalformed' && $region;

    return 'IllegalLocationConstraintException'
      if $code eq 'IllegalLocationConstraintException';

    return 'Other';
  };

  my %error_handlers = (
    PermanentRedirect => sub {
      # Don't recurse through multiple redirects
      return $FALSE
        if $called_from_redirect;

      # With a permanent redirect error, they are telling us the explicit
      # host to use.  The endpoint will be in the form of bucket.host
      my $host = $endpoint;

      # Remove the bucket name from the front of the host name
      # All the requests will need to be of the form https://host/bucket
      $host =~ s/\A$bucket[.]//xsm;
      $self->host($host);

      # We will need to call ourselves again in order to trigger the
      # AuthorizationHeaderMalformed error in order to get the region
      return $self->adjust_region( $bucket, $TRUE );
    },
    AuthorizationHeaderMalformed => sub {
      # Set the signer to use the correct reader evermore
      $self->{signer}->{endpoint} = $region;

      # Only change the host if we haven't been called as a redirect
      # where an exact host has been given
      if ( !$called_from_redirect ) {
        $self->host( sprintf 's3-%s-amazonaws.com', $region );
      }

      return $TRUE;
    },
    IllegalLocationConstraintException => sub {
      # This is hackish; but in this case the region name only appears in the message
      if ( $message =~ /The (\S+) location/xsm ) {
        my $new_region = $1;

        # Correct the region for the signer
        $self->{signer}->{endpoint} = $new_region;

        # Set the proper host for the region
        $self->host( sprintf 's3.%s.amazonaws.com', $new_region );

        return $TRUE;
      }
    },
    'Other' => sub {
      # Some other error
      $self->_remember_errors( $response->content, 1 );
      return $FALSE;
    },
  );

  return $error_handlers{$condition}->();
}

########################################################################
sub reset_errors {
########################################################################
  my ($self) = @_;

  $self->err(undef);
  $self->errstr(undef);
  $self->error(undef);

  return $self;
}

########################################################################
sub _do_http {
########################################################################
  my ( $self, $request, $filename ) = @_;

  # convenient time to reset any error conditions
  $self->reset_errors;

  my $response = $self->ua->request( $request, $filename );

  # For new buckets at non-standard locations, amazon will sometimes
  # respond with a temporary redirect.  In this case it is necessary
  # to try again with the new URL
  my $location = $response->header('Location');

  if ( $response->code =~ /\A3/xsm and defined $location ) {

    $self->get_logger->debug(
      sub {
        return { sprintf 'Redirecting to:  %s', $location };
      }
    );

    $request->uri($location);
    $response = $self->ua->request( $request, $filename );
  }

  $self->get_logger->debug( sub { return Dumper( [$response] ) } );

  $self->last_response($response);

lib/Amazon/S3.pm  view on Meta::CPAN


  my $bucketv2 = bless $bucket, 'Amazon::S3::BucketV2';

  return $bucketv2->DeletePublicAccessBlock;
}

1;

__END__

=pod

=encoding utf8

=head1 NAME

Amazon::S3 - A Perl client library for working with and managing
Amazon S3 buckets and objects.

=head1 SYNOPSIS

  use Amazon::S3;

  my $s3 = Amazon::S3->new(
    { credentials => $credentials,
      region      => 'us-east-1',
    }
  );

  my $bucket = $s3->bucket('example-bucket');

  $bucket->add_key(
    'testing.txt',
    'T',
    { content_type        => 'text/plain',
      'x-amz-meta-colour' => 'orange',
    }
  );

  my $response = $bucket->list
    or die $s3->err . ': ' . $s3->errstr;

  for my $key ( @{ $response->{keys} } ) {
    print $key->{key} . "\n";
  }

  my $object = $bucket->get_key('testing.txt')
    or die $s3->err . ': ' . $s3->errstr;

  print $object->{value};

=head1 DESCRIPTION

C<Amazon::S3> provides a Perl interface to Amazon Simple Storage
Service (S3).

The distribution separates account-level S3 operations from
bucket and object operations.

C<Amazon::S3> represents the S3 client and AWS account context. It
manages credentials, request signing, regions, service endpoints,
bucket creation and discovery, and account-level listing operations.

L<Amazon::S3::Bucket> represents an individual bucket. Object
operations such as uploads, downloads, deletes, ACLs, multipart
uploads, and bucket-scoped listing operations are provided primarily
through that class.

L<Amazon::S3::BucketV2> is a subclass of L<Amazon::S3::Bucket> that
provides a more general interface to S3 APIs. It accepts API
parameters, headers, URI parameters, and request payload structures
using a consistent calling convention.

C<Amazon::S3> originated as a fork of L<Net::Amazon::S3>, but the two
distributions have diverged substantially. Current versions should
not be considered interchangeable.

Version 2.1.0 adds modern S3 checksum support while preserving the
existing C<Amazon::S3> and L<Amazon::S3::Bucket> interfaces. Managed
uploads use CRC64NVME by default, and downloads can request and verify
checksum metadata returned by S3.

=head1 AUTHENTICATION AND CREDENTIALS

C<Amazon::S3> supports either explicit AWS access keys or a credentials
object.

Explicit credentials may be supplied to the constructor:

  my $s3 = Amazon::S3->new(
    { aws_access_key_id     => $aws_access_key_id,
      aws_secret_access_key => $aws_secret_access_key,
      token                 => $session_token,
    }
  );

The C<token> option is required only when temporary AWS credentials
include a session token.

For applications that obtain credentials dynamically, a credentials
object is preferred:

  my $s3 = Amazon::S3->new({ credentials => $credentials } );

The credentials object must provide:

  get_aws_access_key_id()
  get_aws_secret_access_key()
  get_token()

L<Amazon::Credentials> is one implementation of this interface.

Using a credentials object allows the credential provider to manage
credential discovery and refresh independently of C<Amazon::S3>.

C<Amazon::S3> uses Signature Version 4 for AWS API requests.

The signer normally uses the credentials associated with the
C<Amazon::S3> object. A signer may also be supplied to the constructor
using the C<signer> option.

lib/Amazon/S3.pm  view on Meta::CPAN

    etag              => $etag,
    size              => $size,
    storage_class     => $storage_class,
    owner_id          => $owner_id,
    owner_displayname => $owner_displayname,
  }

The C<etag> value is the ETag returned by S3. It must not be assumed
to be a checksum of the complete object.

C<list_object_versions()> is different: it returns the parsed
ListObjectVersions service response rather than this normalized
listing structure and does not automatically follow pagination.

See the corresponding entries under L</METHODS AND SUBROUTINES> for
the method contracts.

=head1 MULTIPART UPLOADS

Multipart upload operations are provided by L<Amazon::S3::Bucket>.

For normal application use,
C<Amazon::S3::Bucket::upload_multipart_object()> is the preferred
interface. It manages initiation, part uploads, completion, checksum
state, and optional abort-on-error behavior.

  my $parts = $bucket->upload_multipart_object(
    { key  => 'large-object.dat',
      data => $data,
    }
  );

The method can also consume data from a file handle or callback.

The lower-level multipart methods are available for applications that
need to control the multipart lifecycle themselves:

  initiate_multipart_upload()
  upload_part_of_multipart_upload()
  complete_multipart_upload()
  abort_multipart_upload()
  list_multipart_upload_parts()
  list_multipart_uploads()

These methods should generally be considered building blocks for
specialized workflows rather than the default multipart API.

See L<Amazon::S3::Bucket> for their complete method documentation.

=head1 DIRECTORY BUCKETS

C<Amazon::S3> provides limited support for Amazon S3 directory
buckets.

Directory buckets use the S3 Express One Zone storage class.

C<Amazon::S3> can currently create and list directory buckets.
Object access within directory buckets is not yet supported because
that requires creating an S3 Express session and using the resulting
temporary credentials when signing requests to the directory bucket's
Zonal endpoint.

A directory bucket can be created by supplying an availability zone
to C<add_bucket()>:

  my $bucket = $s3->add_bucket(
    { bucket            => $bucket_name,
      availability_zone => 'use1-az5',
    }
  );

Directory buckets owned by the account can be listed with
C<list_directory_buckets()>.

See
L<https://docs.aws.amazon.com/AmazonS3/latest/userguide/directory-buckets-overview.html>.

=head1 ERROR HANDLING

C<Amazon::S3> uses both return-value errors and exceptions.

For backward compatibility, many service operations return C<undef> or
a false value when an S3 request fails and record information about the
most recent error on the C<Amazon::S3> object.

The primary error accessors are:

 err()
 errstr()
 error()

C<err()> contains the S3 error code when one is available.

C<errstr()> contains the human-readable service error message.

C<error()> contains the parsed structured error response when the
service returned one.

Typical error handling using the historical interface therefore looks
like:

  my $response = $s3->buckets;

  if (!$response) {
    die $s3->err . ': ' . $s3->errstr;
  }

Applications that prefer request failures to throw exceptions can
enable C<raise_error> when constructing the client:

  my $s3 = Amazon::S3->new(
    credentials => $credentials,
    raise_error => 1,
  );

With C<raise_error> enabled, S3 request failures that would normally
return a failure value instead throw an exception. The error state is
still recorded in C<err()>, C<errstr()>, and C<error()> before the
exception is raised.

When available, the exception includes the HTTP status together with
the S3 error code and message.

Some request, protocol, multipart, checksum verification, and
validation failures always throw exceptions because the operation
cannot safely continue.

The most recent HTTP request and response can be inspected using
C<last_request()> and C<last_response()>.

These accessors are especially useful when diagnosing signing,
endpoint, header, or protocol problems.

C<raise_error> defaults to false to preserve the historical
C<Amazon::S3> interface. New applications may prefer to enable it when
they want request failures to be impossible to overlook.

=head1 METHODS AND SUBROUTINES

This section documents methods provided directly by C<Amazon::S3>.

Methods implemented by L<Amazon::S3::Bucket> or
L<Amazon::S3::BucketV2> are documented by those classes and are not
duplicated here.

Unless otherwise noted, a service operation returns C<undef> when an
error occurs and records error information on the C<Amazon::S3>
object. Some request, protocol, and validation failures throw an
exception instead.

See L</ERROR HANDLING>.

=head2 CONSTRUCTOR

=head3 new

  my $s3 = Amazon::S3->new(%options);

  my $s3 = Amazon::S3->new(\%options);

Creates and returns a new C<Amazon::S3> client object.

The constructor accepts either a list of key/value pairs or a hash
reference.

At least one of the following credential configurations is required:

=over 4

=item *

A C<credentials> object that provides C<get_aws_access_key_id()>,
C<get_aws_secret_access_key()>, and C<get_token()>.

=item *

Both C<aws_access_key_id> and C<aws_secret_access_key>.

=back

The following options are supported:

=over 4

=item aws_access_key_id

AWS access key ID.

This option is required when a C<credentials> object is not supplied.

When explicit credentials are supplied, C<Amazon::S3> stores them
internally for use when signing requests. Applications should avoid

lib/Amazon/S3.pm  view on Meta::CPAN

=item buffer_size

Default buffer size, in bytes, used by operations that stream object
data.

The default is 4096.

=item cache_signer

When true, retain and reuse the Signature Version 4 signer.

When false, construct a signer when one is needed.

The default is false.

See L</AUTHENTICATION AND CREDENTIALS>.

=item checksum_algorithm

Checksum algorithm used when C<Amazon::S3> supplies a checksum with an
upload.

The default is C<crc64nvme>.

Recognized S3 checksum algorithm names are validated by the
constructor. Local checksum implementations provided by this release
are described in L</CHECKSUMS>.

=item credentials

Credentials provider object.

The object must provide:

  get_aws_access_key_id()
  get_aws_secret_access_key()
  get_token()

L<Amazon::Credentials> is one implementation of this interface.

See L</AUTHENTICATION AND CREDENTIALS>.

=item debug

Compatibility option that sets the default logger level to C<debug>.

Applications should normally use C<level> instead.

This option affects the internally created logger only.

=item dns_bucket_names

Controls whether virtual-hosted-style bucket names are used when
possible.

The default is true.

A bucket name that cannot be used as a DNS subdomain is placed in the
request path instead.

=item endpoint_url

Optional explicit S3 service endpoint.

When C<endpoint_url> is supplied, C<Amazon::S3> uses that endpoint as
specified and does not rewrite the host when the configured region
changes.

The C<region> setting still controls the AWS signing region.

This is useful for S3-compatible services, local test environments, and
other cases where the caller must select the service endpoint explicitly.

For example:

  my $s3 = Amazon::S3->new(
    { endpoint_url => 'http://localhost:4566',
      region       => 'us-east-1',
      ...
    }
  );

When C<endpoint_url> is not supplied, C<Amazon::S3> may derive the
standard AWS S3 endpoint from the configured region.

C<endpoint_url> and C<host> may not both be supplied.

=item host

S3 service endpoint.

The default is C<s3.amazonaws.com>.

When C<region()> is set and the host is a standard Amazon S3 endpoint,
C<Amazon::S3> adjusts the host for the configured region.

This option can also be used with S3-compatible and local testing
services.

=item level

Logging level used when C<Amazon::S3> creates its default logger.

The default is C<error>.

See L</LOGGING AND DEBUGGING>.

=item logger

Logger object.

If omitted, C<Amazon::S3::Logger> is used.

A caller-supplied logger is expected to provide the logging methods
used by C<Amazon::S3>.

See L</LOGGING AND DEBUGGING>.

=item raise_error

When true, S3 request failures that would normally be reported through
the return value and the C<err()>, C<errstr()>, and C<error()> accessors
instead throw an exception.

The exception includes the HTTP status and, when available, the S3
error code and message.

The default is false for backward compatibility.

See L</ERROR HANDLING>.

=item region

AWS region used for account-level requests and as the default region
for newly constructed bucket objects.

The default is C<us-east-1>.

=item retry

When true, use retry-aware HTTP handling.

Retries use exponential delays of 1, 2, 4, 8, 16, and 32 seconds.

The default is false.

=item secure

When true, use HTTPS when communicating with the service.

The default is true.

=item signer

lib/Amazon/S3.pm  view on Meta::CPAN


See L</CHECKSUMS>.

=head3 checksum_types

  my $checksum_types = $s3->checksum_types;

Returns the checksum implementations initialized for this client.

The value is a hash reference keyed by algorithm name.

This accessor is intended for introspection. The internal checksum
implementation entries are not a public plugin interface in this
release.

See L</CHECKSUMS>.

=head3 credentials

  my $credentials = $s3->credentials;

  $s3->credentials($credentials);

Gets or sets the credentials provider object.

See L</AUTHENTICATION AND CREDENTIALS>.

=head3 dns_bucket_names

  my $enabled = $s3->dns_bucket_names;

  $s3->dns_bucket_names($boolean);

Gets or sets whether virtual-hosted-style bucket addressing is used
when possible.

The constructor default is true.

=head3 err

Returns the most recent S3 error code or short error identifier.

See L</ERROR HANDLING>.

=head3 error

Returns the most recent parsed structured error response.

See L</ERROR HANDLING>.

=head3 errstr

Returns the most recent human-readable error message.

See L</ERROR HANDLING>.

=head3 host

  my $host = $s3->host;

  $s3->host($endpoint);

Gets or sets the configured S3 endpoint.

The constructor default is C<s3.amazonaws.com>.

See L</S3-COMPATIBLE SERVICES>.

=head3 last_request

Returns the most recent L<HTTP::Request> generated by C<Amazon::S3>.

See L</ERROR HANDLING>.

=head3 last_response

Returns the most recent L<HTTP::Response> received by C<Amazon::S3>.

See L</ERROR HANDLING>.

=head3 logger

  my $logger = $s3->logger;

  $s3->logger($logger);

Gets or sets the logger used by C<Amazon::S3>.

See L</LOGGING AND DEBUGGING>.

=head3 retry

  my $retry = $s3->retry;

  $s3->retry($boolean);

Gets or sets whether retry-aware HTTP handling is enabled.

The constructor default is false.

=head3 secure

  my $secure = $s3->secure;

  $s3->secure($boolean);

Gets or sets whether HTTPS is used.

The constructor default is true.

=head3 timeout

  my $timeout = $s3->timeout;

  $s3->timeout($seconds);

Gets or sets the HTTP request timeout in seconds.

The constructor default is 30.

=head3 verify_checksums

  my $verify_checksums = $s3->verify_checksums;

lib/Amazon/S3.pm  view on Meta::CPAN


The constructor default is true.

See L</CHECKSUMS>.

=head2 AUTHENTICATION AND CONFIGURATION METHODS

=head3 get_credentials

  my ( $access_key_id, $secret_access_key, $token )
    = $s3->get_credentials;

Returns the credentials used by the client.

When a C<credentials> provider is configured, this method obtains the
three values from that provider.

Otherwise it returns the credentials stored by the C<Amazon::S3>
object.

The return values, in order, are:

=over 4

=item 1.

AWS access key ID.

=item 2.

AWS secret access key.

=item 3.

Session token, or C<undef> when no token is configured.

=back

See L</AUTHENTICATION AND CREDENTIALS>.

=head3 get_default_region

  my $region = $s3->get_default_region;

Attempts to determine the default AWS region.

The method checks, in order:

=over 4

=item 1.

C<AWS_REGION>.

=item 2.

C<AWS_DEFAULT_REGION>.

=item 3.

The EC2 instance metadata availability-zone endpoint.

=back

When an availability zone is obtained from instance metadata, the
zone suffix is removed to derive the region.

If no region can be determined, C<us-east-1> is returned.

=head3 get_logger

  my $logger = $s3->get_logger;

Returns the logger associated with the client.

If no logger was supplied to C<new()>, this is the
L<Amazon::S3::Logger> instance created by the constructor.

This method is provided for compatibility with logger interfaces that
expect C<get_logger()>.

See L</LOGGING AND DEBUGGING>.

=head3 level

  my $level = $s3->level;

  $s3->level('debug');

Gets or sets the logging level.

When a level is supplied, both the stored logging level and the
associated logger level are updated.

When called without an argument, returns the current logger level.

The constructor default is C<error>.

See L</LOGGING AND DEBUGGING>.

=head3 region

  my $region = $s3->region;

  $s3->region('us-west-2');

Gets or sets the region used by the client.

The region is used for account-level requests and as the default
region assigned to bucket objects when no bucket-specific region is
supplied.

When the configured host uses the standard C<s3.amazonaws.com> form,
setting the region also adjusts the host to the regional Amazon S3
endpoint.

The constructor default is C<us-east-1>.

=head3 signer

  my $signer = $s3->signer;

Returns the Signature Version 4 signer used for requests.

If a signer was supplied to the constructor, that signer is returned.

Otherwise a signer is constructed from the current credentials,
region, and session token.

When C<cache_signer> is true, a generated signer is retained and
reused. When it is false, a signer can be generated as needed.

This method does not accept a signer argument. Supply a custom signer
using the C<signer> constructor option.

See L</AUTHENTICATION AND CREDENTIALS>.

=head2 BUCKET MANAGEMENT

=head3 add_bucket

  my $bucket = $s3->add_bucket(\%configuration);

Creates a bucket.

The argument is a hash reference containing the bucket configuration.

=over 4

=item bucket

Required. Bucket name.

=item acl_short

Optional canned ACL.

Optional canned ACL applied when creating the bucket.

See L</WORKING WITH BUCKETS AND OBJECTS>.

=item location_constraint

Compatibility name for the region in which the bucket should be
created.

When both C<location_constraint> and C<region> are supplied,
C<location_constraint> takes precedence.

=item region

Region in which the bucket should be created.

If neither C<region> nor C<location_constraint> is supplied, the
client region is used.

lib/Amazon/S3.pm  view on Meta::CPAN

bucket policies to buckets whose public access block settings prohibit
them.

=head3 empty_bucket

  my $count = $s3->empty_bucket($bucket_name);

  my $count = $s3->empty_bucket($bucket_name, $headers);

Deletes all object versions currently listed in the specified bucket.

Returns the number of object versions and delete markers removed. For
an unversioned bucket this is equivalent to the number of objects
deleted.

Objects are listed and deleted in batches until the bucket contains no
remaining objects. The optional C<$headers> hash reference is passed to
the listing requests.

A return value of C<0> means that the operation succeeded but the
bucket contained no objects. The return value is therefore a count and
should not be used as a boolean indication of success or failure.

This method always throws an exception if an error occurs while listing
or deleting objects, regardless of the C<raise_error> setting. If some
objects were successfully deleted before the failure occurred, the
exception includes the number of objects deleted before the error.

B<WARNING: This method permanently deletes all objects returned by the
bucket listing. Use with caution.>

=head3 get_bucket_location

  my $region = $s3->get_bucket_location($bucket_name);

  my $region = $s3->get_bucket_location($bucket);

Returns the region containing a bucket.

The argument may be a bucket name or an L<Amazon::S3::Bucket> object.

For a bucket name, a temporary L<Amazon::S3::Bucket> object is
constructed and its C<get_location_constraint()> method is called.

Amazon S3 represents C<us-east-1> with a null location constraint.
When the bucket location call returns no region,
C<get_bucket_location()> returns C<us-east-1>.

=head3 list_directory_buckets

  my $response = $s3->list_directory_buckets;

  my $response = $s3->list_directory_buckets(
    { uri_params => \%params,
    }
  );

Lists directory buckets owned by the account.

The optional C<uri_params> hash reference is passed as URI parameters
to the S3 Express control endpoint.

The method temporarily switches the client to the S3 Express control
endpoint for the request and restores the previous express-mode state
afterward.

On success, returns the parsed S3 response.

On failure, returns C<undef> and records error information on the
client.

See L</DIRECTORY BUCKETS>.

=head2 OBJECT LISTING AND VERSIONING

=head3 list_bucket

  my $response = $s3->list_bucket(\%parameters);

Lists objects using the original S3 ListObjects API.

The argument is a hash reference. C<bucket> is required. Other defined
entries are sent as ListObjects query parameters.

Common parameters are:

=over 4

=item bucket

Required. Bucket name.

=item delimiter

Optional delimiter used to group matching keys into common prefixes.

=item headers

Optional hash reference containing additional request headers.

=item marker

Optional key after which listing should resume.

=item max-keys

Optional maximum number of results returned by S3.

=item prefix

Optional prefix used to restrict returned keys.

=back

On success, returns the normalized listing structure described in
L</LISTING OBJECTS>.

On failure, returns C<undef> and records error information on the
client.

See L</LISTING OBJECTS>.

=head3 list_bucket_all

lib/Amazon/S3.pm  view on Meta::CPAN


=head2 ADVANCED AND COMPATIBILITY METHODS

=head3 turn_off_special_retry

  $s3->turn_off_special_retry;

Removes the additional HTTP 400 retry condition installed by
C<turn_on_special_retry()>.

When retry handling is disabled, this method has no effect.

This method exists primarily for internal and compatibility use.

=head3 turn_on_special_retry

  $s3->turn_on_special_retry;

When retry handling is enabled, adds HTTP 400 to the conditions
handled by the retry-aware user agent.

This behavior exists because some S3 request timeouts have historically
been returned as HTTP 400 responses.

The constructor calls this method automatically.

When retry handling is disabled, this method has no effect.

This method exists primarily for internal and compatibility use.

=head1 LOGGING AND DEBUGGING

Logging is controlled by the configured logger and logging level.

When no logger is supplied, C<Amazon::S3::Logger> is used.

Valid levels include:

  fatal
  error
  warn
  info
  debug
  trace

The default level is C<error>.

At C<debug> level, C<Amazon::S3> records higher-level request and
configuration information.

At C<trace> level, HTTP request and response information may also be
logged.

Applications should review trace output before retaining or sharing
it. Request and response data may contain sensitive application
information even when authentication values are sanitized.

=head1 S3-COMPATIBLE SERVICES

C<Amazon::S3> can be used with S3-compatible services and local S3
implementations by configuring the service endpoint and related
connection options.

The C<host>, C<secure>, and C<dns_bucket_names> settings are commonly
relevant when using a non-AWS endpoint.

S3-compatible implementations may differ from AWS in supported APIs,
request validation, checksum behavior, or edge cases.

The integration tests used during development include LocalStack, but
applications targeting another S3-compatible implementation should
test against that implementation directly.

=head1 COMPARISON TO OTHER PERL S3 MODULES

Perl applications have several choices for accessing Amazon S3,
including L<Net::Amazon::S3>, L<Paws::S3>, L<Amazon::S3::Lite>, and
L<Amazon::API::S3>. Each takes a different approach.

C<Amazon::S3> provides a dedicated S3 interface with a long-established
API. The distribution combines the account-level C<Amazon::S3>
interface with L<Amazon::S3::Bucket> for common object workflows and
L<Amazon::S3::BucketV2> for broader low-level API access.

C<Net::Amazon::S3> is the project from which C<Amazon::S3> originally
forked. The distributions have since diverged and should not be
considered drop-in replacements for one another.

C<Paws::S3> is part of the larger L<Paws> AWS SDK for Perl and follows
AWS service APIs through its generated service model.

L<Amazon::S3::Lite> is a smaller client intended for applications
where dependency size and startup cost are important.

L<Amazon::API::S3> is generated from the AWS Botocore service model
and is intended to closely reflect the current low-level S3 API.

The appropriate client depends primarily on the interface and level of
abstraction required by the application.

=head1 COMPATIBILITY AND LIMITATIONS

=head2 Minimum Perl Version

C<Amazon::S3> declares Perl 5.10 as its minimum supported Perl
version.

Dependencies may impose additional constraints on older Perl
installations.

Applications using an older Perl should run the complete distribution
test suite after installation.

=head2 Signature Version 4

AWS API requests are signed using Signature Version 4.

Signature Version 2 is not supported.

Because Signature Version 4 includes the AWS region in the signature,
bucket operations must use the region containing the bucket.

A bucket region can be supplied explicitly or determined using bucket
region verification.

=head2 Directory Buckets

Directory bucket support is currently limited to account-level create
and list operations.

See L</DIRECTORY BUCKETS>.

=head1 TESTING

The distribution includes unit tests and integration tests that
exercise behavior requiring an S3 endpoint.

Run the normal distribution test suite with:

  make test

Integration testing during development includes LocalStack.

See F<README-TESTING.md> in the distribution root for test
environment setup, integration-test requirements, and additional
testing instructions.

=head1 SUPPORT

Bug reports and feature requests should be submitted through the
project issue tracker.

When reporting a problem, include the C<Amazon::S3> version, Perl
version, operating system, and enough information to reproduce the
behavior.

For request or protocol problems, debug or trace logging may also be
useful. Review logs before sharing them to ensure that they do not
contain credentials, authorization information, or sensitive object
data.

=head1 REPOSITORY

The source repository, issue tracker, and development history are
available at:

L<https://github.com/rlauer6/Amazon-S3>

=head1 AUTHOR

Original author: Timothy Appnel <tima@cpan.org>

Current maintainer: Rob Lauer <bigfoot@cpan.org>

=head1 SEE ALSO

L<Amazon::S3::Bucket>

L<Amazon::S3::BucketV2>

L<Amazon::S3::Constants>

L<Amazon::S3::Logger>

L<Amazon::Credentials>

L<Net::Amazon::S3>

L<Amazon S3 API Reference|https://docs.aws.amazon.com/AmazonS3/latest/API/Welcome.html>

L<Amazon S3 bucket naming rules|https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucketnamingrules.html>

L<Amazon S3 bucket restrictions and limitations|https://docs.aws.amazon.com/AmazonS3/latest/userguide/BucketRestrictions.html>

L<AWS Signature Version 4|https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html>



( run in 1.967 second using v1.01-cache-2.11-cpan-1bcd28dbaf1 )