Bump version and update Changes

[webservice-scaleway.git] / lib / WebService / Scaleway.pm

package WebService::Scaleway;

use 5.014000;
use strict;
use warnings;

our $VERSION = '0.001001';

use Carp qw/croak/;
use HTTP::Tiny;
use JSON::MaybeXS;
use Scalar::Util qw/blessed/;

my $ht = HTTP::Tiny->new(
	agent      => "WebService-Scaleway/$VERSION ",
	verify_SSL => 1,
);

# Instance of WebService::Scaleway with no API key
# Used to create tokens from email/password
my $dummy = '';
$dummy = bless \$dummy, __PACKAGE__;

sub _account ($) { "https://account.scaleway.com$_[0]"}
sub _api     ($) { "https://api.scaleway.com$_[0]" }

sub _request {
	my ($self, $method, $url, $opts) = @_;
	$opts->{headers} //= {};
	$opts->{headers}{'X-Auth-Token'} = $$self if $$self;
	$opts->{headers}{'Content-Type'} = 'application/json';
	my $ret = $ht->request($method, $url, $opts);
	die 'Request to Scaleway API server was unsuccessful: ' . $ret->{status} . ' ' . $ret->{reason} . '; ' . $ret->{content} unless $ret->{success};

	decode_json $ret->{content} if $ret->{status} != 204;
}

sub _get    { shift->_request(GET    => @_) }
sub _post   { shift->_request(POST   => @_) }
sub _patch  { shift->_request(PATCH  => @_) }
sub _put    { shift->_request(PUT    => @_) }
sub _delete { shift->_request(DELETE => @_) }

sub _tores {
	my @ret = map { bless $_, 'WebService::Scaleway::Resource' } @_;
	wantarray ? @ret : $ret[0]
}

sub new {
	my ($class, $token) = @_;
	$token = $dummy->create_token(@_[1..$#_])->id if @_ > 2;

	bless \$token, $class
}

BEGIN {
	my @account_res = qw/token organization user/;
	my @api_res = qw/server volume snapshot image ip security_group/;

	my %res = (
		map ({ $_ => _account "/${_}s" } @account_res),
		map  { $_ => _api     "/${_}s" } @api_res);

	my %create_parms = (
		token          => [qw/email password expires/],
		server         => [qw/name organization image volumes tags/],
		volume         => [qw/name organization volume_type size/],
		snapshot       => [qw/name organization volume_id/],
		image          => [qw/name organization root_volume arch/],
		ip             => [qw/     organization/],
		security_group => [qw/name organization description/],
	);

	sub dynsub {
		no strict 'refs';
		my $sub = pop;
		*$_ = $sub for @_
	}

	for my $res (keys %res) {
		dynsub $res, "get_$res", sub {
			local *__ANON__ = $res;
			_tores shift->_get("$res{$res}/$_[0]")->{$res}
		};

		dynsub $res.'s', "list_$res".'s', sub {
			local *__ANON__ = $res.'s';
			my @ret = _tores @{shift->_get($res{$res})->{$res.'s'}};
			wantarray ? @ret : $ret[0]
		};

		dynsub "delete_$res", sub {
			local *__ANON__ = "delete_$res";
			shift->_delete("$res{$res}/$_[0]")
		};

		dynsub "create_$res", sub {
			local *__ANON__ = "create_$res";
			my $self = shift;
			my $content = $_[0];
			if (blessed $content || ref $content ne 'HASH') {
				croak "create_$res does not understand positional parameters, pass a hashref instead\n" unless $create_parms{$res};
				my @parms = @{$create_parms{$res}};
				$content = { map {
					$parms[$_] => (blessed $_[$_] ? $_[$_]->id : $_[$_]) } 0 .. $#_ };
			}
			_tores $self->_post($res{$res},        { content => encode_json $content })->{$res}
		};

		dynsub "update_$res", sub {
			local *__ANON__ = "update_$res";
			my $data = blessed $_[1] ? {%{$_[1]}} : $_[1];
			shift->_put("$res{$res}/".$data->{id}, { content => encode_json $data })
		};
	}
}

sub security_group_rule {
	_tores shift->_get(_api "/security_groups/$_[0]/rules/$_[1]")->{rule}
}

sub security_group_rules {
	_tores @{shift->_get(_api "/security_groups/$_[0]/rules")->{rules}}
}

BEGIN {
	*get_security_group_rule  = \&security_group_rule;
	*list_security_group_rule = \&security_group_rules;
}

sub delete_security_group_rule {
	shift->_delete(_api "/security_groups/$_[0]/rules/$_[1]")
}

sub create_security_group_rule {
	my $self = shift;
	my $grp = shift;
	my $content = $_[0];
	unless (ref $content eq 'HASH') {
		my @parms = qw/organization action direction ip_range protocol dest_port_from/;
		$content = { map { $parms[$_] => $_[$_] } 0 .. $#_ };
	}
	$self->_post(_api "/security_groups/$grp/rules",        { content => encode_json $content })
}

sub update_security_group_rule {
	my $data = blessed $_[2] ? {%{$_[2]}} : $_[2];
	shift->_put (_api "/security_groups/$_[0]/rules/".$data->{id}, { content => encode_json $data })
}

sub server_actions {
	@{shift->_get(_api "/servers/$_[0]/action")->{actions}}
}

BEGIN { *list_server_actions = \&server_actions }

sub perform_server_action {
	my $content = encode_json { action => $_[2] };
	_tores shift->_post(_api "/servers/$_[0]/action", { content => $content })->{task};
}

sub refresh_token {
	_tores shift->_patch(_account "/tokens/$_[0]")->{token}
}

sub server_metadata {
	_tores $dummy->_get('http://169.254.42.42/conf?format=json')
}

package # hide from PAUSE
  WebService::Scaleway::Resource;

use overload '""' => sub { shift->id };

our $AUTOLOAD;
sub AUTOLOAD {
	my ($self) = @_;
	my ($attr) = $AUTOLOAD =~ m/::([^:]*)$/s;
	die "No such attribute: $attr" unless exists $self->{$attr};
	$self->{$attr}
}

sub can {
	my ($self, $sub) = @_;
	exists $self->{$sub} ? sub { shift->{$sub} } : undef
}

sub DESTROY {} # Don't call AUTOLOAD on destruction

1;
__END__

=encoding utf-8

=head1 NAME

WebService::Scaleway - Perl interface to Scaleway cloud server provider API

=head1 SYNOPSIS

  use WebService::Scaleway;
  my $token = ...; # API token here
  my $sw = WebService::Scaleway->new($token);
  my $org = $sw->organizations;

  # Create an IP, a volume, and use them for a new Debian Jessie server
  my $ip = $sw->create_ip($org);
  my $vol = $sw->create_volume('testvol', $org, 'l_ssd', 50_000_000_000);
  my ($debian) = grep { $_->name =~ /debian jessie/i } $sw->images;
  my $srv = $sw->create_server('testsrv', $org, $debian, {1 => $vol->id});

  # Now we have a server, an IP, and two volumes (the root volume with
  # Debian Jessie, and the extra volume we just created).

  # Change the server name
  $srv->{name} = 'Debian';
  $sw->update_server($srv);

  # Boot the server
  $sw->perform_server_action($srv, 'poweron');
  say "The server is now booting. To access it, do ssh root@", $ip->address;

=head1 DESCRIPTION

Scaleway is an IaaS provider that offers bare metal ARM cloud servers.
WebService::Scaleway is a Perl interface to the Scaleway API.

=head2 Constructors

WebService::Scaleway objects are defined by their authentication
token. There are two consructors:

=over

=item WebService::Scaleway->B<new>(I<$auth_token>)

Construct a WebService::Scaleway object from a given authentication
token.

=item WebService::Scaleway->B<new>(I<$email>, I<$password>)

Construct a WebService::Scaleway object from an authentication token
obtained by logging in with the given credentials.

=back

=head2 Listing resources

These methods return a list of all resources of a given type
associated to your account. Each resource is a blessed hashref with
C<AUTOLOAD>ed accessors (for example C<< $resource->{name} >> can be
written as C<< $resource->name >>) and that stringifies to the ID of
the resource: C<< $resource->id >>.

There is no difference between B<resources>() and
B<list_resources>().

=over

=item $self->B<tokens>

=item $self->B<list_tokens>

Official documentation: L<https://developer.scaleway.com/#tokens-tokens-get>.

=item $self->B<organizations>

=item $self->B<list_organizations>

Official documentation: L<https://developer.scaleway.com/#organizations-organizations>.

=item $self->B<servers>

=item $self->B<list_servers>

Official documentation: L<https://developer.scaleway.com/#servers-servers-get>.

=item $self->B<volumes>

=item $self->B<list_volumes>

Official documentation: L<https://developer.scaleway.com/#volumes-volumes-get>.

=item $self->B<snapshots>

=item $self->B<list_snapshots>

Official documentation: L<https://developer.scaleway.com/#snapshots-snapshots-get>.

=item $self->B<images>

=item $self->B<list_images>

Official documentation: L<https://developer.scaleway.com/#images-images-get>.

=item $self->B<ips>

=item $self->B<list_ips>

Official documentation: L<https://developer.scaleway.com/#ips-ips-get>.

=item $self->B<security_groups>

=item $self->B<list_security_groups>

Official documentation: L<https://developer.scaleway.com/#security-groups-security-groups-get>.

=item $self->B<security_group_rules>(I<$group_id>)

=item $self->B<list_security_group_rules>(I<$group_id>)

Official documentation: L<https://developer.scaleway.com/#security-groups-manage-rules-get>.

=back

=head2 Retrieving resources

These methods take the ID of a resource and return the resource as a
blessed hashref as described in the previous section.

You can pass a blessed hashref instead of a resource ID, and you'll
get a fresh version of the object passed. Useful if something updated
the object in the meantime.

There is no difference between B<resource>(I<$id>) and
B<get_resource>(I<$id>).

=over

=item $self->B<token>(I<$id>)

=item $self->B<get_token>(I<$id>)

Official documentation: L<https://developer.scaleway.com/#tokens-token-get>.

=item $self->B<user>(I<$id>)

=item $self->B<get_user>(I<$id>)

Official documentation: L<https://developer.scaleway.com/#users-user>.

=item $self->B<server>(I<$id>)

=item $self->B<get_server>(I<$id>)

Official documentation: L<https://developer.scaleway.com/#servers-server-get>.

=item $self->B<volume>(I<$id>)

=item $self->B<get_volume>(I<$id>)

Official documentation: L<https://developer.scaleway.com/#volumes-volume-get>.

=item $self->B<snapshot>(I<$id>)

=item $self->B<get_snapshot>(I<$id>)

Official documentation: L<https://developer.scaleway.com/#snapshots-snapshot-get>.

=item $self->B<image>(I<$id>)

=item $self->B<get_image>(I<$id>)

Official documentation: L<https://developer.scaleway.com/#images-operation-on-a-single-image-get>.

=item $self->B<ip>(I<$id>)

=item $self->B<get_ip>(I<$id>)

Official documentation: L<https://developer.scaleway.com/#ips-ip-get>.

=item $self->B<security_group>(I<$id>)

=item $self->B<get_security_group>(I<$id>)

Official documentation: L<https://developer.scaleway.com/#security-groups-operation-on-a-security-groups-get>.

=item $self->B<security_group_rule>(I<$group_id>, I<$rule_id>)

=item $self->B<get_security_group_rule>(I<$group_id>, I<$rule_id>)

Official documentation: L<https://developer.scaleway.com/#security-groups-operation-on-a-security-rule-get>.

=back

=head2 Deleting resources

These methods take the ID of a resource and delete it. They do not
return anything. You can pass a blessed hashref instead of a resource
ID.

=over

=item $self->B<delete_token>(I<$id>)

Official documentation: L<https://developer.scaleway.com/#tokens-token-delete>.

=item $self->B<delete_server>(I<$id>)

Official documentation: L<https://developer.scaleway.com/#servers-server-delete>.

=item $self->B<delete_volume>(I<$id>)

Official documentation: L<https://developer.scaleway.com/#volumes-volume-delete>.

=item $self->B<delete_snapshot>(I<$id>)

Official documentation: L<https://developer.scaleway.com/#snapshots-snapshot-delete>.

=item $self->B<delete_image>(I<$id>)

Official documentation: L<https://developer.scaleway.com/#images-operation-on-a-single-image-delete>.

=item $self->B<delete_ip>(I<$id>)

Official documentation: L<https://developer.scaleway.com/#ips-ip-delete>.

=item $self->B<delete_security_group>(I<$id>)

Official documentation: L<https://developer.scaleway.com/#security-groups-operation-on-a-security-groups-delete>.

=item $self->B<delete_security_group_rule>(I<$group_id>, I<$rule_id>)

Official documentation: L<https://developer.scaleway.com/#security-groups-operation-on-a-security-rule-delete>.

=back

=head2 Modifying resources

These methods take a hashref representing a resource that already
exists and update it. The value of C<< $resource->{id} >> is used for
identifying this resource on the remote end. Both blessed and
unblessed hashrefs are accepted. The updated resource is returned as a
blessed hashref as described in L</"Listing resources">.

=over

=item $self->B<update_server>(I<$resource>)

Official documentation: L<https://developer.scaleway.com/#servers-server-put>.

=item $self->B<update_snapshot>(I<$resource>)

Official documentation: L<https://developer.scaleway.com/#snapshots-snapshot-put>.

=item $self->B<update_image>(I<$resource>)

Official documentation: L<https://developer.scaleway.com/#images-operation-on-a-single-image-put>.

=item $self->B<update_ip>(I<$resource>)

Official documentation: L<https://developer.scaleway.com/#ips-ip-put>.

=item $self->B<update_security_group>(I<$resource>)

Official documentation: L<https://developer.scaleway.com/#security-groups-operation-on-a-security-groups-put>.

=item $self->B<update_security_group_rule>(I<$group_id>, I<$resource>)

Official documentation: L<https://developer.scaleway.com/#security-groups-operation-on-a-security-rule-put>.

=back

=head2 Creating resources

These methods take either a hash that is passed directly to the API or
a method-specific list of positional parameters. They create a new
resource and return it as a blessed hashref as described in
L</"Listing resources">.

When using positional parameters, you can pass a resource in blessed
hashref format where a resource ID is expected, unless the method's
documentation says otherwise.

Most of these methods require an organization ID. You can obtain it
with the B<organizations> method described above.

=over

=item $self->B<create_token>(I<\%data>)

=item $self->B<create_token>(I<$email>, I<$password>, [I<$expires>])

Authenticates a user against their username and password and returns
an authentication token. If I<$expires> (default: false) is true, the
token will expire.

This method is called internally by the two-argument constructor.

Official documentation: L<https://developer.scaleway.com/#tokens-tokens-get>.

=item $self->B<create_server>(I<\%data>)

=item $self->B<create_server>(I<$name>, I<$organization>, I<$image>, I<$volumes>, [I<$tags>])

Creates and returns a new server.

I<$name> is the server name. I<$organization> is the organization ID.
I<$image> is the image ID. I<$volumes> is a "sparse array" (hashref
from indexes to volume IDs, indexed from 1) of B<extra> volumes (that
is, volumes other than the root volume). I<$tags> is an optional
arrayref of tags.

For the I<$volumes> parameter you can pass hashrefs that describe
volumes instead of volume IDs. This will create new volumes. The
hashrefs are (presumably) passed to B<create_volume>. An example
inspired by the official documentation:

  $volumes = { 1 => {
    name         => "vol_demo",
    organization => "ecc1c86a-eabb-43a7-9c0a-77e371753c0a",
    size         => 10_000_000_000,
    volume_type  => "l_sdd",
  }};

Note that there B<may not> be any blessed hashrefs inside I<$volumes>.

Official documentation: L<https://developer.scaleway.com/#servers-servers-get>.

=item $self->B<create_volume>(I<\%data>)

=item $self->B<create_volume>(I<$name>, I<$organization>, I<$volume_type>, I<$size>)

Creates and returns a new volume. I<$volume_type> currently must be
C<l_ssd>. I<$size> is the size in bytes.

Official documentation: L<https://developer.scaleway.com/#volumes-volumes-get>.

=item $self->B<create_snapshot>(I<\%data>)

=item $self->B<create_snapshot>(I<$name>, I<$organization>, I<$volume_id>)

Creates and returns a snapshot of the volume I<$volume_id>.

Official documentation: L<https://developer.scaleway.com/#snapshots-snapshots-get>.

=item $self->B<create_image>(I<\%data>)

=item $self->B<create_image>(I<$name>, I<$organization>, I<$root_volume>, I<$arch>)

Creates and returns an image from the volume I<$root_volume>. I<$arch>
is the architecture of the image (currently must be C<"arm">).

Official documentation: L<https://developer.scaleway.com/#images-images-get>.

=item $self->B<create_ip>(I<\%data>)

=item $self->B<create_ip>(I<$organization>)

Official documentation: L<https://developer.scaleway.com/#ips-ips-get>.

=item $self->B<create_security_group>(I<\%data>)

=item $self->B<create_security_group>(I<$name>, I<$organization>, I<$description>)

Official documentation: L<https://developer.scaleway.com/#security-groups-security-groups-get>.

=item $self->B<create_security_group_rule>(I<$group_id>)

=item $self->B<create_security_group_rule>(I<$group_id>, I<$organization>, I<$action>, I<$direction>, I<$ip_range>, I<$protocol>, [<$dest_port_from>])


Official documentation: L<https://developer.scaleway.com/#security-groups-manage-rules-get>.

=back

=head2 Miscellaneous methods

These are methods that don't fit any previous category. Any use of
"blessed hashref" refers to the concept described in L</"Listing
resources">. Wherever a resource ID is expected, you can instead pass
a resource as a blessed hashref and the method will call C<< ->id >>
on it for you.

=over

=item $self->B<server_actions>(I<$server_id>)

=item $self->B<list_server_actions>(I<$server_id>)

Returns a list of strings representing possible actions you can
perform on the given server. Example actions are powering on/off a
server or rebooting it.

Official documentation: L<https://developer.scaleway.com/#servers-actions-get>

=item $self->B<perform_server_action>(I<$server_id>, I<$action>)

Performs an action on a server. I<$action> is one of the strings
returned by B<server_actions>. The function returns a blessed hashref
with information about the task.

This is not very useful, as this module does not currently offer any
function for tracking tasks.

Official documentation: L<https://developer.scaleway.com/#servers-actions-post>

=item $self->B<refresh_token>(I<$token_id>)

This method takes the ID of an expirable token, extends its expiration
date by 30 minutes, and returns the new token as a blessed hashref.

Official documentation: L<https://developer.scaleway.com/#tokens-token-patch>

=item $self->B<server_metadata>

This method can only be called from a Scaleway server. It returns
information about the server as a blessed hashref.

Official documentation: L<https://developer.scaleway.com/#metadata-c1-server-metadata>

=back

=head1 SEE ALSO

L<https://developer.scaleway.com/>

=head1 AUTHOR

Marius Gavrilescu, E<lt>marius@ieval.roE<gt>

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2015 by Marius Gavrilescu

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.20.2 or,
at your option, any later version of Perl 5 you may have available.


=cut