The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
WebService-Zaqar-0.010
River stage zero No dependents
++
/ WebService::Zaqar

NAME

WebService::Zaqar -- Wrapper around the Zaqar (aka Marconi) message queue API

SYNOPSIS

  use WebService::Zaqar;
  my $client = WebService::Zaqar->new(
      # base_url => 'https://dfw.queues.api.rackspacecloud.com/',
      base_url => 'http://localhost:8888',
      spore_description_file => 'share/marconi.spore.json');
  
  # for Rackspace only
  my $token = $client->rackspace_authenticate('https://identity.api.rackspacecloud.com/v2.0/tokens',
                                              $rackspace_account,
                                              $rackspace_key);
  
  $client->create_queue(queue_name => 'pets');
  $client->post_messages(queue_name => 'pets',
                         payload => [
                             { ttl => 120,
                               body => [ 'pony', 'horse', 'warhorse' ] },
                             { ttl => 120,
                               body => [ 'little dog', 'dog', 'large dog' ] } ]);
  $client->post_messages(queue_name => 'pets',
                         payload => [
                             { ttl => 120,
                               body => [ 'aleax', 'archon', 'ki-rin' ] } ]);

DESCRIPTION

This library is a Net::HTTP::Spore-based client for the message queue component of OpenStack, Zaqar (previously known as "Marconi").

On top of allowing you to make requests to a Zaqar endpoint, this library also supports Rackspace authentication using their Cloud Identity token system; see do_request.

ATTRIBUTES

base_url

(read-only string)

The base URL for all API queries, except for the Rackspace-specific authentication.

client_uuid

(read-only string, defaults to a new UUID)

All API queries should contain a "Client-ID" header (in practice, some appear to work without this header). If you do not provide a value, a new one will be built with Data::UUID.

The docs recommend reusing the same client UUID between restarts of the client.

rackspace_api_key

(read-only optional string)

API key for Rackspace authentication endpoints.

rackspace_keystone_endpoint

(read-only optional string)

URL for Rackspace authentication endpoints.

rackspace_username

(read-only optional string)

Your Rackspace API username.

spore_client

(read-only object)

This is the Net::HTTP::Spore client build with the spore_description_file attribute. All API method calls will be delegated to this object.

spore_description_file

(read-only required file path or URL)

Path to the SPORE specification file or remote resource.

A spec file for Zaqar v1.0 is provided in the distribution (see share/marconi.spec.json).

token

(read-only string with default predicate)

The token is automatically set when calling rackspace_authenticate successfully. Once set, it will be sent in the "X-Auth-Token" header with each query.

Rackspace invalidates the token after 24h, at which point all the queries will start returning "401 Unauthorized". Consider using do_request to manage this for you.

wants_auth

(read-only boolean, defaults to false)

If this attribute is set to true, you are indicating that the endpoint needs authentication. This means that when a request wrapped with do_request fails with "401 Unauthorized", the client will try (re-)authenticating with rackspace_authenticate, using the values in rackspace_keystone_endpoint, rackspace_username and rackspace_api_key.

METHODS

DELEGATED METHODS

All methods listed in the API docs are implemented by the SPORE client. When a body is required, you must provide it via the payload parameter.

See the share/marconi.spore.json file for the list of methods and their parameters.

All those methods can be called with an instance of WebService::Zaqar as invocant; they will be delegated to the SPORE client.

Unlike "regular" SPORE-based clients, you may use the special __url__ parameter to provide an already-built URL directly. This is helpful when trying to follow links provided by the API itself. E.g. when you make a claim on a queue, the server does not return the claim and message IDs; instead it returns URLs to the claim and messages, which you are then supposed to call if you want to release or update the claim, delete a message, etc.

  my $response = $client->claim_messages(queue_name => 'potato');
  my $claim_href = $response->header('Location');
  $client->release_claim(__url__ => $claim_href);

do_request

  my $response = $client->do_request(sub { $client->list_queues(limit => 20) },
                                     { retries => 2 },
                                     @etc);

This method can be used to manage token generation. The first argument should be a coderef; it will be executing within a try { } statement. If the coderef throws a blessed exception of class Net::HTTP::Spore::Response (or a subclass thereof), that response's status is "401 Unauthorized", and wants_auth was set to a true value, rackspace_authenticate will be called and the coderef will be retried.

If the exception has another status code, it will be rethrown as-is, without retrying. This generally leads to a somewhat cryptic "HTTP response: 403" exception, since Net::HTTP::Spore::Response objects stringify to their status code. If the status code was 599 (internal exception), the response's error message will be thrown instead.

If the exception is not a Net::HTTP::Spore::Response instance at all, it will be rethrown directly.

Otherwise, the coderef's return value is returned.

The second argument is a hashref of options. Currently only "retries" is implemented:

if "retries" is undefined or not provided, do_request will retry indefinitely until successful
if "retries" is 0, do_request will not retry
if "retries" is any other integer, do_request will retry up to that many times.

The coderef will be called with the original invocant of do_request and the rest of the arguments of do_request as parameters.

rackspace_authenticate

  my $token = $client->rackspace_authenticate('https://identity.api.rackspacecloud.com/v2.0/tokens',
                                              $rackspace_account,
                                              $rackspace_key);

Sends an HTTP request to a Cloud Identity endpoint (or compatible) and sets the token received.

See also "token".

SPORE MIDDLEWARES ENABLED

The following modifications are applied to requests before they are made, in order:

serializing the body to JSON
setting the X-Auth-Token header to the authentication token, if available
setting the Date header to the current date in RFC 1123 format
setting the Client-ID header to the value of the client_uuid attribute
if the __url__ parameter is provided to the method call, replace the request path and querystring params with its value

The following modifications are applied to responses before they are returned, in order:

deserializing the body from JSON, except for 401 and 403 responses, which are likely to come from Keystone instead and are plain text.

SEE ALSO

Net::HTTP::Spore

AUTHOR

Fabrice Gabolde <fgabolde@weborama.com>

COPYRIGHT AND LICENSE

Copyright (C) 2014 Weborama

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.