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 ingen_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 ofvalue
, this argument must be provided and gives the length of the data thatgen_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>