package Net::Fastly;

use strict;
use warnings;

use Net::Fastly::Client;
use Net::Fastly::Invoice;
use Net::Fastly::Settings;

our $VERSION = "1.12";

  no strict 'refs';
  our @CLASSES = qw(Net::Fastly::User     Net::Fastly::Customer
                    Net::Fastly::Backend  Net::Fastly::Director
                    Net::Fastly::Domain   Net::Fastly::Healthcheck
                    Net::Fastly::Match    Net::Fastly::Origin   
                    Net::Fastly::Service  Net::Fastly::Syslog
                    Net::Fastly::VCL      Net::Fastly::Version

  foreach my $class (@CLASSES) {
    my $file = $class . '.pm';
    $file =~ s{::}{/}g;
    my $name = $class->_path;
    foreach my $method (qw(get create update delete list)) {
        my $code = "sub { shift->_$method('$class', \@_) }";
        my $glob = "${method}_${name}";
        $glob .= "s" if $method eq 'list';
        # don't create this if it's a list and something isn't listable ...
        next if $method eq 'list' && $class->_skip_list;
        # or if it already exists (i.e it's been overidden)
        next if defined *$glob;
        *$glob = eval "$code";

=head1 NAME

Net::Fastly - client library for interacting with the Fastly web acceleration service


    use Net::Fastly;

    # username/password authentication is deprecated and will not be available
    # starting September 2020; use {api_key: 'your-key'} as the login option
    my $fastly = Net::Fastly->new(%login_opts);
    my $current_user     = $fastly->current_user;
    my $current_customer = $fastly->current_customer;
    my $user     = $fastly->get_user($current_user->id);
    my $customer = $fastly->get_customer($current_customer->id);
    print "Name: ".$user->name."\n";
    print "Works for ".$user->customer->name."\n";
    print "Which is the same as ".$customer->name."\n";
    print "Which has the owner ".$customer->owner->name."\n";
    # Let's see which services we have defined
    foreach my $service ($fastly->list_services) {
        print $service->name." (".$service->id.")\n";
        foreach my $version ($service->versions) {
            print "\t".$version->number."\n";
    my $service        = $fastly->create_service(name => "MyFirstService");
    my $latest_version = $service->version;
    # Create a domain and a backend for the service ...
    my $domain         = $fastly->create_domain(service_id => $service->id, version => $latest_version->number, name => "");
    my $backend        = $fastly->create_backend(service_id => $service->id, version => $latest_version->number, ipv4 => "", port => 80);
    # ... and activate it. You're now hosted on Fastly.
    # Let's take a peek at the VCL that Fastly generated for us
    my $vcl = $latest_version->generated_vcl;
    print "Generated VCL file is:\n".$vcl->content."\n";
    # Now let's create a new version ...
    my $new_version    = $latest_version->clone;
    # ... add a new backend ...
    my $new_backend    = $fastly->create_backend(service_id => $service->id, version => $new_version->number, ipv4 => "", port => 8080);
    # ... and upload some custome vcl (presuming we have permissions)
    $new_version->upload_vcl($vcl_name, slurp($vcl_file));    

    # Purging
    $fastly->purge('');    # regular purge
    $fastly->purge('', 1); # 'soft' purge (see note below)
    $service->purge_by_key('article-1');         # purge by surrogate key, note this works on $service
    $service->purge_by_key('article-1', 1);      # 'soft' purge by surrogate key
    $service->purge_all;                         # use with caution!


=head2 A Note About Authentication

Authenticating with a username/password is deprecated and will no longer be available starting September 2020.

Authenticating with an API Token is shown in the example synopsis below. For more information on API Tokens, please see [Fastly's API Token documentation]( For more information about authenticating to our API, please see our [Authentication section](

=head1 METHODS


=head2 new <opt[s]>

Create a new Fastly client. Options are

=over 4

=item user - your Fastly login

=item password - your Fastly password

=item api_key - your Fastly api key


You only need to pass in C<api_key> OR C<user> and C<password>. 

Some methods require full username and password rather than just auth token.

sub new {
    my $class = shift;
    my %opts  = @_;
    my ($client, $user, $customer) = Net::Fastly::Client->new(%opts);
    my $self  = bless { _client =>  $client, _current_customer => undef, _current_user => undef}, $class;
    if ($user && $customer) {
        $self->{_current_user}     =  Net::Fastly::User->new($self, %$user);
        $self->{_current_customer} =  Net::Fastly::Customer->new($self, %$customer);
    return $self;

=head2 client

Get the current Net::Fastly::Client

sub client { shift->{_client} }

=head2 set_customer <customer id>

Set the current customer to act as.

B<NOTE>: this will only work if you're an admin

sub set_customer {
    my $self = shift;
    my $id   = shift;
    die "You must be fully authed to set the customer" unless $self->fully_authed;
    die "You must be an admin to set the customer" unless $self->current_user->can_do('admin');
    delete $self->{_current_customer};

=head2 authed

Whether or not we're authed at all by either username & password or API key

sub authed { shift->client->authed }

=head2 fully_authed

Whether or not we're fully (username and password) authed

sub fully_authed { shift->client->fully_authed }

=head2 current_user 

Return a User object representing the current logged in user.

This will not work if you're logged in with an API key.

sub current_user {
    my $self = shift;
    die "You must be fully authed to get the current user" unless $self->fully_authed;
    $self->{_current_user} ||= $self->_get("Net::Fastly::User");

=head2 current_customer

Return a Customer object representing the customer of the current logged in user.

sub current_customer {
    my $self = shift;
    die "You must be authed to get the current customer" unless $self->authed;
    $self->{_current_customer} ||= $self->_get("Net::Fastly::Customer");

=head2 commands 

Return a hash representing all commands available.

Useful for information.

sub commands {
    my $self     = shift;
    return $self->{__cache_commands} if ($self->{__cache_commands});
    return eval { $self->{__cache_commands} = $self->client->_get('/commands') };

=head2 purge <path> [soft]

Purge the specified path from your cache.

You can optionally pass in a true value to enable "soft" purging e.g

    $fastly->purge($url, 1);

See L<>

Previously purging made an API call to the C</purge> endpoint of the Fastly API.

The new method of purging is done by making an HTTP request against the URL using the C<PURGE> HTTP method.

This module now uses the new method. The old method can be used by passing the C<use_old_purge_method> into the constructor.

    my $fastly = Net::Fastly->new(%login_opts, use_old_purge_method => 1);

sub purge {
    my $self = shift;
    my $url  = shift;
    my $soft = shift;
    $self->client->_purge($url, headers => { 'Fastly-Soft-Purge' => $soft });

=head2 stats [opt[s]]

Fetches historical stats for each of your fastly services and groups the results by service id.

If you pass in a C<field> opt then fetches only the specified field.

If you pass in a C<service> opt then fetches only the specified service.

The C<field> and C<service> opts can be combined.

If you pass in an C<aggregate> flag then fetches historical stats information aggregated across all of your Fastly services. This cannot be combined with C<field> and C<service>.

Other options available are:

=over 4

=item from & to

=item by

=item region


See for details.

sub stats {
    my $self = shift;
    my %opts = @_;
    die "You can't specify a field or a service for an aggregate request" if $opts{aggregate} && ($opts{field} || $opts{service});
    my $url  = "/stats";

    if (delete $opts{aggregate}) {
        $url .= "/aggregate";
    if (my $service = delete $opts{service}) {
        $url .= "/service/$service";
    if (my $field = delete $opts{field}) {
        $url .= "/field/$field";
    $self->client->_get_stats($url, %opts);

=head2 usage [opt[s]]

Returns usage information aggregated across all Fastly services and grouped by region.

If the C<by_service> flag is passed then teturns usage information aggregated by service and grouped by service & region.

Other options available are:

=over 4

=item from & to

=item by

=item region


See for details.

sub usage {
    my $self = shift;
    my %opts = @_;
    my $url  = "/stats/usage";
    $url .= "_by_service" if delete $opts{by_service};
    $self->client->_get_stats($url, %opts);

=head2 regions

Fetches the list of codes for regions that are covered by the Fastly CDN service.

sub regions {
    my $self = shift;

=head2 create_user <opts>

=head2 create_customer <opts>

=head2 create_service <opts>

=head2 create_version service_id => <service id>, [opts]

=head2 create_backend service_id => <service id>, version => <version number>, name => <name> <opts>

=head2 create_director service_id => <service id>, version => <version number>, name => <name> <opts>

=head2 create_domain service_id => <service id>, version => <version number>, name => <name> <opts>

=head2 create_healthcheck service_id => <service id>, version => <version number>, name => <name> <opts>

=head2 create_match service_id => <service id>, version => <version number>, name => <name> <opts>

=head2 create_origin service_id => <service id>, version => <version number>, name => <name> <opts>

=head2 create_syslog service_id => <service id>, version => <version number>, name => <name> <opts>

=head2 create_vcl service_id => <service id>, version => <version number>, name => <name> <opts>

=head2 create_condition service_id => <service id>, version => <version number>, name => <name> <opts>

Create new objects.


=head2 get_user <id>

=head2 get_customer <id>

=head2 get_service <id>

=head2 get_version <service id> <number>

=head2 get_backend <service id> <version number> <name>

=head2 get_director <service id> <version number> <name>

=head2 get_domain <service id> <version number> <name>

=head2 get_healthcheck <service id> <version number> <name>

=head2 get_invoice [<year> <month>]

Return a Net::Fastly::Invoice objects representing an invoice for all services.

If a year and month are passed in returns the invoice for that whole month. 

Otherwise it returns the invoices for the current month to date.

=head2 get_match <service id> <version number> <name>

=head2 get_origin <service id> <version number> <name>

=head2 get_syslog <service id> <version number> <name>

=head2 get_vcl <service id> <version number> <name>

=head2 get_version <service id> <version number> <name>

=head2 get_settings <service id> <version number>

=head2 get_condition <service id> <version number> <name>

Get existing objects.


=head2 update_user <obj>

=head2 update_customer <obj>

=head2 update_service <obj>

=head2 update_version <obj>

=head2 update_backend <obj>

=head2 update_director <obj>

=head2 update_domain <obj>

=head2 update_healthcheck <obj>

=head2 update_match <obj>

=head2 update_origin <obj>

=head2 update_syslog <obj>

=head2 update_vcl <obj>

=head2 update_version <obj>

=head2 update_settings <obj>

=head2 update_condition <obj>

Update existing objects.

Note - you can also do



=head2 delete_user <obj> 

=head2 delete_customer <obj>

=head2 delete_service <obj>

=head2 delete_version <obj>

=head2 delete_backend <obj>

=head2 delete_director <obj>

=head2 delete_domain <obj>

=head2 delete_healthcheck <obj>

=head2 delete_match <obj>

=head2 delete_origin <obj>

=head2 delete_syslog <obj>

=head2 delete_vcl <obj>

=head2 delete_version <obj>

=head2 delete_condition <obj>

Delete existing objects.

Note - you can also do



=head2 list_users

=head2 list_customers 

=head2 list_versions

=head2 list_services 

=head2 list_backends 

=head2 list_directors 

=head2 list_domains 

=head2 list_healthchecks

=head2 list_matchs 

=head2 list_origins 

=head2 list_syslogs

=head2 list_vcls 

=head2 list_versions 

=head2 list_conditions

Get a list of all objects

=head2 search_services <param[s]>

Search all the services that the current customer has.

In general you'll want to do

        my @services = $fastly->search_services(name => $name);


        my ($service) = $fastly->search_services(name => $name, version => $number);


use Carp;
sub _list {
    my $self     = shift;
    my $class    = shift;
    my %opts     = @_;
    my $list     = $self->client->_get($class->_list_path(%opts), %opts);
    return () unless $list;
    return map { $class->new($self, %$_) } @$list;

sub _get {
    my $self  = shift;
    my $class = shift;
    my $hash;
    if (@_) {
        $hash = $self->client->_get($class->_get_path(@_));
    } else {
        $hash = $self->client->_get("/current_".$class->_path);
    return undef unless $hash;
    return $class->new($self, %$hash);

sub _create {
    my $self  = shift;
    my $class = shift;
    my %args  = @_;
    my $hash  = $self->client->_post($class->_post_path(%args), %args);
    return $class->new($self, %$hash);

sub _update {
    my $self  = shift;
    my $class = shift;
    my $obj   = shift;
    my %fds   = $obj->_as_hash;
    my $hash  = $self->client->_put($class->_put_path($obj), map { $_ => $fds{$_} } grep { $_ !~ m/^(service_id|version)$/ } keys %fds);
    return $class->new($self, %$hash);

sub _delete {
    my $self  = shift;
    my $class = shift;
    my $obj   = shift;
    $obj      = bless $obj, $class if 'HASH' eq ref($obj);
    return defined $self->client->_delete($class->_delete_path($obj));


=head2 load_options <file>

Attempts to load various config options in the form

   <key> = <value>
From a file.

Skips whitespace and lines starting with C<#>.


sub load_options {
    my $file    = shift;
    my %options = ();
    return %options unless -f $file;

    open(my $fh, $file) || die "Couldn't open $file: $!\n";
    while (<$fh>) {
        next if /^#/;
        next if /^\s*$/;
        next unless /=/;
        my ($key, $val) = split /\s*=\s*/, $_, 2;
        $options{$key} = $val;
    return %options;

=head2 get_options <file[s]>

Tries to load options from the file[s] passed in using, 
C<load_options>, stopping when it finds the first one.

Then it overrides those options with command line options 
of the form


sub get_options {
    my @configs = @_;
    my %options;
    foreach my $config (@configs) {
        next unless -f $config;
        %options = load_options($config);
    while (@ARGV && $ARGV[0] =~ m!^-+(\w+)\=(.+)$!) {
        if ($1 eq "config") {
            die "No such file '$2'" unless -f $2;
            my %tmp = load_options($2);
            $options{$_} = $tmp{$_} for keys %tmp;
        } else {
            $options{$1} = $2;
        shift @ARGV;
    die "Couldn't find options from command line arguments or ".join(", ", @configs)."\n" unless keys %options;
    return %options;


Copyright 2011 - Fastly Inc

Distributed under the same terms as Perl itself.

=head1 SUPPORT 

Mail support at fastly dot com if you have problems.