NAME

Net::Thumper - a rudimentary Pure Perl AMQP client

SYNOPSIS

 my $amqp = Net::Thumper->new(
    debug => 0,
    server => 'rabbitmq-host',
    amqp_definition => 'amqp0-8.xml',
 );

 # Connect
 $amqp->connect();
 $amqp->open_channel();
 $amqp->declare_queue('foo');

 # Publish
 $amqp->publish('', 'foo', $payload, {}, { reply_to => 'foo', correlation_id => '1' });

 # Get
 my $msg = $amqp->get('foo');

 # Consume
 my $consumer_tag = $amqp->consume('foo');
 my $msg = $amqp->get('foo');
 $amqp->cancel($consumer_tag);

 # Disconnect
 $amqp->disconnect();
 

DESCRIPTION

This class is a rudimentary AMQP client written in Pure Perl. It has been tested with recent versions of RabbitMQ.

There are a few limitations:

* No concept of 'channels' is exposed, so only one logical channel is possible

* Some parts of the AMQP spec not exposed

* API isn't the cleanest is some places - could be tidied up

While this module mostly works for my purpose, it might be restrictive in some places. Still, the fundamentals are reasonably solid (the low-level communication) so it could probably be fairly easily modified for other purposes.

Patches welcome :)

CONSTRUCTOR

new(debug => $bool, server => $host, port => $port, amqp_definition => $path_to_amqp_xml, debug_hook => \&_debug_hook)

Creates a new Net::Thumper instance. Parameters are:

* server (required) - the server to connect to

* port - server port, defaults to 5672

* amqp_definition (required) - path to the AMQP XML definition (as available from the amqp.org website)

* debug - boolean to indicate whether debugging information should be output. Defaults to false

* debug_hook - optional subroutine reference to call when outputting debug info. If not supplied, output will go to STDERR

METHODS

connect( login => 'login', password => 'password' )

Connects to the server. Additionally sends all handshake frames necessary to start a connection.

Accepts two optional parameters, 'login' and 'password', which both default to 'guest'.

open_channel()

Open a channel. This is hard-coded to channel 1.

declare_queue($queue, %params)

Declare a queue. The optional %params contains options for the queue declaration.

bind_queue($queue, $exchange, $routing_key, %params)

Bind a queue to an exchange using the routing key. The optional %params contains options for the bind

declare_exchange($exchange, $type, %params)

Declare an exchange

publish($exchange, $routing_key, $body, $params, $props)

Publish a message via $exchange with $routing_key. Message contents are passed in $body. $params is a hashref of args to the publish request (such as the mandatory and immediate flags), $props is a hashref of header parameters (such as correlation_id and reply_to)

get($queue, %params)

Get a message from $queue. Return a hashref with the message details, or undef if there is no message. This is essentially a poll of a given queue. %params is an optional hash containing parameters to the Get request.

The message returned in a hashref with the following keys:

* body - the body of the message

* reply_to - the reply_to header of the message

* correlation_id - the correlation_id of the message

* delivery_tag - used in acking messages.

consume($queue, %params)

Indicate that a given queue should be consumed from. %params contains params to be passed to the Consume request.

Returns the consumer tag. Once the client is consuming from a queue, receive() can be called to get any messages.

receive($timeout)

Receive a message from a queue that has previously been consumed from. Wait for up to $timeout seconds before giving up and returning undef.

The message returned is of the same format as that returned from get()

cancel($consumer_tag, %params)

Cancel consuming a queue. $consumer_tag is the tag returned from the original consume() request.

disconnect()

Disconnect from the server.

is_connected()

Return true if we appear to be connected to the server. This just checks that the TCP socket appears to be connected, so the application may actually have disconnected.

THE FUTURE

When I get a chance, I'd like to tidy up the API, improve the tests and split some of the logic into different modules. Could also look at a lighter weight alternative to Moose.

Patches are - of course - welcome.

AUTHORS

Created by Sam Crawley

Contributions by DanC (dconlon)

LICENCE

Development commissioned by NZ Registry Services, and carried out by Catalyst IT - http://www.catalyst.net.nz/

Copyright 2012 NZ Registry Services. This module is licensed under the Artistic License v2.0, which permits relicensing under other Free Software licenses.

cpanm Net::Thumper

perl -MCPAN -e shell
install Net::Thumper