1POE::Component::Server:U:sBearyeCuoxn(t3r)ibuted Perl DoPcOuEm:e:nCtoamtpioonnent::Server::Bayeux(3)
2
6 POE::Component::Server::Bayeux - Bayeux/cometd server implementation in
7 POE
8
10 use POE qw(Component::Server::Bayeux);
11 # Create the server, listening on port 8080
13 my $server = POE::Component::Server::Bayeux->spawn(
14 Port => 8080,
15 Alias => 'bayeux_server',
16 );
17 # 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 # 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 # Don't auto-reply to my own messages
38 return if $message->{clientId} eq $heap->{client_id};
39 # 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 $poe_kernel->run();
57
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 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 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
78 spawn (...)
79 Create a new Bayeux server. Arguments to this method:
80 Port (default: 80)
82 Bind an HTTP server to this port.
83 Alias (default: 'bayeux')
85 The POE session alias for local clients to post to.
86 AnonPublish (default: 0)
88 Allow HTTP-connected clients to publish without handshake.
89 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 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 Debug (default: 0)
102 Either 0 or 1, indicates level of logging.
103 LogFile (default: undef)
105 If present, opens the file path indicated for logging output.
106 DocumentRoot (default: '/var/www')
108 Document root of generic HTTP server for file serving.
109 DirectoryIndex (default: [ 'index.html' ])
111 Index file (think Apache config).
112 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 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 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 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 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 One could use this to perform authentication on the 'handshake'
145 message:
146 sub {
148 my ($client, $message) = @_;
149 return unless $message->isa('POE::Component::Server::Bayeux::Message::Meta');
151 return unless $message->type eq 'handshake';
152 my $error;
154 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 my $authenticated = $message->ext->{username} eq 'admin'
163 && $message->ext->{password} eq 'password' ? 1 : 0;
164 if (! $authenticated) {
166 $error = "Invalid username or password";
167 last;
168 }
169 $client->flags->{is_authenticated} = 1;
171 last;
172 }
173 if ($error) {
175 $message->is_error($error);
176 }
177 }
178 Callback (defaults: sub {})
180 Coderef to receive general event notifications from the server.
181 Sends a hashref like so:
182 {
184 event => 'new_connection',
185 client_id => ...,
186 client => ...,
187 message => ...,
188 }
189 See "Server Callbacks" for more details about every type of
191 event that this will receive.
192 ContentHandler (defaults: {})
194 Additional ContentHandler for POE::Component::Server::HTTP
195 creation. Use this to extend the HTTP server content handling.
196 Returns a class object with methods of interest:
198 logger
200 Returns the Log::Log4perl object used by the server. Use this
201 for unified logging output.
202 session
204 The POE::Session object returned from an internal create()
205 call.
206
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 These same states are called internally to handle the basic PubSub
214 behavior of the server for all clients, local and HTTP.
215 subscribe ({...})
217 Required keys 'channel', 'client_id'. Optional key 'args'
218 (hashref).
219 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 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 $kernel->post('bayeux_server', 'subscribe', {
230 channel => '/chat/demo',
231 client_id => 'local_client',
232 args => {
233 state => 'subscribe_events',
234 },
235 });
236 unsubscribe ({...})
238 Required keys 'channel', 'client_id'.
239 Unsubscribes client_id from the channel indicated.
241 publish ({...})
243 Required keys 'channel' and 'data'. Optional keys 'client_id',
244 'id', and 'ext'.
245 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 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 subscribe
260 Keys 'client_id' and 'channel'
261 unsubscribe
263 Keys 'client_id' and 'channel'
264 publish
266 Keys 'channel' and 'data', optional: 'client_id', 'id', 'ext'
267 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 client_connect
275 Keys 'client_id' and either 'ip' or 'session' depending on the type
276 of client.
277 client_disconnect
279 Key 'client_id'.
280
282 Lots of stuff.
283 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
289 No known bugs, but I'm sure you can find some.
290
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 The full text of the license can be found in the LICENSE file included
301 with this module.
302
304 Eric Waters <ewaters@uarc.com>
305perl v5.34.0 2022-01-21 POE::Component::Server::Bayeux(3)