NAME

    Test::POE::Server::TCP - A POE Component providing TCP server services
    for test cases

VERSION

    version 1.20

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.

    If AF_INET6 sockets are supported the component with create an AF_INET
    and an AF_INET6 socket.

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 spawned 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 AF_INET socket.

    port

      Returns the port that the component is listening on.

    getsockname6

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

    port6

      Returns the port that the component is listening on for AF_INET6.

    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) 2016 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.