NAME
    `Net::Async::Webservice::S3' - use Amazon's S3 web service with
    `IO::Async'

SYNOPSIS
     TODO

DESCRIPTION
    This module provides a webservice API around Amazon's S3 web service for
    use in an IO::Async-based program. Each S3 operation is represented by a
    method that returns a Future; this future, if successful, will
    eventually return the result of the operation.

PARAMETERS
    The following named parameters may be passed to `new' or `configure':

    http => Net::Async::HTTP
            Optional. Allows the caller to provide a specific asynchronous
            HTTP user agent object to use. This will be invoked with a
            single method, as documented by Net::Async::HTTP:

             $response_f = $http->do_request( request => $request, ... )

            If absent, a new instance will be created and added as a child
            notifier of this object. If a value is supplied, it will be used
            as supplied and *not* specifically added as a child notifier. In
            this case, the caller must ensure it gets added to the
            underlying IO::Async::Loop instance, if required.

    access_key => STRING
    secret_key => STRING
            The twenty-character Access Key ID and forty-character Secret
            Key to use for authenticating requests to S3.

    bucket => STRING
            Optional. If supplied, gives the default bucket name to use, at
            which point it is optional to supply to the remaining methods.

    prefix => STRING
            Optional. If supplied, this prefix string is prepended to any
            key names passed in methods, and stripped from the response from
            `list_bucket'. It can be used to keep operations of the object
            contained within the named key space. If this string is
            supplied, don't forget that it should end with the path
            delimiter in use by the key naming scheme (for example `/').

    max_retries => INT
            Optional. Maximum number of times to retry a failed operation.
            Defaults to 3.

    list_max_keys => INT
            Optional. Maximum number of keys at a time to request from S3
            for the `list_bucket' method. Larger values may be more
            efficient as fewer roundtrips will be required per method call.
            Defaults to 1000.

    part_size => INT
            Optional. Size in bytes to break content for using multipart
            upload. If an object key's size is no larger than this value,
            multipart upload will not be used. Defaults to 100 MiB. (Used to
            be called `multipart_chunk_size'.

METHODS
  $f = $s3->list_bucket( %args )
    Requests a list of the keys in a bucket, optionally within some prefix.

    Takes the following named arguments:

    bucket => STR
            The name of the S3 bucket to query

    prefix => STR
    delimiter => STR
            Optional. If supplied, the prefix and delimiter to use to divide
            up the key namespace. Keys will be divided on the `delimiter'
            parameter, and only the key space beginning with the given
            prefix will be queried.

    The Future will return two ARRAY references. The first provides a list
    of the keys found within the given prefix, and the second will return a
    list of the common prefixes of further nested keys.

     ( $keys, $prefixes ) = $f->get

    Each key in the `$keys' list is given in a HASH reference containing

    key => STRING
            The key's name

    last_modified => STRING
            The last modification time of the key given in ISO 8601 format

    etag => STRING
            The entity tag of the key

    size => INT
            The size of the key's value, in bytes

    storage_class => STRING
            The S3 storage class of the key

    Each key in the `$prefixes' list is given as a plain string.

  $f = $s3->get_object( %args )
    Requests the value of a key from a bucket.

    Takes the following named arguments:

    bucket => STR
            The name of the S3 bucket to query

    key => STR
            The name of the key to query

    on_chunk => CODE
            Optional. If supplied, this code will be invoked repeatedly on
            receipt of more bytes of the key's value. It will be passed an
            HTTP::Response object containing the key's metadata, and a byte
            string containing more bytes of the value. Its return value is
            not important.

             $on_chunk->( $header, $bytes )

            If this is supplied then the key's value will not be
            accumulated, and the final result of the Future will be an empty
            string.

    The Future will return a byte string containing the key's value and the
    HTTP::Response containing the key's metadata.

     ( $value, $response ) = $f->get;

    If an `on_chunk' code reference is passed, this string will be empty.

  $f = $s3->put_object( %args )
    Sets a new value for a key in the bucket.

    Takes the following named arguments:

    bucket => STRING
            The name of the S3 bucket to put the value in

    key => STRING
            The name of the key to put the value in

    value => STRING
            Optional. If provided, gives a byte string as the new value for
            the key

    gen_parts => CODE
            Alternative to `value' in the case of larger values, and implies
            the use of multipart upload. Called repeatedly to generate
            successive parts of the upload. Each time it is called it should
            yield two values; an integer giving the length of this part, and
            a generator used to create it. The generator must be a code
            reference of the same form as given in `gen_value' below. When
            there are no more parts it should return an empty list.

             ( $value_length, $gen_value ) = $gen_parts->()

            The `$pos' parameter to `$gen_value' will begin at zero for each
            part.

    gen_value => CODE
            DEPRECATED. See instead `gen_parts'

            Alternative to `value' in the case of larger values. Called
            repeatedly to generate successive chunks of the value. Each
            invocation will be passed a byte position and length, and should
            return a string of bytes.

             $bytes = $gen_value->( $pos, $length )

            This callback will not be invoked on a range outside of the
            length given by the `value_length' parameter. It may return a
            shorter byte chunk than requested.

            If it declines entirely to yield enough content (by returning
            `undef') then the remainder of the declared content length will
            be null-padded. If it returns too much content, it will be
            truncated.

    value_length => INT
            If `gen_value' is given instead of `value', this argument must
            be provided and gives the length of the data that `gen_value'
            will eventually generate.

    The Future will return a single string containing the S3 ETag of the
    newly-set key. For single-part uploads this will be the MD5 sum in hex,
    surrounded by quote marks. For multi-part uploads this is a string in a
    different form, though details of its generation are not specified by
    S3.

     ( $etag ) = $f->get

    The returned MD5 sum from S3 during upload will be checked against an
    internally-generated MD5 sum of the content that was sent, and an error
    result will be returned if these do not match.

  $f = $s3->delete_object( %args )
    Deletes a key from the bucket.

    Takes the following named arguments:

    bucket => STRING
            The name of the S3 bucket to put the value in

    key => STRING
            The name of the key to put the value in

    The Future will return nothing.

SPONSORS
    Parts of this code were paid for by

    * Socialflow http://www.socialflow.com

    * Shadowcat Systems http://www.shadow.cat

AUTHOR
    Paul Evans <leonerd@leonerd.org.uk>

