# NAME

PocketIO - Socket.IO PSGI application

# SYNOPSIS

   use Plack::Builder;

   builder {
       mount '/socket.io' => PocketIO->new(
           handler => sub {
               my $self = shift;

               $self->on(
                   'message' => sub {
                       my $self = shift;
                       my ($message) = @_;

                       ...;
                   }
               );

               $self->send({buffer => []});
           }
       );

       $app;
   };

   # or

   builder {
       mount '/socket.io' =>
         PocketIO->new(class => 'MyApp::Handler', method => 'run');

       $app;
   };

# DESCRIPTION

[PocketIO](http://search.cpan.org/perldoc?PocketIO) is a server implementation of SocketIO in Perl, you still need
`socket.io` javascript library on the client.

[PocketIO](http://search.cpan.org/perldoc?PocketIO) aims to have API as close as possible to the Node.js implementation
and sometimes it might look not very perlish.

## How to use

First you mount [PocketIO](http://search.cpan.org/perldoc?PocketIO) as a normal [Plack](http://search.cpan.org/perldoc?Plack) application. It is recommended
to mount it to the `/socket.io` path since that will not require any changes on
the client side.

When the client is connected your handler is called with a [PocketIO::Socket](http://search.cpan.org/perldoc?PocketIO::Socket)
object as a first parameter.

## Sending and receiving messages

A simple echo handler can look like this:

   sub {
       my $self = shift;

       $self->on('message' => sub {
           my $self = shift;
           my ($message) = @_;

           $self->send($message);
       });
   }

## Sending and receiving events

Events are special messages that behave like rpc calls.

   sub {
       my $self = shift;

       $self->on('username' => sub {
           my $self = shift;
           my ($nick) = @_;

           ...
       });

       $self->emit('username', 'vti');
   }

## Broadcasting and sending messages/events to everybody

Broadcasting is sending messages to everybody except you:

   $self->broadcast->send('foo');
   $self->broadcast->emit('foo');

Method `sockets` represents all connected clients:

   $self->sockets->send('foo');
   $self->sockets->emit('foo');

## Acknowlegements

Sometimes you want to know when the client received a message or event. In order
to achieve this just pass a callback as the last parameter:

   $self->send('foo', sub {'client got message'});
   $self->emit('foo', sub {'client got event'});

## Storing data in the socket object

Often it is required to store some data in the client object. Instead of using
global variables there are two handy methods:

   sub {
       my $self = shift;

       $self->set(foo => 'bar', sub { 'ready' });
       $self->get('foo' => sub {
           my $self = shift;
           my ($err, $foo) = @_;
       });
   }

## Namespacing

Not implemented yet.

## Volatile messages

Not implemented yet.

## Rooms

A room is a named group of connections for more fine-grained
broadcasts.  You can subscribe or unsubscribe a socket to/from a room:

   sub {
       my $self = shift;

       $self->join('a room');

       $self->sockets->in('a room')->emit('message', data);
       $self->broadcast->to('a room')->emit("other message");
   }

# CONFIGURATIONS

- handler

       PocketIO->new(
           handler => sub {
               my $socket = shift;

               $socket->on(
                   'message' => sub {
                       my $socket = shift;
                   }
               );

               $socket->send('hello');
           }
       );
- class or instance, method

       PocketIO->new(class => 'MyHandler', method => 'run');

       # or

       PocketIO->new(instance => MyHandler->new(foo => 'bar'), method => 'run');

       package MyHandler;

       sub new { ...  } # or use Moose, Boose, Goose, Doose

       sub run {
           my $self = shift;

           return sub {

               # same code as above
           }
       }

   Loads `class`, creates a new object or uses a passed `instance` and runs
   `run` method expecting it to return an anonymous subroutine.

# TLS/SSL

For TLS/SSL a secure proxy is needed. `stunnel` or [App::TLSMe](http://search.cpan.org/perldoc?App::TLSMe) are
recommended.

# SCALING

See [PocketIO::Pool::Redis](http://search.cpan.org/perldoc?PocketIO::Pool::Redis).

# DEBUGGING

Use `POCKETIO_DEBUG` and `POCKETIO_CONNECTION_DEBUG` variables for debugging.

# METHODS

## `new`

Create a new [PocketIO](http://search.cpan.org/perldoc?PocketIO) instance.

## `pool`

Holds [PocketIO::Pool](http://search.cpan.org/perldoc?PocketIO::Pool) object by default.

## `call`

For Plack apps compatibility.

## `to_app`

Returns PSGI code reference.

# SEE ALSO

More information about SocketIO you can find on the website [http://socket.io/](http://socket.io/), or
on the GitHub [https://github.com/LearnBoost/Socket.IO](https://github.com/LearnBoost/Socket.IO).

[Protocol::SocketIO](http://search.cpan.org/perldoc?Protocol::SocketIO), [PSGI](http://search.cpan.org/perldoc?PSGI)

# DEVELOPMENT

## Repository

   http://github.com/vti/pocketio

# CREDITS

Socket.IO author(s) and contributors.

Jens Gassmann

Uwe Voelker

Oskari Okko Ojala

Jason May

Michael FiG

Peter Stuifzand

tokubass

mvgrimes

# AUTHOR

Viacheslav Tykhanovskyi, `[email protected]`.

# COPYRIGHT AND LICENSE

Copyright (C) 2011-2013, Viacheslav Tykhanovskyi

This program is free software, you can redistribute it and/or modify it under
the terms of the Artistic License version 2.0.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.