/ 
POE-Component-Proxy-TCP-1.2
River stage one • 1 direct dependent • 1 total dependent
/ POE::Component::Proxy::TCP

NAME

POE::Component::Proxy::TCP - a simplified TCP proxy

SYNOPSIS

use POE qw(Component::Proxy::TCP);
POE::Component::Proxy::TCP->new
(Alias => "ProxyServerSessionAlias",
 Port               => $local_server_port,
 OrigPort           => $remote_server_port,
 OrigAddress        => $remote_server_host,
 DataFromClient    => \&data_from_client_handler,
 DataFromServer    => \&data_from_server_handler,
);


# gets called with data passed from server.
# called inside the per client connected session created by PoCo::Server::TCP
sub data_from_server_handler {
  my $server_data = shift; 
  # show obtaining other session info esp per proxy session info
};

# gets called with data passed from remote client
# 
sub data_from_client_handler {
  my $server_data = shift; 
};

# show obtaining other session info esp per proxy session info
# Reserved HEAP variables:

$heap->{self}        = Proxy object / instance var hash 
$heap->{self}->losta stuff add documentation
[do the per connection ones]

EXAMPLE

use warnings;
use strict;
use diagnostics;
use POE;
use POE::Filter::Stream;
use POE::Filter::Line;
use POE::Component::Proxy::TCP;
$|++;  

POE::Component::Proxy::TCP->new
(Alias => "ProxyServerSessionAlias",
 Port               => 4000,
 OrigPort           => 5000,
 OrigAddress        => "localhost",
 DataFromClient    => sub {print "From client:", shift(), "\n";},
 DataFromServer    => sub {print "From server:", shift(), "\n";},
 RemoteClientFilter => "POE::Filter::Stream",
 RemoteServerOutputFilter => "POE::Filter::Stream",
 RemoteServerInputFilter => "POE::Filter::Stream"
);

$poe_kernel->run();
exit 0;

DESCRIPTION

The POE::Component::Proxy::TCP proxy component hides the steps needed to create a TCP proxy server using PoCo::Server::TCP and PoCo::Client::TCP. The steps aren't many, but they're still tiresome after a while.

The proxy that PoCo::Client::TCP helps you create accepts tcp connections on a specified well-know port from remote clients, and connects to a remote server at a specified host and port. It then copies all data that it receives from either side to the other, calling given callbacks to perform any application specific processing. When writing callbacks, one must pay attention to which session runs the callback and what heap variables are available in that session.

Session Structure

- Proxy Server Listener Session, created by PoCo::Server::TCP
  - Proxy Server Connection Sessions, per remote client connection
    Created in PoCo::Server:
    - Proxy Client Connection Sessions, created by 
      PoCo::Client::TCP

Constructor parameters:
Alias

Alias is an optional name by which the server side of the proxy will be named.

Alias => 'proxyServer'
DataFromClient

DataFromClient is a coderef that will be called to handle input recieved from the remote client. The callback receives its parameters directly from PoCo::Client::TCP after its fileration. ARG0 is the input record. This coderef is executed in a Proxy Client Connection Session. @_[HEAP]->{self} holds a reference to the proxy object from which various parameters by be obtained.

DataFromClient => \&data_input_handler
DataFromServer

DataFromServer is a coderef that will be called to handle input recieved from the remote server. The callback receives its parameters directly from PoCo::Server::TCP after its fileration. ARG0 is the input record. This coderef is executed in a Proxy Server Connection Session. @_[HEAP]->{self} holds a reference to the proxy object from which various parameters by be obtained.

DataFromServer => \&server_data_input_handler
RemoteClientFilter

[The sense of client and server in what follows is reversed! Yeah, I know why that is, but its ugly and should get fixed someday.]

RemoteClientFilter specifies the type of filter that will parse input from the server (!). It may either be a scalar or a list reference. If it is a scalar, it will contain a POE::Filter class name. If it is a list reference, the first item in the list will be a POE::Filter class name, and the remaining items will be constructor parameters for the filter. For example, this changes the line separator to a vertical bar:

RemoteClientFilter => [ "POE::Filter::Line", InputLiteral => "|" ],

RemoteClientFilter is optional. The component will supply a "POE::Filter::Stream" instance if none is specified. If you supply a different value for Filter, then you must also use that filter class.

RemoteServerInputFilter

RemoteServerInputFilter specifies the type of filter that will parse input from each client. It may either be a scalar or a list reference. If it is a scalar, it will contain a POE::Filter class name. If it is a list reference, the first item in the list will be a POE::Filter class name, and the remaining items will be constructor parameters for the filter. For example, this changes the line separator to a vertical bar:

RemoteServerInputFilter => [ "POE::Filter::Line", InputLiteral => "|" ],

RemoteServerInputFilter is optional. The component will supply a "POE::Filter::Stream" instance if none is specified. If you supply a different value for Filter, then you must also use that filter class.

RemoteServerOutputFilter

RemoteServerOutputFilter specifies the type of filter that will parse input from each client. It may either be a scalar or a list reference. If it is a scalar, it will contain a POE::Filter class name. If it is a list reference, the first item in the list will be a POE::Filter class name, and the remaining items will be constructor parameters for the filter. For example, this changes the line separator to a vertical bar:

RemoteServerOutputFilter => [ "POE::Filter::Line", InputLiteral => "|" ],

RemoteServerOutputFilter is optional. The component will supply a "POE::Filter::Stream" instance if none is specified. If you supply a different value for Filter, then you must also use that filter class.

OrigPort

OrigPort is the port the to which the proxy server will connect to when client connects to the proxy server.

Port => 80
Port

Port is the port the on which the proxy server will listen for tcp connections.

Port => 30023
OrigAddress

Address or host to which the proxy will connect when connected to by a client. It defaults to localhost. It's passed directly to PoCo::Client::TCP as its RemoteAddress parameter, so it can be in whatever form SocketFactory supports. At the time of this writing, that's a dotted quad, an IPv6 address, a host name, or a packed Internet address.

Address => '127.0.0.1'   # Localhost IPv4
Address => "::1"         # Localhost IPv6
Address =>'www.dc.state.fl.us'

EVENTS

SEE ALSO

POE::Component::Server::TCP, POE::Component::Client::TCP, 
POE::Wheel::SocketFactory, POE::Wheel::ReadWrite, POE::Filter

CAVEATS

Like most reusable components, PoCo::Proxy::TCP started as a hardcoded fragement of another project, and was converted to a component by parameterization. Undoubtly thare are still hardcoded elements that need to be changed for given applications that can now only be changed by hacking the source. This will be fixed incrementally. Suggestions encouraged. In particular, there outght to be a semistandard way to added states to to nested sessions.[There almost is one implied by other PoCos I think?.]

BUGS

AUTHORS & COPYRIGHTS

POE::Component::Proxy::TCP is Copyright 2004 by Andrew V. Purshottam. All rights are reserved. POE::Component::Proxy::TCP is free software, and it may be redistributed and/or modified under the same terms as Perl itself.

POE::Component::Proxy::TCP is based on:
 - POE::Component::Server::TCP - for module structure and parameter 
   handling.
 - POE::Component::Server::HTTP - for instance variable conventions

This POD is based on PODs in POE distribution, which were probably mainly written by Rocco.