Welcome to ProxyBroker2

Relevant source files

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

• README.md
• CLAUDE.md
• CHANGELOG.md
• proxybroker/init.py
• proxybroker/proxy.py
• tests/test_server.py
• tests/test_api.py
• pyproject.toml

ProxyBroker2 is an open-source tool that asynchronously finds, validates, and serves public proxies. It acts as the modernized, actively-maintained successor to the original ProxyBroker (v0.3.2) and supports Python versions 3.10 through 3.14.

Sources: README.md:1-20, CLAUDE.md:6-10

The system discovers proxies from over 50 sources, validates them against judge servers to detect anonymity levels, and provides a local rotating proxy server. It supports multiple protocols, including HTTP(S), SOCKS4, and SOCKS5, and provides first-class support for IPv6 addresses.

Sources: README.md:25-45, CHANGELOG.md:16-30

Core Architecture

The system consists of five main components that manage the lifecycle of a proxy from discovery to consumption.

Component Overview

Component	Responsibility	Relevant Class/Module
Broker	Orchestrates discovery, validation, and serving tasks.	api.py / Broker
Providers	Extract proxy data from 50+ external sources.	providers.py / Provider
Checker	Validates protocol support and anonymity levels.	checker.py / Checker
ProxyPool	Manages a min-heap priority queue of validated proxies.	api.py / ProxyPool
Server	Serves requests via a local port using rotated proxies.	server.py / Server

Sources: CLAUDE.md:46-68, proxybroker/init.py:63-75

Component Relationship Diagram

This diagram shows how the core classes interact to find and validate proxies.

Proxy Lifecycle and Validation

ProxyBroker2 uses an asynchronous pipeline to ensure that only working, high-quality proxies reach the user.

Discovery and Parsing

Providers extract proxy information from text, JSON, or CSV sources. The system supports custom providers defined via YAML or JSON configuration files. It uses the canonicalize_ip helper to normalize both IPv4 and IPv6 addresses, ensuring unique entries in the pool.

Sources: CHANGELOG.md:33-55, CLAUDE.md:144-160

Anonymity Levels

The Checker identifies three distinct levels of anonymity by analyzing headers like Via and X-Forwarded-For against judge servers.

• Transparent: The proxy reveals the client's real IP address.
• Anonymous: The proxy identifies itself as a proxy but hides the client's IP.
• High (Elite): The proxy does not identify as a proxy and hides the client's IP.

Sources: tests/README.md:92-97, proxybroker/proxy.py:108-115

Priority and Selection

The ProxyPool maintains a priority queue based on avg_resp_time. It uses a two-stage process:

1. Newcomers: Proxies with fewer than a minimum required number of requests.
2. Main Pool: Proven proxies that meet error rate and response time thresholds.

Sources: CLAUDE.md:52-56, tests/test_server.py:240-265

Proxy Model and Data Structure

The Proxy class serves as the primary data structure, containing metadata and connection logic.

Proxy Attributes

Attribute	Type	Description
host	str	IP address (IPv4 or RFC 5952 IPv6).
port	int	Connection port (0-65535).
types	dict	Supported protocols and their anonymity levels.
avg_resp_time	float	Rolling average of response times in seconds.
error_rate	float	Ratio of failed requests to total requests.
geo	tuple	Geolocation data (Country, City, Region).

Sources: proxybroker/proxy.py:100-145, proxybroker/proxy.py:202-215

IPv6 Implementation

ProxyBroker2 implements first-class IPv6 support. IPv6 addresses are bracketed in URI authority components (e.g., [2001:db8::1]:8080) to comply with RFC 3986. SOCKS5 negotiators use ATYP=0x04 for IPv6 destinations.

Sources: CHANGELOG.md:18-35, proxybroker/proxy.py:33-45

Usage and Interfaces

Command Line Interface (CLI)

Users interact with ProxyBroker2 primarily through the python -m proxybroker module.

• find: Discovers and validates proxies.
• grab: Discovers proxies without validation for speed.
• serve: Starts a local proxy server that rotates through the discovered pool.

Sources: README.md:143-175, CLAUDE.md:37-43

Python API Example

The following snippet demonstrates the standard asynchronous pattern for using the Broker.

import asyncio
from proxybroker import Broker

async def main():
    proxies = asyncio.Queue()
    broker = Broker(proxies)
    # Find and validate 10 HTTP proxies
    await broker.find(types=["HTTP"], limit=10)

if __name__ == "__main__":
    asyncio.run(main())

Sources: README.md:185-205, tests/test_api.py:75-85

Local Proxy Server

The serve command provides a rotating proxy service on a local port. Clients can retrieve proxy information for a specific request by checking the X-Proxy-Info header or querying the internal proxycontrol API.

Sources: README.md:235-255, tests/test_server.py:115-130

Conclusion

ProxyBroker2 provides a production-ready asynchronous framework for proxy management. Its architecture separates discovery, validation, and serving, allowing for a robust pipeline that ensures high anonymity and low latency. With modern support for IPv6 and a customizable provider system, it serves as a comprehensive tool for developers requiring automated proxy rotation and verification.

Sources: README.md:5-15, CLAUDE.md:162-175