Class methods

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( $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_reader_sockets( @sockets )

Add the given sockets to the readers watch list.

watch_writer_sockets( @sockets )

Add the given sockets to the writers watch list.

remove_writer_sockets( @sockets )

Remove the given sockets from the writers watch list.

close_sockets( @sockets )

Close the given sockets and cleanup the related internal structures.

set_verbosity( $level )

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

error( $message )

Log $message to STDERR, always.

notice( $message )

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

info( $message )

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

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 "##".)

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" subclasses may wish to use this to store some internal information about the socket or the connection.

get_nick( $socket )

set_nick( $socket, $nickname )

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

get_buffer( $socket )

set_buffer( $socket, $data )

Get or 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( $socket )

set_callback( $socket, $coderef )

Get or set the callback currently associated with the socket.

add_to_buffer( $socket, $data )

Add data to the writing buffer of the socket.

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.

Connector hooks

There is a single parameter that all connectors accept: "hook". Given a code reference, the code reference will be called when data is received on the corresponding socket.

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

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

"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.