The Perl Toolchain Summit 2025 Needs You: You can help 🙏 Learn more

 / 
Centrifugo-Client-1.05
River stage zero No dependents
/ Centrifugo::Client

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