NAME

Centrifugo::Client

SYNOPSIS

 use Centrifugo::Client;
 use AnyEvent;

 my $cclient = Centrifugo::Client->new("$CENTRIFUGO_WS/connection/websocket");

 $cclient -> on('connect', sub{
		my ($infoRef)=@_;
		print "Connected to Centrifugo version ".$infoRef->{version};
		
		# When connected, client_id() is defined, so we can subscribe to our private channel
		$cclient->subscribe( '&'.$cclient->client_id() );
		
	}) -> on('message', sub{
		my ($infoRef)=@_;
		print "MESSAGE: ".encode_json $infoRef->{data};

	}) -> connect(
		user => $USER_ID,
		timestamp => $TIMESTAMP,
		token => $TOKEN
	);

 # Now start the event loop to keep the program alive
 AnyEvent->condvar->recv;
	

DESCRIPTION

This library allows to communicate with Centrifugo through a websocket.

FUNCTION new

my $client = Centrifugo::Client->new( $URL );

or

my $client = Centrifugo::Client->new( $URL,
   debug => 'true',          # If true, some informations are written on STDERR
   authEndpoint => "...",    # The full URL used to ask for a key to subscribe to private channels
   max_alive_period => 30,   # If max_alive_period has passed since last communication with server, a PING is send (default 0)
   refresh_period => 5,      # Check frequency for max_alive_period (default 10s)
   ws_params => {            # These parameters are passed to AnyEvent::WebSocket::Client->new(...)
		 ssl_no_verify => 'true',
		 timeout => 600
	  },
   );

FUNCTION connect - send authorization parameters to Centrifugo so your connection could start subscribing on channels.

$client->connect( user => $USER_ID, timestamp => $TIMESTAMP, token => $TOKEN, [info => $info,] [uid => $uid,] );

(this function retuns $self to allow chains of multiple function calls)

It is possible to provide a UID for this command, but if you don't, a random one will be generated for you, but cannot be retrieved afterward.

FUNCTION publish - allows clients directly publish messages into channel (use with caution. Client->Server communication is NOT the aim of Centrifugo)

$client->publish( channel=>$channel, data=>$data, [uid => $uid] );

$data must be a HASHREF to a structure (which will be encoded to JSON), for example :

    $client->public ( channel => "public", 
		data => {
			nick => "Anonymous",
			text => "My message",
	    } );

or even :

$client->public ( channel => "public", data => { } ); # Sends an empty message to the "public" channel

This function returns the UID used to send the command to the server. (a random string if none is provided)

FUNCTION disconnect

$client->disconnect();

FUNCTION subscribe - allows to subscribe on channel after client successfully connected.

$client->subscribe( channel => $channel, [ client => $clientId ,] [ uid => $uid ,] );

If the channel is private (starts with a '$'), then a request to $this->{AUTH_URL} is done automatically to get the channel key. In that case, the 'client' parameter is mandatory.

This function returns the UID used to send the command to the server. (a random string if none is provided)

FUNCTION unsubscribe - allows to unsubscribe from channel.

$client->unsubscribe( channel => $channel, [ uid => $uid ] );

This function returns the UID used to send the command to the server. (a random string if none is provided)

FUNCTION presence - allows to ask server for channel presence information.

$client->presence( channel => $channel, [ uid => $uid ] );

This function returns the UID used to send the command to the server. (a random string if none is provided)

FUNCTION history - allows to ask server for channel presence information.

$client->history( channel => $channel, [ uid => $uid ] );

This function returns the UID used to send the command to the server. (a random string if none is provided)

FUNCTION ping - allows to send ping command to server, server will answer this command with ping response.

$client->ping( [ uid => $uid ] );

This function returns the UID used to send the command to the server. (a random string if none is provided)

FUNCTION on - Register a callback for the given event.

Known events are 'message', 'connect', 'disconnect', 'subscribe', 'unsubscribe', 'publish', 'presence', 'history', 'join', 'leave', 'refresh', 'ping', 'ws_closed', 'ws_error'

$client->on( 'connect', sub { my( $dataRef ) = @_; ... });

(this function retuns $self to allow chains of multiple function calls)

Note : Events that are an answer to the client requests (ie 'connect', 'publish', ...) have an 'uid' which is added into the %data structure.

FUNCTION client_id - return the client_id if it is connected to Centrifugo and the server returned this ID (which is not the case on the demo server).

$client->client_id()

FUNCTION generate_token - return the private token that must be used to connect a client to Centrifugo.

$key = Centrifugo::Client::generate_token($secret, $user, $timestamp [,$info])

INPUT : $secret is the private secret key, only known by the server.

$user is the user name.

$timestamp is the current timestamp.

$info is a JSON encoded string.

The same function may be used to generate a private channel key :

$key = generate_token($secret, $client, $channel [,$info])

INPUT : $client is the client_id given when connected to Centrifugo.

$channel is the name of the channel (should start with a '$' as it is private).

And to sign each request to access to the HTTP API :

$sign = generate_token($self, $data)

INPUT : $data is a JSON string with your API commands

cpanm Centrifugo::Client

perl -MCPAN -e shell
install Centrifugo::Client