/ 
PawsX-S3-Uploader-0.0.1
/ PawsX::S3::Uploader

NAME

PawsX::S3::Uploader - upload to S3 from a streaming source

VERSION

version 0.0.1

SYNOPSIS

use Paws;
use PawsX::S3::Uploader;
use Feature::Compat::Try; # or a recent perl

my $s3 = Paws->service(S3 => ( region => 'eu-west-1' ));

my $uploader = PawsX::S3::Uploader(
    s3     => $s3,
    bucket => 'my-bucket',
    key    => 'my-object-key',

    # optional, anything that PutObject and CreateMultipartUpload
    # can understand
    extra_arguments => {
        ServerSideEncryption => 'aws:kms',
        SSEKMSKeyId          => 'the-secret-key-id',
        Metadata             => { foo => 'bar' },
        Tagging              => 'foo=bar&baz=3',
    }
);

try {
    while (my $block = read_data_from_somewhere()) {
        $uploader->add($block);
    }

    $uploader->finish;
}
catch ($error) {
    # if `read_data_from_somewhere` can throw, you need to abort
    # the upload yourself
    $uploader->abort();

    warn $error;
}

DESCRIPTION

This class automates uploading objects to AWS S3 via Paws, for the cases where you can't keep the whole data in memory, or you can't even generate it all ahead of time.

Underneath, it uses PutObject for objects smaller than 5MB, and CreateMultipartUpload / UploadPart / CompleteMultipartUpload for larger objects.

Exceptions in UploadPart cause the upload to be aborted, and the exception is re-thrown (so you can trap it yourself if you need to). You should also explicitly abort the upload if something goes wrong in your own code.

ATTRIBUTES

s3

Required, a Paws::S3 object.

bucket

Required, the S3 bucket to upload to.

key

Required, the object key to use.

extra_arguments

Optional hashref, its contents will be passed to PutObject or CreateMultipartUpload.

min_part_size

Optional integer, the minimum size for a part. Defaults to 5MB because uploading smaller parts via UploadPart fails with an "Entity too small" error.

You can set a larger value to reduce the number of requests. If you try setting a value smaller than 5MB, your value will be ignored.

always_multipart

Optional boolean, defaults to false. If true, the uploader will do a multipart upload even for objects smaller than min_part_size. This may be useful if the credentials you're using don't allow PutObject but allow the other methods.

callback

Optional coderef, a progress callback. See "Progress tracking", below.

METHODS

add

$uploader->add($some_data);

Appends the given string to the object being uploaded. You keep adding data until you're done, then call "finish".

This method can die with any exception that CreateMultipartUpload or UploadPart can throw. In that case, "abort" will be called automatically, because the multipart upload cannot continue.

This method will also die if you call it after "finish" or after "abort": you can't re-use uploader objects, you need to create one for each upload.

finish

my $output = $uploader->finish();

Completes the upload, once all the data has been added.

This method can die with any exception that PutObject, CreateMultipartUpload, UploadPart, or CompleteMultipartUpload can throw.

It will also die if you call it more than once or after "abort": you can't re-use uploader objects, you need to create one for each upload.

This method returns the Paws response object for the whole upload, either a Paws::S3::PutObjectOutput or Paws::S3::CompleteMultipartUploadOutput. After this method returns, the same value is also available via the "output" method.

abort

$uploader->abort();

If, for whatever reason, you cannot complete the upload, you should call this method. It will call AbortMultipartUpload and free up the resources in AWS that were created by CreateMultipartUpload.

This method gets called automatically if UploadPart died inside "add".

It's safe to call this method multiple times on the same uploader object, and even if no multipart upload was actually started, so you don't have to worry about the internal state of the uploader: if you caught an exception, or your code can't complete the upload, you call abort and it will do (or not do) what's needed.

This method will die if you call it after "finish", though.

output

Once an upload is finished, this method returns the Paws response object for the whole upload, either a Paws::S3::PutObjectOutput or Paws::S3::CompleteMultipartUploadOutput. It's the same value that was returned by finish.

upload_fh

my $output = $uploader->upload_fh($filehandle);

Uploads all data from the filehandle. This is a shortcut method that repeatedly reads data from the given filehandle, adds it to the upload, and finishes once it reaches end-of-file.

Progress tracking

If you provide a "callback" to the constructor, it will be called whenever the uploader does something. It will receive 2 arguments: a string identifying the event, and a hashref with some details. These are the events:

  • add => { size => ... }

  • start_multipart => { upload_id => ... }

  • upload_part => { size => ..., part_number => ... }

  • complete_multipart => {}

  • abort_multipart => { size => ..., part_number => ... }

  • put_object => { size => ... }

  • finish => { ouput => ... }

The finish event provides the same output as returned by "finish" and "output".

AUTHOR

Gianni Ceccarelli <gceccarelli@veritone.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Veritone Hire.

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