Amazon-S3-Lite
3 results

 view release on metacpan or  search on metacpan

share/README.md  view on Meta::CPAN 

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 (options, default: us-east-1)

    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 the configure log level (or
    WARN) and logs to STDERR.  If Log::Log4perl is not installed, a
    minimal internal logger.

- 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

    Maximum number of objects to return per call (1-1000, default 1000).

- continuation\_token

    Resume a truncated listing from a prior call's
    `next_continuation_token`.

- start\_after

    Return only keys lexicographically after this value.

Returns a hashref:

    {
      bucket                 => 'my-bucket',
      prefix                 => 'logs/',
      is_truncated           => 0,

share/README.md  view on Meta::CPAN 


    $s3->create_bucket($bucket);
    $s3->create_bucket($bucket, region => 'eu-west-1', acl => 'private');

Creates a new S3 bucket. Options:

- region

    The region in which to create the bucket. Defaults to the region the
    object was constructed with. **Note:** `us-east-1` is S3's implicit
    default - the `CreateBucketConfiguration` body is intentionally
    omitted for that region as including it causes a `InvalidLocationConstraint`
    error. For all other regions the `LocationConstraint` element is
    sent automatically.

- acl

    Canned ACL string, e.g. `private` (the S3 default), `public-read`.

Returns true on success. Croaks on failure.

## delete\_bucket

    $s3->delete_bucket($bucket);
    $s3->delete_bucket($bucket, region => 'us-west-2');

Deletes an empty bucket. Returns a true value on success. S3 refuses
to delete a bucket that still contains objects, so callers must empty
the bucket first (for example by iterating ["list\_all\_objects\_v2"](#list_all_objects_v2) and
calling ["delete\_object"](#delete_object) on each key).

- region

    Override the region the delete is signed against. Defaults to the
    region the object was constructed with.

## put\_public\_access\_block

    $s3->put_public_access_block($bucket);
    $s3->put_public_access_block(
      $bucket,
      block_public_acls       => 1,
      ignore_public_acls      => 1,
      block_public_policy      => 0,
      restrict_public_buckets => 0,
    );

Sets the Block Public Access configuration on a bucket. Each of the
four settings is a boolean; any setting not supplied **defaults to
true** (fully locked down), so an argument-less call blocks all public
access. Returns a true value on success.

- block\_public\_acls
- ignore\_public\_acls
- block\_public\_policy
- restrict\_public\_buckets

    Each accepts a true/false value. Omitted settings default to true.
    Note that hosting content publicly (for example a static website, or
    a policy-scoped private bucket that grants anonymous `GetObject` from
    a VPC endpoint) requires the relevant setting to be false so the
    bucket policy is not rejected.

## put\_bucket\_website

    $s3->put_bucket_website($bucket);
    $s3->put_bucket_website($bucket, index => 'index.html', error => 'error.html');

Configures the bucket as an S3 static website endpoint. Returns a true
value on success.

- index

    The index document suffix. Defaults to `index.html`.

- error

    The error document key. Optional; when omitted, no error document is
    configured.

## get\_bucket\_website

    my $config = $s3->get_bucket_website($bucket);

Returns the bucket's website configuration as a hashref, or `undef`
if the bucket has no website configuration. The hashref contains
whichever of the following are set:

- index\_document

    The index document suffix.

- error\_document

    The error document key.

- redirect\_all\_requests\_to

    The hostname all requests are redirected to, if the bucket is
    configured as a redirect.

## delete\_bucket\_website

    $s3->delete_bucket_website($bucket);

Removes the website configuration from a bucket. Returns a true value
on success.

## put\_bucket\_policy

    $s3->put_bucket_policy($bucket, \%policy);
    $s3->put_bucket_policy($bucket, $json_string);

Attaches a bucket policy. The policy may be given either as a Perl
data structure (a hashref, which is encoded to canonical JSON) or as a
pre-encoded JSON string. Returns a true value on success.

## get\_bucket\_policy

    my $policy = $s3->get_bucket_policy($bucket);
    my $json   = $s3->get_bucket_policy($bucket, raw => 1);

Returns the bucket's policy, or `undef` if the bucket has no policy
(S3 returns `NoSuchBucketPolicy`). By default the policy is decoded
and returned as a hashref; pass `raw => 1` to get the raw JSON
string instead.

- raw

share/README.md  view on Meta::CPAN 

    `undef` for Lambda entries.

- events

    Arrayref of event type strings.

- filters

    Arrayref of hashrefs, each with `name` (`prefix` or `suffix`)
    and `value`.

Returns an empty arrayref if no notification configuration is set.
Croaks on failure.

## remove\_bucket\_notification\_configuration

    $s3->remove_bucket_notification_configuration($bucket);

Removes all notification configurations from `$bucket` by sending an
empty `NotificationConfiguration` document to S3. After this call S3
will no longer deliver any events for the bucket.

Returns true on success. Croaks on failure.

# ERROR HANDLING

Methods croak on:

- Network-level failures (connection refused, timeout, DNS failure)
- HTTP 5xx responses from S3
- Unexpected HTTP 3xx responses that could not be resolved

Methods return `undef` on:

- HTTP 404 (key or bucket not found), where the return type allows it

All other HTTP error codes (400, 403, 409, etc.) cause a croak with a
message containing the HTTP status line and the S3 error body where
available.

# DEPENDENCIES

- [HTTP::Tiny](https://metacpan.org/pod/HTTP%3A%3ATiny) (core since Perl 5.14)
- [Amazon::Signature4::Lite](https://metacpan.org/pod/Amazon%3A%3ASignature4%3A%3ALite)
- [XML::Twig](https://metacpan.org/pod/XML%3A%3ATwig) (for parsing list and copy responses)
- [Digest::MD5](https://metacpan.org/pod/Digest%3A%3AMD5) (core, for Content-MD5 headers)
- [MIME::Base64](https://metacpan.org/pod/MIME%3A%3ABase64) (core)
- [URI::Escape](https://metacpan.org/pod/URI%3A%3AEscape)
- [Carp](https://metacpan.org/pod/Carp) (core)

Optional:

- [Amazon::Credentials](https://metacpan.org/pod/Amazon%3A%3ACredentials) - automatic credential discovery from IAM
roles, ECS task roles, ~/.aws/credentials, and environment.
- [Log::Log4perl](https://metacpan.org/pod/Log%3A%3ALog4perl) - structured logging; if present, used in
preference to the built-in minimal logger.

# LAMBDA USAGE NOTES

In a Lambda container, credentials come from the execution role via
the ECS credential provider endpoint (indicated by
`AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` in the environment).
[Amazon::Credentials](https://metacpan.org/pod/Amazon%3A%3ACredentials) handles this automatically when installed and
is the recommended approach. If you prefer not to take that
dependency, the Lambda runtime also populates `AWS_ACCESS_KEY_ID`,
`AWS_SECRET_ACCESS_KEY`, and `AWS_SESSION_TOKEN` directly, which
this module picks up automatically from the environment.

**Region note:** The `list_buckets` method is a global S3 operation
and is always signed against `us-east-1`, regardless of the region
supplied to the constructor. This is an S3 requirement, not a
limitation of this module, and is handled transparently - your
object's region is not changed.

**Cold start:** Because this module depends only on [HTTP::Tiny](https://metacpan.org/pod/HTTP%3A%3ATiny) (Perl
core), [XML::Twig](https://metacpan.org/pod/XML%3A%3ATwig), [AWS::Signature4](https://metacpan.org/pod/AWS%3A%3ASignature4), and [URI::Escape](https://metacpan.org/pod/URI%3A%3AEscape), it adds
minimal overhead to Lambda container image builds compared to
LWP-based S3 clients.

# TESTING

When testing against LocalStack, be aware that LocalStack is more
lenient than real S3 regarding SigV4 requirements. In particular,
LocalStack may accept requests where the `x-amz-content-sha256`
header is missing or where session token handling is incorrect. Tests
that pass against LocalStack should always be verified against real S3
before release.

# SEE ALSO

[Amazon::S3](https://metacpan.org/pod/Amazon%3A%3AS3) - the full-featured S3 client this module draws from

[Amazon::S3::Thin](https://metacpan.org/pod/Amazon%3A%3AS3%3A%3AThin) - another excellent lightweight S3 client with a
similar philosophy, broader feature coverage, and a longer track
record. Uses LWP by default and returns raw [HTTP::Response](https://metacpan.org/pod/HTTP%3A%3AResponse)
objects. See ["DESCRIPTION"](#description) for a detailed comparison.

[Net::Amazon::S3](https://metacpan.org/pod/Net%3A%3AAmazon%3A%3AS3) - a Moose-based full-featured alternative

[Amazon::Signature4::Lite](https://metacpan.org/pod/Amazon%3A%3ASignature4%3A%3ALite) - the signing module used internally

[Amazon::Credentials](https://metacpan.org/pod/Amazon%3A%3ACredentials) - credential provider with IAM role and profile
support

# AUTHOR

Rob Lauer <rlauer@treasurersbriefcase.com>

# LICENSE

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



( run in 1.791 second using v1.01-cache-2.11-cpan-364913b4093 )