Class methods

    my $proxy = Net::Proxy->new( { in => { ... }, { out => { ... } } );

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

The connector parameters are described in the table below, as well as in each connector documentation.

mainloop

    Net::Proxy->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

    Net::Proxy->add_listeners( @sockets );

Add the given sockets to the list of listening sockets.

watch_reader_sockets

    Net::Proxy->watch_reader_sockets( @sockets );

Add the given sockets to the readers watch list.

watch_writer_sockets

    Net::Proxy->watch_writer_sockets( @sockets );

Add the given sockets to the writers watch list.

remove_writer_sockets

    Net::Proxy->remove_writer_sockets( @sockets );

Remove the given sockets from the writers watch list.

close_sockets

    Net::Proxy->close_sockets( @sockets );

Close the given sockets and cleanup the related internal structures.

set_verbosity

    Net::Proxy->set_verbosity( $level );

Set the logging level. 0 means not messages except warnings and errors.

error

    Net::Proxy->error( $message );

Log $message to STDERR, always.

notice

    Net::Proxy->notice( $message );

Log $message to STDERR if verbosity level is equal to 1 or more.

info

    Net::Proxy->info( $message );

Log $message to STDERR if verbosity level is equal to 2 or more.

debug

    Net::Proxy->debug( $message );

Log $message to STDERR if verbosity level is equal to 3 or more.

(Note: throughout the Net::Proxy source code, calls to "debug()" are commented with "##".)

get_max_buffer_size

    my $buffsize = Net::Proxy->get_max_buffer_size;

Get the maximum allowed length of the internal write buffers used by each connector.

set_max_buffer_size

    Net::Proxy->set_max_buffer_size($buffsize);

Get or set the maximum allowed length of the internal write buffers used by each connector. A value of 0 means that the maximum length is not checked. The default value is 16384 bytes (16kB).

Note that this is a global value, shared by all proxies and connectors.

Class methods related to sockets

get_peer

    my $peer = Net::Proxy->get_peer( $socket );

Get the socket peer.

set_peer

    Net::Proxy->set_peer( $socket, $peer );

Set the socket peer.

get_connector

    my $connector = Net::Proxy->get_connector( $socket );

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

set_connector

    Net::Proxy->set_connector( $socket, $connector );

Set the socket connector (a Net::Proxy::Connector object).

get_state

    my $state = Net::Proxy->get_state( $socket );

Get the socket state.

set_state

    Net::Proxy->set_state( $socket, $state );

Set the socket state. Some "Net::Proxy::Connector" subclasses may wish to use this to store some internal information about the socket or the connection.

get_nick

    my $nick = Net::Proxy->get_nick( $socket );

Get the socket nickname.

set_nick

    Net::Proxy->set_nick( $socket, $nickname );

Set the socket nickname. Typically used by Net::Proxy::Connector to give informative names to socket (used in the log messages).

get_buffer

    my $buffer = Net::Proxy->get_buffer( $socket );

Get the content of the writing buffer for the socket.

set_buffer

    Net::Proxy->set_buffer( $socket, $data );

Set the content of the writing buffer for the socket. Used by Net::Proxy::Connector in "raw_read_from()" and "ranw_write_to()".

get_callback

    Net::Proxy->get_callback( $socket );

Get the callback currently associated with the socket.

set_callback

    Net::Proxy->set_callback( $socket, $coderef );

Set the callback currently associated with the socket.

add_to_buffer

    Net::Proxy->add_to_buffer( $socket, $data );

Add data to the writing buffer of the socket.

Instance methods

    $proxy->register();

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

unregister

    $proxy->unregister();

Unregister the Net::Proxy object.

in_connector

    my $connector = $proxy->in_connector();

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

out_connector

    my $connector = $proxy->out_connector();

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

Statistical methods

stat_inc_opened

    $proxy->stat_inc_opened();

Increment the "opened" connection counter for this proxy.

stat_inc_closed

    $proxy->stat_inc_closed();

Increment the "closed" connection counter for this proxy.

stat_opened

    my $opened = $proxy->stat_opened();

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

stat_closed

    my $closed = $proxy->stat_closed();

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

stat_total_opened

    my $opened = $proxy->stat_total_opened();

Return the total count of "opened" connections across all proxy objects.

stat_total_closed

    my $closed = $proxy->stat_total_closed();

Return the total count of "closed" connections across all proxy objects.

Connector hooks

The code reference should have the following signature:

    sub callback {
        my ($dataref, $sock, $connector) = @_;
        ...
    }

$dataref is a reference to the chunk of data received, $sock is a reference to the socket that received the data, and $connector is the "Net::Proxy::Connector" object that created the socket. This allows someone to eventually store data in a stash stored in the connector, so as to share data between sockets.

Available connectors

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

This is the simplest possible proxy connector. 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 connector can connect to a TCP server though a web proxy that accepts HTTP CONNECT requests.

dual (Net::Proxy::Connector::dual)

This proxy connector is a Y-shaped connector: depending on the client behaviour right after the connection is established, it connects it to one of two services, handled by two distinct connectors.

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

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

Summary

"N/A" means that the given Net::Proxy::Connector cannot be used in that position (either "in" or "out").

     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
    ------------+-----------------+-----------------
     dual       | host            | N/A
                | port            |
                | timeout         |
                | server_first    |
                | client_first    |
    ------------+-----------------+-----------------
     dummy      | N/A             | N/A
    ------------+-----------------+-----------------
     ssl        | host            | host
                | port            | port
                | start_cleartext | start_cleartext
    ------------+-----------------+-----------------
     connect_ssl| N/A             | host
                |                 | port
                |                 | proxy_host
                |                 | proxy_port
                |                 | proxy_user
                |                 | proxy_pass
                |                 | proxy_agent

Net::Proxy::Connector::dummy is used as the "out" parameter for a Net::Proxy::Connector::dual, since the later is linked to two different connector objects.