view release on metacpan or  search on metacpan

lib/Amazon/CloudFront/Thin.pm  view on Meta::CPAN

}

42;
__END__
=encoding utf8

=head1 NAME

Amazon::CloudFront::Thin - A thin, lightweight, low-level Amazon CloudFront client

=head1 SYNOPSIS

    use Amazon::CloudFront::Thin;

    my $cloudfront = Amazon::CloudFront::Thin->new({
        aws_access_key_id     => $key_id,
        aws_secret_access_key => $access_key,
        distribution_id       => 'my-cloudfront-distribution',
    });

    my $res = $cloudfront->create_invalidation(
       '/path/to/some/object.jpg',
       '/path/to/another/object.bin',
    );

=head1 DESCRIPTION

Amazon::CloudFront::Thin is a thin, lightweight, low level client for Amazon CloudFront.

It is designed for only ONE purpose: send a request and get a response.

It offers the following features:

=over 4

=item Low Level

Every request returns an L<HTTP::Response> object so you can easily inspect
what's happening inside, and can handle errors as you like.

=item Low Dependency

It has very few dependencies, so installation is easy and bloat-free
for your application. Aside from core modules like Digest::SHA, we
only rely on basic web modules like URI and HTTP::Message, which
you're probably already loaded from within your preferred web framework
or application.

=item Low Learning Cost

The interface is designed to follow Amazon CloudFront's official REST APIs.
So it is easy to learn and use by following the official documentation.

=back

=head2 Comparison to alternative modules

There are several useful modules for CloudFront on CPAN, like
L<Paws::CloudFront>, who provide a nice interface. You are welcome
to check them out to see if they suit your needs best. The reason
I wrote Amazon::CloudFront::Thin is because I needed to invalidate
CloudFront paths quickly and easily, and the alternatives felt either
like an "all or nothing" approach or lacked the documentation or
features I needed.

=head2 Amazon CloudFront setup in a Nutshell

Amazon CloudFront is the content-delivery (CDN) service of Amazon Web
Services (AWS). You use it by
L<< creating distributions|https://console.aws.amazon.com/cloudfront/home?region=us-east-1#distributions: >>
(each with its own "distribution id" which we use below). To manage
your distributions with this module, you need to provide credentials
allowed to access/change your CloudFront distributions. You do this
by going to L<< AWS's Identity and Access Management (IAM) console|https://console.aws.amazon.com/iam/home >>
and creating a new user. When you do that, the user's C<Access Key ID>
and C<Secret Access Key> credentials will be shown to you. You'll also
need to pass those to Amazon::CloudFront::Thin's constructor as shown
in the SYNOPSIS and below, as C<aws_access_key_id> and
C<aws_secret_access_key>, respectively. Finally, please note that
B<the provided IAM credentials must have the rights to change your CloudFront>.
You can do that by clicking on the user (in the Amazon IAM console where
you created it) and attaching a policy to it, such as the
C<CloudFrontFullAccess> standard policy. Otherwise you'll get errors when
trying to invalidate your CloudFront distributions.

=head1 CONSTRUCTOR

=head2 new( \%params )

B<Receives>: hashref with options.

B<Returns>: Amazon::CloudFront::Thin object.

    use Amazon::CloudFront::Thin;
    use IO::Socket::SSL;
    use Furl;

    
    my $cloudfront = Amazon::CloudFront::Thin->new(
        aws_access_key_id     => 'my_key_id',
        aws_secret_access_key => 'my_key_secret',
        distribution_id       => 'my-cloudfront-distribution-id',

        # optional
        ua => Furl->new(
            ssl_opts => { SSL_verify_mode => SSL_VERIFY_PEER()
        },
    );


Available arguments are:

=over

=item * C<aws_access_key_id> (B<required>)
Your L<< CloudFront credential|/"Amazon CloudFront setup in a Nutshell" >> key id.

=item * C<aws_secret_access_key> (B<required>)
Your L<< CloudFront credential|/"Amazon CloudFront setup in a Nutshell" >> secret.

=item * C<distribution_id> (B<required>)
The id of the L<< CloudFront distribution|/"Amazon CloudFront setup in a Nutshell" >>
you want to manage.

=item * C<ua> (Optional)
An LWP::UserAgent compatible object (otherwise, LWP::UserAgent will be used).
The object must provide a C<request()> method that receives an HTTP::Request
and returns a response. The responses, whatever they are, will be forwarded
to your call. Also, the object must be able to handle B<HTTPS>. If you don't
want to use LWP::UserAgent, there is a (highly incomplete) list of
alternatives below:

Compatible: L<Furl>, L<LWP::UserAgent>, L<HTTP::Thin>, L<WWW::Curl::Simple>.

Incompatible: L<HTTP::Lite>, L<Hijk>, L<HTTP::Lite>, L<HTTP::Tiny>.

=back

=head1 ACCESSORS

=head2 ua

Gets/Sets the current user agent object doing the requests to Amazon
CloudFront. Defaults to LWP::UserAgent. You can replace it either
using this accessor or during object construction (see above for an
example that loads C<Furl> instead of C<LWP::UserAgent>).

=head1 METHODS

=head2 create_invalidation( $path )

=head2 create_invalidation( @paths )

=head2 create_invalidation( \@paths )

B<Receives>: list of strings (or arrayref of strings), each specifying
a different path to invalidate.

B<Returns>: an L<HTTP::Response> object for the request. Use the C<content()>
method on the returned object to read the contents:

    my $res = $cloudfront->create_invalidation( '/path/to/some/object.png' );

    if ($res->is_success) {
        my $content = $res->content;
    }

This method creates a new invalidation batch request on Amazon CloudFront.
Please note that B<paths are case sensitive> and that
B<the leading '/' is optional>, meaning C<"foo/BAR"> and C<"FOO/bar">
are completely different, but C<"foo/bar"> and C<"/foo/bar"> (note the '/')
point to the same object.

Each path is wrapped under CDATA on the resulting XML, so it should be
safe for non-ASCII and unsafe characters in your paths.

For more information, please refer to
L<< Amazon's API documentation for CreateInvalidation|https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_CreateInvalidation.html >>.
For information on invalidations in general, including limitations,
please refer to L<< Amazon's CloudFront Developer Guide|https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Invalidation.html >>.
Finally, please refer to L<< Amazon's CloudFront error messages|https://docs.aws.amazon.com/cloudfront/latest/APIReference/CommonErrors.html >>
for more information on how to interpret errors returned as responses.

=head1 HANDLING UNICODE FILENAMES & PATHS

Amazon appears to reference filenames containing non ASCII characters
by URL Encoding the filenames. The following code takes a path such as
C<"events/الابحاث"> which contains both a slash to indicate a directory
boundary and a non-ascii filename and creates an invalidation:

    use Amazon::CloudFront::Thin;
    use URL::Encode qw( url_encode_utf8 );

    my $cloudfront = Amazon::CloudFront::Thin::->new( ... );

    my $encoded_filename = url_encode_utf8($path);

    # "/" will be encoded as %2F, but we want it as "/"
    $encoded_filename    =~ s!%2F!/!g;

    $cloudfront->create_invalidation( '/' . $encoded_filename );


=head1 AUTHOR

Breno G. de Oliveira C<< garu at cpan.org >>

=head1 LICENSE AND COPYRIGHT

Copyright 2015-2019 Breno G. de Oliveira C<< <garu at cpan.org> >>. All rights reserved.

This module is free software; you can redistribute it and/or modify it
under the same terms as Perl itself. See L<perlartistic>.


=head1 DISCLAIMER OF WARRANTY