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};           
        }) -> on('message', sub{
                my ($infoRef)=@_;
                print "MESSAGE: ".encode_json $infoRef->{data};

        }) -> connect(
                user => $USER_ID,
                timestamp => $TIMESTAMP,
                token => $TOKEN
        );
        
 $cclient->subscribe( channel => 'my-channel&' );
 $cclient->subscribe( channel => 'public-channel' );
 $cclient->subscribe( channel => '$private' );

 # 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
           debug_ws => 'true',       # If true, all web socket messages are written on STDERR
           authEndpoint => "...",    # The full URL used to ask for a key to subscribe to private channels
           max_alive_period => 30,   # interval (in s) since last communication with server that triggers a PING (default 0)
           refresh_period => 5,      # Check frequency for max_alive_period (default 10s)
           retry => 0.5 ,            # interval (in ms) between reconnect attempts which value grows exponentially (default 1.0)
           max_retry => 30,          # upper interval value limit when reconnecting. (default 30)
           resubscribe => 'true',    # automatic resubscribing on subscriptions (default: 'true')
           recover => 'true',        # Recovers the lost messages after a reconnection (default: 'false')
           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 and 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, [ 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.

If channel contains a '&', then the function adds the client_id behind the client channel boundary. (even after a reconnect)

This function returns the UIDs 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