Security & Error Handling

Relevant source files

The following files were used as context for generating this wiki page:

• CLAUDE.md
• README.md
• CHANGELOG.md
• tests/test_checker.py
• tests/test_server.py
• tests/test_public_contracts.py

ProxyBroker2 manages security and error handling through automated proxy validation, strict anonymity detection, and a hierarchical exception system. The project prioritizes "Async Safety" and "Contract-based testing" to prevent deadlocks, memory leaks, and race conditions that previously affected legacy versions.

This system ensures that only functional and safe proxies enter the usable pool while providing developers with granular error feedback for network failures, protocol mismatches, and validation timeouts.

Error Handling Architecture

The project employs a structured exception hierarchy to categorize different failure modes. Most specific errors inherit from a base ProxyError class. This allows users to catch broad categories of failures or target specific issues like DNS resolution or connection timeouts.

Exception Hierarchy

Exception Class	Description	Base Class
ProxyError	Base class for all proxy-related errors	Exception
ProxyConnError	Failure to establish a connection to the proxy	ProxyError
ProxyRecvError	Error receiving data from the proxy	ProxyError
ProxySendError	Error sending data through the proxy	ProxyError
ProxyTimeoutError	Operation timed out based on timeout setting	ProxyError
NoProxyError	Raised when the ProxyPool is empty or filters return no results	Exception
ResolveError	DNS resolution failure for proxy hosts	Exception

Sources: tests/test_public_contracts.py:270-305, CLAUDE.md:145-147

Async Resource Management

The Broker class manages lifecycle security by cleaning up signal handlers during stop() calls to prevent memory leaks. It also uses asyncio.create_task() instead of deprecated patterns to avoid race conditions.

Proxy Validation & Anonymity Security

The Checker component secures the proxy pool by validating anonymity levels against "Judge" servers. It detects if a proxy leaks the user's real IP address through HTTP headers or payload analysis.

Anonymity Levels

Level	Description	Security Posture
High	No indicators of proxy usage; real IP is hidden.	Best
Anonymous	Proxy usage is visible (via headers), but real IP is hidden.	Good
Transparent	Real IP address is visible in headers (e.g., Via, X-Forwarded-For).	Low

Sources: README.md:94-96, tests/test_checker.py:100-115

Validation Logic

The Checker performs verification by comparing the response from a judge against the user's real_ext_ip. For IPv6 security, it uses RFC 5952 canonicalization to ensure that different textual representations (e.g., uppercase vs. lowercase) of the same IP address are correctly identified as leaks.

Proxy Pool Stability

The ProxyPool protects the system from "bad" proxies by enforcing quality thresholds. Proxies that fail validation or exceed error limits are automatically discarded or prevented from moving from the newcomers queue to the main pool.

Quality Thresholds

• Error Rate: Proxies exceeding the max_error_rate (default e.g., 0.5) are dropped.
• Response Time: Proxies slower than max_resp_time are removed from the heap.
• Minimum Requests: Proxies stay in a _newcomers state until they pass min_req_proxy checks.

Sources: tests/test_server.py:230-265, CLAUDE.md:72-74

Heap Invariant Security

To prevent heap corruption, the pool uses heapq operations based on proxy.avg_resp_time. The remove() method is implemented with an $O(N \log N)$ heap-safe operation to maintain ordering after a proxy is purged.
Sources: CLAUDE.md:78-80, tests/test_server.py:295-310

SSL and Protocol Security

ProxyBroker2 handles SSL verification and protocol-specific constraints to ensure secure tunnels.

• SSL Verification: The verify_ssl parameter (default False in some testing contexts) controls whether the broker validates certificates.
• IPv6 Security: IPv6 addresses in URI authority are bracketed (RFC 3986) to prevent ambiguity with port separators.
• SOCKS4 Limitation: The system explicitly raises a BadResponseError if an IPv6 destination is attempted over SOCKS4, as the protocol does not support it.

Sources: CHANGELOG.md:88-92, tests/test_public_contracts.py:45-55, CLAUDE.md:120-125

Summary

The security and error handling framework in ProxyBroker2 ensures high reliability through automated anonymity classification and strict pool management. By canonicalizing IP addresses and providing a robust exception hierarchy, the system allows for safe, asynchronous proxy rotation while effectively mitigating common network and protocol-level failures.