view release on metacpan or  search on metacpan

share/README.md  view on Meta::CPAN

It is not a replacement for [Amazon::S3](https://metacpan.org/pod/Amazon%3A%3AS3) or [Net::Amazon::S3](https://metacpan.org/pod/Net%3A%3AAmazon%3A%3AS3), which
support the full S3 API surface including multipart upload, bucket
management, ACLs, versioning, and presigned URLs. If you need those
features, use one of those distributions instead.

[Amazon::S3::Thin](https://metacpan.org/pod/Amazon%3A%3AS3%3A%3AThin) is another excellent lightweight S3 client with a
similar philosophy and a longer track record. It is more complete than
this module - supporting presigned URLs, bulk delete, and
virtual-hosted-style requests - and returns raw [HTTP::Response](https://metacpan.org/pod/HTTP%3A%3AResponse)
objects so callers handle status codes and errors
themselves. `Amazon::S3::Lite` differs in three ways: it has no
dependency on LWP (`Amazon::S3::Thin` defaults to [LWP::UserAgent](https://metacpan.org/pod/LWP%3A%3AUserAgent)),
it returns parsed hashrefs rather than raw response objects, and it
has first-class support for Lambda IAM role credential rotation. If
you need the broader feature set or prefer direct HTTP access,
`Amazon::S3::Thin` is a fine choice.

# CONSTRUCTOR

## new

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

Returns a new `Amazon::S3::Lite` object. Options:

- region (required)

    The AWS region for your bucket, e.g. `us-east-1`.

- aws\_access\_key\_id / aws\_secret\_access\_key

    Static credentials. `token` may also be supplied for STS temporary
    credentials (as used by Lambda execution roles).

    These are only consulted if no `credentials` object is provided.

- token

    Optional STS session token, used alongside static credentials for
    temporary credential sets.

- credentials

    An object providing credential getters. The object must respond to:

        $creds->aws_access_key_id
        $creds->aws_secret_access_key
        $creds->token            # may return undef

    Any object that satisfies this interface is accepted -
    [Amazon::Credentials](https://metacpan.org/pod/Amazon%3A%3ACredentials), [Paws::Credential::\*](https://metacpan.org/pod/Paws%3A%3ACredential%3A%3A%2A), or your own. The
    getters are called at request time, so objects that refresh expiring
    credentials transparently are supported.

- logger

    An object providing the standard log methods:

        $logger->trace(...)
        $logger->debug(...)
        $logger->info(...)
        $logger->warn(...)
        $logger->error(...)

    If not supplied, the module looks for [Log::Log4perl](https://metacpan.org/pod/Log%3A%3ALog4perl). If available,
    it calls `Log::Log4perl::easy_init` with level WARN and logs to
    STDERR.  If Log::Log4perl is not installed, a minimal internal logger
    is used that prints WARN and above to STDERR.

- host

    Override the S3 endpoint host. Defaults to `s3.amazonaws.com`.
    Useful for S3-compatible services (MinIO, Ceph, LocalStack).

- secure

    Use HTTPS. Default is 1 (true). Set to 0 only for testing against
    local S3-compatible endpoints.

- timeout

    HTTP request timeout in seconds. Default is 30.

## Credential resolution order

When no `credentials` object is passed, credentials are resolved in
this order:

1. Constructor arguments `aws_access_key_id` and `aws_secret_access_key`.
2. Environment variables `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`,
and optionally `AWS_SESSION_TOKEN`.
3. [Amazon::Credentials](https://metacpan.org/pod/Amazon%3A%3ACredentials), if installed. This covers IAM instance roles,
Lambda execution roles, ECS task roles, and `~/.aws/credentials`
profiles.
4. If none of the above yield credentials, the constructor croaks.

# METHODS

All methods croak on unrecoverable errors (network failure, HTTP 5xx).
HTTP 404 is not an exception - methods that can meaningfully return
`undef` for a missing resource do so.

## list\_objects\_v2

    my $result = $s3->list_objects_v2($bucket, %options);

Lists objects in `$bucket` using the S3 ListObjectsV2 API.

Options:

- prefix

    Limit results to keys beginning with this string.

- delimiter

    Group keys sharing a common prefix up to this delimiter. Grouped
    prefixes are returned in `common_prefixes`.

- max\_keys