/ 
Net-Proxy-0.02
River stage one • 1 direct dependent • 1 total dependent
/ Net::Proxy

NAME

Net::Proxy - Framework for proxying network connections in many ways

SYNOPSIS

use Net::Proxy;

# proxy connections from localhost:6789 to remotehost:9876
# using standard TCP connections
my $proxy = Net::Proxy->new(
    in  => { proto => tcp, port => '6789' },
    out => { proto => tcp, host => 'remotehost', port => '9876' },
);

# register the proxy object
$proxy->register();

# and you can setup multiple proxies

# and now proxy connections indefinitely
Net::Proxy->mainloop();

DESCRIPTION

A Net::Proxy object represents a proxy that accepts connections and then relays the data transfered between the source and the destination.

The goal of this module is to abstract the different protocols used to connect from the proxy to the destination. See "AVAILABLE CONNECTORS"

METHODS

If you only intend to use Net::Proxy and not write new connectors, you only need to know about new(), register() and mainloop().

Class methods

new( { in => { ... }, { out => { ... } } )

Return a new Net::Proxy object, with two connectors configured as described in the hashref.

mainloop( $max_connections )

This method initialises all the registered Net::Proxy objects and then loops on all the sockets ready for reading, passing the data through the various Net::Proxy::Connector objets to handle the specifics of each connection.

If $max_connections is given, the proxy will stop after having fully processed that many connections. Otherwise, this method does not return.

add_listeners( @sockets )

Add the given sockets to the list of listening sockets.

watch_sockets( @sockets )

Add the given sockets to the watch list.

close_sockets( @sockets )

Close the given sockets and cleanup the related internal structures.

add_loggers( @loggers )

Add the given loggers to the list of logging objects managed by the class.

They all must have a log() method that accepts a list of pair with arguments message and level, just like Log::Dispatch. Levels are exactly the same as those used by Log::Dispatch. Internally, Net::Proxy will only use numerical values for level.

log( message => $mesg, level => $level )

Log a message that will be dispatched to the loggers registered with add_logger().

Some of the class methods are related to the socket objects that handle the actual connections.

get_peer( $socket )
set_peer( $socket, $peer )

Get or set the socket peer.

get_connector( $socket )
set_connector( $socket, $connector )

Get or set the socket connector (a Net::Proxy::Connector object).

get_state( $socket )
set_state( $socket, $state )

Get or set the socket state. Some Net::Proxy::Connector classes may wish to use this to store some internal information about the socket or the connection.

Instance methods

register()

Register a Net::Proxy object so that it will be included in the mainloop() processing.

unregister()

Unregister the Net::Proxy object.

in_connector()

Return the Net::Proxy::Connector objet that handles the incoming connection and handles the data coming from the "client" side.

out_connector()

Return the Net::Proxy::Connector objet that creates the outgoing connection and handles the data coming from the "server" side.

Statistical methods

The following methods manage some statistical information about the individual proxies:

stat_inc_opened()
stat_inc_closed()

Increment the "opened" or "closed" connection counter for this proxy.

stat_opened()
stat_closed()

Return the count of "opened" or "closed" connections for this proxy.

stat_total_opened()
stat_total_closed()

Return the total count of "opened" or "closed" connection across all proxy objects.

AVAILABLE CONNECTORS

All connection types are provided with the help of specialised classes. The logic for protocol xxx is provided by the Net::Proxy::Connector::xxx class.

tcp (Net::Proxy::Connector::tcp)

This is the simplest possible proxy. On the "in" side, it sits waiting for incoming connections, and on the "out" side, it connects to the configured host/port.

connect (Net::Proxy::Connector::connect)

This proxy can connect to a TCP server though a web proxy that accepts HTTP CONNECT requests.

dummy (Net::Proxy::Connector::dummy)

This proxy does nothing. You can use it as a template for writing new Net::Proxy::Connector classes.

Summary

This table summarises all the available Net::Proxy::Connector classes and the parameters their constructors recognise.

 Connector  | in parameters   | out parameters
------------+-----------------+----------------
 tcp        | host            | host
            | port            | port
------------+-----------------+----------------
 connect    | N/A             | host
            |                 | port
            |                 | proxy_host
            |                 | proxy_port
            |                 | proxy_user
            |                 | proxy_pass
            |                 | proxy_agent
------------+-----------------+----------------
 dummy      | N/A             | N/A

AUTHOR

Philippe 'BooK' Bruhat, <book@cpan.org>.

BUGS

Please report any bugs or feature requests to bug-net-proxy@rt.cpan.org, or through the web interface at http://rt.cpan.org/. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

TODO

Here's my own wishlist:

  • port connect-tunnel to use Net::Proxy.

    This requires writing Net::Proxy::Connector::connect.

  • port sslh (unreleased reverse proxy that can listen on a port and proxy to a SSH server or a HTTPS server depending on the client) to use Net::Proxy.

    This requires writing Net::Proxy::Connector::dual.

  • write a script fully compatible with GNU httptunnel (http://www.nocrew.org/software/httptunnel.html.

    This requires writing Net::Proxy::Connector::httptunnel.

  • enhance the httptunnel protocol to support multiple connections

    This requires writing Net::Proxy::Connector::httptunnel2 (or whatever I may call it then).

  • Implement RFC 3093 - Firewall Enhancement Protocol (FEP), as Net::Proxy::Connector::FEP. This RFC was published on April 1, 2001.

  • Add support for filters, so that the data can be transformed on the fly (could be useful to deceive intrusion detection systems, for example).

COPYRIGHT

Copyright 2006 Philippe 'BooK' Bruhat, All Rights Reserved.

LICENSE

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