view release on metacpan or  search on metacpan

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

    region      => 'us-east-1',
    credentials => $creds_obj,
  });

  # List objects in a bucket
  my $result = $s3->list_objects_v2('my-bucket', prefix => 'logs/');

  foreach my $obj ( @{ $result->{objects} } ) {
    printf "%s  %d bytes\n", $obj->{key}, $obj->{size};
  }

  # Paginate
  while ( $result->{is_truncated} ) {
    $result = $s3->list_objects_v2('my-bucket',
      prefix             => 'logs/',
      continuation_token => $result->{next_continuation_token},
    );
    # ... process $result->{objects}
  }

  # Get an object
  my $obj = $s3->get_object('my-bucket', 'path/to/key.json');
  print $obj->{content};

  # Head an object (existence check / metadata only)
  my $meta = $s3->head_object('my-bucket', 'path/to/key.json');
  if ($meta) {
    print $meta->{content_length};
  }

  # Put an object
  $s3->put_object('my-bucket', 'path/to/key.json', $json_string,
    content_type => 'application/json',
    metadata     => { source => 'lambda' },
  );

  # Copy an object
  $s3->copy_object(
    src_bucket => 'my-bucket', src_key => 'orig/file.json',
    dst_bucket => 'my-bucket', dst_key => 'archive/file.json',
  );

  # Delete an object
  $s3->delete_object('my-bucket', 'path/to/key.json');

  # List all buckets
  my $result = $s3->list_buckets;
  for my $bucket ( @{ $result->{buckets} } ) {
    print $bucket->{name}, "\n";
  }

  # Create a bucket
  $s3->create_bucket('my-bucket');
  $s3->create_bucket('my-bucket', region => 'eu-west-1');

  # Configure a Lambda notification trigger
  $s3->put_bucket_notification_configuration('my-bucket',
    type       => 'lambda',
    lambda_arn => $function_arn,
    events     => 's3:ObjectCreated:*',
    filters    => { prefix => 'uploads/' },
  );

  # Configure an SQS notification trigger
  $s3->put_bucket_notification_configuration('my-bucket',
    type      => 'sqs',
    queue_arn => $queue_arn,
    events    => 's3:ObjectCreated:*',
  );

  # Retrieve notification configuration
  my $configs = $s3->get_bucket_notification_configuration('my-bucket');
  for my $cfg ( @{$configs} ) {
    printf "id=%s lambda=%s queue=%s\n",
      $cfg->{id}, $cfg->{lambda_arn} // '', $cfg->{queue_arn} // '';
  }

=head1 DESCRIPTION

C<Amazon::S3::Lite> is a minimal Amazon S3 client covering the
operations most commonly needed in AWS Lambda functions and
lightweight scripts: listing buckets, listing objects, reading,
writing, copying, and deleting.

It is built on L<HTTP::Tiny> (core since Perl 5.14) and
L<Amazon::Signature4::Lite>, with no dependency on LWP or any part of
the libwww-perl ecosystem. The dependency list is intentionally small,
making it well-suited for Lambda container images where minimizing
cold-start time and image size matters.

It is not a replacement for L<Amazon::S3> or L<Net::Amazon::S3>, 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.

L<Amazon::S3::Thin> 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 L<HTTP::Response>
objects so callers handle status codes and errors
themselves. C<Amazon::S3::Lite> differs in three ways: it has no
dependency on LWP (C<Amazon::S3::Thin> defaults to L<LWP::UserAgent>),
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,
C<Amazon::S3::Thin> is a fine choice.

=head1 CONSTRUCTOR

=head2 new

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

Returns a new C<Amazon::S3::Lite> object. Options:

=over 4

=item region (options, default: us-east-1)

The AWS region for your bucket, e.g. C<us-east-1>.

=item aws_access_key_id / aws_secret_access_key

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

These are only consulted if no C<credentials> object is provided.

=item token

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

=item 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 -
L<Amazon::Credentials>, L<Paws::Credential::*>, or your own. The
getters are called at request time, so objects that refresh expiring
credentials transparently are supported.

=item logger

An object providing the standard log methods:

  $logger->trace(...)
  $logger->debug(...)

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

=item error_document

The error document key.

=item redirect_all_requests_to

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

=back

=head2 delete_bucket_website

  $s3->delete_bucket_website($bucket);

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

=head2 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.

=head2 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 C<undef> if the bucket has no policy
(S3 returns C<NoSuchBucketPolicy>). By default the policy is decoded
and returned as a hashref; pass C<< raw => 1 >> to get the raw JSON
string instead.

=over 4

=item raw

When true, return the policy as its raw JSON string rather than a
decoded hashref.

=back

=head2 put_bucket_notification_configuration

  # Lambda trigger
  $s3->put_bucket_notification_configuration($bucket,
    type       => 'lambda',
    lambda_arn => $function_arn,
    events     => 's3:ObjectCreated:*',
  );

  # SQS trigger
  $s3->put_bucket_notification_configuration($bucket,
    type      => 'sqs',
    queue_arn => $queue_arn,
    events    => [qw(s3:ObjectCreated:* s3:ObjectRemoved:*)],
    filters   => { prefix => 'uploads/', suffix => '.csv' },
  );

Sets the bucket notification configuration for C<$bucket>, routing
S3 events to a Lambda function or SQS queue.

Options:

=over 4

=item type (required)

The notification target type. Must be C<lambda> or C<sqs>.

=item lambda_arn (required when type is C<lambda>)

The ARN of the Lambda function to invoke.

=item queue_arn (required when type is C<sqs>)

The ARN of the SQS queue to deliver messages to.

=item events (required)

A scalar event name or an arrayref of event names.
Common values: C<s3:ObjectCreated:*>, C<s3:ObjectRemoved:*>.

=item filters

A hashref of S3 key filter rules. Supported keys are C<prefix>
and C<suffix>.

=item id

An identifier for the configuration entry. Defaults to C<notification-1>.

=back

Returns true on success. Croaks on failure.

=head2 get_bucket_notification_configuration

  my $configs = $s3->get_bucket_notification_configuration($bucket);

  for my $cfg ( @{$configs} ) {
    if ( $cfg->{lambda_arn} ) {
      printf "Lambda: id=%s arn=%s\n", $cfg->{id}, $cfg->{lambda_arn};
    }
    elsif ( $cfg->{queue_arn} ) {
      printf "SQS:    id=%s arn=%s\n", $cfg->{id}, $cfg->{queue_arn};
    }
    print "  events: ", join(', ', @{ $cfg->{events} }), "\n";
  }

Retrieves the current notification configuration for C<$bucket>.
Handles both Lambda (C<CloudFunctionConfiguration>) and SQS
(C<QueueConfiguration>) entries, which are the XML element names
the S3 API returns regardless of how the configuration was created.

Returns an arrayref of configuration hashrefs, each containing: