Net::Proxy(3pm)

📦
version 0.13 · 3 versions
, in debian trixie, ubuntu resolute, ubuntu stonking

💖 Net::Proxy 💖 — the Net::Proxy(3pm) page, bestie edition

User Contributed Perl Documentation · Net::Proxy(3pm)

✨ NAME ✨

Net::Proxy — a whole framework for proxying network connections in so many ways, no cap.

🎀 SYNOPSIS 🎀

okay so here's the whole vibe in one go:

use Net::Proxy;

# proxy connections from localhost:6789 to remotehost:9876
# using standard TCP connections
my $proxy = Net::Proxy->new(
    {   in  => { type => 'tcp', port => '6789' },
        out => { type => '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();

periodt. that's the whole thing 💅

🦋 DESCRIPTION 🦋

So a Net::Proxy object? It's literally a proxy. It accepts connections, then relays the data transferred between the source and the destination. main character energy fr fr.

The goal of this module is to abstract away the different methods used to connect from the proxy to the destination. iykyk.

A proxy is a program that transfers data across a network boundary between a client and a server. Net::Proxy introduces the concept of "connectors" (implemented as Net::Proxy::Connector subclasses, slay), which abstract the server part (connected to the client) and the client part (connected to the server) of the proxy.

This architecture makes it easy to implement specific techniques to cross a given network boundary — possibly by using a proxy on one side of the network fence, and a reverse-proxy on the other side of the fence. 🧚 lowkey genius.

See "AVAILABLE CONNECTORS" for details about the existing 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(). that's it bestie, you're free 🌸

💫 Class methods 💫

  • new
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. it's giving forever mode 💀

  • 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. bye bestie 👋

  • 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. one size fits all, unfortunately 🙈

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

  • 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 🌈

  • register
$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 📊

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

  • 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. 🌍

🎀 CONNECTORS 🎀

okay so here's the tea, bestie: every single connection type in Net::Proxy gets its own lil specialised class. 💅 The logic for protocol "xxx" lives in the Net::Proxy::Connector::xxx class. cute, right? one class per vibe. periodt.

✨ Connector hooks ✨

There's exactly one parameter that literally every connector accepts: hook. 🪝 Hand it a code reference and that code ref gets called every time data shows up on the matching socket. it's giving "call me when something happens" energy.

That code reference needs this exact signature, no cap:

sub callback {
    my ($dataref, $sock, $connector) = @_;
    ...
}
  • $dataref — a reference to the chunk of data that just got received 🍓
  • $sock — a reference to the socket that received it 🧦
  • $connector — the Net::Proxy::Connector object that created the socket 👑

and why do we get the connector passed in, you ask? so you can eventually stash data inside the connector and share it between sockets. lowkey genius. 🤝

🌈 Available connectors 🌈

  • tcp (Net::Proxy::Connector::tcp) — the simplest possible proxy connector, fr fr. On the in side it just sits there waiting for incoming connections (main character energy: patient, unbothered), and on the out side it connects to the host/port you configured. 🛋️
  • connect (Net::Proxy::Connector::connect) — this one can connect to a TCP server through a web proxy that accepts HTTP CONNECT requests. sneaky but legal. 🕵️♀️
  • dual (Net::Proxy::Connector::dual) — a Y-shaped connector, iykyk. Depending on what the client does right after the connection is established, it gets routed to one of two services, each handled by its own distinct connector. pick a lane, bestie. 🔀
  • dummy (Net::Proxy::Connector::dummy) — does absolutely nothing. 💀 it's basically the template you copy when you're writing your own new Net::Proxy::Connector classes. it's giving mannequin.

📋 Summary 📋

This is the rundown of every available Net::Proxy::Connector class and which parameters their constructors actually recognise. 👀

"N/A" means that particular connector cannot be used in that position (so, either in or out). no exceptions, sorry babe.

  • tcp
    • in parameters: host, port
    • out parameters: host, port
  • connect
    • in parameters: N/A
    • out parameters: host, port, proxy_host, proxy_port, proxy_user, proxy_pass, proxy_agent
  • dual
    • in parameters: host, port, timeout, server_first, client_first
    • out parameters: N/A
  • dummy
    • in parameters: N/A
    • out parameters: N/A
  • ssl
    • in parameters: host, port, start_cleartext
    • out parameters: host, port, start_cleartext
  • connect_ssl
    • in parameters: N/A
    • out parameters: host, port, proxy_host, proxy_port, proxy_user, proxy_pass, proxy_agent

and here's the plot twist 🫢: Net::Proxy::Connector::dummy is what you use as the out parameter for a Net::Proxy::Connector::dual, because the dual is already linked to two different connector objects. it's the placeholder bestie standing in so the math works out. 🎀

👑 AUTHOR 👑

Philippe 'BooK' Bruhat, "<book@cpan.org>". iconic, we stan. 💜

🐛 BUGS 🐛

Found a bug? Want a feature? Please report it to "bug-net-proxy@rt.cpan.org", or through the web interface at <http://rt.cpan.org/>. They'll get notified, and then you'll automatically get notified about the progress on your bug as changes get made. so you're in the loop the whole time, no ghosting. 🫶

📝 TODO 📝

okay so here's the personal wishlist, the "someday maybe" board:

This one will probably be named Net::Proxy::Connector::httptunnel.

  • Enhance the httptunnel protocol to support multiple connections.
  • Implement RFC 3093 - Firewall Enhancement Protocol (FEP), as Net::Proxy::Connector::FEP. This RFC was published on April 1, 2001. 🗓️ (yes, that date. we see it. we're not gonna say anything.)

This is probably impossible with Net::Proxy, since the FEP driver is a rather low-level driver (at the IP level of the network stack).

  • Implement DNS tunnel connectors.

See <http://savannah.nongnu.org/projects/nstx/>, OzymanDNS, <http://www.doxpara.com/slides/BH_EU_05-Kaminsky.pdf>, <http://thomer.com/howtos/nstx.html> for examples.

  • Implement an UDP connector. (Is it feasible? 🤔)
  • Implement a connector that can be plugged to the STDIN/STDOUT of an external process, like the ProxyCommand option of OpenSSH.
  • Implement Net::Proxy::Connector::unix, for UNIX sockets.
  • Implement ICMP tunnel connectors.

See <http://www.linuxexposed.com/Articles/Hacking/Case-of-a-wireless-hack.html>, <http://sourceforge.net/projects/itun>, <http://www.cs.uit.no/~daniels/PingTunnel/>, <http://thomer.com/icmptx/> for examples.

Since ICMP implies low-level packet reading and writing, it may not be possible for Net::Proxy to handle it.

Look also here: <http://gray-world.net/tools/>

  • Implement a Net::Proxy::Connector::starttls connector that can upgrade upgrade a connection to SSL transparently, even if the client or server doesn't support STARTTLS.

Martin Werthmöller provided a full implementation of a connector that can handle IMAP connections and upgrade them to TLS if the client sends a STARTTLS command. My implementation will split this in two parts Net::Proxy::Connector::ssl and Net::Proxy::Connector::starttls, that inherits from the former.

the "upgrade upgrade" is in the original and honestly? mood. 💅

🦋 SUPPORT 🦋

You can find documentation for this module with the perldoc command. go on, run it, it's free:

perldoc Net::Proxy

You can also look for information at:

Copyright 2006-2014 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.

and that's a wrap, bestie 🎀✨ this page ships as perl v5.38.2, dated 2024-05-15, and it's Net::Proxy(3pm) — go forth and proxy responsibly. mwah. 💋

📦 where this page comes from