NAME
POE::Component::Server::Bayeux - Bayeux/cometd server implementation in
POE
SYNOPSIS
use POE qw(Component::Server::Bayeux);
# Create the server, listening on port 8080
my $server = POE::Component::Server::Bayeux->spawn(
Port => 8080,
Alias => 'bayeux_server',
);
# Create a local client, a reply-bot
POE::Session->create(
inline_states => {
_start => sub {
my ($kernel, $heap) = @_[KERNEL, HEAP];
$kernel->alias_set('test_local_client');
# Subscribe to /chat/demo, assigning a state for events
$kernel->post('bayeux_server', 'subscribe', {
channel => '/chat/demo',
client_id => $heap->{client_id},
args => {
state => 'subscribe_response',
},
});
},
subscribe_response => sub {
my ($kernel, $heap, $message) = @_[KERNEL, HEAP, ARG0];
# Don't auto-reply to my own messages
return if $message->{clientId} eq $heap->{client_id};
# Auto-reply to every message posted
$kernel->post('bayeux_server', 'publish', {
channel => $message->{channel},
client_id => $heap->{client_id},
data => {
user => 'Autobot',
chat => "I got your message, ".($message->{data}{user} || 'anon'),
},
});
},
},
heap => {
client_id => 'test_local_client',
},
);
$poe_kernel->run();
DESCRIPTION
This module implements the Bayeux Protocol (1.0draft1) from the Dojo
Foundation. Also called cometd, Bayeux is a low-latency routing protocol
for JSON encoded events between clients and servers in a
publish-subscribe model.
This is the server implementation. There is also a client found at
POE::Component::Client::Bayeux. With this server, you can roll out a
cometd server and basic HTTP server with POE communication capabilities.
It comes bundled with test code that you can run in your browser to test
the functionality for a basic chat program.
Please note: This is the first release of this code. Not much testing
has been done, so please keep that in mind if you plan on using this for
production. It was developed for a production environment that is still
being built, so future versions of this code will be released over the
next month that will be more feature complete and less prone to errors.
USAGE
spawn (...)
Create a new Bayeux server. Arguments to this method:
*Port* (default: 80)
Bind an HTTP server to this port.
*Alias* (default: 'bayeux')
The POE session alias for local clients to post to.
*AnonPublish* (default: 0)
Allow HTTP-connected clients to publish without handshake.
*ConnectTimeout* (default: 120)
Seconds before an HTTP-connected client is timed out and forced
to rehandshake. Clients must not go this long between having a
connect open.
*ClientMaxConnections* (default: 10)
Maximum number of concurrent connections allowed from a single
IP address. Not effective for anything but the bayeux/cometd
connections, as the simple HTTP server doesn't support counting
concurrent connections.
*Debug* (default: 0)
Either 0 or 1, indicates level of logging.
*LogFile* (default: undef)
If present, opens the file path indicated for logging output.
*DocumentRoot* (default: '/var/www')
Document root of generic HTTP server for file serving.
*DirectoryIndex* (default: [ 'index.html' ])
Index file (think Apache config).
*TypeExpires* (default: {})
Provide a hashref of MIME types and their associated expiry
time. Similar to mod_expires 'ExpiresByType $key "access plus
$value seconds"'.
*PostHandle* (default: undef)
Provide a subref which will be called with the HTTP::Request and
HTTP::Response of any simple HTTP requests before the request is
completed. This could allow the code to modify the headers of
the response as needed (i.e., path-based expiry time).
*Services* (default: {})
Each key of this hash represents a service channel that will be
available. The name of the channel will be '/service/$key', and
the handling is dependent on the $value. Provide '_handler' as a
fallback handler.
If $value is a coderef, the code will be called with a single
arg of the message being acted upon. The return value(s) of the
coderef will be considered response(s) to be sent back to the
client, so return an empty array if you don't want this to
happen (if you've added responses by
$message->request->add_response()).
*MessageACL* (defaults: sub {})
Coderef to perform authorization checks on messages. Code block
is passed two args, the Client, and the Message. If the message
should be rejected, the code should set is_error() on the
message.
One could use this to perform authentication on the 'handshake'
message:
sub {
my ($client, $message) = @_;
return unless $message->isa('POE::Component::Server::Bayeux::Message::Meta');
return unless $message->type eq 'handshake';
my $error;
while (1) {
if (! $message->ext ||
! (defined $message->ext->{username} && defined $message->ext->{password})) {
$error = "Must pass username and password in ext to handshake";
last;
}
my $authenticated = $message->ext->{username} eq 'admin'
&& $message->ext->{password} eq 'password' ? 1 : 0;
if (! $authenticated) {
$error = "Invalid username or password";
last;
}
$client->flags->{is_authenticated} = 1;
last;
}
if ($error) {
$message->is_error($error);
}
}
*Callback* (defaults: sub {})
Coderef to receive general event notifications from the server.
Sends a hashref like so:
{
event => 'new_connection',
client_id => ...,
client => ...,
message => ...,
}
See "Server Callbacks" for more details about every type of
event that this will receive.
*ContentHandler* (defaults: {})
Additional ContentHandler for POE::Component::Server::HTTP
creation. Use this to extend the HTTP server content handling.
Returns a class object with methods of interest:
*logger*
Returns the Log::Log4perl object used by the server. Use this
for unified logging output.
*session*
The POE::Session object returned from an internal create() call.
POE STATES
Most of the server code is regarding interaction with HTTP-connected
clients. For this, see POE::Component::Server::Bayeux::Client. It
supports locally connected POE sessions, and for this, makes the
following states available.
These same states are called internally to handle the basic PubSub
behavior of the server for all clients, local and HTTP.
subscribe ({...})
Required keys 'channel', 'client_id'. Optional key 'args' (hashref).
Subscribes client_id to the channel indicated. If subscribe() is
called by another session, it's treated as a non-HTTP request and
will not perform authentication on the subscription. Local clients
need not handshake or connect.
Events published to the subscribed channel are sent to the calling
session's method named 'deliver', which can be overrided by the args
hashref key 'state'. For example:
$kernel->post('bayeux_server', 'subscribe', {
channel => '/chat/demo',
client_id => 'local_client',
args => {
state => 'subscribe_events',
},
});
unsubscribe ({...})
Required keys 'channel', 'client_id'.
Unsubscribes client_id from the channel indicated.
publish ({...})
Required keys 'channel' and 'data'. Optional keys 'client_id', 'id',
and 'ext'.
Publishes a message to the channel specified. The keys 'client_id',
'id' and 'ext' are passed thru, appended to the message sent. For
local clients who subscribed from another session, the message is
immediately posted to their callback state. For HTTP clients,
messages are put into queue and flushed if they have an open
/meta/connect.
client_push ({...})
Server Callbacks
Using the Callback feature of the server spawning, you can be notified
about every significant event on the server. Below describes all the
current callback events:
*subscribe*
Keys 'client_id' and 'channel'
*unsubscribe*
Keys 'client_id' and 'channel'
*publish*
Keys 'channel' and 'data', optional: 'client_id', 'id', 'ext'
*client_push*
Keys 'channel' and 'client_id', optional: (any extra). Indicates
data was pushed to the client not as a normal request/response or a
publish/subscribe (out-of-sequence reply to a /service, for
example). Likely only triggered by local sessions.
*client_connect*
Keys 'client_id' and either 'ip' or 'session' depending on the type
of client.
*client_disconnect*
Key 'client_id'.
TODO
Lots of stuff.
The code currently implements only the long-polling transport and
doesn't yet strictly follow all the directives in the protocol document
http://svn.xantus.org/shortbus/trunk/bayeux/bayeux.html
KNOWN BUGS
No known bugs, but I'm sure you can find some.
SEE ALSO
POE, POE::Component::Server::HTTP
COPYRIGHT
Copyright (c) 2008 Eric Waters and XMission LLC
(http://www.xmission.com/). All rights reserved. This program is free
software; you can redistribute it and/or modify it under the same terms
as Perl itself.
The full text of the license can be found in the LICENSE file included
with this module.
AUTHOR
Eric Waters <ewaters@uarc.com>
