credentials results from the CPAN

credentials

Amazon-S3

view release on metacpan or search on metacpan

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.2'; ## 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;

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

########################################################################
  my ( $self, $conf ) = @_;

  my $bucket = delete $conf->{bucket};

  die 'no bucket'
    if !$bucket;

  my $headers = delete $conf->{headers};

  croak 'must specify bucket'
    if !$bucket;

  $conf ||= {};

  my ( $marker, $next_marker, $query_next )
    = @{ $LIST_OBJECT_MARKERS{'3'} };

  if ( $conf->{'key-marker'} ) {
    $conf->{$query_next} = delete $conf->{'key-marker'};
  }

  if ( %{$conf} ) {

    # remove undefined elements
    foreach ( keys %{$conf} ) {
      next if defined $conf->{$_};

      delete $conf->{$_};
    }
  }

  my $path = create_api_uri( path => "$bucket/", api => 'versions', %{$conf} );

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

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

  $self->get_logger->debug(
    sub {
      return Dumper(
        [ marker      => $marker,
          next_marker => $next_marker,
          response    => $r,
        ],
      );
    },
  );

  return $r;
}

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

  my $aws_access_key_id;
  my $aws_secret_access_key;
  my $token;

  if ( $self->credentials ) {
    $aws_access_key_id     = $self->credentials->get_aws_access_key_id;
    $aws_secret_access_key = $self->credentials->get_aws_secret_access_key;
    $token                 = $self->credentials->get_token;
  }
  else {
    $aws_access_key_id     = $self->aws_access_key_id;
    $aws_secret_access_key = $self->aws_secret_access_key;
    $token                 = $self->token;
  }

  return ( $aws_access_key_id, $aws_secret_access_key, $token );
}

# Log::Log4perl compatibility routines
########################################################################
sub get_logger {
########################################################################
  my ($self) = @_;

  return $self->logger;
}

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

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

    $self->get_logger->level( uc $args[0] );
  }

  return $self->get_logger->level;
}

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

  return $self->_signer
    if $self->_signer;

  my $creds   = $self->credentials ? $self->credentials : $self;
  my $express = $self->express;

  my $signer = Amazon::S3::Signature::V4->new(
    { access_key_id  => $creds->get_aws_access_key_id,
      secret         => $creds->get_aws_secret_access_key,
      region         => $self->region || $self->get_default_region,
      service        => $express ? 's3express' : 's3',
      security_token => $creds->get_token,
    },
  );

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

  return $signer;
}

########################################################################
sub _validate_acl_short {
########################################################################
  my ( $self, $policy_name ) = @_;

  croak sprintf '%s is not a supported canned access policy', $policy_name
    if none { $policy_name eq $_ } qw(private public-read public-read-write authenticated-read);

  return;
}

########################################################################
# Determine if a bucket can used as subdomain for the host
# Specifying the bucket in the URL path is being deprecated
# So, if the bucket name is suitable, we need to use it
# as a subdomain in the host name instead.
#
# Currently buckets with periods in their names cannot be handled in
# that manner due to SSL certificate issues, they will have to remain
# in the url path instead.
#
########################################################################
sub is_domain_bucket { goto &_can_bucket_be_subdomain; }
########################################################################

########################################################################
sub _can_bucket_be_subdomain {
########################################################################
  my ($bucketname) = @_;

  return $FALSE
    if length $bucketname > $MAX_BUCKET_NAME_LENGTH - 1;

  return $FALSE
    if length $bucketname < $MIN_BUCKET_NAME_LENGTH;

  return $FALSE
    if $bucketname !~ m{\A[[:lower:]][[:lower:]\d-]*\z}xsm;

  return $FALSE
    if $bucketname !~ m{[[:lower:]\d]\z}xsm;

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

########################################################################
  my ( $self, $response, $force_raise ) = @_;

  my $remembered = eval { return $self->_remember_errors( $response->content, $TRUE ); };

  if ( !$remembered ) {
    $self->err('network_error');
    $self->errstr( $response->status_line );
  }

  if ( $self->raise_error || $force_raise ) {
    croak sprintf '%s - %s: %s', $response->status_line, $self->err, $self->errstr;
  }

  return $TRUE;
}
# returns 1 if errors were found
########################################################################
sub _remember_errors {
########################################################################
  my ( $self, $src, $keep_root ) = @_;

  return
    if !$src;

  if ( !ref $src && $src !~ /^[[:space:]]*</xsm ) {
    ( my $code = $src ) =~ s/^[[:space:]]*[(]([\d]*)[)].*$/$1/xsm;

    $self->err($code);
    $self->errstr($src);

    return $TRUE;
  }

  my $r = ref $src ? $src : $self->_xpc_of_content( $src, $keep_root );

  $self->error($r);

  # apparently buckets() does not keep_root
  if ( $r->{Error} ) {
    $r = $r->{Error};
  }

  my ( $code, $message ) = @{$r}{qw(Code Message)};

  return $FALSE
    if !$code;

  $self->err($code);
  $self->errstr($message);

  return $TRUE;
}

# Deprecated - this adds a header for the old V2 auth signatures
########################################################################
sub _add_auth_header { ## no critic (ProhibitUnusedPrivateSubroutines)
########################################################################
  my ( $self, $headers, $method, $path ) = @_;

  my ( $aws_access_key_id, $aws_secret_access_key, $token ) = $self->get_credentials;

  if ( not $headers->header('Date') ) {
    $headers->header( Date => time2str(time) );
  }

  if ($token) {
    $headers->header( $AMAZON_HEADER_PREFIX . 'security-token' => $token );
  }

  my $canonical_string = $self->_canonical_string( $method, $path, $headers );

  $self->get_logger->trace(
    sub {
      return Dumper(
        [ headers          => $headers,
          canonincal_sring => $canonical_string,
        ]
      );
    }
  );

  my $encoded_canonical = $self->_encode( $aws_secret_access_key, $canonical_string );

  $headers->header(
    Authorization => sprintf 'AWS %s:%s',
    $aws_access_key_id, $encoded_canonical
  );

  return;
}

# generates an HTTP::Headers objects given one hash that represents http
# headers to set and another hash that represents an object's metadata.
########################################################################
sub _merge_meta {
########################################################################
  my ( $self, $headers, $metadata ) = @_;

  $headers  //= {};
  $metadata //= {};

  my $http_header = HTTP::Headers->new;

  foreach my $p ( pairs %{$headers} ) {
    my ( $k, $v ) = @{$p};
    $http_header->header( $k => $v );
  }

  foreach my $p ( pairs %{$metadata} ) {
    my ( $k, $v ) = @{$p};
    $http_header->header( "$METADATA_PREFIX$k" => $v );
  }

  return $http_header;
}

# generate a canonical string for the given parameters.  expires is optional and is
# only used by query string authentication.
########################################################################
sub _canonical_string {

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

  $hmac->add($str);

  my $b64 = encode_base64( $hmac->digest, $EMPTY );

  return $urlencode ? urlencode($b64) : return $b64;
}

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

  my $parameters = get_parameters(@args);

  my ( $bucketname, $region, $verify_region )
    = @{$parameters}{qw(bucket region verify_region)};

  # only set to default region if a region wasn't passed or region
  # verification not requested
  if ( !$region && !$verify_region ) {
    $region = $self->region;
  }

  return Amazon::S3::BucketV2->new(
    { bucket        => $bucketname,
      account       => $self,
      region        => $region,
      verify_region => $verify_region,
    },
  );
}

########################################################################
sub delete_public_access_block {
########################################################################
  my ( $self, $bucket ) = @_;

  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.

By default, signers are not cached. Setting C<cache_signer> to true
causes C<Amazon::S3> to retain and reuse the signer object.

Applications should avoid dumping C<Amazon::S3>, credential, or signer
objects to logs. These objects participate in request authentication
and may contain or provide access to sensitive authentication
material.

=head1 CHECKSUMS

Version 2.1.0 adds checksum generation for uploads and checksum
verification for downloads.

The default upload checksum algorithm is C<crc64nvme>.

C<Amazon::S3> provides local implementations for:

  crc64nvme
  crc32
  crc32c
  md5
  sha1
  sha256
  sha512

Amazon S3 also defines XXHash checksum algorithms. They are recognized
by C<Amazon::S3> but are not implemented locally in this release.

=head2 Uploads

When an upload is performed through L<Amazon::S3::Bucket>,
C<Amazon::S3> calculates the configured checksum when that operation
supports checksum submission.

The checksum algorithm is selected using C<checksum_algorithm>. The
default is C<crc64nvme>.

Managed multipart uploads performed by
C<Amazon::S3::Bucket::upload_multipart_object()> also use the
configured checksum algorithm.

Low-level multipart methods do not implicitly enable an additional
checksum algorithm. Applications that directly manage the multipart
workflow are responsible for selecting and carrying the checksum
algorithm through that workflow.

=head2 Downloads

Checksum verification is enabled by default.

When C<verify_checksums> is true, object downloads request checksum
metadata from S3. C<Amazon::S3> verifies supported C<FULL_OBJECT>
checksums returned by the service.

Verification is opportunistic. If S3 does not return a checksum, or
returns a checksum for an algorithm that C<Amazon::S3> cannot
calculate locally, the object can still be downloaded.

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

    last_modified     => $last_modified,
    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
dumping the client object to logs.

See L</AUTHENTICATION AND CREDENTIALS>.

=item aws_secret_access_key

AWS secret access key.

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

See L</AUTHENTICATION AND CREDENTIALS>.

=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

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

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

Optional Signature Version 4 signer object.

When supplied, this signer is used instead of constructing one from
the configured credentials.

See L</AUTHENTICATION AND CREDENTIALS>.

=item timeout

HTTP request timeout in seconds.

The default is 30.

=item token

Optional AWS session token used with temporary credentials.

=item verify_checksums

Controls checksum verification when downloading objects.

The default is true.

See L</CHECKSUMS>.

=back

If neither a credentials provider nor both explicit access key values
are supplied, the constructor throws an exception.

An invalid C<checksum_algorithm> also causes the constructor to throw
an exception.

On success, returns the new C<Amazon::S3> object.

=head2 ACCESSORS

=head3 buffer_size

  my $buffer_size = $s3->buffer_size;

  $s3->buffer_size($bytes);

Gets or sets the default streaming buffer size in bytes.

The constructor default is 4096.

=head3 cache_signer

  my $cache_signer = $s3->cache_signer;

  $s3->cache_signer($boolean);

Gets or sets whether a generated request signer is retained for reuse.

The constructor default is false.

See L</AUTHENTICATION AND CREDENTIALS>.

=head3 checksum_algorithm

  my $algorithm = $s3->checksum_algorithm;

  $s3->checksum_algorithm('sha256');

Gets or sets the checksum algorithm selected for uploads.

The constructor default is C<crc64nvme>.

The constructor validates the initial value. Callers that change this
accessor after construction are responsible for supplying an
algorithm supported by the operation being performed.

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;

  $s3->verify_checksums($boolean);

Gets or sets whether supported checksums returned for downloaded
objects are verified.

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.

For C<us-east-1>, no location constraint is sent.

=item headers

Optional hash reference containing additional request headers.

=item availability_zone

When supplied, create an S3 directory bucket in the specified
availability zone.

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

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>

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

L<LocalStack|https://localstack.io>

=head1 LICENCE

This library is free software; you may redistribute it and/or modify
it under the same terms as Perl itself.

Portions of this distribution contain code modified from Amazon. That
code is made available under the following notice:

  #  This software code is made available "AS IS" without warranties of any
  #  kind.  You may copy, display, modify and redistribute the software
  #  code either by itself or as incorporated into your code; provided that
  #  you do not remove any proprietary notices.  Your use of this software
  #  code is at your own risk and you waive any claim against Amazon
  #  Digital Services, Inc. or its affiliates with respect to your use of
  #  this software code. (c) 2006 Amazon Digital Services, Inc. or its
  #  affiliates.

=cut

( run in 0.871 second using v1.01-cache-2.11-cpan-3f962061493 )