1POE::Component::Server:U:sBearyeCuoxn(t3r)ibuted Perl DoPcOuEm:e:nCtoamtpioonnent::Server::Bayeux(3)
2
3
4

NAME

6       POE::Component::Server::Bayeux - Bayeux/cometd server implementation in
7       POE
8

SYNOPSIS

10         use POE qw(Component::Server::Bayeux);
11
12         # Create the server, listening on port 8080
13         my $server = POE::Component::Server::Bayeux->spawn(
14             Port  => 8080,
15             Alias => 'bayeux_server',
16         );
17
18         # Create a local client, a reply-bot
19         POE::Session->create(
20             inline_states => {
21                 _start => sub {
22                     my ($kernel, $heap) = @_[KERNEL, HEAP];
23                     $kernel->alias_set('test_local_client');
24
25                     # Subscribe to /chat/demo, assigning a state for events
26                     $kernel->post('bayeux_server', 'subscribe', {
27                         channel => '/chat/demo',
28                         client_id => $heap->{client_id},
29                         args => {
30                             state => 'subscribe_response',
31                         },
32                     });
33                 },
34                 subscribe_response => sub {
35                     my ($kernel, $heap, $message) = @_[KERNEL, HEAP, ARG0];
36
37                     # Don't auto-reply to my own messages
38                     return if $message->{clientId} eq $heap->{client_id};
39
40                     # Auto-reply to every message posted
41                     $kernel->post('bayeux_server', 'publish', {
42                         channel => $message->{channel},
43                         client_id => $heap->{client_id},
44                         data => {
45                             user => 'Autobot',
46                             chat => "I got your message, ".($message->{data}{user} || 'anon'),
47                         },
48                     });
49                 },
50             },
51             heap => {
52                 client_id => 'test_local_client',
53             },
54         );
55
56         $poe_kernel->run();
57

DESCRIPTION

59       This module implements the Bayeux Protocol (1.0draft1) from the Dojo
60       Foundation.  Also called cometd, Bayeux is a low-latency routing
61       protocol for JSON encoded events between clients and servers in a
62       publish-subscribe model.
63
64       This is the server implementation.  There is also a client found at
65       POE::Component::Client::Bayeux.  With this server, you can roll out a
66       cometd server and basic HTTP server with POE communication
67       capabilities.  It comes bundled with test code that you can run in your
68       browser to test the functionality for a basic chat program.
69
70       Please note: This is the first release of this code.  Not much testing
71       has been done, so please keep that in mind if you plan on using this
72       for production.  It was developed for a production environment that is
73       still being built, so future versions of this code will be released
74       over the next month that will be more feature complete and less prone
75       to errors.
76

USAGE

78   spawn (...)
79           Create a new Bayeux server.  Arguments to this method:
80
81           Port (default: 80)
82               Bind an HTTP server to this port.
83
84           Alias (default: 'bayeux')
85               The POE session alias for local clients to post to.
86
87           AnonPublish (default: 0)
88               Allow HTTP-connected clients to publish without handshake.
89
90           ConnectTimeout (default: 120)
91               Seconds before an HTTP-connected client is timed out and forced
92               to rehandshake.  Clients must not go this long between having a
93               connect open.
94
95           ClientMaxConnections (default: 10)
96               Maximum number of concurrent connections allowed from a single
97               IP address.  Not effective for anything but the bayeux/cometd
98               connections, as the simple HTTP server doesn't support counting
99               concurrent connections.
100
101           Debug (default: 0)
102               Either 0 or 1, indicates level of logging.
103
104           LogFile (default: undef)
105               If present, opens the file path indicated for logging output.
106
107           DocumentRoot (default: '/var/www')
108               Document root of generic HTTP server for file serving.
109
110           DirectoryIndex (default: [ 'index.html' ])
111               Index file (think Apache config).
112
113           TypeExpires (default: {})
114               Provide a hashref of MIME types and their associated expiry
115               time.  Similar to mod_expires 'ExpiresByType $key "access plus
116               $value seconds"'.
117
118           PostHandle (default: undef)
119               Provide a subref which will be called with the HTTP::Request
120               and HTTP::Response of any simple HTTP requests before the
121               request is completed.  This could allow the code to modify the
122               headers of the response as needed (i.e., path-based expiry
123               time).
124
125           Services (default: {})
126               Each key of this hash represents a service channel that will be
127               available.  The name of the channel will be '/service/$key',
128               and the handling is dependent on the $value.  Provide
129               '_handler' as a fallback handler.
130
131               If $value is a coderef, the code will be called with a single
132               arg of the message being acted upon.  The return value(s) of
133               the coderef will be considered response(s) to be sent back to
134               the client, so return an empty array if you don't want this to
135               happen (if you've added responses by
136               $message->request->add_response()).
137
138           MessageACL (defaults: sub {})
139               Coderef to perform authorization checks on messages.  Code
140               block is passed two args, the Client, and the Message.  If the
141               message should be rejected, the code should set is_error() on
142               the message.
143
144               One could use this to perform authentication on the 'handshake'
145               message:
146
147                 sub {
148                     my ($client, $message) = @_;
149
150                     return unless $message->isa('POE::Component::Server::Bayeux::Message::Meta');
151                     return unless $message->type eq 'handshake';
152
153                     my $error;
154
155                     while (1) {
156                         if (! $message->ext ||
157                             ! (defined $message->ext->{username} && defined $message->ext->{password})) {
158                             $error = "Must pass username and password in ext to handshake";
159                             last;
160                         }
161
162                         my $authenticated = $message->ext->{username} eq 'admin'
163                             && $message->ext->{password} eq 'password' ? 1 : 0;
164
165                         if (! $authenticated) {
166                             $error = "Invalid username or password";
167                             last;
168                         }
169
170                         $client->flags->{is_authenticated} = 1;
171                         last;
172                     }
173
174                     if ($error) {
175                         $message->is_error($error);
176                     }
177                 }
178
179           Callback (defaults: sub {})
180               Coderef to receive general event notifications from the server.
181               Sends a hashref like so:
182
183                 {
184                     event => 'new_connection',
185                     client_id => ...,
186                     client => ...,
187                     message => ...,
188                 }
189
190               See "Server Callbacks" for more details about every type of
191               event that this will receive.
192
193           ContentHandler (defaults: {})
194               Additional ContentHandler for POE::Component::Server::HTTP
195               creation.  Use this to extend the HTTP server content handling.
196
197           Returns a class object with methods of interest:
198
199           logger
200               Returns the Log::Log4perl object used by the server.  Use this
201               for unified logging output.
202
203           session
204               The POE::Session object returned from an internal create()
205               call.
206

POE STATES

208       Most of the server code is regarding interaction with HTTP-connected
209       clients.  For this, see POE::Component::Server::Bayeux::Client.  It
210       supports locally connected POE sessions, and for this, makes the
211       following states available.
212
213       These same states are called internally to handle the basic PubSub
214       behavior of the server for all clients, local and HTTP.
215
216   subscribe ({...})
217           Required keys 'channel', 'client_id'.  Optional key 'args'
218           (hashref).
219
220           Subscribes client_id to the channel indicated.  If subscribe() is
221           called by another session, it's treated as a non-HTTP request and
222           will not perform authentication on the subscription.  Local clients
223           need not handshake or connect.
224
225           Events published to the subscribed channel are sent to the calling
226           session's method named 'deliver', which can be overrided by the
227           args hashref key 'state'.  For example:
228
229             $kernel->post('bayeux_server', 'subscribe', {
230                 channel => '/chat/demo',
231                 client_id => 'local_client',
232                 args => {
233                     state => 'subscribe_events',
234                 },
235             });
236
237   unsubscribe ({...})
238           Required keys 'channel', 'client_id'.
239
240           Unsubscribes client_id from the channel indicated.
241
242   publish ({...})
243           Required keys 'channel' and 'data'.  Optional keys 'client_id',
244           'id', and 'ext'.
245
246           Publishes a message to the channel specified.  The keys
247           'client_id', 'id' and 'ext' are passed thru, appended to the
248           message sent.  For local clients who subscribed from another
249           session, the message is immediately posted to their callback state.
250           For HTTP clients, messages are put into queue and flushed if they
251           have an open /meta/connect.
252
253   client_push ({...})
254   Server Callbacks
255       Using the Callback feature of the server spawning, you can be notified
256       about every significant event on the server.  Below describes all the
257       current callback events:
258
259       subscribe
260           Keys 'client_id' and 'channel'
261
262       unsubscribe
263           Keys 'client_id' and 'channel'
264
265       publish
266           Keys 'channel' and 'data', optional: 'client_id', 'id', 'ext'
267
268       client_push
269           Keys 'channel' and 'client_id', optional: (any extra).  Indicates
270           data was pushed to the client not as a normal request/response or a
271           publish/subscribe (out-of-sequence reply to a /service, for
272           example).  Likely only triggered by local sessions.
273
274       client_connect
275           Keys 'client_id' and either 'ip' or 'session' depending on the type
276           of client.
277
278       client_disconnect
279           Key 'client_id'.
280

TODO

282       Lots of stuff.
283
284       The code currently implements only the long-polling transport and
285       doesn't yet strictly follow all the directives in the protocol document
286       http://svn.xantus.org/shortbus/trunk/bayeux/bayeux.html
287

KNOWN BUGS

289       No known bugs, but I'm sure you can find some.
290

SEE ALSO

292       POE, POE::Component::Server::HTTP
293
295       Copyright (c) 2008 Eric Waters and XMission LLC
296       (http://www.xmission.com/).  All rights reserved.  This program is free
297       software; you can redistribute it and/or modify it under the same terms
298       as Perl itself.
299
300       The full text of the license can be found in the LICENSE file included
301       with this module.
302

AUTHOR

304       Eric Waters <ewaters@uarc.com>
305
306
307
308perl v5.34.0                      2022-01-21 POE::Component::Server::Bayeux(3)
Impressum