NAME

IO::Multiplex::Intermediary - multiplexing with fault tolerance

SYNOPSIS

use IO::Multiplex::Intermediary;

my $intermediary = IO::Multiplex::Intermediary->new;

$intermediary->run;

DESCRIPTION

WARNING! THIS MODULE HAS BEEN DEEMED ALPHA BY THE AUTHOR. THE API MAY CHANGE IN SUBSEQUENT VERSIONS.

This library is for users who want to optimize user experience. It keeps the external connection operations and application operations separate as separate processes, so that if the application crashes.

The core is robust in its simplicity. The library is meant for your application to extend the IO::Multiplex::Intermediary::Client module that ships with this distribution and use its hooks. If the application crashes, the end users on the external side will not be disconnected. When the controller reconnects, the users will be welcomed back to the real interaction in any way that the developer who extends this module sees fit.

The intermediary opens two ports: one for end users to connect to, and one for the application to connect to. The intermediary server and client use JSON to communicate with each other. Here is an example of the life cycle of the intermediary and application:

 User land       |  Intermediary      |  Application
                 |                    |
 Connect         |                    |
                 |  Accept user       |
                 |  connection        |
                 |                    |
                 |  Send the          |
                 |  connection        |
                 |  action to         |
                 |   the app          |
                 |                    |  Receive
                 |                    |  connection
                 |                    |
                 |                    |  Track any
                 |                    |  user data
                 |                    |
 User sends      |                    |
 something       |                    |
                 | Read the message   |
                 |                    |
                 | Send the message   |
                 | to the app         |
                 |                    |  Read the message
                 |                    |
                 |                    |  Process the message
                 |                    |  (build_response)
                 |                    |
                 |                    |  Send the response
                 |  Get the response  |
                 |                    |
                 |  Send the response |
                 |  to the appropriate|
                 |  user              |
Disconnect       |                    |
                 |  Send the discon.  |
                 |  message to the    |
                 |  intermediary      |
                 |                    |  Become aware of
                 |                    |  the disconnect
                 |                    |  and act
                 |                    |  accordingly

EXAMPLES

NOTE: Examples are in the examples/ directory supplied with the distribution.

PARAMETERS FOR new

external_port

This is the port that the end users will use to access the application. If it is not specified, the default is 6715.

client_port

This is the port that intermediary will use to communicate internally with the application.

METHODS

send($id, $data)

Sends $data (string format) to the socket that belongs to $id

HOOKS

These methods are NOT for complete overriding. They do important things that involve communication with the client. They are here so that you can hook around these methods in any way you see fit.

client_connect

Method called when the client connects to the intermediary

client_input

Method called when the client sends data to the intermediary

client_disconnect

Method called when the client disconnects from the intermediary

connect

Method called when a user connects to the intermediary

input

Method called when a user sends data to the intermediary

disconnect

Method called when a user disconnects from the intermediary

SEE ALSO

IO::Multiplex

AUTHOR

Jason May <jason.a.may@gmail.com>

LICENSE

This library is free software and may be distributed under the same terms as perl itself.