NAME
    AnyEvent::EC2::Tiny - Tiny asynchronous (non-blocking) interface to EC2
    using AnyEvent

VERSION
    version 0.002

SYNOPSIS
        use v5.14;
        use AnyEvent::EC2::Tiny;

        my $ec2 = AnyEvent::EC2::Tiny->new(
            AWSAccessKey => $ENV{'AWS_ACCESS_KEY'},
            AWSSecretKey => $ENV{'AWS_SECRET_KEY'},
            region       => $ENV{'AWS_REGION'},
            debug        => 1,
        );

        # We are essentially encoding 'raw' EC2 API calls with a v2
        # signature and turning XML responses into Perl data structures
        my $xml = $ec2->send(
            'RegionName.1' => 'us-east-1',
            Action         => 'DescribeRegions',

            success_cb => sub {
                my $xml = shift;

                # prints ec2.us-east-1.amazonaws.com
                say $xml->{'regionInfo'}{'item'}[0]{'regionEndpoint'};
            },

            fail_cb => sub {
                my $error = shift;
                $error->{'type'} # HTTP or XML
                $error->{'data'} # hashref to body, errors, xml, headers, etc.
                $error->{'text'} # text of the error
            },
        );

DESCRIPTION
    This is a basic asynchronous, non-blocking, interface to EC2 based on
    Net::EC2::Tiny. It's relatively compatible while the only difference is
    with regards to the callbacks and returned information.

METHODS
  send
    "send()" expects the same arguments as "send()" in Net::EC2::Tiny,
    except you should also provide two additional arguments.

   success_cb
        $ec2->send(
            ...
            success_cb => sub {
                my $xml = shift;
                # do whatever you want with it
            },
        );

    Receives the resulting XML you would normally receive. Then you do
    whatever you want with it, such as fetching the information or using it
    to create another request.

   fail_cb
        $ec2->send(
            ...
            fail_cb => sub {
                my $error = shift;

                if ( $error->{'type'} eq 'HTTP' ) {
                    # this was an HTTP error
                    my $http_headers = $error->{'data'}{'headers'};
                    my $http_body    = $error->{'data'}{'body'};

                    warn 'HTTP error received: ', $error->{'text'};
                } else {
                    # $error->{'type'} eq 'XML'
                    # this was an XML error
                    my $http_headers = $error->{'data'}{'headers'};
                    my $http_body    = $error->{'data'}{'body'};
                    my $xml          = $error->{'data'}{'xml'};
                    my $xml_errors   = $error->{'data'}{'errors'};

                    warn "XML error received: ', $error->{'text'};
                }
            },
        );

    Since we can't simply "die" or "croak" in event-based code (the event
    loop would catch it and you won't be able to do much about it), we
    instead provide a failure callback. The failure callback receives a hash
    reference including all information relevant to the request.

    These are the available keys in the returned hash reference:

    "type"
        Either HTTP or XML.

        Since there are two possible failures (one being the HTTP request,
        and the other being any problems expressed in the XML returned) you
        can use the "type" key to know which type of error you received.

    "data"
        Additional information for the error.

        HTTP error receives the HTTP body ("body") and headers ("headers").

        XML error receives the HTTP body ("body"), headers ("headers"), XML
        data ("xml") and XML errors ("errors").

    "text"
        A string containing the error that occured. This matches the errors
        returned by Net::EC2::Tiny.

CREDITS
    Credit goes to Mark Allen for Net::EC2::Tiny.

AUTHOR
    Sawyer X <xsawyerx@cpan.org>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2013 by Sawyer X.

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