NAME

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

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};

DESCRIPTION

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

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

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.

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.

Amazon::S3::BucketV2 is a subclass of 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.

Amazon::S3 originated as a fork of 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 Amazon::S3 and Amazon::S3::Bucket interfaces. Managed uploads use CRC64NVME by default, and downloads can request and verify checksum metadata returned by S3.

AUTHENTICATION AND CREDENTIALS

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 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()

Amazon::Credentials is one implementation of this interface.

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

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

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

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

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

CHECKSUMS

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

The default upload checksum algorithm is crc64nvme.

Amazon::S3 provides local implementations for:

crc64nvme
crc32
crc32c
md5
sha1
sha256
sha512

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

Uploads

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

The checksum algorithm is selected using checksum_algorithm. The default is crc64nvme.

Managed multipart uploads performed by 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.

Downloads

Checksum verification is enabled by default.

When verify_checksums is true, object downloads request checksum metadata from S3. Amazon::S3 verifies supported 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 Amazon::S3 cannot calculate locally, the object can still be downloaded.

COMPOSITE checksums are not independently verified.

Partial and ranged downloads are not checksum verified because the checksum returned for an object describes the complete object rather than the requested byte range.

The verify_checksums setting controls download verification only. It does not disable checksum generation for uploads.

WORKING WITH BUCKETS AND OBJECTS

Amazon::S3 creates bucket objects that provide the object-oriented interface used for most S3 operations.

Creating and Representing Buckets

add_bucket() creates a bucket in S3.

bucket() and bucketv2() do not create a bucket. They construct client-side objects representing a bucket.

A bucket region can be supplied explicitly when constructing a bucket object. Region verification can also be requested when the bucket region is not already known; doing so requires an additional service request.

Amazon S3 applies public-access-block settings to new buckets by default. Applications that intentionally create public buckets or apply public ACLs must ensure that the account and bucket public access settings permit the requested policy.

Directory buckets have additional creation requirements. See "DIRECTORY BUCKETS".

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

Calling bucket() does not create the bucket and does not verify that it exists. It constructs an Amazon::S3::Bucket object associated with the Amazon::S3 client.

A bucket can be assigned a region explicitly:

my $bucket = $s3->bucket(
  { bucket => 'example-bucket',
    region => 'us-west-2',
  }
);

The bucket interface provides operations including:

add_key()
add_key_filename()
copy_object()
delete_key()
delete_keys()
get_acl()
get_key()
get_key_filename()
head_key()
set_acl()

See Amazon::S3::Bucket for the method reference for bucket and object operations.

LISTING OBJECTS

The distribution provides both the original S3 ListObjects API and ListObjectsV2.

At the Amazon::S3 level these are exposed as:

list_bucket()
list_bucket_v2()

The corresponding convenience methods:

list_bucket_all()
list_bucket_all_v2()

follow pagination automatically and return the combined result.

Amazon::S3::Bucket provides bucket-oriented wrappers for these operations.

Choosing a Listing API

ListObjectsV2 is generally preferred for new code.

list_bucket() uses the original marker-based pagination model.

list_bucket_v2() uses the continuation-token model introduced by ListObjectsV2 and also supports start-after.

Applications that need control over individual result pages should use list_bucket() or list_bucket_v2() directly.

Applications that simply need all matching objects can use the corresponding _all method.

Prefixes and Delimiters

S3 keys are not filesystem paths. However, prefix and delimiter can be used to present a hierarchy-like view of keys.

For example, given these keys:

bar/baz
bar/buz
bar/buz/biz
bar/buz/zip

a request using:

prefix    => 'bar/'
delimiter => '/'

returns the keys at that level and rolls deeper keys into a common prefix.

A typical request is:

my $response = $s3->list_bucket_v2(
  { bucket    => 'example-bucket',
    prefix    => 'bar/',
    delimiter => '/',
  }
);

The rolled-up prefixes are returned in common_prefixes.

Pagination

list_bucket() resumes a truncated listing using marker.

When a delimiter is used, the normalized response can contain next_marker. Without a delimiter, the last returned key can be used as the marker for the next request.

list_bucket_v2() resumes a truncated listing using the continuation token returned by S3. In the normalized Amazon::S3 result, next_marker contains NextContinuationToken.

For example:

my $response = $s3->list_bucket_v2(
  { bucket => 'example-bucket',
  }
);

while ( $response->{is_truncated} ) {
  $response = $s3->list_bucket_v2(
    { bucket               => 'example-bucket',
      'continuation-token' => $response->{next_marker},
    }
  );
}

When application code does not need to process individual pages, list_bucket_all() and list_bucket_all_v2() perform this work automatically.

Listing Results

list_bucket() and list_bucket_v2() normalize their results into the same general structure:

{
  bucket          => $bucket_name,
  prefix          => $prefix,
  marker          => $marker,
  next_marker     => $next_marker,
  max_keys        => $max_keys,
  is_truncated    => $boolean,
  keys            => \@keys,
  common_prefixes => \@prefixes,
}

common_prefixes is present when the request uses a delimiter and S3 returns rolled-up prefixes.

Each element of keys is a hash reference containing object metadata:

{
  key               => $key,
  last_modified     => $last_modified,
  etag              => $etag,
  size              => $size,
  storage_class     => $storage_class,
  owner_id          => $owner_id,
  owner_displayname => $owner_displayname,
}

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

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 "METHODS AND SUBROUTINES" for the method contracts.

MULTIPART UPLOADS

Multipart upload operations are provided by Amazon::S3::Bucket.

For normal application use, 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 Amazon::S3::Bucket for their complete method documentation.

DIRECTORY BUCKETS

Amazon::S3 provides limited support for Amazon S3 directory buckets.

Directory buckets use the S3 Express One Zone storage class.

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 add_bucket():

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

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

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

ERROR HANDLING

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

Many service operations return undef when the request fails and record information about the most recent error on the Amazon::S3 object.

The primary error accessors are:

err()
errstr()
error()

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

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

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

Typical error handling therefore looks like:

my $response = $s3->buckets;

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

Some request, protocol, multipart, and checksum verification failures throw exceptions instead. When an S3 service error is available, exceptions include the HTTP status and the service error code and message.

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

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

Applications should not assume that all failures use the same mechanism. Callers should check documented return values and use exception handling where an operation can throw.

METHODS AND SUBROUTINES

This section documents methods provided directly by Amazon::S3.

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

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

See "ERROR HANDLING".

CONSTRUCTOR

new

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

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

Creates and returns a new 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:

The following options are supported:

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

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

On success, returns the new Amazon::S3 object.

ACCESSORS

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.

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 "AUTHENTICATION AND CREDENTIALS".

checksum_algorithm

my $algorithm = $s3->checksum_algorithm;

$s3->checksum_algorithm('sha256');

Gets or sets the checksum algorithm selected for uploads.

The constructor default is 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 "CHECKSUMS".

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 "CHECKSUMS".

credentials

my $credentials = $s3->credentials;

$s3->credentials($credentials);

Gets or sets the credentials provider object.

See "AUTHENTICATION AND CREDENTIALS".

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.

err

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

See "ERROR HANDLING".

error

Returns the most recent parsed structured error response.

See "ERROR HANDLING".

errstr

Returns the most recent human-readable error message.

See "ERROR HANDLING".

host

my $host = $s3->host;

$s3->host($endpoint);

Gets or sets the configured S3 endpoint.

The constructor default is s3.amazonaws.com.

See "S3-COMPATIBLE SERVICES".

last_request

Returns the most recent HTTP::Request generated by Amazon::S3.

See "ERROR HANDLING".

last_response

Returns the most recent HTTP::Response received by Amazon::S3.

See "ERROR HANDLING".

logger

my $logger = $s3->logger;

$s3->logger($logger);

Gets or sets the logger used by Amazon::S3.

See "LOGGING AND DEBUGGING".

retry

my $retry = $s3->retry;

$s3->retry($boolean);

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

The constructor default is false.

secure

my $secure = $s3->secure;

$s3->secure($boolean);

Gets or sets whether HTTPS is used.

The constructor default is true.

timeout

my $timeout = $s3->timeout;

$s3->timeout($seconds);

Gets or sets the HTTP request timeout in seconds.

The constructor default is 30.

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 "CHECKSUMS".

AUTHENTICATION AND CONFIGURATION METHODS

get_credentials

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

Returns the credentials used by the client.

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

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

The return values, in order, are:

  1. AWS access key ID.
  2. AWS secret access key.
  3. Session token, or undef when no token is configured.

See "AUTHENTICATION AND CREDENTIALS".

get_default_region

my $region = $s3->get_default_region;

Attempts to determine the default AWS region.

The method checks, in order:

  1. AWS_REGION.
  2. AWS_DEFAULT_REGION.
  3. The EC2 instance metadata availability-zone endpoint.

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

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

get_logger

my $logger = $s3->get_logger;

Returns the logger associated with the client.

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

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

See "LOGGING AND DEBUGGING".

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 error.

See "LOGGING AND DEBUGGING".

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 s3.amazonaws.com form, setting the region also adjusts the host to the regional Amazon S3 endpoint.

The constructor default is us-east-1.

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 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 signer constructor option.

See "AUTHENTICATION AND CREDENTIALS".

BUCKET MANAGEMENT

add_bucket

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

Creates a bucket.

The argument is a hash reference containing the bucket configuration.

On success, returns an Amazon::S3::Bucket object for the newly created bucket.

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

bucket

my $bucket = $s3->bucket($bucket_name);

my $bucket = $s3->bucket($bucket_name, $region);

my $bucket = $s3->bucket(
  { bucket        => $bucket_name,
    region        => $region,
    verify_region => $boolean,
  }
);

Constructs and returns an Amazon::S3::Bucket object.

This method does not create an S3 bucket and does not otherwise verify that the bucket exists.

The hash-reference form accepts:

The returned bucket object is associated with this Amazon::S3 client.

See Amazon::S3::Bucket.

buckets

my $response = $s3->buckets;

my $response = $s3->buckets($verify_region);

Lists the general-purpose buckets owned by the account.

verify_region is an optional boolean. When true, each returned Amazon::S3::Bucket object is constructed with region verification enabled.

Region verification can require an additional service request for each bucket and can therefore significantly increase the cost and latency of buckets().

The default is false.

On success, returns a hash reference containing:

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

bucketv2

my $bucket = $s3->bucketv2(
  { bucket        => $bucket_name,
    region        => $region,
    verify_region => $boolean,
  }
);

Constructs and returns an Amazon::S3::BucketV2 object.

The accepted parameters are:

Like bucket(), this method constructs a client-side object. It does not create the S3 bucket.

delete_bucket

my $ok = $s3->delete_bucket($bucket);

my $ok = $s3->delete_bucket(
  { bucket  => $bucket_name,
    region  => $region,
    headers => $headers,
  }
);

Deletes an S3 bucket.

The first form accepts an Amazon::S3::Bucket object and uses its bucket name and region.

The hash-reference form accepts:

The bucket must be empty before Amazon S3 will delete it.

Returns a true value on success.

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

delete_public_access_block

my $response = $s3->delete_public_access_block($bucket);

Removes the public access block configuration from a bucket.

The argument is expected to be an Amazon::S3::Bucket object.

The method performs the DeletePublicAccessBlock operation through the Amazon::S3::BucketV2 interface and returns that operation's result.

This operation may be required before applying public ACLs or public bucket policies to buckets whose public access block settings prohibit them.

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 Amazon::S3::Bucket object.

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

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

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 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 undef and records error information on the client.

See "DIRECTORY BUCKETS".

OBJECT LISTING AND VERSIONING

list_bucket

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

Lists objects using the original S3 ListObjects API.

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

Common parameters are:

On success, returns the normalized listing structure described in "LISTING OBJECTS".

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

See "LISTING OBJECTS". =head3 list_bucket_all

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

Lists all matching objects using the original ListObjects API.

The accepted parameters are the same as for list_bucket().

The method follows pagination automatically and can therefore make multiple S3 requests.

On success, returns the combined normalized listing result.

On a pagination failure, the method throws an exception.

See "LISTING OBJECTS". =head3 list_bucket_all_v2

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

Lists all matching objects using ListObjectsV2.

The accepted parameters are the same as for list_bucket_v2().

The method follows pagination automatically and can therefore make multiple S3 requests.

On success, returns the combined normalized listing result.

On a pagination failure, the method throws an exception.

See "LISTING OBJECTS". =head3 list_bucket_v2

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

Lists objects using the S3 ListObjectsV2 API.

The argument is a hash reference. bucket is required. Other defined entries are sent as ListObjectsV2 query parameters.

Common parameters are:

On success, returns the normalized listing structure described in "LISTING OBJECTS".

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

See "LISTING OBJECTS". =head3 list_object_versions

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

Lists object versions in a bucket.

The argument is a hash reference.

On success, returns the parsed ListObjectVersions service response. This method does not automatically follow pagination.

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

See "LISTING OBJECTS" and https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectVersions.html. =head2 ADVANCED AND COMPATIBILITY METHODS

turn_off_special_retry

$s3->turn_off_special_retry;

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

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

This method exists primarily for internal and compatibility use.

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.

LOGGING AND DEBUGGING

Logging is controlled by the configured logger and logging level.

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

Valid levels include:

fatal
error
warn
info
debug
trace

The default level is error.

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

At 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.

S3-COMPATIBLE SERVICES

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

The host, secure, and 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.

COMPARISON TO OTHER PERL S3 MODULES

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

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

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

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

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

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.

COMPATIBILITY AND LIMITATIONS

Minimum Perl Version

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.

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.

Directory Buckets

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

See "DIRECTORY BUCKETS".

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 README-TESTING.md in the distribution root for test environment setup, integration-test requirements, and additional testing instructions.

SUPPORT

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

When reporting a problem, include the 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.

REPOSITORY

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

https://github.com/rlauer6/Amazon-S3

AUTHOR

Original author: Timothy Appnel tima@cpan.org

Current maintainer: Rob Lauer bigfoot@cpan.org

SEE ALSO

Amazon::S3::Bucket

Amazon::S3::BucketV2

Amazon::S3::Constants

Amazon::S3::Logger

Amazon::Credentials

Net::Amazon::S3

Amazon S3 API Reference

Amazon S3 bucket naming rules

Amazon S3 bucket restrictions and limitations

AWS Signature Version 4

Amazon S3 directory buckets

LocalStack

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.