File: README

package info (click to toggle)
libtest-poe-server-tcp-perl 1.14-1
  • links: PTS, VCS
  • area: main
  • in suites: jessie-kfreebsd, wheezy
  • size: 204 kB
  • ctags: 47
  • sloc: perl: 539; makefile: 2
file content (396 lines) | stat: -rw-r--r-- 13,205 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
NAME
    Test::POE::Server::TCP - A POE Component providing TCP server services
    for test cases

VERSION
    version 1.14

SYNOPSIS
    A very simple echo server with logging of requests by each client:

       use strict;
       use POE;
       use Test::POE::Server::TCP;

       POE::Session->create(
         package_states => [
            'main' => [qw(
                            _start
                            testd_connected
                            testd_disconnected
                            testd_client_input
            )],
         ],
       );
   
       $poe_kernel->run();
       exit 0;
   
       sub _start {
         # Spawn the Test::POE::Server::TCP server.
         $_[HEAP]->{testd} = Test::POE::Server::TCP->spawn(
            address => '127.0.0.1',
            port => 0,
         );
         return;
       }
   
       sub testd_connected {
         my ($heap,$id) = @_[HEAP,ARG0];

         # A client connected the unique ID is in ARG0
         # Create a blank arrayref for this client on *our* heap

         $heap->{clients}->{ $id } = [ ];

         return;
       }
   
       sub testd_client_input {
         my ($kernel,$heap,$sender,$id,$input) = @_[KERNEL,HEAP,SENDER,ARG0,ARG1];

         # The client sent us a line of input
         # lets store it

         push @{ $heap->{clients}->{ $id }, $input;

         # Okay, we are an echo server so lets send it back to the client
         # We know the SENDER so can always obtain the server object.

         my $testd = $sender->get_heap();
         $testd->send_to_client( $id, $input );

         # Or even

         # $sender->get_heap()->send_to_client( $id, $input );

         # Alternatively we could just post back to the SENDER

         # $kernel->post( $sender, 'send_to_client', $id, $input );

         return;
       }

       sub testd_disconnected {
         my ($heap,$id) = @_[HEAP,ARG0];

         # Client disconnected for whatever reason
         # We need to free up our storage

         delete $heap->{clients}->{ $id };

         return;
       }

    Using the module in a testcase:

       use strict;
       use Test::More;
       use POE qw(Wheel::SocketFactory Wheel::ReadWrite Filter::Line);
       use Test::POE::Server::TCP;
   
       plan tests => 5;
   
       my @data = (
         'This is a test',
         'This is another test',
         'This is the last test',
       );
   
       POE::Session->create(
         package_states => [
            'main' => [qw(
                            _start
                            _sock_up
                            _sock_fail
                            _sock_in
                            _sock_err
                            testd_connected
                            testd_disconnected
                            testd_client_input
            )],
         ],
         heap => { data => \@data, },
       );
   
       $poe_kernel->run();
       exit 0;
   
       sub _start {
         $_[HEAP]->{testd} = Test::POE::Server::TCP->spawn(
            address => '127.0.0.1',
            port => 0,
         );
         return;
       }
   
       sub testd_registered {
         my ($heap,$object) = @_[HEAP,ARG0];
         $heap->{port} = $object->port();
         $heap->{factory} = POE::Wheel::SocketFactory->new(
            RemoteAddress  => '127.0.0.1',
            RemotePort     => $heap->{port},
            SuccessEvent   => '_sock_up',
            FailureEvent   => '_sock_fail',
         );
         return;
       }
   
       sub _sock_up {
         my ($heap,$socket) = @_[HEAP,ARG0];
         delete $heap->{factory};
         $heap->{socket} = POE::Wheel::ReadWrite->new(
            Handle => $socket,
            InputEvent => '_sock_in',
            ErrorEvent => '_sock_err',
         );
         $heap->{socket}->put( $heap->{data}->[0] );
         return;
       }
   
       sub _sock_fail {
         my $heap = $_[HEAP];
         delete $heap->{factory};
         $heap->{testd}->shutdown();
         return;
       }
   
       sub _sock_in {
         my ($heap,$input) = @_[HEAP,ARG0];
         my $data = shift @{ $heap->{data} };
         ok( $input eq $data, 'Data matched' );
         unless ( scalar @{ $heap->{data} } ) {
           delete $heap->{socket};
           return;
         }
         $heap->{socket}->put( $heap->{data}->[0] );
         return;
       }
   
       sub _sock_err {
         delete $_[HEAP]->{socket};
         return;
       }
   
       sub testd_connected {
         my ($heap,$state,$id) = @_[HEAP,STATE,ARG0];
         pass($state);
         return;
       }
   
       sub testd_disconnected {
         pass($_[STATE]);
         $poe_kernel->post( $_[SENDER], 'shutdown' );
         return;
       }
   
       sub testd_client_input {
         my ($sender,$id,$input) = @_[SENDER,ARG0,ARG1];
         my $testd = $_[SENDER]->get_heap();
         $testd->send_to_client( $id, $input );
         return;
       }

DESCRIPTION
    Test::POE::Server::TCP is a POE component that provides a TCP server
    framework for inclusion in client component test cases, instead of
    having to roll your own.

    Once registered with the component, a session will receive events
    related to client connects, disconnects, input and flushed output. Each
    of these events will refer to a unique client ID which may be used in
    communication with the component when sending data to the client or
    disconnecting a client connection.

CONSTRUCTOR
    "spawn"
        Takes a number of optional arguments:

          'alias', set an alias on the component;
          'address', bind the listening socket to a particular address;
          'port', listen on a particular port, default is 0, assign a random port;
          'options', a hashref of POE::Session options;
          'filter', specify a POE::Filter to use for client connections, default is POE::Filter::Line;
          'inputfilter', specify a POE::Filter for client input;
          'outputfilter', specify a POE::Filter for output to clients;
          'prefix', specify a different prefix than 'testd' for events;

        The semantics for "filter", "inputfilter" and "outputfilter" are the
        same as for POE::Component::Server::TCP in that one may provide
        either a "SCALAR", "ARRAYREF" or an "OBJECT".

        If the component is "spawn"ed within another session it will
        automatically "register" the parent session to receive "all" events.

METHODS
    "session_id"
        Returns the POE::Session ID of the component.

    "shutdown"
        Terminates the component. Shuts down the listener and disconnects
        connected clients.

    "send_to_client"
        Send some output to a connected client. First parameter must be a
        valid client id. Second parameter is a string of text to send. The
        second parameter may also be an arrayref of items to send to the
        client. If the filter you have used requires an arrayref as input,
        nest that arrayref within another arrayref.

    "send_to_all_clients"
        Send some output to all connected clients. The parameter is a string
        of text to send. The parameter may also be an arrayref of items to
        send to the clients. If the filter you have used requires an
        arrayref as input, nest that arrayref within another arrayref.

    "client_info"
        Retrieve socket information of a given client. Requires a valid
        client ID as a parameter. If called in a list context it returns a
        list consisting of, in order, the client address, the client TCP
        port, our address and our TCP port. In a scalar context it returns a
        HASHREF with the following keys:

          'peeraddr', the client address;
          'peerport', the client TCP port;
          'sockaddr', our address;
          'sockport', our TCP port;

    "client_wheel"
        Retrieve the POE::Wheel::ReadWrite object of a given client.
        Requires a valid client ID as a parameter. This enables one to
        manipulate the given POE::Wheel::ReadWrite object, say to switch
        POE::Filter.

    "disconnect"
        Places a client connection in pending disconnect state. Requires a
        valid client ID as a parameter. Set this, then send an applicable
        message to the client using send_to_client() and the client
        connection will be terminated.

    "terminate"
        Immediately disconnects a client conenction. Requires a valid client
        ID as a parameter.

    "pause_listening"
        Stops the underlying listening socket from accepting new
        connections. This lets you test whether you handle the connection
        timing out gracefully.

    "resume_listening"
        The companion of "pause_listening"

    "getsockname"
        Access to the POE::Wheel::SocketFactory method of the underlying
        listening socket.

    "port"
        Returns the port that the component is listening on.

    "start_listener"
        If the listener fails on "listen" you can attempt to restart it with
        this.

INPUT EVENTS
    These are events that the component will accept:

    "register"
        Takes N arguments: a list of event names that your session wants to
        listen for, minus the 'testd_' prefix.

        Registering for 'all' will cause it to send all TESTD-related events
        to you; this is the easiest way to handle it.

    "unregister"
        Takes N arguments: a list of event names which you don't want to
        receive. If you've previously done a 'register' for a particular
        event which you no longer care about, this event will tell the POP3D
        to stop sending them to you. (If you haven't, it just ignores you.
        No big deal).

    "shutdown"
        Terminates the component. Shuts down the listener and disconnects
        connected clients.

    "send_to_client"
        Send some output to a connected client. First parameter must be a
        valid client id. Second parameter is a string of text to send. The
        second parameter may also be an arrayref of items to send to the
        client. If the filter you have used requires an arrayref as input,
        nest that arrayref within another arrayref.

    "send_to_all_clients"
        Send some output to all connected clients. The parameter is a string
        of text to send. The parameter may also be an arrayref of items to
        send to the clients. If the filter you have used requires an
        arrayref as input, nest that arrayref within another arrayref.

    "disconnect"
        Places a client connection in pending disconnect state. Requires a
        valid client ID as a parameter. Set this, then send an applicable
        message to the client using send_to_client() and the client
        connection will be terminated.

    "terminate"
        Immediately disconnects a client conenction. Requires a valid client
        ID as a parameter.

    "start_listener"
        If the listener fails on "listen" you can attempt to restart it with
        this.

OUTPUT EVENTS
    The component sends the following events to registered sessions. If you
    have changed the "prefix" option in "spawn" then substitute "testd" with
    the event prefix that you specified.

    "testd_registered"
        This event is sent to a registering session. ARG0 is the
        Test::POE::Server::TCP object.

    "testd_listener_failed"
        Generated if the component cannot either start a listener or there
        is a problem accepting client connections. ARG0 contains the name of
        the operation that failed. ARG1 and ARG2 hold numeric and string
        values for $!, respectively.

        If the operation was "listen", the component will remove the
        listener. You may attempt to start it again using "start_listener".

    "testd_connected"
        Generated whenever a client connects to the component. ARG0 is the
        client ID, ARG1 is the client's IP address, ARG2 is the client's TCP
        port. ARG3 is our IP address and ARG4 is our socket port.

    "testd_disconnected"
        Generated whenever a client disconnects. ARG0 was the client ID,
        ARG1 was the client's IP address, ARG2 was the client's TCP port.
        ARG3 was our IP address and ARG4 was our socket port.

    "testd_client_input"
        Generated whenever a client sends us some traffic. ARG0 is the
        client ID, ARG1 is the data sent ( tokenised by whatever POE::Filter
        you specified ).

    "testd_client_flushed"
        Generated whenever anything we send to the client is actually
        flushed down the 'line'. ARG0 is the client ID.

CREDITS
    This module uses code borrowed from POE::Component::Server::TCP by Rocco
    Caputo, Ann Barcomb and Jos Boumans.

SEE ALSO
    POE

    POE::Component::Server::TCP

AUTHOR
    Chris Williams <chris@bingosnet.co.uk>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2010 by Chris Williams, Rocco Caputo, Ann
    Barcomb and Jos Boumans.

    This is free software; you can redistribute it and/or modify it under
    the same terms as the Perl 5 programming language system itself.