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.

    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 100.

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_value => CODE
            Alternative to `value' in the case of larger values. Called
            repeatedly to generate successive chunks of the value. Each
            invocation should return either a string of bytes, or `undef' to
            indicate completion.

    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 MD5 sum of the
    newly-set key, as a 32-character hexadecimal string.

     ( $md5_hex ) = $f->get

    The returned MD5 sum from S3 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>