Protocol Negotiators
Relevant source files
The following files were used as context for generating this wiki page:
Protocol Negotiators are specialized components in ProxyBroker2 that handle the initial handshake and protocol-specific communication required to establish a connection through a proxy. Each negotiator implements the logic for a specific protocol, such as HTTP, HTTPS, SOCKS4, or SOCKS5, ensuring that the proxy server correctly identifies and processes the incoming request.
The negotiators act as an abstraction layer between the Proxy object and the underlying network socket. When a proxy is checked or used for a request, the system assigns the appropriate negotiator to manage the protocol-level "negotiation" phase. This design allows ProxyBroker2 to support diverse proxy types including standard HTTP(S) proxies and binary-oriented SOCKS proxies.
Sources: proxybroker/negotiators.py:15-30, proxybroker/proxy.py:165-167
Architecture and Base Classes
The negotiator system uses an abstract base class to define a consistent interface for all protocol implementations.
BaseNegotiator
Every negotiator inherits from the BaseNegotiator class. This class requires an instance of a Proxy during initialization and enforces the implementation of an asynchronous negotiate method. It also contains flags that influence how the proxy checker interacts with the protocol.
Sources: proxybroker/negotiators.py:53-67
Negotiator Properties
| Property | Description |
|---|---|
name | String identifier for the protocol (e.g., "SOCKS5"). |
check_anon_lvl | Boolean indicating if the protocol supports anonymity level detection. |
use_full_path | Boolean indicating if the full URL path should be used in the request (common for HTTP). |
Sources: proxybroker/negotiators.py:56-58
Negotiator Implementations
SOCKS Negotiators
The SOCKS negotiators handle binary handshakes. The Socks5Ngtr supports modern IPv6 destinations using ATYP=0x04, while Socks4Ngtr is restricted to IPv4 as per the original protocol specification.
The diagram shows the SOCKS5 handshake process including version negotiation and connection request.
Sources: proxybroker/negotiators.py:70-137
HTTP and CONNECT Negotiators
These negotiators use text-based HTTP commands. HttpNgtr is a pass-through for standard HTTP proxies, while HttpsNgtr and Connect80Ngtr utilize the HTTP CONNECT method to establish a tunnel.
- HttpNgtr: Enables anonymity level checking and uses the full URL path.
- HttpsNgtr: Performs a
CONNECTrequest to port 443 and then upgrades the connection to SSL. - Connect80Ngtr / Connect25Ngtr: Used for tunneling to specific ports (80 for web, 25 for SMTP).
Sources: proxybroker/negotiators.py:173-221
IPv6 Support and Bracketing
The negotiator system implements first-class IPv6 support. For HTTP-based CONNECT requests, negotiators must bracket IPv6 literals (e.g., [2001:db8::1]) to prevent ambiguity between the address colons and the port separator.
For SOCKS5, the Socks5Ngtr checks the address type using ipaddress.IPv6Address. If it is an IPv6 address, it sets the ATYP byte to 0x04 and packs the 16-byte address.
Sources: proxybroker/negotiators.py:33-50, proxybroker/negotiators.py:91-100
Integration within the Proxy Lifecycle
The Proxy class manages its negotiator through a setter property. When a protocol string is assigned to Proxy.ngtr, the corresponding negotiator class is instantiated from the NGTRS mapping.
The flowchart illustrates how a specific negotiator is selected and initialized based on the protocol string.
Sources: proxybroker/proxy.py:165-167, proxybroker/negotiators.py:224-231
Negotiator Registry (NGTRS)
The system maintains a central dictionary mapping protocol names to their respective negotiator classes:
- HTTP:
HttpNgtr - HTTPS:
HttpsNgtr - SOCKS4:
Socks4Ngtr - SOCKS5:
Socks5Ngtr - CONNECT:80:
Connect80Ngtr - CONNECT:25:
Connect25Ngtr
Sources: proxybroker/negotiators.py:224-231
Conclusion
Protocol Negotiators provide the essential logic required for ProxyBroker2 to communicate across different proxy standards. By encapsulating complex handshakes—such as the SOCKS5 binary protocol or HTTP CONNECT tunneling—within dedicated classes, the system maintains a clean separation between high-level proxy management and low-level protocol implementation. This modularity ensures robust support for both IPv4 and IPv6 traffic across all supported proxy types.